dcclib.validation

SchemaDownloadError

Bases: Exception

Raised when a DCC schema (or the list of released versions) could not be fetched from PTB's servers. This error signals a network/availability problem rather than an invalid document. Callers that need to validate offline should provide a local schema file instead (e.g. XsdValidator.from_file / the CLI --schema option).

SchematronFinding dataclass 

SchematronFinding(node: etree.Element)

Class to represent a single finding of a schematron validation.

A finding is created for every schematron rule that fired, either because an sch:assert failed or because an sch:report matched.

Create a SchematronFinding from an SVRL element.

Parameters:
  • node (etree.Element) –

    a svrl:failed-assert or svrl:successful-report element

is_error property 

is_error: bool

Whether this finding invalidates the document.

is_failed_assertion property 

is_failed_assertion: bool

Whether this finding comes from an sch:assert whose test was false.

is_successful_report property 

is_successful_report: bool

Whether this finding comes from an sch:report whose test was true.

SchematronFindingKind

Bases: StrEnum

The kind of schematron rule that produced a finding.

The values are the SVRL element names, so a finding keeps the vocabulary of the SVRL document it was parsed from.

default_severity property 

default_severity: Severity

The severity of a rule of this kind with no role attribute.

A failing sch:assert states that the document is wrong, while a matching sch:report merely reports something about it.

SchematronValidationResult dataclass 

SchematronValidationResult(findings: list[SchematronFinding] | None = None)

Class to represent the result of an XML validation against a schematron file.

errors property 

errors: list[SchematronFinding]

All findings that invalidate the document.

infos property 

infos: list[SchematronFinding]

All findings that merely inform about the document.

warnings property 

warnings: list[SchematronFinding]

All findings that warn about the document without invalidating it.

by_severity 

by_severity(severity: Severity) -> list[SchematronFinding]

All findings of a given severity.

Parameters:
  • severity (Severity) –

    the severity to filter by
Returns:

SchematronValidator 

SchematronValidator(svrl_content: str)

Bases: Constructible, Validatable

Class to validate XML files against a schematron file.

Create a SchematronValidator.

Parameters:
  • svrl_content (str) –

    the content of the compiled schematron file

for_dcc classmethod 

for_dcc()

Create a SchematronValidator for the DCC schematron.

Returns:
  • –

    the SchematronValidator

from_file classmethod 

from_file(schematron_path: str)

Create a SchematronValidator from a file path.

Parameters:
  • schematron_path (str) –

    the path to the schematron file
Returns:
  • –

    the SchematronValidator

from_str classmethod 

from_str(schematron_content: str)

Create a SchematronValidator from a string.

Parameters:
  • schematron_content (str) –

    the content of the schematron file
Returns:
  • –

    the SchematronValidator

from_tree classmethod 

from_tree(tree: etree.Element)

Create a SchematronValidator from an etree.Element tree.

Parameters:
  • tree (etree.Element) –

    the etree.Element tree
Returns:
  • –

    the SchematronValidator

validate_file 

validate_file(xml_path: str) -> SchematronValidationResult

Validate an XML file against a schematron file.

Parameters:
  • xml_path (str) –

    the path to the XML file to validate
Returns:

validate_str 

validate_str(xml_content: str) -> SchematronValidationResult

Validate an XML file against a schematron file.

Parameters:
  • xml_content (str) –

    the XML string to validate
Returns:

validate_tree 

validate_tree(tree: etree.Element) -> SchematronValidationResult

Validate an XML file against a schematron file.

Parameters:
  • tree (etree.Element) –

    the XML tree to validate
Returns:

Severity

Bases: StrEnum

How much a validation finding matters.

Being a :class:~enum.StrEnum keeps the members usable wherever a plain string is expected: they render and compare equal to "error", "warning" and "info", and serialise to those values in JSON.

rank property 

rank: int

Sort key ordering the severities from most to least severe.

Validatable

Bases: ABC

Abstract base class for classes that can validate a tree structure, file, or string representation.

validate_file abstractmethod 

validate_file(xml_path: str)

Validate a file path.

Parameters:
  • xml_path (str) –

    the path to the file

