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

pysdmx/model/dataflow.py

@@ -35,15 +35,39 @@ class Role(str, Enum):
     ATTRIBUTE = "A"
     """The component provides descriptive information about the data."""
 
+    def __str__(self) -> str:
+        """Return the role as a string."""
+        return self.name.capitalize()
+
+    def __repr__(self) -> str:
+        """Role String representation."""
+        return f"{self.__class__.__name__}.{self._name_}"
+
 
-class ArrayBoundaries(Struct, frozen=True):
+class ArrayBoundaries(Struct, frozen=True, repr_omit_defaults=True):
     """The minimum and maximum number of items in the SDMX array."""
 
     min_size: int = 0
     max_size: Optional[int] = None
 
-
-class Component(Struct, frozen=True, omit_defaults=True):
+    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)}"
+
+    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)})"
+
+
+class Component(
+    Struct, frozen=True, omit_defaults=True, repr_omit_defaults=True
+):
     """A component of a dataset (aka **variable**), such the frequency.
 
     Concepts are used to **describe the relevant characteristics** of a
@@ -98,11 +122,12 @@ class Component(Struct, frozen=True, omit_defaults=True):
         description: Additional descriptive information about the component.
         local_codes: The expected local values for the component (e.g. currency
             codes).
-        attachment_level: The attachement level (if role = A only).
+        attachment_level: The attachment level (if role = A only).
             Attributes can be attached at different levels such as
             D (for dataset-level attributes), O (for observation-level
             attributes) or a combination of dimension IDs, separated by
             commas, for series- and group-level attributes).
+            A post_init check makes this attribute mandatory for attributes.
         array_def: Any additional constraints for array types.
     """
 
@@ -129,6 +154,12 @@ class Component(Struct, frozen=True, omit_defaults=True):
                     "only allowed for attribute components"
                 ),
             )
+        if self.role == Role.ATTRIBUTE and self.attachment_level is None:
+            raise Invalid(
+                "Validation Error",
+                "The attachment_level field is mandatory "
+                "for attribute components",
+            )
 
     @property
     def dtype(self) -> DataType:
@@ -186,16 +217,18 @@ class Component(Struct, frozen=True, omit_defaults=True):
             return None
 
     def __str__(self) -> str:
-        """Returns a human-friendly description."""
-        out = []
-        for k in self.__annotations__:
-            v = self.__getattribute__(k)
-            if v:
-                if k == "concept":
-                    out.append(f"{k}=({str(v)})")
-                else:
-                    out.append(f"{k}={str(v)}")
-        return ", ".join(out)
+        """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)})"
 
 
 class Components(UserList[Component]):
@@ -313,8 +346,21 @@ class Components(UserList[Component]):
                     f"There is already a component with ID: {fld.id}",
                 )
 
+    def __str__(self) -> str:
+        """Custom string representation without the class name."""
+        return f"data: {len(self)} components"
+
+    def __repr__(self) -> str:
+        """Custom __repr__ that omits empty sequences."""
+        attrs = []
+        for attr, value in self.__dict__.items():
+            attrs.append(f"{attr}={repr(value)}")
+        return f"{self.__class__.__name__}({', '.join(attrs)})"
 
-class DataflowInfo(Struct, frozen=True, omit_defaults=True):
+
+class DataflowInfo(
+    Struct, frozen=True, omit_defaults=True, repr_omit_defaults=True
+):
     """Extended information about a dataflow.
 
     The information includes:
@@ -355,16 +401,32 @@ class DataflowInfo(Struct, frozen=True, omit_defaults=True):
     dsd_ref: Optional[str] = None
 
     def __str__(self) -> str:
-        """Returns a human-friendly description."""
-        out = []
-        for k in self.__annotations__:
-            v = self.__getattribute__(k)
-            if v:
-                out.append(f"{k}={v}")
-        return ", ".join(out)
-
-
-class Schema(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 Schema(Struct, frozen=True, omit_defaults=True, repr_omit_defaults=True):
     """The allowed content within a certain context.
 
     This is the equivalent to the result of a schema query in the
@@ -403,13 +465,32 @@ class Schema(Struct, frozen=True, omit_defaults=True):
     generated: datetime = datetime.now(timezone.utc)
 
     def __str__(self) -> str:
-        """Returns a human-friendly description."""
-        out = []
-        for k in self.__annotations__:
-            v = self.__getattribute__(k)
-            if v:
-                out.append(f"{k}={v}")
-        return ", ".join(out)
+        """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 the value is a list of artefacts, we can summarize it
+                if attr == "artefacts":
+                    class_name = "Artefact"
+                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)})"
 
     @property
     def short_urn(self) -> str:
