xtce-lib 0.1.0a1__py3-none-any.whl

xtce_lib/__init__.py

@@ -0,0 +1,33 @@
+"""xtce-lib."""
+
+import logging
+
+log = logging.getLogger(__name__)
+log.addHandler(logging.NullHandler())
+
+from . import generated, xtce
+from .common.validation import ValidationReport, XtceSchemaError, XtceSemanticError
+from .common.xtce_database import XtceDatabase
+from .common.xtce_file import XtceFile
+from .common.xtce_path import PathNode, XtcePath
+from .common.xtce_registry import ResolvedReference, XtceRegistry
+from .common.xtce_version import XtceVersion
+from .exceptions import DowngradePolicy, XtceDowngradeError, XtceUnsupportedError
+
+__all__ = [
+    "generated",
+    "xtce",
+    "ValidationReport",
+    "XtceSchemaError",
+    "XtceSemanticError",
+    "XtceDatabase",
+    "XtceFile",
+    "PathNode",
+    "XtcePath",
+    "ResolvedReference",
+    "XtceRegistry",
+    "XtceVersion",
+    "DowngradePolicy",
+    "XtceDowngradeError",
+    "XtceUnsupportedError",
+]

xtce_lib/common/__init__.py

@@ -0,0 +1 @@
+"""XTCE common module."""

xtce_lib/common/validation.py

