pysdmx 1.3.0__py3-none-any.whl → 1.4.0rc1__py3-none-any.whl

pysdmx/model/message.py

@@ -19,22 +19,60 @@ from typing import Any, Dict, List, Optional, Sequence, Type, Union
 from msgspec import Struct
 
 from pysdmx.errors import Invalid, NotFound
-from pysdmx.model import (
-    AgencyScheme,
+from pysdmx.model.__base import ItemScheme, MaintainableArtefact, Organisation
+from pysdmx.model.category import Categorisation, CategoryScheme
+from pysdmx.model.code import Codelist, Hierarchy, HierarchyAssociation
+from pysdmx.model.concept import ConceptScheme
+from pysdmx.model.dataflow import (
+    Dataflow,
+    DataStructureDefinition,
+    ProvisionAgreement,
+)
+from pysdmx.model.dataset import ActionType, Dataset
+from pysdmx.model.map import (
+    MultiRepresentationMap,
+    RepresentationMap,
+    StructureMap,
+)
+from pysdmx.model.metadata import MetadataReport
+from pysdmx.model.organisation import AgencyScheme, DataProviderScheme
+from pysdmx.model.submission import SubmissionResult
+from pysdmx.model.vtl import (
+    CustomTypeScheme,
+    NamePersonalisationScheme,
     RulesetScheme,
     TransformationScheme,
     UserDefinedOperatorScheme,
+    VtlMappingScheme,
 )
-from pysdmx.model.__base import ItemScheme, Organisation
-from pysdmx.model.code import Codelist
-from pysdmx.model.concept import ConceptScheme
-from pysdmx.model.dataflow import Dataflow, DataStructureDefinition
-from pysdmx.model.dataset import ActionType, Dataset
-from pysdmx.model.submission import SubmissionResult
 
 
-class Header(Struct, kw_only=True):
-    """Header for the SDMX messages."""
+class Header(Struct, repr_omit_defaults=True, kw_only=True):
+    """Header for the SDMX messages.
+
+    Represents the Header of an SDMX message, containing metadata about the
+    message such as the sender, receiver, and other relevant information.
+
+    Attributes:
+        id: Unique identifier for the message. (default: generated UUID)
+        test: Indicates if the message is a test message. (default: False)
+        prepared: Timestamp when the message was prepared.
+          (default: current UTC time)
+        sender: Organisation that sent the message.
+          (default: Organisation with id "ZZZ")
+        receiver: Optional Organisation that received the message.
+          (default: None)
+        source: Optional source of the message. (default: None)
+        dataset_action: Optional action for the dataset
+          (only for SDMX Data messages). (default: None)
+        structure: Dimension at observation mapping
+          (dict with short URN as key and Dimension ID as value)
+          (only for SDMX Data Messages)
+          (Overridden by dimension_at_observation argument in writers).
+          (default: None)
+        dataset_id: DatasetID defined at SDMX-ML
+          (only for SDMX-ML Data messages). (default: None)
+    """
 
     id: str = str(uuid.uuid4())
     test: bool = False
@@ -46,53 +84,84 @@ class Header(Struct, kw_only=True):
     structure: Optional[Dict[str, str]] = None
     dataset_id: Optional[str] = None
 
+    def __post_init__(self) -> None:
+        """Header post-initialization."""
+        if isinstance(self.sender, str):
+            self.sender = Organisation(id=self.sender)
 
-class Message(Struct, frozen=True):
-    """Message class holds the content of SDMX Message.
+        if isinstance(self.receiver, str):
+            self.receiver = Organisation(id=self.receiver)
+
+    def __str__(self) -> str:
+        """Custom string representation without the class name."""
+        processed_output = []
+        for attr, value, *_ in self.__rich_repr__():  # type: ignore[misc]
+            processed_output.append(f"{attr}: {value}")
+        return f"{', '.join(processed_output)}"
+
+
+class StructureMessage(Struct, repr_omit_defaults=True, frozen=True):
+    """Message class holds the content of an SDMX Structure Message.
 
     Attributes:
-        structures: Sequence of structure objects (ItemScheme, Schema).
-           They represent the contents of a Structure Message.
-        data: Sequence of Dataset objects. They represent the contents of a
-           SDMX Data Message in any format.
-        submission: Sequence of SubmissionResult objects. They represent the
-              contents of a SDMX Submission Message.
+        header: The header of the SDMX message.
+        structures: Sequence of MaintainableArtefact objects.
+          They represent the contents of a Structure Message.
     """
 
     header: Optional[Header] = None
-    structures: Optional[
-        Sequence[
-            Union[
-                ItemScheme,
-                DataStructureDefinition,
-                Dataflow,
-            ]
-        ]
-    ] = None
-    data: Optional[Sequence[Dataset]] = None
-    submission: Optional[Sequence[SubmissionResult]] = None
+    structures: Optional[Sequence[MaintainableArtefact]] = None
 
     def __post_init__(self) -> None:
         """Checks if the content is valid."""
         if self.structures is not None:
             for obj_ in self.structures:
-                if not isinstance(
-                    obj_, (ItemScheme, DataStructureDefinition, Dataflow)
-                ):
+                if not isinstance(obj_, (MaintainableArtefact)):
                     raise Invalid(
                         f"Invalid structure: {type(obj_).__name__} ",
                         "Check the docs on structures.",
                     )
-        if self.data is not None:
-            for data_value in self.data:
-                if not isinstance(data_value, Dataset):
-                    raise Invalid(
-                        f"Invalid data type: "
-                        f"{type(data_value).__name__} "
-                        f"for Data Message, requires a Dataset object.",
-                        "Check the docs for the proper structure on data.",
+
+    def __str__(self) -> str:
+        """Custom string representation with detailed structure counts."""
+        processed_output = []
+        for attr, value, *_ in self.__rich_repr__():  # type: ignore[misc]
+            if attr in ["data", "structures"] and value:
+                # Count occurrences of each class in structures
+                class_counts: Dict[str, int] = {}
+                for obj in value:
+                    class_name = obj.__class__.__name__
+                    class_counts[class_name] = (
+                        class_counts.get(class_name, 0) + 1
                     )
 
+                # Format the counts
+                value = ", ".join(
+                    f"{count} {class_name.lower()}"
+                    for class_name, count in class_counts.items()
+                )
+
+            # Handle sequences and omit empty ones
+            if (
+                isinstance(value, Sequence)
+                and not isinstance(value, str)
+                and not value
+            ):
+                continue
+
+            processed_output.append(f"{attr}: {value}")
+        return f"{', '.join(processed_output)}"
+
+    def __repr__(self) -> str:
+        """Custom __repr__ that omits empty sequences."""
+        attrs = []
+        for attr, value, *_ in self.__rich_repr__():  # type: ignore[misc]
+            # Omit empty sequences
+            if isinstance(value, (list, tuple, set)) and not value:
+                continue
+            attrs.append(f"{attr}={repr(value)}")
+        return f"{self.__class__.__name__}({', '.join(attrs)})"
+
     def __get_elements(self, type_: Type[Any]) -> List[Any]:
         """Returns a list of elements of a specific type."""
         if self.structures is None:
@@ -105,6 +174,14 @@ class Message(Struct, frozen=True):
                 structures.append(element)
         return structures
 
+    def __get_enumerations(
+        self, type_: Type[Any], is_vl: bool = False
+    ) -> List[Any]:
+        """Returns a list of elements of a specific type."""
+        enums = self.__get_elements(type_)
+        t = "valuelist" if is_vl else "codelist"
+        return [e for e in enums if e.sdmx_type == t]
+
     def __get_single_structure(
         self,
         type_: Type[Union[ItemScheme, DataStructureDefinition, Dataflow]],
@@ -131,7 +208,7 @@ class Message(Struct, frozen=True):
 
     def get_codelists(self) -> List[Codelist]:
         """Returns the Codelists."""
-        return self.__get_elements(Codelist)
+        return self.__get_enumerations(Codelist, False)
 
     def get_concept_schemes(self) -> List[ConceptScheme]:
         """Returns the Concept Schemes."""
@@ -169,6 +246,123 @@ class Message(Struct, frozen=True):
         """Returns a specific Dataflow."""
         return self.__get_single_structure(Dataflow, short_urn)
 
+    def get_transformation_schemes(self) -> List[TransformationScheme]:
+        """Returns the TransformationSchemes."""
+        return self.__get_elements(TransformationScheme)
+
+    def get_user_defined_operator_schemes(
+        self,
+    ) -> List[UserDefinedOperatorScheme]:
+        """Returns the UserDefinedOperatorSchemes."""
+        return self.__get_elements(UserDefinedOperatorScheme)
+
+    def get_ruleset_schemes(self) -> List[RulesetScheme]:
+        """Returns the RulesetSchemes."""
+        return self.__get_elements(RulesetScheme)
+
+    def get_category_schemes(self) -> List[CategoryScheme]:
+        """Returns the CategorySchemes."""
+        return self.__get_elements(CategoryScheme)
+
+    def get_value_lists(self) -> List[Codelist]:
+        """Returns the Codelists."""
+        return self.__get_enumerations(Codelist, True)
+
+    def get_hierarchies(self) -> List[Hierarchy]:
+        """Returns the HierarchyCodelists."""
+        return self.__get_elements(Hierarchy)
+
+    def get_hierarchy_associations(self) -> List[HierarchyAssociation]:
+        """Returns the HierarchyAssociations."""
+        return self.__get_elements(HierarchyAssociation)
+
+    def get_data_provider_schemes(self) -> List[DataProviderScheme]:
+        """Returns the DataProviderSchemes."""
+        return self.__get_elements(DataProviderScheme)
+
+    def get_provision_agreements(self) -> List[ProvisionAgreement]:
+        """Returns the ProvisionAgreements."""
+        return self.__get_elements(ProvisionAgreement)
+
+    def get_structure_maps(self) -> List[StructureMap]:
+        """Returns the StructureMaps."""
+        return self.__get_elements(StructureMap)
+
+    def get_representation_maps(
+        self,
+    ) -> List[Union[MultiRepresentationMap, RepresentationMap]]:
+        """Returns the RepresentationMaps."""
+        out = []
+        out.extend(self.__get_elements(RepresentationMap))
+        out.extend(self.__get_elements(MultiRepresentationMap))
+        return out
+
+    def get_categorisations(self) -> List[Categorisation]:
+        """Returns the Categorisations."""
+        return self.__get_elements(Categorisation)
+
+    def get_custom_type_schemes(self) -> List[CustomTypeScheme]:
+        """Returns the CustomType Schemes."""
+        return self.__get_elements(CustomTypeScheme)
+
+    def get_vtl_mapping_schemes(self) -> List[VtlMappingScheme]:
+        """Returns the VTL Mapping Schemes."""
+        return self.__get_elements(VtlMappingScheme)
+
+    def get_name_personalisation_schemes(
+        self,
+    ) -> List[NamePersonalisationScheme]:
+        """Returns the NamePersonalisationSchemes."""
+        return self.__get_elements(NamePersonalisationScheme)
+
+
+class MetadataMessage(Struct, frozen=True):
+    """Message class holds the content of an SDMX Reference Metadata Message.
+
+    Attributes:
+        header: The header of the SDMX message.
+        reports: Sequence of metadata reports.
+    """
+
+    header: Optional[Header] = None
+    reports: Optional[Sequence[MetadataReport]] = None
+
+    def get_reports(self) -> Sequence[MetadataReport]:
+        """Returns the metadata reports."""
+        if self.reports:
+            return self.reports
+        else:
+            raise NotFound("No metadata reports werefound in the message.")
+
+
+class Message(StructureMessage, frozen=True):
+    """Message class holds the content of SDMX Message.
+
+    Attributes:
+        header: The header of the SDMX message.
+        structures: Sequence of MaintainableArtefact objects.
+        data: Sequence of Dataset objects. They represent the contents of a
+           SDMX Data Message in any format.
+        submission: Sequence of SubmissionResult objects. They represent the
+              contents of a SDMX Submission Message.
+    """
+
+    data: Optional[Sequence[Dataset]] = None
+    submission: Optional[Sequence[SubmissionResult]] = None
+
+    def __post_init__(self) -> None:
+        """Checks if the content is valid."""
+        super().__post_init__()
+        if self.data is not None:
+            for data_value in self.data:
+                if not isinstance(data_value, Dataset):
+                    raise Invalid(
+                        f"Invalid data type: "
+                        f"{type(data_value).__name__} "
+                        f"for Data Message, requires a Dataset object.",
+                        "Check the docs for the proper structure on data.",
+                    )
+
     def get_datasets(self) -> Sequence[Dataset]:
         """Returns the Datasets."""
         if self.data is not None:
@@ -188,17 +382,3 @@ class Message(Struct, frozen=True):
             f"No Dataset with Short URN {short_urn} found in data.",
             "Could not find the requested Dataset.",
         )
-
-    def get_transformation_schemes(self) -> List[TransformationScheme]:
-        """Returns the TransformationSchemes."""
-        return self.__get_elements(TransformationScheme)
-
-    def get_user_defined_operator_schemes(
-        self,
-    ) -> List[UserDefinedOperatorScheme]:
-        """Returns the UserDefinedOperatorSchemes."""
-        return self.__get_elements(UserDefinedOperatorScheme)
-
-    def get_ruleset_schemes(self) -> List[RulesetScheme]:
-        """Returns the RulesetSchemes."""
-        return self.__get_elements(RulesetScheme)

pysdmx/model/metadata.py

@@ -13,8 +13,14 @@ from typing import Any, Dict, Iterator, List, Optional, Sequence
 
 from msgspec import Struct
 
+from pysdmx.model.__base import Annotation, MaintainableArtefact
+from pysdmx.model.concept import Facets
+from pysdmx.model.dataset import ActionType
 
-class MetadataAttribute(Struct, frozen=True, omit_defaults=True):
+
+class MetadataAttribute(
+    Struct, frozen=True, omit_defaults=True, repr_omit_defaults=True
+):
     """An entry in a metadata report.
 
     An attribute is iterable, as it may contain other attributes.
@@ -29,40 +35,70 @@ class MetadataAttribute(Struct, frozen=True, omit_defaults=True):
     id: str
     value: Optional[Any] = None
     attributes: Sequence["MetadataAttribute"] = ()
+    annotations: Sequence[Annotation] = ()
+    format: Optional[Facets] = None
 
     def __iter__(self) -> Iterator["MetadataAttribute"]:
         """Return an iterator over the list of attributes."""
         yield from self.attributes
 
     def __str__(self) -> str:
-        """Returns a human-friendly description."""
-        return f"{self.id}: {self.value}"
-
-
-class MetadataReport(Struct, frozen=True, omit_defaults=True):
+        """Custom string representation without the class name."""
+        processed_output = []
+        for attr, value, *_ in self.__rich_repr__():  # type: ignore[misc]
+            # str is taken as a Sequence, so we need to check it's not a str
+            if isinstance(value, Sequence) and not isinstance(value, str):
+                # Handle non-empty lists
+                if not value:
+                    continue
+                class_name = value[0].__class__.__name__
+                value = f"{len(value)} {class_name.lower()}s"
+
+            processed_output.append(f"{attr}: {value}")
+        return f"{', '.join(processed_output)}"
+
+    def __repr__(self) -> str:
+        """Custom __repr__ that omits empty sequences."""
+        attrs = []
+        for attr, value, *_ in self.__rich_repr__():  # type: ignore[misc]
+            # Omit empty sequences
+            if isinstance(value, (list, tuple, set)) and not value:
+                continue
+            attrs.append(f"{attr}={repr(value)}")
+        return f"{self.__class__.__name__}({', '.join(attrs)})"
+
+
+class MetadataReport(MaintainableArtefact, frozen=True, omit_defaults=True):
     """An organized collection of metadata.
 
     A metadata report is iterable and it is also possible to directly
     retrieve an attribute using its ID.
 
     Attributes:
-        id: The identifier of the report (e.g. DTI_MACRO).
-        name: The name of the report (e.g. "Configuration metadata for
-            the MACRO dataflow").
         metadataflow: The URN of the dataflow for which the report
             belongs.
         targets: The URN(s) of SDMX artefact(s) to which the report relates.
         attributes: The list of metadata attributes included in the report.
             Attributes may contain other attributes.
-        version: The version of the metadata report.
+        metadataProvisionAgreement: reference to a metadata provision
+            agreement
+        publicationPeriod: The reporting period to which the metadata report
+            relates
+        publicationYear: The year when the report was published
+        reportingBegin: The oldest period to which the report relates.
+        reportingEnd: The most recent period to which the report relates.
+        action: The action to be performed by the receiver.
     """
 
-    id: str
-    name: str
-    metadataflow: str
-    targets: Sequence[str]
-    attributes: Sequence[MetadataAttribute]
-    version: str = "1.0"
+    metadataflow: str = ""
+    targets: Sequence[str] = ()
+    attributes: Sequence[MetadataAttribute] = ()
+    metadataProvisionAgreement: Optional[str] = None
+    publicationPeriod: Optional[str] = None
+    publicationYear: Optional[str] = None
+    reportingBegin: Optional[str] = None
+    reportingEnd: Optional[str] = None
+    action: Optional[ActionType] = None
 
     def __iter__(self) -> Iterator[MetadataAttribute]:
         """Return an iterator over the list of report attributes."""
@@ -99,6 +135,33 @@ class MetadataReport(Struct, frozen=True, omit_defaults=True):
                 return out[0]
         return None
 
+    def __str__(self) -> str:
+        """Custom string representation without the class name."""
+        processed_output = []
+        for attr, value, *_ in self.__rich_repr__():  # type: ignore[misc]
+            # str is taken as a Sequence, so we need to check it's not a str
+            if isinstance(value, Sequence) and not isinstance(value, str):
+                # Handle non-empty lists
+                if not value:
+                    continue
+                class_name = value[0].__class__.__name__
+                if class_name == "MetadataAttribute":
+                    class_name = "Metadata Attribute"
+                value = f"{len(value)} {class_name.lower()}s"
+
+            processed_output.append(f"{attr}: {value}")
+        return f"{', '.join(processed_output)}"
+
+    def __repr__(self) -> str:
+        """Custom __repr__ that omits empty sequences."""
+        attrs = []
+        for attr, value, *_ in self.__rich_repr__():  # type: ignore[misc]
+            # Omit empty sequences
+            if isinstance(value, (list, tuple, set)) and not value:
+                continue
+            attrs.append(f"{attr}={repr(value)}")
+        return f"{self.__class__.__name__}({', '.join(attrs)})"
+
 
 def merge_attributes(
     attrs: Sequence[MetadataAttribute],

pysdmx/model/submission.py

@@ -11,10 +11,15 @@ class SubmissionResult(Struct, frozen=True):
     status: str
 
     def __str__(self) -> str:
-        """Return a string representation of the SubmissionResult."""
-        return (
-            f"<Submission Result - "
-            f"Action: {self.action} - "
-            f"Short URN: {self.short_urn} - "
-            f"Status: {self.status}>"
-        )
+        """Custom string representation without the class name."""
+        processed_output = []
+        for attr, value, *_ in self.__rich_repr__():  # type: ignore[misc]
+            processed_output.append(f"{attr}: {value}")
+        return f"{', '.join(processed_output)}"
+
+    def __repr__(self) -> str:
+        """Custom __repr__ that omits empty sequences."""
+        attrs = []
+        for attr, value, *_ in self.__rich_repr__():  # type: ignore[misc]
+            attrs.append(f"{attr}={repr(value)}")
+        return f"{self.__class__.__name__}({', '.join(attrs)})"

pysdmx/model/vtl.py

@@ -6,7 +6,14 @@ from typing import Literal, Optional, Sequence, Union
 from msgspec import Struct
 
 from pysdmx.errors import Invalid
-from pysdmx.model.__base import DataflowRef, Item, ItemScheme, Reference
+from pysdmx.model import Codelist, Concept
+from pysdmx.model.__base import (
+    DataflowRef,
+    Item,
+    ItemReference,
+    ItemScheme,
+    Reference,
+)
 from pysdmx.model.dataflow import Dataflow
 
 
@@ -92,14 +99,14 @@ class VtlDataflowMapping(
 class VtlCodelistMapping(VtlMapping, frozen=True, omit_defaults=True):
     """Single mapping with a codelist."""
 
-    codelist: str = ""
+    codelist: Union[str, Codelist, Reference] = ""
     codelist_alias: str = ""
 
 
 class VtlConceptMapping(VtlMapping, frozen=True, omit_defaults=True):
     """Single mapping with a concept."""
 
-    concept: str = ""
+    concept: Union[str, Concept, ItemReference] = ""
     concept_alias: str = ""
 
 
@@ -141,30 +148,38 @@ class VtlScheme(ItemScheme, frozen=True, omit_defaults=True):
 class CustomTypeScheme(VtlScheme, frozen=True, omit_defaults=True):
     """A collection of custom specifications for VTL basic scalar types."""
 
+    items: Sequence[CustomType] = ()
+
 
 class NamePersonalisationScheme(VtlScheme, frozen=True, omit_defaults=True):
     """A collection of name personalisations."""
 
+    items: Sequence[NamePersonalisation] = ()
+
+
+class VtlMappingScheme(ItemScheme, frozen=True, omit_defaults=True):
+    """A collection of VTL mappings."""
+
 
 class RulesetScheme(VtlScheme, frozen=True, omit_defaults=True):
     """A collection of rulesets."""
 
-    vtl_mapping_scheme: Optional[str] = None
+    vtl_mapping_scheme: Optional[Union[str, VtlMappingScheme, Reference]] = (
+        None
+    )
     items: Sequence[Ruleset] = ()
 
 
 class UserDefinedOperatorScheme(VtlScheme, frozen=True, omit_defaults=True):
     """A collection of user-defined operators."""
 
-    vtl_mapping_scheme: Optional[str] = None
-    ruleset_schemes: Sequence[Union[str, Reference]] = ()
+    vtl_mapping_scheme: Optional[Union[str, VtlMappingScheme, Reference]] = (
+        None
+    )
+    ruleset_schemes: Sequence[Union[str, RulesetScheme, Reference]] = ()
     items: Sequence[UserDefinedOperator] = ()
 
 
-class VtlMappingScheme(ItemScheme, frozen=True, omit_defaults=True):
-    """A collection of VTL mappings."""
-
-
 class TransformationScheme(VtlScheme, frozen=True, omit_defaults=True):
     """VTL Transformation Scheme class.
 
@@ -195,9 +210,11 @@ class TransformationScheme(VtlScheme, frozen=True, omit_defaults=True):
           The user-defined operator schemes.
     """
 
-    vtl_mapping_scheme: Optional[VtlMappingScheme] = None
-    name_personalisation_scheme: Optional[NamePersonalisationScheme] = None
-    custom_type_scheme: Optional[CustomTypeScheme] = None
+    vtl_mapping_scheme: Optional[Union[VtlMappingScheme, Reference]] = None
+    name_personalisation_scheme: Optional[
+        Union[NamePersonalisationScheme, Reference]
+    ] = None
+    custom_type_scheme: Optional[Union[CustomTypeScheme, Reference]] = None
     ruleset_schemes: Sequence[Union[RulesetScheme, Reference]] = ()
     user_defined_operator_schemes: Sequence[
         Union[UserDefinedOperatorScheme, Reference]

pysdmx/toolkit/__init__.py

@@ -1 +1 @@
-"""VTL toolkit for PySDMX."""
+"""Toolkit for PySDMX."""