@@ -442,9 +523,12 @@ class DataStructureDefinition(MaintainableArtefact, frozen=True, kw_only=True):
         valid_from: The date from which the data structure is valid.
         valid_to: The date until which the data structure is valid.
         version: The version of the data structure.
+        evolving_structure: Whether new dimensions may be added under a
+            minor version update.
     """
 
     components: Components
+    evolving_structure: bool = False
 
     def __extract_artefacts(self) -> Sequence[str]:
         """Extract the artefacts used to generate the schema."""
@@ -492,7 +576,7 @@ class Dataflow(
 ):
     """A flow of data that providers will provide."""
 
-    structure: Optional[str] = None
+    structure: Optional[Union[DataStructureDefinition, str]] = None
 
 
 class ProvisionAgreement(

pysdmx/model/dataset.py

@@ -10,9 +10,15 @@ from pysdmx.model import Schema
 
 
 class ActionType(Enum):
-    """ActionType enumeration.
+    """Enumeration that defines the Dataset Action.
+
+    Arguments:
+        Append: Append data to an existing dataset.
+        Replace: Replace the existing dataset with new data.
+        Delete: Delete the data provided from the data source.
+        Information: Provide information about the dataset
+          without modifying it.
 
-    Enumeration that withholds the Action type for writing purposes.
     """
 
     Append = "Append"
@@ -20,8 +26,16 @@ class ActionType(Enum):
     Delete = "Delete"
     Information = "Information"
 
+    def __str__(self) -> str:
+        """Return the action as a string."""
+        return self.name.capitalize()
+
+    def __repr__(self) -> str:
+        """Action String representation."""
+        return f"{self.__class__.__name__}.{self._name_}"
 
-class SeriesInfo(Struct, frozen=True):
+
+class SeriesInfo(Struct, frozen=True, repr_omit_defaults=True):
     """A group of related data, such as a time series, or a case series.
 
     Attributes:
@@ -44,17 +58,41 @@ class SeriesInfo(Struct, frozen=True):
     is_active: bool = True
 
     def __str__(self) -> str:
-        """Returns a human-friendly description."""
-        out = []
-        for k in self.__annotations__:
-            v = self.__getattribute__(k)
-            if v:
-                out.append(f"{k}={v}")
-        return ", ".join(out)
-
-
-class Dataset(Struct, frozen=False, kw_only=True):
-    """Core Dataset class."""
+        """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)})"
+
+
+class Dataset(Struct, frozen=False, repr_omit_defaults=True, kw_only=True):
+    """An organised collection of data.
+
+    It includes metadata such as the structure of the dataset, attributes,
+    action type, reporting periods and publication details.
+
+    Args:
+        structure: The structure referenced from a dataset,
+          which can be a string (short_urn) or a Schema object.
+        attributes: dictionary of attributes at dataset level, with its values.
+        action: Defines the :class:`Action <pysdmx.model.dataset.ActionType>`
+          of the dataset, default is ActionType.Information.
+        reporting_begin: The start date for reporting, if applicable.
+        reporting_end: The end date for reporting, if applicable.
+        data_extraction_date: The date when the data was extracted.
+        valid_from: The start date for the validity of the dataset.
+        valid_to: The end date for the validity of the dataset.
+        publication_year: The year of publication of the dataset.
+        publication_period: The period of publication of the dataset.
+        set_id: An optional identifier for the dataset.
+    """
 
     structure: Union[str, Schema]
     attributes: Dict[str, Any] = {}
@@ -79,3 +117,17 @@ class Dataset(Struct, frozen=False, kw_only=True):
             return self.structure
         else:
             return self.structure.short_urn
+
+    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)}"
+
+    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/gds.py

