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).

SchematronReport dataclass 

SchematronReport(failed_assert)

Class to represent a report from a schematron validation.

SchematronValidationResult dataclass 

SchematronValidationResult(
    is_valid: bool, failed_assertions: list[SchematronReport] = None, successful_reports: list[SchematronReport] = None
)

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

SchematronValidator 

SchematronValidator(svrl_content: str)

Bases: Constructible, Validatable

Class to validate XML files against a schematron file.

Create a SchematronValidator. :param svrl_content: 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. :param schematron_path: the path to the schematron file :returns: the SchematronValidator

from_str classmethod 

from_str(schematron_content: str)

Create a SchematronValidator from a string. :param schematron_content: 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. @param tree: the etree.Element tree @return: the SchematronValidator

validate_file 

validate_file(xml_path: str) -> SchematronValidationResult

Validate an XML file against a schematron file. :param xml_path: the path to the XML file to validate :returns: the validation result

validate_str 

validate_str(xml_content: str) -> SchematronValidationResult

Validate an XML file against a schematron file. :param xml_content: the XML string to validate :returns: the validation result

validate_tree 

validate_tree(tree: etree.Element) -> SchematronValidationResult

Validate an XML file against a schematron file. :param tree: the XML tree to validate :returns: the validation result

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. @param xml_path: the path to the file

validate_str abstractmethod 

validate_str(xml_content: str)

Validate a string representation. @param xml_content: the string representation

validate_tree abstractmethod 

validate_tree(tree: etree.Element)

Validate a tree structure. @param tree: 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)

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. :param xmlschema_doc: the XML schema document :param parser: 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. :param schema_path: 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. :param schema_content: 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. :param tree: 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. :param version: 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. :param xml_path: the path to the XML file :return: the validation result

validate_str 

validate_str(xml_content: str) -> XsdValidationResult

Validate an XML file against an XSD schema. :param xml_content: the XML string to validate :return: the validation result

validate_tree 

validate_tree(tree: etree.Element) -> XsdValidationResult

Validate an XML tree against an XSD schema. :param tree: the XML tree to validate :return: the validation result

compile_schematron_to_svrl 

compile_schematron_to_svrl(schematron: str) -> str

Compile a schematron file to a svrl file. :param schematron: 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). :return: 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

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).

SchematronReport dataclass 

SchematronReport(failed_assert)

Class to represent a report from a schematron validation.

XmlError dataclass 

XmlError(log_error)

Class to represent an error that occurred during XML validation.

results

SchematronValidationResult dataclass 

SchematronValidationResult(
    is_valid: bool, failed_assertions: list[SchematronReport] = None, successful_reports: list[SchematronReport] = None
)

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

XsdValidationResult dataclass 

XsdValidationResult(is_valid: bool, errors: list[XmlError] = 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. :param svrl_content: 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. :param schematron_path: the path to the schematron file :returns: the SchematronValidator

from_str classmethod 

from_str(schematron_content: str)

Create a SchematronValidator from a string. :param schematron_content: 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. @param tree: the etree.Element tree @return: the SchematronValidator

validate_file 

validate_file(xml_path: str) -> SchematronValidationResult

Validate an XML file against a schematron file. :param xml_path: the path to the XML file to validate :returns: the validation result

validate_str 

validate_str(xml_content: str) -> SchematronValidationResult

Validate an XML file against a schematron file. :param xml_content: the XML string to validate :returns: the validation result

validate_tree 

validate_tree(tree: etree.Element) -> SchematronValidationResult

Validate an XML file against a schematron file. :param tree: the XML tree to validate :returns: the validation result

compile_schematron_to_svrl 

compile_schematron_to_svrl(schematron: str) -> str

Compile a schematron file to a svrl file. :param schematron: the schematron content to compile

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. @param xml_path: the path to the file

validate_str abstractmethod 

validate_str(xml_content: str)

Validate a string representation. @param xml_content: the string representation

validate_tree abstractmethod 

validate_tree(tree: etree.Element)

Validate a tree structure. @param tree: 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. :param xmlschema_doc: the XML schema document :param parser: 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. :param schema_path: 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. :param schema_content: 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. :param tree: 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. :param version: 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. :param xml_path: the path to the XML file :return: the validation result

validate_str 

validate_str(xml_content: str) -> XsdValidationResult

Validate an XML file against an XSD schema. :param xml_content: the XML string to validate :return: the validation result

validate_tree 

validate_tree(tree: etree.Element) -> XsdValidationResult

Validate an XML tree against an XSD schema. :param tree: the XML tree to validate :return: the validation result

detect_schema_version 

detect_schema_version(tree: etree.Element) -> str

Detect the schema version of an XML file. :param tree: the DCC XML tree :return: 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). :return: 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.

:param version: the plain version string, e.g. "3.3.0" :return: the path to the locally cached XSD schema file :raises SchemaDownloadError: if the schema could not be downloaded from PTB