pandaSDMX-1.8.1.tar.gz

"""SDMX Information Model (SDMX-IM). This module implements many of the classes described in the SDMX-IM specification ('spec'), which is available from: - https://sdmx.org/?page_id=5008 - https://sdmx.org/wp-content/uploads/ SDMX_2-1-1_SECTION_2_InformationModel_201108.pdf Details of the implementation: - Python typing and pydantic are used to enforce the types of attributes that reference instances of other classes. - Some classes have convenience attributes not mentioned in the spec, to ease navigation between related objects. These are marked “:mod:`sdmx` extension not in the IM.” - Class definitions are grouped by section of the spec, but these sections appear out of order so that dependent classes are defined first. """ # TODO for complete implementation of the IM, enforce TimeKeyValue (instead of KeyValue) # for {Generic,StructureSpecific} TimeSeriesDataSet. import logging from collections import ChainMap from collections.abc import Collection from collections.abc import Iterable as IterableABC from copy import copy from datetime import date, datetime, timedelta from enum import Enum from functools import lru_cache from inspect import isclass from itertools import product from operator import attrgetter, itemgetter from typing import ( Any, Dict, Generator, Generic, Iterable, List, Mapping, Optional, Sequence, Set, Tuple, Type, TypeVar, Union, ) from warnings import warn from pandasdmx.util import ( BaseModel, DictLike, compare, dictlike_field, only, Resource, validate_dictlike, validator, ) log = logging.getLogger(__name__) # Used by writers to select from InternationalString. # Exposed through pandasdmx.api.Request.default_locale DEFAULT_LOCALE = "en" # Configure validation level (new in v1.8.0) # This is currently used only to prevent URN matching ValidationLevels = Enum("ValidationLevels", "strict sloppy") DEFAULT_VAL_LEVEL = ValidationLevels.sloppy # §3.2: Base structures class InternationalString: """SDMX-IM InternationalString. SDMX-IM LocalisedString is not implemented. Instead, the 'localizations' is a mapping where: - keys correspond to the 'locale' property of LocalisedString. - values correspond to the 'label' property of LocalisedString. When used as a type hint with pydantic, InternationalString fields can be assigned to in one of four ways:: class Foo(BaseModel): name: InternationalString = InternationalString() # Equivalent: no localizations f = Foo() f = Foo(name={}) # Using an explicit locale f.name['en'] = "Foo's name in English" # Using a (locale, label) tuple f.name = ('fr', "Foo's name in French") # Using a dict f.name = {'en': "Replacement English name", 'fr': "Replacement French name"} # Using a bare string, implicitly for the DEFAULT_LOCALE f.name = "Name in DEFAULT_LOCALE language" Only the first method preserves existing localizations; the latter three replace them. """ localizations: Dict[str, str] = {} def __init__(self, value=None, **kwargs): super().__init__() # Handle initial values according to type if isinstance(value, str): # Bare string value = {DEFAULT_LOCALE: value} elif ( isinstance(value, Collection) and len(value) == 2 and isinstance(value[0], str) ): # 2-tuple of str is (locale, label) value = {value[0]: value[1]} elif isinstance(value, dict): # dict; use directly pass elif isinstance(value, IterableABC): # Iterable of 2-tuples value = {locale: label for (locale, label) in value} elif value is None: # Keyword arguments → dict, possibly empty value = dict(kwargs) else: raise ValueError(value, kwargs) self.localizations = value # Convenience access def __getitem__(self, locale): return self.localizations[locale] def __setitem__(self, locale, label): self.localizations[locale] = label # Duplicate of __getitem__, to pass existing tests in test_dsd.py def __getattr__(self, name): try: return self.__dict__["localizations"][name] except KeyError: raise AttributeError(name) from None def __add__(self, other): result = copy(self) result.localizations.update(other.localizations) return result def localized_default(self, locale=None): """Return the string in *locale* if not empty, or else the first defined.""" if locale and (locale in self.localizations) and self.localizations[locale]: return self.localizations[locale] if len(self.localizations): # No label in the default locale; use the first stored non-empty str value return next(filter(None, self.localizations.values())) else: return "" def __str__(self): return self.localized_default(DEFAULT_LOCALE) def __repr__(self): return "\n".join( ["{}: {}".format(*kv) for kv in sorted(self.localizations.items())] ) def __eq__(self, other): try: return self.localizations == other.localizations except AttributeError: return NotImplemented @classmethod def __get_validators__(cls): yield cls.__validate @classmethod def __validate(cls, value, values, config, field): # Any value that the constructor can handle can be assigned if not isinstance(value, InternationalString): value = InternationalString(value) try: # Update existing value existing = values[field.name] existing.localizations.update(value.localizations) return existing except KeyError: # No existing value/None; return the assigned value return value class Annotation(BaseModel): #: Can be used to disambiguate multiple annotations for one AnnotableArtefact. id: Optional[str] = None #: Title, used to identify an annotation. title: Optional[str] = None #: Specifies how the annotation is processed. type: Optional[str] = None #: A link to external descriptive text. url: Optional[str] = None #: Content of the annotation. text: InternationalString = InternationalString() class AnnotableArtefact(BaseModel): #: :class:`Annotations <.Annotation>` of the object. #: #: :mod:`pandaSDMX` implementation: The IM does not specify the name of this #: feature. annotations: List[Annotation] = [] def get_annotation(self, **attrib): """Return a :class:`Annotation` with given `attrib`, e.g. 'id'. If more than one `attrib` is given, all must match a particular annotation. Raises ------ KeyError If there is no matching annotation. """ for anno in self.annotations: if all(getattr(anno, key, None) == value for key, value in attrib.items()): return anno raise KeyError(attrib) def pop_annotation(self, **attrib): """Remove and return a :class:`Annotation` with given `attrib`, e.g. 'id'. If more than one `attrib` is given, all must match a particular annotation. Raises ------ KeyError If there is no matching annotation. """ for i, anno in enumerate(self.annotations):