@@ -0,0 +1,161 @@
+"""Models for GDS data.
+
+This module defines classes for representing GDS-specific data,
+such as agencies, in the SDMX data model.
+"""
+
+from typing import List, Optional, Sequence, Union
+
+from msgspec import Struct
+
+from pysdmx.model.__base import MaintainableArtefact
+from pysdmx.util import parse_maintainable_urn
+
+
+class GdsBase(Struct, repr_omit_defaults=True, frozen=True):
+    """Base class for all GDS models with a custom __str__ method."""
+
+    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__
+                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 GdsEndpoint(GdsBase, frozen=True):
+    """Represents a GDS endpoint.
+
+    Attributes:
+        api_version: The API version of the endpoint.
+        url: The URL of the endpoint.
+        comments: Comments about the endpoint.
+        message_formats: List of message formats supported by the endpoint.
+        rest_resources: List of REST resources available at the endpoint.
+    """
+
+    api_version: str
+    url: str
+    comments: str
+    message_formats: List[str]
+    rest_resources: List[str]
+
+
+class GdsServiceReference(GdsBase, frozen=True):
+    """Represents a GDS service reference.
+
+    Attributes:
+        id: The ID of the service reference.
+        name: The name of the service reference.
+        urn: The URN of the service reference.
+        service: The service associated with the reference.
+        description: An optional description of the service reference.
+    """
+
+    id: str
+    name: str
+    urn: str
+    service: str
+    description: Optional[str] = None
+
+    @property
+    def short_urn(self) -> str:
+        """Returns a short URN for the ServiceReference."""
+        return parse_maintainable_urn(self.service).__str__()
+
+
+class GdsService(GdsBase, MaintainableArtefact, frozen=True, kw_only=True):
+    """Represents a GDS service.
+
+    Attributes:
+        agency: The AgencyID of the service's owner.
+        base: The base URL of the service.
+        endpoints: List of GDS endpoints available at the service.
+        authentication: Optional authentication method for the service.
+    """
+
+    base: str
+    endpoints: List[GdsEndpoint]
+    authentication: Optional[str] = None
+
+
+class GdsCatalog(GdsBase, MaintainableArtefact, frozen=True, kw_only=True):
+    """Represents a GDS catalog.
+
+    Attributes:
+        agency: The AgencyID of the catalog's owner.
+        id: The ID of the catalog.
+        urn: The URN of the catalog.
+        version: The version of the catalog.
+        services: Optional list of GdsService or GdsServiceReference,
+        depending on the references parameter, that are associated with the
+        catalog.
+        endpoints: List of GDS endpoints available at the catalog.
+    """
+
+    services: Optional[List[Union[GdsService, GdsServiceReference]]] = None
+    endpoints: Optional[List[GdsEndpoint]] = None
+
+
+class GdsSdmxApi(GdsBase, frozen=True):
+    """Represents an SDMX API version.
+
+    Attributes:
+        release: The release version of the SDMX API.
+        description: A description of the release.
+    """
+
+    release: str
+    description: str
+
+
+class ResolverResult(
+    GdsBase, frozen=True, rename={"query_response_status_code": "status_code"}
+):
+    """Represents a single resolver result.
+
+    Attributes:
+        api_version: The API version of the resolver result.
+        query: The query URL for the resource.
+        status_code: The HTTP response code for the query.
+    """
+
+    api_version: str
+    query: str
+    status_code: int
+
+
+class GdsUrnResolver(GdsBase, frozen=True):
+    """Represents the response for a URN resolver query.
+
+    Attributes:
+        agency: The agency maintaining the resource.
+        resource_id: The ID of the resource.
+        version: The version of the resource.
+        sdmx_type: The type of SDMX resource.
+        resolver_results: A list of resolver results.
+    """
+
+    agency: str
+    resource_id: str
+    version: str
+    sdmx_type: str
+    resolver_results: List[ResolverResult]

pysdmx/model/map.py

@@ -10,7 +10,43 @@ from pysdmx.model.__base import MaintainableArtefact
 from pysdmx.util._date_pattern_map import convert_dpm
 
 