validate_str abstractmethod 

validate_str(xml_content: str)

Validate a string representation.

Parameters:
  • xml_content (str) –

    the string representation

validate_tree abstractmethod 

validate_tree(tree: etree.Element)

Validate a tree structure.

Parameters:
  • tree (etree.Element) –

    the tree structure

XmlError dataclass 

XmlError(log_error)

Class to represent an error that occurred during XML validation.

XsdValidationResult dataclass 

XsdValidationResult(is_valid: bool, errors: list[XmlError] | None = None)

Class to represent the result of an XML validation against a schema.

XsdValidator 

XsdValidator(xmlschema_doc: etree.Element, parser: etree.XMLParser)

Bases: Constructible, Validatable

Class to validate XML files against a schema.

Create an XsdValidator.

Parameters:
  • xmlschema_doc (etree.Element) –

    the XML schema document

  • parser (etree.XMLParser) –

    the XML parser

from_auto_detection classmethod 

from_auto_detection()

Create an XsdValidator by auto-detecting the schema version.

Returns:
  • –

    the XsdValidator

from_file classmethod 

from_file(schema_path: str)

Create an XsdValidator from a file path.

Parameters:
  • schema_path (str) –

    the path to the XSD schema file
Returns:
  • –

    the XsdValidator
Raises:
  • FileNotFoundError –

    if the schema file does not exist

from_str classmethod 

from_str(schema_content: str)

Create an XsdValidator from a string.

Parameters:
  • schema_content (str) –

    the content of the XSD schema
Returns:
  • –

    the XsdValidator

from_tree classmethod 

from_tree(tree: etree.Element)

Create an XsdValidator from an XML schema tree.

Parameters:
  • tree (etree.Element) –

    the XML schema tree
Returns:
  • –

    the XsdValidator

from_version classmethod 

from_version(version: str)

Create an XsdValidator from a schema version string.

The released XSD schema for the version is downloaded (on first use) and cached locally via dcc_json_toolkit.

Parameters:
  • version (str) –

    the schema version string (e.g. "3.3.0")
Returns:
  • –

    the XsdValidator

validate_file 

validate_file(xml_path: str) -> XsdValidationResult

Validate an XML file against an XSD schema.

Parameters:
  • xml_path (str) –

    the path to the XML file
Returns:

validate_str 

validate_str(xml_content: str) -> XsdValidationResult

Validate an XML file against an XSD schema.

Parameters:
  • xml_content (str) –

    the XML string to validate
Returns:

validate_tree 

validate_tree(tree: etree.Element) -> XsdValidationResult

Validate an XML tree against an XSD schema.

Parameters:
  • tree (etree.Element) –

    the XML tree to validate
Returns:

compile_schematron_to_svrl 

compile_schematron_to_svrl(schematron: str) -> str

Compile a schematron file to a svrl file.

Parameters:
  • schematron (str) –

    the schematron content to compile

get_released_schema_versions cached 

get_released_schema_versions() -> list[str]

