space_packet_parser.xtce.validation
===================================

.. py:module:: space_packet_parser.xtce.validation

.. autoapi-nested-parse::

   XTCE document validation classes and utilities.



Attributes
----------

.. autoapisummary::

   space_packet_parser.xtce.validation.logger


Exceptions
----------

.. autoapisummary::

   space_packet_parser.xtce.validation.XtceValidationError


Classes
-------

.. autoapisummary::

   space_packet_parser.xtce.validation.ValidationLevel
   space_packet_parser.xtce.validation.ValidationError
   space_packet_parser.xtce.validation.ValidationResult


Functions
---------

.. autoapisummary::

   space_packet_parser.xtce.validation._get_cache_dir
   space_packet_parser.xtce.validation._get_cache_path
   space_packet_parser.xtce.validation._read_from_cache
   space_packet_parser.xtce.validation._write_to_cache
   space_packet_parser.xtce.validation._fix_known_schema_issues
   space_packet_parser.xtce.validation._load_schema
   space_packet_parser.xtce.validation._find_schema_url
   space_packet_parser.xtce.validation._validate_xtce_schema
   space_packet_parser.xtce.validation._validate_xtce_structure
   space_packet_parser.xtce.validation.validate_xtce


Module Contents
---------------

.. py:data:: logger

.. py:class:: ValidationLevel(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Validation levels for XTCE documents.


   .. py:attribute:: SCHEMA
      :value: 'schema'



   .. py:attribute:: STRUCTURE
      :value: 'structure'



   .. py:attribute:: ALL
      :value: 'all'



.. py:class:: ValidationError

   Represents a validation error or warning.


   .. py:attribute:: message
      :type:  str


   .. py:attribute:: error_code
      :type:  str


   .. py:attribute:: xpath_location
      :type:  str | None
      :value: None



   .. py:attribute:: line_number
      :type:  int | None
      :value: None



   .. py:attribute:: column_number
      :type:  int | None
      :value: None



   .. py:attribute:: context
      :type:  dict[str, Any] | None


   .. py:method:: __str__() -> str

      String representation of validation error.



.. py:class:: ValidationResult

   Results of XTCE document validation.


   .. py:attribute:: valid
      :type:  bool


   .. py:attribute:: validation_level
      :type:  ValidationLevel


   .. py:attribute:: errors
      :type:  list[ValidationError]
      :value: []



   .. py:attribute:: schema_version
      :type:  str | None
      :value: None



   .. py:attribute:: schema_location
      :type:  str | None
      :value: None



   .. py:attribute:: validation_time_ms
      :type:  float | None
      :value: None



   .. py:method:: __bool__()


   .. py:method:: add_error(message: str, error_code: str, xpath_location: str | None = None, line_number: int | None = None, context: dict[str, Any] | None = None)

      Add a validation error.



   .. py:method:: __str__() -> str

      String representation of validation result.



.. py:exception:: XtceValidationError(message: str, validation_result: ValidationResult | None = None)

   Bases: :py:obj:`Exception`


   Exception raised during XTCE validation.


   .. py:attribute:: validation_result
      :value: None



.. py:function:: _get_cache_dir() -> pathlib.Path

   Get cross-platform cache directory for space_packet_parser.


.. py:function:: _get_cache_path(schema_url: str) -> pathlib.Path

   Get cache file path for a schema URL using SHA-256 hash.


.. py:function:: _read_from_cache(cache_path: pathlib.Path) -> bytes | None

   Read cached schema content, return None if not found or unreadable.


.. py:function:: _write_to_cache(cache_path: pathlib.Path, content: bytes) -> None

   Write content to cache, creating directories as needed.


.. py:function:: _fix_known_schema_issues(schema_content: bytes) -> bytes

   Fix known issues in the official XTCE XSD schema.

   The official OMG XTCE schema references xml:base but doesn't declare
   the xml namespace, causing lxml validation to fail.

   :param schema_content: The schema content as bytes
   :type schema_content: bytes

   :returns: The fixed schema content as bytes
   :rtype: bytes


.. py:function:: _load_schema(schema_location: str | pathlib.Path, timeout: int = 30) -> tuple[lxml.etree.XMLSchema, str]

   Load XSD schema from URL or local path

   :param schema_location: URL or local path to the XSD schema document
   :type schema_location: Union[str, Path]
   :param timeout: Timeout in seconds for URL downloads
   :type timeout: int

   :returns: Parsed XMLSchema object and version string
   :rtype: tuple[ElementTree.XMLSchema, str]

   :raises XtceValidationError: If schema cannot be loaded or parsed


.. py:function:: _find_schema_url(xml_tree: lxml.etree.ElementTree) -> str

   Find the XSD location from the root attributes of the document

   :param xml_tree: XML tree of document being validated
   :type xml_tree: ElementTree.ElementTree

   :returns: **schema_location** -- URL of XSD
   :rtype: str


.. py:function:: _validate_xtce_schema(xml_tree: lxml.etree.ElementTree, local_xsd: str | pathlib.Path | None = None, timeout: int = 30) -> ValidationResult

   Validate XML document against XSD schema.

   :param xml_tree: XTCE XML tree object
   :type xml_tree: ElementTree.ElementTree
   :param local_xsd: Optional local schema location. If specified, schema references in root element (or lack thereof) are ignored.
   :type local_xsd: Optional[Union[str, Path]]
   :param timeout: Timeout in seconds for schema downloads
   :type timeout: int

   :returns: Truthy if result is valid, Falsy otherwise
   :rtype: ValidationResult


.. py:function:: _validate_xtce_structure(xml_tree: lxml.etree.ElementTree) -> ValidationResult

   Validate XTCE document structure and reference integrity.

   This performs structural validation beyond XSD schema validation,
   checking XTCE-specific business rules and reference integrity.

   :param xml_tree: Parsed XML tree of the XTCE document
   :type xml_tree: ElementTree.ElementTree

   :returns: Truthy if result is valid, Falsy otherwise
   :rtype: ValidationResult


.. py:function:: validate_xtce(xml_source: str | pathlib.Path | lxml.etree.ElementTree, level: str = 'all', timeout: int = 30, print_results: bool = True, raise_on_error: bool = True, local_xsd: str | pathlib.Path | None = None) -> ValidationResult

   Validate an XTCE XML document.

   This is the main validation entry point for XTCE documents. It can perform
   schema or structural validation based on the level parameter.

   :param xml_source: Path to XML file, XML string content, or ElementTree
   :type xml_source: Union[str, Path, ElementTree.ElementTree]
   :param level: Validation level: "schema", "structure", or "all". Default "all".
   :type level: str
   :param timeout: Timeout in seconds for schema downloads
   :type timeout: int
   :param print_results: Default True. Prints results before returning Truthy or Falsy result.
   :type print_results: bool
   :param raise_on_error: Default True. If False, returns a ValidationResult object with information about the validation results.
                          If True, raises an exception unless the ValidationResult reports valid.
   :type raise_on_error: bool
   :param local_xsd: Local path to an XSD for schema validation. If not provided and schema validation is requested,
                     XSD is retrieved from schema reference attribute in document root.
   :type local_xsd: Optional[str, Path]

   :returns: Truthy if result is valid, Falsy otherwise
   :rtype: ValidationResult