-class DatePatternMap(Struct, frozen=True, omit_defaults=True, tag=True):
+class _BaseMap(
+    Struct,
+    frozen=True,
+    omit_defaults=True,
+    repr_omit_defaults=True,
+):
+    """Base class for mapping definitions."""
+
+    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 value:
+                    class_name = value[0].__class__.__name__
+                    value = f"{len(value)} {class_name.lower()}s"
+                # redundant if check for python 3.9 and lower versions cov
+                if 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)})"
+
+
+class DatePatternMap(_BaseMap, frozen=True, omit_defaults=True, tag=True):
     """A mapping based on a date pattern.
 
     Examples:
@@ -41,6 +77,8 @@ class DatePatternMap(Struct, frozen=True, omit_defaults=True, tag=True):
             the target structure (e.g. `FREQ`). In this case, the input date
             can be converted to a different format, depending on the
             frequency of the converted data.
+        resolvePeriod: The point in time to resolve to when mapping from low
+            frequency to higher frequency periods.
     """
 
     source: str
@@ -50,6 +88,9 @@ class DatePatternMap(Struct, frozen=True, omit_defaults=True, tag=True):
     id: Optional[str] = None
     locale: str = "en"
     pattern_type: Literal["fixed", "variable"] = "fixed"
+    resolvePeriod: Optional[
+        Literal["startOfPeriod", "endOfPeriod", "midPeriod"]
+    ] = None
 
     @property
     def py_pattern(self) -> str:
@@ -57,7 +98,7 @@ class DatePatternMap(Struct, frozen=True, omit_defaults=True, tag=True):
         return convert_dpm(self.pattern)
 
 
-class FixedValueMap(Struct, frozen=True, omit_defaults=True, tag=True):
+class FixedValueMap(_BaseMap, frozen=True, omit_defaults=True, tag=True):
     """Set a component to a fixed value.
 
     Examples:
@@ -81,7 +122,9 @@ class FixedValueMap(Struct, frozen=True, omit_defaults=True, tag=True):
     located_in: Literal["source", "target"] = "target"
 
 
-class ImplicitComponentMap(Struct, frozen=True, omit_defaults=True, tag=True):
+class ImplicitComponentMap(
+    _BaseMap, frozen=True, omit_defaults=True, tag=True
+):
     """A mapping where the value in the source is copied to the target.
 
     Examples:
@@ -103,7 +146,7 @@ class ImplicitComponentMap(Struct, frozen=True, omit_defaults=True, tag=True):
     target: str
 
 
-class MultiValueMap(Struct, frozen=True, omit_defaults=True, kw_only=True):
+class MultiValueMap(_BaseMap, frozen=True, omit_defaults=True, kw_only=True):
     """Provides the values for a mapping between one or more components.
 
     Examples:
@@ -158,7 +201,7 @@ class MultiValueMap(Struct, frozen=True, omit_defaults=True, kw_only=True):
         return tuple(out)
 
 
-class ValueMap(Struct, frozen=True, omit_defaults=True, kw_only=True):
+class ValueMap(_BaseMap, frozen=True, omit_defaults=True, kw_only=True):
     """Maps the values of two components together.
 
     Examples:
@@ -232,7 +275,7 @@ class MultiRepresentationMap(
         return len(self.maps)
 
 
-class MultiComponentMap(Struct, frozen=True, omit_defaults=True, tag=True):
+class MultiComponentMap(_BaseMap, frozen=True, omit_defaults=True, tag=True):
     """Maps one or more source components to one or more target components.
 
     Examples:
@@ -293,7 +336,7 @@ class RepresentationMap(MaintainableArtefact, frozen=True, omit_defaults=True):
         return len(self.maps)
 
 
-class ComponentMap(Struct, frozen=True, omit_defaults=True, tag=True):
+class ComponentMap(_BaseMap, frozen=True, omit_defaults=True, tag=True):
     """Maps a source component to a target component.
 
     Examples:
@@ -314,7 +357,7 @@ class ComponentMap(Struct, frozen=True, omit_defaults=True, tag=True):
 
     source: str
     target: str
-    values: RepresentationMap
+    values: Union[RepresentationMap, str]
 
 
 class StructureMap(MaintainableArtefact, frozen=True, omit_defaults=True):