@@ -0,0 +1,71 @@
+"""Common validation utilities."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Generic, TypeVar
+
+from .xtce_path import XtcePath
+
+
+class BaseValidationError(ABC):
+    """Abstract base class for all validation errors."""
+
+    @abstractmethod
+    def format(self) -> str:
+        """Return a formatted string representation of the error."""
+        pass
+
+
+@dataclass(frozen=True)
+class XtceSchemaError(BaseValidationError):
+    """An XTCE schema validation error."""
+
+    line: int
+    message: str
+
+    def format(self) -> str:
+        """Return a formatted string representation of the error."""
+        return f"Line {self.line}: {self.message}"
+
+
+@dataclass(frozen=True)
+class XtceSemanticError(BaseValidationError):
+    """An XTCE semantic validation error."""
+
+    scope: XtcePath
+    message: str
+
+    def format(self) -> str:
+        """Return a formatted string representation of the error."""
+        return f"[{self.scope}] {self.message}"
+
+
+ErrorType = TypeVar("ErrorType", bound=BaseValidationError)
+
+
+@dataclass
+class ValidationReport(Generic[ErrorType]):
+    """A generic report for XTCE validation."""
+
+    title: str
+    errors: list[ErrorType] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        """True if the validation pass found no errors."""
+        return len(self.errors) == 0
+
+    def add_error(self, error: ErrorType) -> None:
+        """Append an error to the report."""
+        self.errors.append(error)
+
+    def summary(self) -> str:
+        """Generate a console-friendly report."""
+        if self.is_valid:
+            return f"{self.title}: PASSED"
+
+        lines = [f"{self.title}: FAILED with {len(self.errors)} errors"]
+        for err in self.errors:
+            lines.append(f"  {err.format()}")
+
+        return "\n".join(lines)

xtce_lib/common/xtce_database.py

@@ -0,0 +1,286 @@
+"""XTCE database object."""
+
+import itertools
+from pathlib import Path
+from typing import Any, Iterable, Self
+
+from pydantic import validate_call
+from xsdata.formats.dataclass.serializers import XmlSerializer
+from xsdata.formats.dataclass.serializers.config import SerializerConfig
+
+from xtce_lib.common.xtce_version import XtceVersion
+from xtce_lib.exceptions import DowngradePolicy
+from xtce_lib.xtce._type_aliases_ext import ReferenceableXtceObject
+from xtce_lib.xtce.command import CommandMetadata, MetaCommandRef
+from xtce_lib.xtce.common import Alias, AncillaryData
+from xtce_lib.xtce.enum import SystemType
+from xtce_lib.xtce.reference import ParameterRef
+from xtce_lib.xtce.space_system import Header, Service, SpaceSystem
+from xtce_lib.xtce.telemetry import TelemetryMetadata
+
+from .validation import ValidationReport, XtceSemanticError
+from .xtce_file import XtceFile
+from .xtce_path import XtcePath
+from .xtce_registry import XtceRegistry
+
+
+class XtceDatabase:
+    """An XTCE database."""
+
+    @validate_call
+    def __init__(self, name: str) -> None:
+        """Initialize a new XTCE database."""
+        self._root_system = SpaceSystem(name=name)
+        self._registry: XtceRegistry | None = None
+
+    @classmethod
+    @validate_call
+    def from_space_system(cls, space_system: SpaceSystem) -> Self:
+        """Create a new XTCE database from an existing SpaceSystem."""
+        # Bypass __init__
+        instance = cls.__new__(cls)
+        instance._root_system = space_system
+        instance._registry = None
+        return instance
+
+    # TODO maybe from_file(), not sure how to handle XtceFile vs XtceDatabase yet
+
+    # The below methods allow for accessing the properties of the root SpaceSystem
+    # directly from the database, makes for a slightly cleaner API
+
+    @property
+    def name(self) -> str:
+        """The name of the SpaceSystem."""
+        return self._root_system.name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        self._root_system.name = value
+
+    @property
+    def short_description(self) -> str | None:
+        """The short description of the SpaceSystem."""
+        return self._root_system.short_description
+
+    @short_description.setter
+    def short_description(self, value: str | None) -> None:
+        self._root_system.short_description = value
+
+    @property
+    def long_description(self) -> str | None:
+        """The long description of the SpaceSystem."""
+        return self._root_system.long_description
+
+    @long_description.setter
+    def long_description(self, value: str | None) -> None:
+        self._root_system.long_description = value
+
+    @property
+    def aliases(self) -> list[Alias]:
+        """The aliases of the SpaceSystem."""
+        return self._root_system.aliases
+
+    @aliases.setter
+    def aliases(self, value: list[Alias]) -> None:
+        self._root_system.aliases = value
+
+    @property
+    def ancillary_data(self) -> list[AncillaryData]:
+        """The ancillary data of the SpaceSystem."""
+        return self._root_system.ancillary_data
+
+    @ancillary_data.setter
+    def ancillary_data(self, value: list[AncillaryData]) -> None:
+        self._root_system.ancillary_data = value
+
+    @property
+    def header(self) -> Header | None:
+        """The header of the SpaceSystem."""
+        return self._root_system.header
+
+    @header.setter
+    def header(self, value: Header | None) -> None:
+        self._root_system.header = value
+
+    @property
+    def telemetry_metadata(self) -> TelemetryMetadata | None:
+        """The telemetry metadata of the SpaceSystem."""
+        return self._root_system.telemetry_metadata
+
+    @telemetry_metadata.setter
+    def telemetry_metadata(self, value: TelemetryMetadata | None) -> None:
+        self._root_system.telemetry_metadata = value
+
+    @property
+    def command_metadata(self) -> CommandMetadata | None:
+        """The command metadata of the SpaceSystem."""
+        return self._root_system.command_metadata
+
+    @command_metadata.setter
+    def command_metadata(self, value: CommandMetadata | None) -> None:
+        self._root_system.command_metadata = value
+
+    @property
+    def services(self) -> list[Service]:
+        """The services of the SpaceSystem."""
+        return self._root_system.services
+
+    @services.setter
+    def services(self, value: list[Service]) -> None:
+        self._root_system.services = value
+
+    @property
+    def space_systems(self) -> list[SpaceSystem]:
+        """The child SpaceSystems of the SpaceSystem."""
+        return self._root_system.space_systems
+
+    @space_systems.setter
+    def space_systems(self, value: list[SpaceSystem]) -> None:
+        self._root_system.space_systems = value
+
+    @property
+    def system_type(self) -> SystemType:
+        """The system type of the SpaceSystem."""
+        return self._root_system.system_type
+
+    @system_type.setter
+    def system_type(self, value: SystemType) -> None:
+        self._root_system.system_type = value
+
+    @property
+    def asset_type(self) -> str:
+        """The asset type of the SpaceSystem."""
+        return self._root_system.asset_type
+
+    @asset_type.setter
+    def asset_type(self, value: str) -> None:
+        self._root_system.asset_type = value
+
+    @property
+    def operational_status(self) -> str | None:
+        """The operational status of the SpaceSystem."""
+        return self._root_system.operational_status
+
+    @operational_status.setter
+    def operational_status(self, value: str | None) -> None:
+        self._root_system.operational_status = value
+
+    @property
+    def base(self) -> str | None:
+        """The base of the SpaceSystem."""
+        return self._root_system.base
+
+    @base.setter
+    def base(self, value: str | None) -> None:
+        self._root_system.base = value
+
+    @property
+    def root_system(self) -> SpaceSystem:
+        """The root SpaceSystem of the database."""
+        return self._root_system
+
+    @property
+    def registry(self) -> XtceRegistry:
+        """Get the registry of all XTCE objects in this database."""
+        if self._registry is None:
+            self._registry = XtceRegistry()
+            self._index_space_system(self.root_system, XtcePath("/"), self._registry)
+        return self._registry
+
+    def rebuild_registry(self) -> None:
+        """Force a rebuild of the registry."""
+        new_registry = XtceRegistry()
+        self._index_space_system(self.root_system, XtcePath("/"), new_registry)
+        self._registry = new_registry
+
+    def validate(self) -> ValidationReport[XtceSemanticError]:
+        """Perform semantic validation of this database."""
+        report = ValidationReport[XtceSemanticError](title="Semantic Validation")
+        self.rebuild_registry()  # Ensure registry is up to date before validation
+        self.root_system.validate_semantics(report, self.registry, XtcePath("/"))
+        return report
+
+    @validate_call
+    def to_file(
+        self,
+        path: Path,
+        xtce_version: XtceVersion,
+        *,
+        downgrade_policy: DowngradePolicy = DowngradePolicy.STRICT,
+        **kwargs: Any,
+    ) -> XtceFile:
+        """Write the database to an XTCE XML file.
+
+        Any keyword arguments override the default serializer configuration.
+        """
+        # Translate the SpaceSystem
+        space_system = self._root_system.to_xsdata(
+            version=xtce_version,
+            policy=downgrade_policy,
+        )
+
+        # Serialize to file
+        config_kwargs: dict[str, Any] = {
+            "indent": "    ",
+        }
+        config_kwargs.update(kwargs)
+        config = SerializerConfig(**config_kwargs)
+        serializer = XmlSerializer(config=config)
+
+        with path.open("w", encoding="utf-8") as f:
+            serializer.write(  # type: ignore[reportUnknownMemberType]
+                f,
+                space_system,
+                ns_map={"xtce": xtce_version.value.namespace},
+            )
+
+        return XtceFile(path)
+
+    def _index_space_system(
+        self,
+        space_system: SpaceSystem,
+        parent_path: XtcePath,
+        registry: XtceRegistry,
+    ) -> None:
+        """Recursively walk the SpaceSystem hierarchy and index all elements."""
+        current_path = parent_path / space_system.name
+        registry.register(current_path, space_system)
+
+        collections_to_index: list[Iterable[ReferenceableXtceObject] | None] = []
+
+        if space_system.command_metadata:
+            cmd = space_system.command_metadata
+            collections_to_index.extend(
+                [
+                    cmd.argument_types,
+                    [
+                        meta_command
+                        for meta_command in cmd.meta_commands
+                        if not isinstance(meta_command, MetaCommandRef)
+                    ],
+                ]
+            )
+
+        if space_system.telemetry_metadata:
+            tlm = space_system.telemetry_metadata
+            collections_to_index.extend(
+                [
+                    tlm.parameter_types,
+                    [
+                        parameter
+                        for parameter in tlm.parameters
+                        if not isinstance(parameter, ParameterRef)
+                    ],
+                    tlm.containers,
+                    tlm.message_set.messages if tlm.message_set else None,
+                ]
+            )
+
+        # Iterate through all objects and register in one pass
+        valid_collections = (c for c in collections_to_index if c)
+        for item in itertools.chain.from_iterable(valid_collections):
+            registry.register(current_path / item.name, item)
+
+        # Recurse into child SpaceSystems
+        for child in space_system.space_systems:
+            self._index_space_system(child, current_path, registry)

xtce_lib/common/xtce_file.py

@@ -0,0 +1,207 @@
+"""XTCE file object."""
+
+import importlib.resources
+import re
+import tempfile
+from importlib.abc import Traversable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from lxml import etree
+from xsdata.formats.dataclass.parsers import XmlParser
+
+from xtce_lib.xtce.space_system import SpaceSystem
+
+from .validation import ValidationReport, XtceSchemaError
+from .xtce_version import XtceVersion
+
+if TYPE_CHECKING:
+    from xtce_lib.generated.xtce_1_1.models import SpaceSystem as SpaceSystem11
+    from xtce_lib.generated.xtce_1_2.models import SpaceSystem as SpaceSystem12
+    from xtce_lib.generated.xtce_1_3.models import SpaceSystem as SpaceSystem13
+
+    from .xtce_database import XtceDatabase
+
+    AnySpaceSystem = SpaceSystem11 | SpaceSystem12 | SpaceSystem13
+else:
+    AnySpaceSystem = Any
+
+
+class XtceFile:
+    """XTCE file manager for parsing and validation."""
+
+    # TODO add unified model
+
+    # Cache at class level
+    _schema_cache: ClassVar[dict[XtceVersion, etree.XMLSchema]] = {}
+    _NAMESPACE_PATTERN: ClassVar[re.Pattern[str]] = re.compile(r"^\{([^}]+)\}")
+
+    def __init__(self, file_path: str | Path) -> None:
+        """Initialize the XTCE file object."""
+        self._file_path = Path(file_path).resolve()
+
+        self._namespace = self.get_namespace(self._file_path)
+        self._version = XtceVersion.from_namespace(self._namespace)
+        self._raw_model: AnySpaceSystem | None = None
+
+        self._schema_resource, self._xml_resource = self._get_xsd_resources()
+
+    @property
+    def file_path(self) -> Path:
+        """Get the XTCE file path."""
+        return self._file_path
+
+    @property
+    def namespace(self) -> str:
+        """Get the XML namespace of the XTCE file."""
+        return self._namespace
+
+    @property
+    def version(self) -> str:
+        """Get the XTCE version of the file."""
+        return self._version.value.version
+
+    @property
+    def database(self) -> "XtceDatabase":
+        """Get the XTCE database object for this file."""
+        if self._raw_model is None:
+            self.parse_raw()
+
+        from .xtce_database import XtceDatabase
+
+        return XtceDatabase.from_space_system(
+            SpaceSystem.from_xsdata(self._raw_model, self._version)
+        )
+
+    @property
+    def raw_model(self) -> Any:
+        """Get the raw parsed model of the XTCE file."""
+        if self._raw_model is None:
+            self.parse_raw()
+        return self._raw_model
+
+    @staticmethod
+    def get_namespace(file_path: str | Path) -> str:
+        """Extract the namespace from the file path.
+
+        Args:
+            file_path (str | Path): The path to the XTCE XML file.
+
+        Returns:
+            str: The namespace of the XTCE XML file.
+
+        Raises:
+            ValueError: If the XML file is invalid or if no namespace is found.
+
+        """
+        file_path = Path(file_path)
+        try:
+            for _, element in etree.iterparse(file_path, events=["start"]):
+                if isinstance(element.tag, str):
+                    match = XtceFile._NAMESPACE_PATTERN.match(element.tag)
+                    if match:
+                        return match.group(1)
+
+        except etree.XMLSyntaxError as e:
+            raise ValueError(f"Invalid XML file: {file_path}: {e}")
+
+        raise ValueError(f"No namespace found in XML file: {file_path}")
+
+    def validate(self) -> ValidationReport[XtceSchemaError]:
+        """Validate the XTCE file against its corresponding XSD schema.
+
+        Returns:
+            ValidationReport[XtceSchemaError]: The result of the validation.
+
+        Raises:
+            ValueError: If the XML file is invalid or if validation fails.
+
+        """
+        validator = self._get_validator()
+        report = ValidationReport[XtceSchemaError](title="XSD Validation")
+
+        try:
+            xml_doc = etree.parse(self._file_path)
+            is_valid = validator.validate(xml_doc)
+
+            if is_valid:
+                return report
+
+            for error in validator.error_log:
+                # Strip the namespace
+                clean_message = re.sub(r"\{(?:http|urn)[^}]+\}", "", error.message)
+
+                report.add_error(
+                    XtceSchemaError(line=error.line, message=clean_message)
+                )
+
+            return report
+
+        except etree.XMLSyntaxError as e:
+            # Catastrophic syntax error
+            report.add_error(XtceSchemaError(line=e.lineno or 0, message=str(e)))
+            return report
+
+    def parse_raw(self, strict: bool = False) -> None:
+        """Parse the XML file into the version-specific xsdata dataclasses.
+
+        Args:
+            strict: If True, validates the file against the schema before parsing.
+
+        Raises:
+            ValueError: If validation fails in strict mode or if parsing fails.
+
+        """
+        if strict:
+            result = self.validate()
+            if not result.is_valid:
+                raise ValueError(
+                    f"Cannot parse invalid XTCE file: {result.errors[0].message}"
+                )
+
+        # Import the correct generated module based on the XTCE version
+        module_path = f"xtce_lib.generated.{self._version.value.module_name}.models"
+        models_module = importlib.import_module(module_path)
+
+        # Parse XML into the SpaceSystem root class
+        root_class = getattr(models_module, "SpaceSystem")
+        parser = XmlParser()
+        self._raw_model = parser.parse(str(self._file_path), root_class)
+
+        # TODO catch exceptions?
+
+    def _get_validator(self) -> etree.XMLSchema:
+        """Get the XMLSchema validator for the XTCE version of this file."""
+        if self._version in self._schema_cache:
+            return self._schema_cache[self._version]
+
+        try:
+            # Write the XSD resources to a temporary directory so that relative paths
+            # like xml.xsd are resolved correctly
+            with tempfile.TemporaryDirectory() as temp_dir:
+                temp_path = Path(temp_dir)
+
+                schema_path = temp_path / self._schema_resource.name
+                xml_xsd_path = temp_path / self._xml_resource.name
+
+                schema_path.write_bytes(self._schema_resource.read_bytes())
+                xml_xsd_path.write_bytes(self._xml_resource.read_bytes())
+
+                schema_doc = etree.parse(schema_path)
+                xmlschema = etree.XMLSchema(schema_doc)
+
+                self.__class__._schema_cache[self._version] = xmlschema
+                return xmlschema
+
+        except etree.XMLSchemaParseError as e:
+            raise ValueError(
+                f"Failed to compile XSD schema for version {self._version}: {e}"
+            )
+
+    def _get_xsd_resources(self) -> tuple[Traversable, Traversable]:
+        """Get schema resources for the XTCE version of this file."""
+        files = importlib.resources.files("xtce_lib.xsd")
+        schema_file = files / self._version.value.xsd_name
+        xsd_file = files / "xml.xsd"
+
+        return schema_file, xsd_file