Fetch the list of released DCC schema versions from PTB (https://www.ptb.de/dcc/releases.json).

Returns:
  • list[str] –

    list of version strings (e.g. ["2.1.0", "2.1.1", ..., "3.3.0"])
Raises:
  • SchemaDownloadError –

    if the list could not be fetched from PTB

resolve_severity 

resolve_severity(kind: SchematronFindingKind, role: str = '', flag: str = '') -> Severity

Determine the severity of a schematron finding.

Parameters:
  • kind (SchematronFindingKind) –

    the SVRL element the finding was parsed from

  • role (str, default: '' ) –

    the rule's role attribute, if any

  • flag (str, default: '' ) –

    the rule's flag attribute, if any
Returns:

errors

SchemaDownloadError

Bases: Exception

Raised when a DCC schema (or the list of released versions) could not be fetched from PTB's servers. This error signals a network/availability problem rather than an invalid document. Callers that need to validate offline should provide a local schema file instead (e.g. XsdValidator.from_file / the CLI --schema option).

SchematronFinding dataclass 

SchematronFinding(node: etree.Element)

Class to represent a single finding of a schematron validation.

A finding is created for every schematron rule that fired, either because an sch:assert failed or because an sch:report matched.

Create a SchematronFinding from an SVRL element.

Parameters:
  • node (etree.Element) –

    a svrl:failed-assert or svrl:successful-report element

is_error property 

is_error: bool

Whether this finding invalidates the document.

is_failed_assertion property 

is_failed_assertion: bool

Whether this finding comes from an sch:assert whose test was false.

is_successful_report property 

is_successful_report: bool

Whether this finding comes from an sch:report whose test was true.

XmlError dataclass 

XmlError(log_error)

Class to represent an error that occurred during XML validation.

results

SchematronValidationResult dataclass 

SchematronValidationResult(findings: list[SchematronFinding] | None = None)

Class to represent the result of an XML validation against a schematron file.

errors property 

errors: list[SchematronFinding]

All findings that invalidate the document.

infos property 

infos: list[SchematronFinding]

All findings that merely inform about the document.

warnings property 

warnings: list[SchematronFinding]

All findings that warn about the document without invalidating it.

by_severity 

by_severity(severity: Severity) -> list[SchematronFinding]

All findings of a given severity.

Parameters:
  • severity (Severity) –

    the severity to filter by
Returns:

XsdValidationResult dataclass 

XsdValidationResult(is_valid: bool, errors: list[XmlError] | None = None)

Class to represent the result of an XML validation against a schema.

schematron

SchematronValidator 

SchematronValidator(svrl_content: str)

Bases: Constructible, Validatable

Class to validate XML files against a schematron file.

Create a SchematronValidator.

Parameters:
  • svrl_content (str) –

    the content of the compiled schematron file

for_dcc classmethod 

for_dcc()

Create a SchematronValidator for the DCC schematron.

Returns:
  • –

    the SchematronValidator

from_file classmethod 

from_file(schematron_path: str)

Create a SchematronValidator from a file path.

Parameters:
  • schematron_path (str) –

    the path to the schematron file
Returns:
  • –

    the SchematronValidator

from_str classmethod 

from_str(schematron_content: str)

Create a SchematronValidator from a string.

Parameters:
  • schematron_content (str) –

    the content of the schematron file
Returns:
  • –

    the SchematronValidator

from_tree classmethod 

from_tree(tree: etree.Element)

Create a SchematronValidator from an etree.Element tree.

Parameters:
  • tree (etree.Element) –

    the etree.Element tree
Returns:
  • –

    the SchematronValidator

validate_file 

validate_file(xml_path: str) -> SchematronValidationResult

Validate an XML file against a schematron file.

Parameters:
  • xml_path (str) –

    the path to the XML file to validate
Returns:

validate_str 

validate_str(xml_content: str) -> SchematronValidationResult

Validate an XML file against a schematron file.

Parameters:
  • xml_content (str) –

    the XML string to validate
Returns:

validate_tree 

validate_tree(tree: etree.Element) -> SchematronValidationResult

Validate an XML file against a schematron file.

Parameters:
  • tree (etree.Element) –

    the XML tree to validate
Returns:

compile_schematron_to_svrl 

compile_schematron_to_svrl(schematron: str) -> str

Compile a schematron file to a svrl file.

Parameters:
  • schematron (str) –

    the schematron content to compile

severity

SchematronFindingKind

Bases: StrEnum

The kind of schematron rule that produced a finding.

The values are the SVRL element names, so a finding keeps the vocabulary of the SVRL document it was parsed from.

default_severity property 

default_severity: Severity

The severity of a rule of this kind with no role attribute.

A failing sch:assert states that the document is wrong, while a matching sch:report merely reports something about it.

Severity

Bases: StrEnum

How much a validation finding matters.

Being a :class:~enum.StrEnum keeps the members usable wherever a plain string is expected: they render and compare equal to "error", "warning" and "info", and serialise to those values in JSON.

rank property 

rank: int

Sort key ordering the severities from most to least severe.

resolve_severity 

resolve_severity(kind: SchematronFindingKind, role: str = '', flag: str = '') -> Severity

Determine the severity of a schematron finding.

Parameters:
  • kind (SchematronFindingKind) –

    the SVRL element the finding was parsed from

  • role (str, default: '' ) –

    the rule's role attribute, if any

  • flag (str, default: '' ) –

    the rule's flag attribute, if any
Returns:

validatable

Validatable

Bases: ABC

Abstract base class for classes that can validate a tree structure, file, or string representation.

validate_file abstractmethod 

validate_file(xml_path: str)

Validate a file path.

Parameters:
  • xml_path (str) –

    the path to the file

validate_str abstractmethod 

validate_str(xml_content: str)

Validate a string representation.

Parameters:
  • xml_content (str) –

    the string representation

validate_tree abstractmethod 

validate_tree(tree: etree.Element)

Validate a tree structure.

Parameters:
  • tree (etree.Element) –

    the tree structure

xsd

XsdValidator 

XsdValidator(xmlschema_doc: etree.Element, parser: etree.XMLParser)

Bases: Constructible, Validatable

Class to validate XML files against a schema.

Create an XsdValidator.

Parameters:
  • xmlschema_doc (etree.Element) –

    the XML schema document

  • parser (etree.XMLParser) –

    the XML parser

from_auto_detection classmethod 

from_auto_detection()

Create an XsdValidator by auto-detecting the schema version.

Returns:
  • –

    the XsdValidator

from_file classmethod 

from_file(schema_path: str)

Create an XsdValidator from a file path.

Parameters:
  • schema_path (str) –

    the path to the XSD schema file
Returns:
  • –

    the XsdValidator
Raises:
  • FileNotFoundError –

    if the schema file does not exist

from_str classmethod 

from_str(schema_content: str)

Create an XsdValidator from a string.

Parameters:
  • schema_content (str) –

    the content of the XSD schema
Returns:
  • –

    the XsdValidator

from_tree classmethod 

from_tree(tree: etree.Element)

Create an XsdValidator from an XML schema tree.

Parameters:
  • tree (etree.Element) –

    the XML schema tree
Returns:
  • –

    the XsdValidator

from_version classmethod 

from_version(version: str)

Create an XsdValidator from a schema version string.

The released XSD schema for the version is downloaded (on first use) and cached locally via dcc_json_toolkit.

Parameters:
  • version (str) –

    the schema version string (e.g. "3.3.0")
Returns:
  • –

    the XsdValidator

validate_file 

validate_file(xml_path: str) -> XsdValidationResult

Validate an XML file against an XSD schema.

Parameters:
  • xml_path (str) –

    the path to the XML file
Returns:

validate_str 

validate_str(xml_content: str) -> XsdValidationResult

Validate an XML file against an XSD schema.

Parameters:
  • xml_content (str) –

    the XML string to validate
Returns:

validate_tree 

validate_tree(tree: etree.Element) -> XsdValidationResult

Validate an XML tree against an XSD schema.

Parameters:
  • tree (etree.Element) –

    the XML tree to validate
Returns:

detect_schema_version 

detect_schema_version(tree: etree.Element) -> str

Detect the schema version of an XML file.

Parameters:
  • tree (etree.Element) –

    the DCC XML tree
Returns:
  • str –

    the detected schema version string (e.g. "3.3.0")

get_released_schema_versions cached 

get_released_schema_versions() -> list[str]

Fetch the list of released DCC schema versions from PTB (https://www.ptb.de/dcc/releases.json).

Returns:
  • list[str] –

    list of version strings (e.g. ["2.1.0", "2.1.1", ..., "3.3.0"])
Raises:
  • SchemaDownloadError –

    if the list could not be fetched from PTB

get_schema_path cached 

get_schema_path(version: str) -> str

Resolve a DCC schema version to a local XSD file path.

Uses dcc_json_toolkit to download (on first use) and cache the released XSD schema for the given version, returning the path to the locally cached dcc.xsd. Results are memoised so each version is fetched at most once.

Parameters:
  • version (str) –

    the plain version string, e.g. "3.3.0"
Returns:
  • str –

    the path to the locally cached XSD schema file
Raises:
  • SchemaDownloadError –

    if the schema could not be downloaded from PTB