API reference¶

Top-level methods and classes¶

`Client`([source, log_level])	Client for a SDMX REST web service.
`Resource`(value)	Enumeration of SDMX REST API endpoints.
`add_source`(info[, id, override])	Add a new data source.
`list_sources`()	Return a sorted list of valid source IDs.
`log`	Top-level logger.
`read_sdmx`(filename_or_obj[, format])	Load a SDMX-ML or SDMX-JSON message from a file or file-like object.
`read_url`(url, **kwargs)	Request a URL directly.
`to_pandas`(obj, args, *kwargs)	Convert an SDMX obj to `pandas` object(s).
`to_xml`(obj, **kwargs)	Convert an SDMX obj to SDMX-ML.

class sdmx.Client(source=None, log_level=None, **session_opts)[source]¶

Client for a SDMX REST web service.

Parameters

source (str or source.Source) – Identifier of a data source. If a string, must be one of the known sources in list_sources().
log_level (int) –
Override the package-wide logger with one of the standard logging levels.

Deprecated since version 2.0: Will be removed in sdmx version 3.0.
**session_opts – Additional keyword arguments are passed to Session.

get(resource_type=None, resource_id=None, tofile=None, use_cache=False, dry_run=False, **kwargs)[source]¶

Retrieve SDMX data or metadata.

(Meta)data is retrieved from the source of the current Client. The item(s) to retrieve can be specified in one of two ways:

resource_type, resource_id: These give the type (see Resource) and, optionally, ID of the item(s). If the resource_id is not given, all items of the given type are retrieved.
a resource object, i.e. a MaintainableArtefact: resource_type and resource_id are determined by the object’s class and id attribute, respectively.

Data is retrieved with resource_type=’data’. In this case, the optional keyword argument key can be used to constrain the data that is retrieved. Examples of the formats for key:

{'GEO': ['EL', 'ES', 'IE']}: dict with dimension name(s) mapped to an iterable of allowable values.
{'GEO': 'EL+ES+IE'}: dict with dimension name(s) mapped to strings joining allowable values with ‘+’, the logical ‘or’ operator for SDMX web services.
'....EL+ES+IE': str in which ordered dimension values (some empty, '') are joined with '.'. Using this form requires knowledge of the dimension order in the target data resource_id; in the example, dimension ‘GEO’ is the fifth of five dimensions: '.'.join(['', '', '', '', 'EL+ES+IE']). CubeRegion.to_query_string() can also be used to create properly formatted strings.

For formats 1 and 2, but not 3, the key argument is validated against the relevant DataStructureDefinition, either given with the dsd keyword argument, or retrieved from the web service before the main query.

For the optional param keyword argument, some useful parameters are:

‘startperiod’, ‘endperiod’: restrict the time range of data to retrieve.
‘references’: control which item(s) related to a metadata resource are retrieved, e.g. references=’parentsandsiblings’.

Parameters

resource_type (str or Resource, optional) – Type of resource to retrieve.
resource_id (str, optional) – ID of the resource to retrieve.
tofile (str or PathLike or file-like object, optional) – File path or file-like to write SDMX data as it is recieved.
use_cache (bool, optional) – If True, return a previously retrieved Message from cache, or update the cache with a newly-retrieved Message.
dry_run (bool, optional) – If True, prepare and return a requests.Request object, but do not execute the query. The prepared URL and headers can be examined by inspecting the returned object.
**kwargs – Other, optional parameters (below).

Other Parameters

dsd (DataStructureDefinition) – Existing object used to validate the key argument. If not provided, an additional query executed to retrieve a DSD in order to validate the key.
force (bool) – If True, execute the query even if the source does not support queries for the given resource_type. Default: False.
headers (dict) – HTTP headers. Given headers will overwrite instance-wide headers passed to the constructor. Default: None to use the default headers of the source.
key (str or dict) – For queries with resource_type=’data’. str values are not validated; dict values are validated using make_constraint().
params (dict) – Query parameters. The SDMX REST web service guidelines describe parameters and allowable values for different queries. params is not validated before the query is executed.
provider (str) – ID of the agency providing the data or metadata. Default: ID of the source agency.

An SDMX web service is a ‘data source’ operated by a specific, ‘source’ agency. A web service may host data or metadata originally published by one or more ‘provider’ agencies. Many sources are also providers. Other agencies—e.g. the SDMX Global Registry—simply aggregate (meta)data from other providers, but do not providing any (meta)data themselves.
resource (MaintainableArtefact subclass) – Object to retrieve. If given, resource_type and resource_id are ignored.
version (str) – version> of a resource to retrieve. Default: the keyword ‘latest’.

Returns

The requested SDMX message or, if dry_run is True, the prepared request object.

Return type

Message or Request

Raises

NotImplementedError – If the source does not support the given resource_type and force is not True.

preview_data(flow_id, key={})[source]¶

Return a preview of data.

For the Dataflow flow_id, return all series keys matching key. preview_data() uses a feature supported by some data providers that returns SeriesKeys without the corresponding Observations.

To count the number of series:

keys = sdmx.Client('PROVIDER').preview_data('flow')
len(keys)

To get a pandas object containing the key values:

keys_df = sdmx.to_pandas(keys)

Parameters

flow_id (str) – Dataflow to preview.
key (dict, optional) – Mapping of dimension to values, where values may be a ‘+’-delimited list of values. If given, only SeriesKeys that match key are returned. If not given, preview_data is equivalent to list(client.series_keys(flow_id)).

Returns

Return type

list of SeriesKey

series_keys(flow_id, use_cache=True)[source]¶

Return all SeriesKey for flow_id.

Returns
Return type: list

session = None¶: Session for queries sent from the instance.

source = None¶: source.Source for requests sent from the instance.

sdmx.Request(*args, **kwargs)[source]¶: Compatibility function for Client.

New in version 2.0.

Deprecated since version 2.0: Will be removed in sdmx version 3.0.

class sdmx.Resource(value)[source]¶

Enumeration of SDMX REST API endpoints.

`Enum` member	`sdmx.model` class
`categoryscheme`	`CategoryScheme`
`codelist`	`Codelist`
`conceptscheme`	`ConceptScheme`
`data`	`DataSet`
`dataflow`	`DataflowDefinition`
`datastructure`	`DataStructureDefinition`
`provisionagreement`	`ProvisionAgreement`

classmethod from_obj(obj)[source]¶: Return an enumeration value based on the class of obj.

sdmx.add_source(info, id=None, override=False, **kwargs)[source]¶

Add a new data source.

The info expected is in JSON format:

{
  "id": "ESTAT",
  "documentation": "http://data.un.org/Host.aspx?Content=API",
  "url": "http://ec.europa.eu/eurostat/SDMX/diss-web/rest",
  "name": "Eurostat",
  "supported": {"codelist": false, "preview": true}
}

…with unspecified values using the defaults; see Source.

Parameters

info (dict-like) – String containing JSON information about a data source.
id (str) – Identifier for the new datasource. If None (default), then info[‘id’] is used.
override (bool) – If True, replace any existing data source with id. Otherwise, raise ValueError.
**kwargs – Optional callbacks for handle_response and finish_message hooks.

sdmx.list_sources()[source]¶

Return a sorted list of valid source IDs.

These can be used to create Client instances.

sdmx.log = <Logger sdmx (WARNING)>[source]¶: Top-level logger.

New in version 0.4.

sdmx.read_sdmx(filename_or_obj, format=None, **kwargs)[source]¶

Load a SDMX-ML or SDMX-JSON message from a file or file-like object.

Parameters

filename_or_obj (str or PathLike or file) –
format ('XML' or 'JSON', optional) –

Other Parameters

dsd (DataStructureDefinition) – For “structure-specific” format`=``XML` messages only.

sdmx.read_url(url, **kwargs)[source]¶: Request a URL directly.

sdmx.to_pandas(obj, *args, **kwargs)[source]¶

Convert an SDMX obj to pandas object(s).

See sdmx.writer.pandas.

sdmx.to_xml(obj, **kwargs)[source]¶

Convert an SDMX obj to SDMX-ML.

Parameters: kwargs – Passed to lxml.etree.to_string(), e.g. pretty_print = True.
Raises: NotImplementedError – If writing specific objects to SDMX-ML has not been implemented in sdmx.

`message`: SDMX messages¶

Classes for SDMX messages.

Message and related classes are not defined in the SDMX information model, but in the SDMX-ML standard.

sdmx also uses DataMessage to encapsulate SDMX-JSON data returned by data sources.

class sdmx.message.DataMessage(*, header: sdmx.message.Header = <Header> source: test: False, footer: sdmx.message.Footer = None, response: requests.models.Response = None, data: List[sdmx.model.DataSet] = [], dataflow: sdmx.model.DataflowDefinition = <DataflowDefinition (missing id)>, observation_dimension: Optional[Union[sdmx.model._AllDimensions, sdmx.model.DimensionComponent, List[sdmx.model.DimensionComponent]]] = None)[source]¶

Bases: sdmx.message.Message

Data Message.

Note

A DataMessage may contain zero or more DataSet, so data is a list. To retrieve the first (and possibly only) data set in the message, access the first element of the list: msg.data[0].

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two DataMessages are the same if:

Message.compare() is True
their dataflow and observation_dimension compare equal.
they have the same number of DataSets, and
corresponding DataSets compare equal (see DataSet.compare()).

Parameters: strict (bool, optional) – Passed to compare().

data: List[sdmx.model.DataSet]¶: list of DataSet.

dataflow: sdmx.model.DataflowDefinition¶: DataflowDefinition that contains the data.

observation_dimension: Optional[Union[sdmx.model._AllDimensions, sdmx.model.DimensionComponent, List[sdmx.model.DimensionComponent]]]¶: The “dimension at observation level”.

property structure¶: DataStructureDefinition used in the dataflow.

class sdmx.message.ErrorMessage(*, header: sdmx.message.Header = <Header> source: test: False, footer: sdmx.message.Footer = None, response: requests.models.Response = None)[source]¶

Bases: sdmx.message.Message

footer: Optional[sdmx.message.Footer]¶: (optional) Footer instance.

header: sdmx.message.Header¶: Header instance.

response: Optional[requests.models.Response]¶: requests.Response instance for the response to the HTTP request that returned the Message. This is not part of the SDMX standard.

class sdmx.message.Footer(*, severity: str = None, text: List[sdmx.model.InternationalString] = [], code: int = None)[source]¶

Bases: sdmx.util.BaseModel

Footer of an SDMX-ML message.

SDMX-JSON messages do not have footers.

code: Optional[int]¶

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two Footers are the same if their code, severity, and text are equal.

Parameters: strict (bool, optional) – Passed to compare().

severity: Optional[str]¶

text: List[sdmx.model.InternationalString]¶: The body text of the Footer contains zero or more blocks of text.

class sdmx.message.Header(*, error: str = None, extracted: datetime.datetime = None, id: str = None, prepared: datetime.datetime = None, reporting_begin: datetime.datetime = None, reporting_end: datetime.datetime = None, receiver: sdmx.model.Agency = None, sender: sdmx.model.Agency = None, source: sdmx.model.InternationalString =, test: bool = False)[source]¶

Bases: sdmx.util.BaseModel

Header of an SDMX-ML message.

SDMX-JSON messages do not have headers.

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two Headers are the same if their corresponding attributes are equal.

Parameters: strict (bool, optional) – Passed to compare().

error: Optional[str]¶: (optional) Error code for the message.

extracted: Optional[datetime.datetime]¶: Date and time at which the data was extracted.

id: Optional[str]¶: Identifier for the message.

prepared: Optional[datetime.datetime]¶: Date and time at which the message was generated.

receiver: Optional[sdmx.model.Agency]¶: Intended recipient of the message, e.g. the user’s name for an authenticated service.

reporting_begin: Optional[datetime.datetime]¶: Start of the time period covered by a DataMessage.

reporting_end: Optional[datetime.datetime]¶: End of the time period covered by a DataMessage.

sender: Optional[sdmx.model.Agency]¶: The Agency associated with the data Source.

source: sdmx.model.InternationalString¶

test: bool¶

class sdmx.message.Message(*, header: sdmx.message.Header = <Header> source: test: False, footer: sdmx.message.Footer = None, response: requests.models.Response = None)[source]¶

Bases: sdmx.util.BaseModel

class Config[source]¶

Bases: object

arbitrary_types_allowed = True¶

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two Messages are the same if their header and footer compare equal.

Parameters: strict (bool, optional) – Passed to compare().

footer: Optional[sdmx.message.Footer]¶: (optional) Footer instance.

header: sdmx.message.Header¶: Header instance.

response: Optional[requests.models.Response]¶: requests.Response instance for the response to the HTTP request that returned the Message. This is not part of the SDMX standard.

class sdmx.message.StructureMessage(*, header: sdmx.message.Header = <Header> source: test: False, footer: sdmx.message.Footer = None, response: requests.models.Response = None, categorisation: sdmx.util.DictLike[str, sdmx.model.Categorisation] = {}, category_scheme: sdmx.util.DictLike[str, sdmx.model.CategoryScheme] = {}, codelist: sdmx.util.DictLike[str, sdmx.model.Codelist] = {}, concept_scheme: sdmx.util.DictLike[str, sdmx.model.ConceptScheme] = {}, constraint: sdmx.util.DictLike[str, sdmx.model.ContentConstraint] = {}, dataflow: sdmx.util.DictLike[str, sdmx.model.DataflowDefinition] = {}, structure: sdmx.util.DictLike[str, sdmx.model.DataStructureDefinition] = {}, organisation_scheme: sdmx.util.DictLike[str, sdmx.model.AgencyScheme] = {}, provisionagreement: sdmx.util.DictLike[str, sdmx.model.ProvisionAgreement] = {})[source]¶

Bases: sdmx.message.Message

add(obj: sdmx.model.IdentifiableArtefact)[source]¶: Add obj to the StructureMessage.

categorisation: sdmx.util.DictLike[str, sdmx.model.Categorisation]¶: Collection of Categorisation.

category_scheme: sdmx.util.DictLike[str, sdmx.model.CategoryScheme]¶: Collection of CategoryScheme.

codelist: sdmx.util.DictLike[str, sdmx.model.Codelist]¶: Collection of Codelist.

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two StructureMessages compare equal if DictLike.compare() is True for each of the object collection attributes.

Parameters: strict (bool, optional) – Passed to DictLike.compare().

concept_scheme: sdmx.util.DictLike[str, sdmx.model.ConceptScheme]¶: Collection of ConceptScheme.

constraint: sdmx.util.DictLike[str, sdmx.model.ContentConstraint]¶: Collection of ContentConstraint.

dataflow: sdmx.util.DictLike[str, sdmx.model.DataflowDefinition]¶: Collection of DataflowDefinition.

get(obj_or_id: Union[str, sdmx.model.IdentifiableArtefact]) → Optional[sdmx.model.IdentifiableArtefact][source]¶

Retrieve obj_or_id from the StructureMessage.

Parameters

obj_or_id (str or IdentifiableArtefact) – If an IdentifiableArtefact, return an object of the same class and id; if str, an object with this ID.

Returns

.IdentifiableArtefact – with the given ID and possibly class.
None – if there is no match.

Raises

ValueError – if obj_or_id is a string and there are ≥2 objects (of different classes) with the same ID.

organisation_scheme: sdmx.util.DictLike[str, sdmx.model.AgencyScheme]¶: Collection of AgencyScheme.

provisionagreement: sdmx.util.DictLike[str, sdmx.model.ProvisionAgreement]¶: Collection of ProvisionAgreement.

structure: sdmx.util.DictLike[str, sdmx.model.DataStructureDefinition]¶: Collection of DataStructureDefinition.

`model`: SDMX Information Model¶

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 “pandaSDMX 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.

class sdmx.model.ActionType(value)¶

Bases: enum.Enum

An enumeration.

append = 3¶

delete = 1¶

information = 4¶

replace = 2¶

class sdmx.model.Agency(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, parent: Optional[Union[Item, ItemScheme]] = None, child: List[Item] = [], contact: List[sdmx.model.Contact] = [])[source]¶

Bases: sdmx.model.Organisation

contact: List[sdmx.model.Contact]¶

class sdmx.model.AgencyScheme(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, is_partial: bool = None, items: Dict[str, IT] = {})[source]¶

Bases: sdmx.model.ItemScheme[sdmx.model.Agency], sdmx.model.OrganisationScheme

is_partial: Optional[bool]¶

items: Dict[str, IT]¶: Members of the ItemScheme. Both ItemScheme and Item are abstract classes. Concrete classes are paired: for example, a Codelist contains Codes.

class sdmx.model.AnnotableArtefact(*, annotations: List[sdmx.model.Annotation] = [])[source]¶

Bases: sdmx.util.BaseModel

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

get_annotation(**attrib)[source]¶

Return a 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.

pop_annotation(**attrib)[source]¶

Remove and return a 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.

class sdmx.model.Annotation(*, id: str = None, title: str = None, type: str = None, url: str = None, text: sdmx.model.InternationalString =)[source]¶

Bases: sdmx.util.BaseModel

id: Optional[str]¶: Can be used to disambiguate multiple annotations for one AnnotableArtefact.

text: sdmx.model.InternationalString¶: Content of the annotation.

title: Optional[str]¶: Title, used to identify an annotation.

type: Optional[str]¶: Specifies how the annotation is processed.

url: Optional[str]¶: A link to external descriptive text.

class sdmx.model.AttachmentConstraint(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, data_content_keys: sdmx.model.DataKeySet = None, role: sdmx.model.ConstraintRole, attachment: Set[sdmx.model.ConstrainableArtefact] = {})[source]¶

Bases: sdmx.model.Constraint

attachment: Set[sdmx.model.ConstrainableArtefact]¶

class sdmx.model.AttributeDescriptor(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, components: List[CT] = [], auto_order: int = 1)[source]¶

Bases: sdmx.model.ComponentList[sdmx.model.DataAttribute]

components: List[CT]¶

class sdmx.model.AttributeRelationship[source]¶: Bases: sdmx.util.BaseModel

class sdmx.model.AttributeValue(*args, value: Union[str, sdmx.model.Code], value_for: sdmx.model.DataAttribute = None, start_date: datetime.date = None)[source]¶

Bases: sdmx.util.BaseModel

SDMX-IM AttributeValue.

In the spec, AttributeValue is an abstract class. Here, it serves as both the concrete subclasses CodedAttributeValue and UncodedAttributeValue.

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two AttributeValues are equal if their properties are equal.

Parameters: strict (bool, optional) – Passed to compare().

start_date: Optional[datetime.date]¶

value: Union[str, sdmx.model.Code]¶

value_for: Optional[sdmx.model.DataAttribute]¶

class sdmx.model.Categorisation(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, category: sdmx.model.Category = None, artefact: sdmx.model.IdentifiableArtefact = None)[source]¶

Bases: sdmx.model.MaintainableArtefact

artefact: Optional[sdmx.model.IdentifiableArtefact]¶

category: Optional[sdmx.model.Category]¶

class sdmx.model.Category(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, parent: Optional[Union[Item, ItemScheme]] = None, child: List[Item] = [])[source]¶

Bases: sdmx.model.Item

SDMX-IM Category.

child: List[sdmx.model.Item]¶

parent: Optional[Union[sdmx.model.Item, sdmx.model.ItemScheme]]¶

class sdmx.model.CategoryScheme(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, is_partial: bool = None, items: Dict[str, IT] = {})[source]¶

Bases: sdmx.model.ItemScheme[sdmx.model.Category]

is_partial: Optional[bool]¶

items: Dict[str, IT]¶: Members of the ItemScheme. Both ItemScheme and Item are abstract classes. Concrete classes are paired: for example, a Codelist contains Codes.

class sdmx.model.Code(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, parent: Optional[Union[Item, ItemScheme]] = None, child: List[Item] = [])[source]¶

Bases: sdmx.model.Item

SDMX-IM Code.

child: List[sdmx.model.Item]¶

parent: Optional[Union[sdmx.model.Item, sdmx.model.ItemScheme]]¶

class sdmx.model.Codelist(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, is_partial: bool = None, items: Dict[str, IT] = {})[source]¶

Bases: sdmx.model.ItemScheme[sdmx.model.Code]

is_partial: Optional[bool]¶

items: Dict[str, IT]¶: Members of the ItemScheme. Both ItemScheme and Item are abstract classes. Concrete classes are paired: for example, a Codelist contains Codes.

class sdmx.model.Component(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, concept_identity: sdmx.model.Concept = None, local_representation: sdmx.model.Representation = None)[source]¶

Bases: sdmx.model.IdentifiableArtefact

concept_identity: Optional[sdmx.model.Concept]¶

local_representation: Optional[sdmx.model.Representation]¶

class sdmx.model.ComponentList(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, components: List[CT] = [], auto_order: int = 1)[source]¶

Bases: sdmx.model.IdentifiableArtefact, Generic[sdmx.model.CT]

append(value: CT)[source]¶: Append value to components.

auto_order¶

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two ComponentLists are the same if:

IdentifiableArtefact.compare() is True, and
corresponding components compare equal.

Parameters: strict (bool, optional) – Passed to compare() and IdentifiableArtefact.compare().

components: List[CT]¶

get(id) → CT[source]¶: Return the component with the given id.

getdefault(id, cls=None, **kwargs) → CT[source]¶

Return or create the component with the given id.

If the component is automatically created, its Dimension.order attribute is set to the value of auto_order, which is then incremented.

Parameters

id (str) – Component ID.
cls (type, optional) – Hint for the class of a new object.
kwargs – Passed to the constructor of Component, or a Component subclass if components is overridden in a subclass of ComponentList.

class sdmx.model.ComponentValue(*, value_for: sdmx.model.Component, value: str)[source]¶

Bases: sdmx.util.BaseModel

value: str¶

value_for: sdmx.model.Component¶

class sdmx.model.Concept(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, parent: Optional[Union[Item, ItemScheme]] = None, child: List[Item] = [], core_representation: sdmx.model.Representation = None, iso_concept: sdmx.model.ISOConceptReference = None)[source]¶

Bases: sdmx.model.Item

core_representation: Optional[sdmx.model.Representation]¶

iso_concept: Optional[sdmx.model.ISOConceptReference]¶

class sdmx.model.ConceptScheme(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, is_partial: bool = None, items: Dict[str, IT] = {})[source]¶

Bases: sdmx.model.ItemScheme[sdmx.model.Concept]

is_partial: Optional[bool]¶

items: Dict[str, IT]¶: Members of the ItemScheme. Both ItemScheme and Item are abstract classes. Concrete classes are paired: for example, a Codelist contains Codes.

class sdmx.model.ConstrainableArtefact[source]¶

Bases: sdmx.util.BaseModel

SDMX-IM ConstrainableArtefact.

class sdmx.model.Constraint(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, data_content_keys: sdmx.model.DataKeySet = None, role: sdmx.model.ConstraintRole)[source]¶

Bases: sdmx.model.MaintainableArtefact

class Config[source]¶

Bases: object

validate_assignment = False¶

data_content_keys: Optional[sdmx.model.DataKeySet]¶: DataKeySet included in the Constraint.

role: sdmx.model.ConstraintRole¶

class sdmx.model.ConstraintRole(*, role: sdmx.model.ConstraintRoleType)[source]¶

Bases: sdmx.util.BaseModel

role: sdmx.model.ConstraintRoleType¶

class sdmx.model.ConstraintRoleType(value)¶

Bases: enum.Enum

An enumeration.

actual = 2¶

allowable = 1¶

class sdmx.model.Contact(*, name: sdmx.model.InternationalString = , org_unit: sdmx.model.InternationalString = , telephone: str = None, responsibility: sdmx.model.InternationalString = , email: List[str], uri: List[str])[source]¶

Bases: sdmx.util.BaseModel

Organization contact information.

IMF is the only data provider that returns messages with Contact information. These differ from the IM in several ways. This class reflects these differences:

‘name’ and ‘org_unit’ are InternationalString, instead of strings.
‘email’ may be a list of e-mail addresses, rather than a single address.
‘uri’ may be a list of URIs, rather than a single URI.

email: List[str]¶

name: sdmx.model.InternationalString¶

org_unit: sdmx.model.InternationalString¶

responsibility: sdmx.model.InternationalString¶

telephone: Optional[str]¶

uri: List[str]¶

class sdmx.model.ContentConstraint(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, data_content_keys: sdmx.model.DataKeySet = None, role: sdmx.model.ConstraintRole, data_content_region: List[sdmx.model.CubeRegion] = [], content: Set[sdmx.model.ConstrainableArtefact] = {})[source]¶

Bases: sdmx.model.Constraint

class Config[source]¶

Bases: object

validate_assignment_exclude = 'data_content_region'¶

content: Set[sdmx.model.ConstrainableArtefact]¶

data_content_region: List[sdmx.model.CubeRegion]¶: CubeRegions included in the ContentConstraint.

to_query_string(structure)[source]¶

class sdmx.model.CubeRegion(*, included: bool = True, member: Dict[Dimension, sdmx.model.MemberSelection] = {})[source]¶

Bases: sdmx.util.BaseModel

included: bool¶

member: Dict[sdmx.model.Dimension, sdmx.model.MemberSelection]¶

to_query_string(structure)[source]¶

class sdmx.model.DataAttribute(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, concept_identity: sdmx.model.Concept = None, local_representation: sdmx.model.Representation = None, related_to: sdmx.model.AttributeRelationship = None, usage_status: sdmx.model.UsageStatus = None)[source]¶

Bases: sdmx.model.Component

related_to: Optional[sdmx.model.AttributeRelationship]¶

usage_status: Optional[sdmx.model.UsageStatus]¶

class sdmx.model.DataKey(*, included: bool, key_value: Dict[sdmx.model.Component, sdmx.model.ComponentValue])[source]¶

Bases: sdmx.util.BaseModel

included: bool¶

key_value: Dict[sdmx.model.Component, sdmx.model.ComponentValue]¶: Mapping from Component to ComponentValue comprising the key.

class sdmx.model.DataKeySet(*, included: bool, keys: List[sdmx.model.DataKey] = [])[source]¶

Bases: sdmx.util.BaseModel

included: bool¶: True if the keys are included in the Constraint; False if they are excluded.

keys: List[sdmx.model.DataKey]¶: DataKeys appearing in the set.

class sdmx.model.DataProvider(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, parent: Optional[Union[Item, ItemScheme]] = None, child: List[Item] = [], contact: List[sdmx.model.Contact] = [])[source]¶

Bases: sdmx.model.Organisation, sdmx.model.ConstrainableArtefact

SDMX-IM DataProvider.

contact: List[sdmx.model.Contact]¶

class sdmx.model.DataProviderScheme(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, is_partial: bool = None, items: Dict[str, IT] = {})[source]¶

Bases: sdmx.model.ItemScheme[sdmx.model.DataProvider], sdmx.model.OrganisationScheme

is_partial: Optional[bool]¶

items: Dict[str, IT]¶: Members of the ItemScheme. Both ItemScheme and Item are abstract classes. Concrete classes are paired: for example, a Codelist contains Codes.

class sdmx.model.DataSet(*, annotations: List[sdmx.model.Annotation] = [], action: sdmx.model.ActionType = None, attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue] = {}, valid_from: str = None, structured_by: sdmx.model.DataStructureDefinition = None, obs: List[sdmx.model.Observation] = [], series: sdmx.util.DictLike[sdmx.model.SeriesKey, List[sdmx.model.Observation]] = {}, group: sdmx.util.DictLike[sdmx.model.GroupKey, List[sdmx.model.Observation]] = {})[source]¶

Bases: sdmx.model.AnnotableArtefact

action: Optional[sdmx.model.ActionType]¶

add_obs(observations, series_key=None)[source]¶

Add observations to a series with series_key.

Checks consistency and adds group associations.

attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue]¶

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two DataSets are the same if:

their action, valid_from compare equal.
all dataset-level attached attributes compare equal.
they have the same number of observations, series, and groups.

Parameters: strict (bool, optional) – Passed to compare().

group: sdmx.util.DictLike[sdmx.model.GroupKey, List[sdmx.model.Observation]]¶: Map of group key → list of observations. sdmx extension not in the IM.

obs: List[sdmx.model.Observation]¶: All observations in the DataSet.

series: sdmx.util.DictLike[sdmx.model.SeriesKey, List[sdmx.model.Observation]]¶: Map of series key → list of observations. sdmx extension not in the IM.

structured_by: Optional[sdmx.model.DataStructureDefinition]¶

valid_from: Optional[str]¶

class sdmx.model.DataStructureDefinition(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, grouping: sdmx.model.ComponentList = None, attributes: sdmx.model.AttributeDescriptor = <AttributeDescriptor: >, dimensions: sdmx.model.DimensionDescriptor = <DimensionDescriptor: >, measures: sdmx.model.MeasureDescriptor = <MeasureDescriptor: >, group_dimensions: sdmx.util.DictLike[str, sdmx.model.GroupDimensionDescriptor] = {})[source]¶

Bases: sdmx.model.Structure, sdmx.model.ConstrainableArtefact

SDMX-IM DataStructureDefinition (‘DSD’).

attributes: sdmx.model.AttributeDescriptor¶: A AttributeDescriptor that describes the attributes of the data structure.

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two DataStructureDefinitions are the same if each of attributes, dimensions, measures, and group_dimensions compares equal.

Parameters: strict (bool, optional) – Passed to ComponentList.compare().

dimensions: sdmx.model.DimensionDescriptor¶: A DimensionDescriptor that describes the dimensions of the data structure.

classmethod from_keys(keys)[source]¶

Return a new DSD given some keys.

The DSD’s dimensions refers to a set of new Concepts and Codelists, created to represent all the values observed across keys for each dimension.

Parameters: keys (iterable of Key) – or of subclasses such as SeriesKey or GroupKey.

group_dimensions: sdmx.util.DictLike[str, sdmx.model.GroupDimensionDescriptor]¶: Mapping from GroupDimensionDescriptor.id to GroupDimensionDescriptor.

make_constraint(key)[source]¶

Return a constraint for key.

key is a dict wherein:

keys are str ids of Dimensions appearing in this DSD’s dimensions, and
values are ‘+’-delimited str containing allowable values, _or_ iterables of str, each an allowable value.

For example:

cc2 = dsd.make_constraint({'foo': 'bar+baz', 'qux': 'q1+q2+q3'})

cc2 includes any key where the ‘foo’ dimension is ‘bar’ or ‘baz’, and the ‘qux’ dimension is one of ‘q1’, ‘q2’, or ‘q3’.

Returns: A constraint with one CubeRegion in its data_content_region , including only the values appearing in keys.
Return type: ContentConstraint
Raises: ValueError – if key contains a dimension IDs not appearing in dimensions.

make_key(key_cls, values: Mapping, extend=False, group_id=None)[source]¶

Make a Key or subclass.

Parameters

key_cls (Key or SeriesKey or GroupKey) – Class of Key to create.
values (dict) – Used to construct Key.values.
extend (bool, optional) – If True, make_key will not return KeyError on mission dimensions. Instead dimensions (key_cls is Key or SeriesKey) or group_dimensions (key_cls is GroupKey) will be extended by creating new Dimension objects.
group_id (str, optional) – When key_cls is :class`.GroupKey`, the ID of the GroupDimensionDescriptor that structures the key.

Returns

An instance of key_cls.

Return type

Key

Raises

KeyError – If any of the keys of values is not a Dimension or Attribute in the DSD.

measures: sdmx.model.MeasureDescriptor¶: A MeasureDescriptor.

class sdmx.model.DataflowDefinition(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, structure: sdmx.model.DataStructureDefinition = <DataStructureDefinition (missing id)>)[source]¶

Bases: sdmx.model.StructureUsage, sdmx.model.ConstrainableArtefact

structure: sdmx.model.DataStructureDefinition¶

class sdmx.model.Datasource(*, url: str)[source]¶

Bases: sdmx.util.BaseModel

url: str¶

class sdmx.model.Dimension(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, concept_identity: sdmx.model.Concept = None, local_representation: sdmx.model.Representation = None, order: int = None)[source]¶

Bases: sdmx.model.DimensionComponent

SDMX-IM Dimension.

order: Optional[int]¶

class sdmx.model.DimensionComponent(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, concept_identity: sdmx.model.Concept = None, local_representation: sdmx.model.Representation = None, order: int = None)[source]¶

Bases: sdmx.model.Component

order: Optional[int]¶

class sdmx.model.DimensionDescriptor(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, components: List[CT] = [], auto_order: int = 1)[source]¶

Bases: sdmx.model.ComponentList[sdmx.model.DimensionComponent]

Describes a set of dimensions.

IM: “An ordered set of metadata concepts that, combined, classify a statistical series, and whose values, when combined (the key) in an instance such as a data set, uniquely identify a specific observation.”

components is a list (ordered) of Dimension, MeasureDimension, and/or TimeDimension.

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

assign_order()[source]¶

Assign the DimensionComponent.order attribute.

The Dimensions in components are numbered, starting from 1.

components: List[CT]¶

classmethod from_key(key)[source]¶

Create a new DimensionDescriptor from a key.

For each KeyValue in the key:

A new Dimension is created.
A new Codelist is created, containing the KeyValue.value.

Parameters: key (Key or GroupKey or SeriesKey) –

id: str¶: Unique identifier of the object.

order_key(key)[source]¶: Return a key ordered according to the DSD.

uri: Optional[str]¶: Universal resource identifier that may or may not be resolvable.

urn: Optional[str]¶: Universal resource name. For use in SDMX registries; all registered objects have a URN.

urn_group: Dict¶

class sdmx.model.DimensionRelationship(*, dimensions: List[sdmx.model.DimensionComponent] = [], group_key: GroupDimensionDescriptor = None)[source]¶

Bases: sdmx.model.AttributeRelationship

dimensions: List[sdmx.model.DimensionComponent]¶

group_key: Optional[sdmx.model.GroupDimensionDescriptor]¶: NB the IM says “0..*” here in a diagram, but the text does not match.

class sdmx.model.Facet(*, type: sdmx.model.FacetType = FacetType(is_sequence=None, min_length=None, max_length=None, min_value=None, max_value=None, start_value=None, end_value=None, interval=None, time_interval=None, decimals=None, pattern=None, start_time=None, end_time=None), value: str = None, value_type: sdmx.model.FacetValueType = None)[source]¶

Bases: sdmx.util.BaseModel

class Config[source]¶

Bases: object

extra = 'forbid'¶

type: sdmx.model.FacetType¶

value: Optional[str]¶

value_type: Optional[sdmx.model.FacetValueType]¶

class sdmx.model.FacetType(*, is_sequence: bool = None, min_length: int = None, max_length: int = None, min_value: float = None, max_value: float = None, start_value: float = None, end_value: str = None, interval: float = None, time_interval: datetime.timedelta = None, decimals: int = None, pattern: str = None, start_time: datetime.datetime = None, end_time: datetime.datetime = None)[source]¶

Bases: sdmx.util.BaseModel

class Config[source]¶

Bases: object

extra = 'forbid'¶

decimals: Optional[int]¶

end_time: Optional[datetime.datetime]¶

end_value: Optional[str]¶

interval: Optional[float]¶

is_sequence: Optional[bool]¶

max_length: Optional[int]¶

max_value: Optional[float]¶

min_length: Optional[int]¶

min_value: Optional[float]¶

pattern: Optional[str]¶

start_time: Optional[datetime.datetime]¶

start_value: Optional[float]¶

time_interval: Optional[datetime.timedelta]¶

class sdmx.model.FacetValueType(value)¶

Bases: enum.Enum

An enumeration.

alpha = 13¶

alphaNumeric = 14¶

basicTimePeriod = 20¶

bigInteger = 2¶

boolean = 9¶

count = 11¶

dataSetReference = 43¶

dateTime = 34¶

day = 38¶

decimal = 6¶

double = 8¶

duration = 40¶

exclusiveValueRange = 16¶

float = 7¶

gregorianDay = 25¶

gregorianMonth = 23¶

gregorianTimePeriod = 21¶

gregorianYear = 22¶

gregorianYearMonth = 24¶

identifiableReference = 42¶

inclusiveValueRange = 12¶

incremental = 17¶

integer = 3¶

keyValues = 41¶

long = 4¶

month = 36¶

monthDay = 37¶

numeric = 15¶

observationalTimePeriod = 18¶

reportingDay = 33¶

reportingMonth = 31¶

reportingQuarter = 30¶

reportingSemester = 28¶

reportingTimePeriod = 26¶

reportingTrimester = 29¶

reportingWeek = 32¶

reportingYear = 27¶

short = 5¶

standardTimePeriod = 19¶

string = 1¶

time = 39¶

timesRange = 35¶

uri = 10¶

class sdmx.model.GenericDataSet(*, annotations: List[sdmx.model.Annotation] = [], action: sdmx.model.ActionType = None, attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue] = {}, valid_from: str = None, structured_by: sdmx.model.DataStructureDefinition = None, obs: List[sdmx.model.Observation] = [], series: sdmx.util.DictLike[sdmx.model.SeriesKey, List[sdmx.model.Observation]] = {}, group: sdmx.util.DictLike[sdmx.model.GroupKey, List[sdmx.model.Observation]] = {})[source]¶

Bases: sdmx.model.DataSet

SDMX-IM GenericDataSet.

action: Optional[sdmx.model.ActionType]¶

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue]¶

group: sdmx.util.DictLike[sdmx.model.GroupKey, List[sdmx.model.Observation]]¶: Map of group key → list of observations. sdmx extension not in the IM.

obs: List[sdmx.model.Observation]¶: All observations in the DataSet.

series: sdmx.util.DictLike[sdmx.model.SeriesKey, List[sdmx.model.Observation]]¶: Map of series key → list of observations. sdmx extension not in the IM.

structured_by: Optional[sdmx.model.DataStructureDefinition]¶

valid_from: Optional[str]¶

class sdmx.model.GenericTimeSeriesDataSet(*, annotations: List[sdmx.model.Annotation] = [], action: sdmx.model.ActionType = None, attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue] = {}, valid_from: str = None, structured_by: sdmx.model.DataStructureDefinition = None, obs: List[sdmx.model.Observation] = [], series: sdmx.util.DictLike[sdmx.model.SeriesKey, List[sdmx.model.Observation]] = {}, group: sdmx.util.DictLike[sdmx.model.GroupKey, List[sdmx.model.Observation]] = {})[source]¶

Bases: sdmx.model.DataSet

SDMX-IM GenericTimeSeriesDataSet.

action: Optional[sdmx.model.ActionType]¶

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue]¶

group: sdmx.util.DictLike[sdmx.model.GroupKey, List[sdmx.model.Observation]]¶: Map of group key → list of observations. sdmx extension not in the IM.

obs: List[sdmx.model.Observation]¶: All observations in the DataSet.

series: sdmx.util.DictLike[sdmx.model.SeriesKey, List[sdmx.model.Observation]]¶: Map of series key → list of observations. sdmx extension not in the IM.

structured_by: Optional[sdmx.model.DataStructureDefinition]¶

valid_from: Optional[str]¶

class sdmx.model.GroupDimensionDescriptor(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, components: List[CT] = [], auto_order: int = 1, attachment_constraint: bool = None, constraint: sdmx.model.AttachmentConstraint = None)[source]¶

Bases: sdmx.model.ComponentList[sdmx.model.DimensionComponent]

assign_order()[source]¶: assign_order() has no effect for GroupDimensionDescriptor.

attachment_constraint: Optional[bool]¶

constraint: Optional[sdmx.model.AttachmentConstraint]¶

class sdmx.model.GroupKey(arg: Mapping = None, *, attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue] = {}, described_by: sdmx.model.GroupDimensionDescriptor = None, values: sdmx.util.DictLike[str, sdmx.model.KeyValue] = {}, id: str = None)[source]¶

Bases: sdmx.model.Key

described_by: Optional[sdmx.model.GroupDimensionDescriptor]¶

id: Optional[str]¶

class sdmx.model.GroupRelationship(*, group_key: GroupDimensionDescriptor = None)[source]¶

Bases: sdmx.model.AttributeRelationship

group_key: Optional[sdmx.model.GroupDimensionDescriptor]¶

class sdmx.model.ISOConceptReference(*, agency: str, id: str, scheme_id: str)[source]¶

Bases: sdmx.util.BaseModel

class Config[source]¶

Bases: object

extra = 'forbid'¶

agency: str¶

id: str¶

scheme_id: str¶

class sdmx.model.IdentifiableArtefact(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {})[source]¶

Bases: sdmx.model.AnnotableArtefact

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two IdentifiableArtefacts are the same if they have the same id, uri, and urn.

Parameters: strict (bool, optional) – Passed to compare().

id: str¶: Unique identifier of the object.

uri: Optional[str]¶: Universal resource identifier that may or may not be resolvable.

urn: Optional[str]¶: Universal resource name. For use in SDMX registries; all registered objects have a URN.

urn_group: Dict¶

class sdmx.model.InternationalString(value=None, **kwargs)[source]¶

Bases: object

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] = {}¶

localized_default(locale=None)[source]¶: Return the string in locale, or else the first defined.

class sdmx.model.Item(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, parent: Optional[Union[Item, ItemScheme]] = None, child: List[Item] = [])[source]¶

Bases: sdmx.model.NameableArtefact

class Config[source]¶

Bases: object

validate_assignment_exclude = 'parent'¶

append_child(other)[source]¶

child: List[sdmx.model.Item]¶

get_child(id)[source]¶: Return the child with the given id.

get_scheme()[source]¶: Return the ItemScheme to which the Item belongs, if any.

property hierarchical_id¶

Construct the ID of an Item in a hierarchical ItemScheme.

Returns, for example, ‘A.B.C’ for an Item with id ‘C’ that is the child of an item with id ‘B’, which is the child of a root Item with id ‘A’.

See also

ItemScheme.get_hierarchical

parent: Optional[Union[sdmx.model.Item, sdmx.model.ItemScheme]]¶

class sdmx.model.ItemScheme(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, is_partial: bool = None, items: Dict[str, IT] = {})[source]¶

Bases: sdmx.model.MaintainableArtefact, Generic[sdmx.model.IT]

SDMX-IM Item Scheme.

The IM states that ItemScheme “defines a set of Items…” To simplify indexing/retrieval, this implementation uses a dict for the items attribute, in which the keys are the id of the Item.

Because this may change in future versions of pandaSDMX, user code should not access items directly. Instead, use the getattr() and indexing features of ItemScheme, or the public methods, to access and manipulate Items:

>>> foo = ItemScheme(id='foo')
>>> bar = Item(id='bar')
>>> foo.append(bar)
>>> foo
<ItemScheme: 'foo', 1 items>
>>> (foo.bar is bar) and (foo['bar'] is bar) and (bar in foo)
True

append(item: IT)[source]¶

Add item to the ItemScheme.

Parameters: item (same class as items) – Item to add.

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two ItemSchemes are the same if:

MaintainableArtefact.compare() is True, and
their items have the same keys, and corresponding Items compare equal.

Parameters: strict (bool, optional) – Passed to compare() and MaintainableArtefact.compare().

classmethod convert_to_dict(v)[source]¶

extend(items: Iterable[IT])[source]¶

Extend the ItemScheme with members of items.

Parameters: items (iterable of Item) – Elements must be of the same class as items.

get_hierarchical(id: str) → IT[source]¶: Get an Item by its hierarchical_id.

is_partial: Optional[bool]¶

items: Dict[str, IT]¶: Members of the ItemScheme. Both ItemScheme and Item are abstract classes. Concrete classes are paired: for example, a Codelist contains Codes.

setdefault(obj=None, **kwargs) → IT[source]¶

Retrieve the item name, or add it with kwargs and return it.

The returned object is a reference to an object in the ItemScheme, and is of the appropriate class.

class sdmx.model.Key(arg: Mapping = None, *, attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue] = {}, described_by: sdmx.model.DimensionDescriptor = None, values: sdmx.util.DictLike[str, sdmx.model.KeyValue] = {})[source]¶

Bases: sdmx.util.BaseModel

SDMX Key class.

The constructor takes an optional list of keyword arguments; the keywords are used as Dimension or Attribute IDs, and the values as KeyValues.

For convience, the values of the key may be accessed directly:

>>> k = Key(foo=1, bar=2)
>>> k.values['foo']
1
>>> k['foo']
1

Parameters

dsd (DataStructureDefinition) – If supplied, the dimensions and attributes are used to separate the kwargs into KeyValues and AttributeValues. The kwarg for described_by, if any, must be dimensions or appear in group_dimensions.
kwargs – Dimension and Attribute IDs, and/or the class properties.

attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue]¶

copy(arg=None, **kwargs)[source]¶

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters

include – fields to include in new model
exclude – fields to exclude from new model, as with values this takes precedence over include
update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
deep – set to True to make a deep copy of the model

Returns

new model instance

described_by: Optional[sdmx.model.DimensionDescriptor]¶

get_values()[source]¶

order(value=None)[source]¶

values: sdmx.util.DictLike[str, sdmx.model.KeyValue]¶: Individual KeyValues that describe the key.

class sdmx.model.KeyValue(*args, id: str, value: Any = None, value_for: sdmx.model.Dimension = None)[source]¶

Bases: sdmx.util.BaseModel

One value in a multi-dimensional Key.

id: str¶

value: Any¶: The actual value.

value_for: Optional[sdmx.model.Dimension]¶

class sdmx.model.MaintainableArtefact(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None)[source]¶

Bases: sdmx.model.VersionableArtefact

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two MaintainableArtefacts are the same if:

VersionableArtefact.compare() is True, and
they have the same maintainer.

Parameters: strict (bool, optional) – Passed to compare() and VersionableArtefact.compare().

is_external_reference: Optional[bool]¶: True if the content of the object is held externally; i.e., not the current Message.

is_final: Optional[bool]¶: True if the object is final; otherwise it is in a draft state.

maintainer: Optional[sdmx.model.Agency]¶: Association to the Agency responsible for maintaining the object.

service_url: Optional[str]¶: URL of an SDMX-compliant web service from which the object can be retrieved.

structure_url: Optional[str]¶: URL of an SDMX-ML document containing the object.

class sdmx.model.MeasureDescriptor(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, components: List[CT] = [], auto_order: int = 1)[source]¶

Bases: sdmx.model.ComponentList[sdmx.model.PrimaryMeasure]

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

components: List[CT]¶

id: str¶: Unique identifier of the object.

uri: Optional[str]¶: Universal resource identifier that may or may not be resolvable.

urn: Optional[str]¶: Universal resource name. For use in SDMX registries; all registered objects have a URN.

urn_group: Dict¶

class sdmx.model.MeasureDimension(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, concept_identity: sdmx.model.Concept = None, local_representation: sdmx.model.Representation = None, order: int = None)[source]¶

Bases: sdmx.model.DimensionComponent

SDMX-IM MeasureDimension.

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

concept_identity: Optional[sdmx.model.Concept]¶

id: str¶: Unique identifier of the object.

local_representation: Optional[sdmx.model.Representation]¶

order: Optional[int]¶

uri: Optional[str]¶: Universal resource identifier that may or may not be resolvable.

urn: Optional[str]¶: Universal resource name. For use in SDMX registries; all registered objects have a URN.

urn_group: Dict¶

class sdmx.model.MemberSelection(*, included: bool = True, values_for: sdmx.model.Component, values: List[sdmx.model.SelectionValue] = [])[source]¶

Bases: sdmx.util.BaseModel

included: bool¶

values: List[sdmx.model.SelectionValue]¶: Value(s) included in the selection. Note that the name of this attribute is not stated in the IM, so ‘values’ is chosen for the implementation in this package.

values_for: sdmx.model.Component¶

class sdmx.model.MemberValue(*, value: str, cascade_values: bool = None)[source]¶

Bases: sdmx.model.SelectionValue

cascade_values: Optional[bool]¶

value: str¶

class sdmx.model.NameableArtefact(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =)[source]¶

Bases: sdmx.model.IdentifiableArtefact

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two NameableArtefacts are the same if:

IdentifiableArtefact.compare() is True, and
they have the same name and description.

Parameters: strict (bool, optional) – Passed to compare() and IdentifiableArtefact.compare().

description: sdmx.model.InternationalString¶: Multi-lingual description of the object.

name: sdmx.model.InternationalString¶: Multi-lingual name of the object.

class sdmx.model.Observation(*, attached_attribute: sdmx.util.DictLike[str, sdmx.model.AttributeValue] = {}, series_key: sdmx.model.SeriesKey = None, dimension: sdmx.model.Key = None, value: Optional[Union[Any, sdmx.model.Code]] = None, value_for: sdmx.model.PrimaryMeasure = None, group_keys: Set[sdmx.model.GroupKey] = {})[source]¶

Bases: sdmx.util.BaseModel

SDMX-IM Observation.

This class also implements the spec classes ObservationValue, UncodedObservationValue, and CodedObservation.

attached_attribute: sdmx.util.DictLike[str, sdmx.model.AttributeValue]¶

property attrib¶: Return a view of combined observation, series & group attributes.

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two Observations are equal if:

their dimension, value, series_key, and value_for are all equal,
their corresponding attached_attribute and group_keys are all equal.

Parameters: strict (bool, optional) – Passed to compare().

property dim¶

dimension: Optional[sdmx.model.Key]¶: Key for dimension(s) varying at the observation level.

group_keys: Set[sdmx.model.GroupKey]¶: sdmx extension not in the IM.

property key¶: Return the entire key, including KeyValues at the series level.

series_key: Optional[sdmx.model.SeriesKey]¶

value: Optional[Union[Any, sdmx.model.Code]]¶: Data value.

value_for: Optional[sdmx.model.PrimaryMeasure]¶

class sdmx.model.Organisation(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, parent: Optional[Union[Item, ItemScheme]] = None, child: List[Item] = [], contact: List[sdmx.model.Contact] = [])[source]¶

Bases: sdmx.model.Item

contact: List[sdmx.model.Contact]¶

class sdmx.model.OrganisationScheme[source]¶

Bases: object

SDMX-IM abstract OrganisationScheme.

sdmx.model.PACKAGE = {<class 'sdmx.model.AgencyScheme'>: 'base', <class 'sdmx.model.DataProviderScheme'>: 'base', <class 'sdmx.model.DataProvider'>: 'base', <class 'sdmx.model.Agency'>: 'base', <class 'sdmx.model.Category'>: 'categoryscheme', <class 'sdmx.model.CategoryScheme'>: 'categoryscheme', <class 'sdmx.model.Categorisation'>: 'categoryscheme', <class 'sdmx.model.Code'>: 'codelist', <class 'sdmx.model.Codelist'>: 'codelist', <class 'sdmx.model.ConceptScheme'>: 'conceptscheme', <class 'sdmx.model.Concept'>: 'conceptscheme', <class 'sdmx.model.StructureUsage'>: 'datastructure', <class 'sdmx.model.DataflowDefinition'>: 'datastructure', <class 'sdmx.model.DataStructureDefinition'>: 'datastructure', <class 'sdmx.model.ProvisionAgreement'>: 'registry', <class 'sdmx.model.ContentConstraint'>: 'registry'}¶: The SDMX-IM defines ‘packages’; these are used in URNs.

class sdmx.model.Period(*, is_inclusive: bool, period: datetime.datetime)[source]¶

Bases: sdmx.util.BaseModel

is_inclusive: bool¶

period: datetime.datetime¶

class sdmx.model.PrimaryMeasure(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, concept_identity: sdmx.model.Concept = None, local_representation: sdmx.model.Representation = None)[source]¶

Bases: sdmx.model.Component

SDMX-IM PrimaryMeasure.

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

concept_identity: Optional[sdmx.model.Concept]¶

id: str¶: Unique identifier of the object.

local_representation: Optional[sdmx.model.Representation]¶

uri: Optional[str]¶: Universal resource identifier that may or may not be resolvable.

urn: Optional[str]¶: Universal resource name. For use in SDMX registries; all registered objects have a URN.

urn_group: Dict¶

class sdmx.model.ProvisionAgreement(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, structure_usage: sdmx.model.StructureUsage = None, data_provider: sdmx.model.DataProvider = None)[source]¶

Bases: sdmx.model.MaintainableArtefact, sdmx.model.ConstrainableArtefact

data_provider: Optional[sdmx.model.DataProvider]¶

structure_usage: Optional[sdmx.model.StructureUsage]¶

class sdmx.model.QueryDatasource(*, url: str)[source]¶

Bases: sdmx.model.Datasource

url: str¶

class sdmx.model.RESTDatasource(*, url: str)[source]¶

Bases: sdmx.model.QueryDatasource

url: str¶

class sdmx.model.RangePeriod(*, start: sdmx.model.Period, end: sdmx.model.Period)[source]¶

Bases: sdmx.model.TimeRangeValue

end: sdmx.model.Period¶

start: sdmx.model.Period¶

class sdmx.model.ReportingYearStartDay(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, concept_identity: sdmx.model.Concept = None, local_representation: sdmx.model.Representation = None, related_to: sdmx.model.AttributeRelationship = None, usage_status: sdmx.model.UsageStatus = None)[source]¶

Bases: sdmx.model.DataAttribute

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

concept_identity: Optional[sdmx.model.Concept]¶

id: str¶: Unique identifier of the object.

local_representation: Optional[sdmx.model.Representation]¶

related_to: Optional[sdmx.model.AttributeRelationship]¶

uri: Optional[str]¶: Universal resource identifier that may or may not be resolvable.

urn: Optional[str]¶: Universal resource name. For use in SDMX registries; all registered objects have a URN.

urn_group: Dict¶

usage_status: Optional[sdmx.model.UsageStatus]¶

class sdmx.model.Representation(*, enumerated: sdmx.model.ItemScheme = None, non_enumerated: List[sdmx.model.Facet] = [])[source]¶

Bases: sdmx.util.BaseModel

class Config[source]¶

Bases: object

extra = 'forbid'¶

enumerated: Optional[sdmx.model.ItemScheme]¶

non_enumerated: List[sdmx.model.Facet]¶

class sdmx.model.SelectionValue[source]¶

Bases: sdmx.util.BaseModel

SDMX-IM SelectionValue.

class sdmx.model.SeriesKey(arg: Mapping = None, *, attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue] = {}, described_by: sdmx.model.DimensionDescriptor = None, values: sdmx.util.DictLike[str, sdmx.model.KeyValue] = {}, group_keys: Set[sdmx.model.GroupKey] = {})[source]¶

Bases: sdmx.model.Key

property group_attrib¶: Return a view of combined group attributes.

group_keys: Set[sdmx.model.GroupKey]¶: sdmx extension not in the IM.

class sdmx.model.SimpleDatasource(*, url: str)[source]¶

Bases: sdmx.model.Datasource

url: str¶

class sdmx.model.Structure(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, grouping: sdmx.model.ComponentList = None)[source]¶

Bases: sdmx.model.MaintainableArtefact

grouping: Optional[sdmx.model.ComponentList]¶

class sdmx.model.StructureSpecificDataSet(*, annotations: List[sdmx.model.Annotation] = [], action: sdmx.model.ActionType = None, attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue] = {}, valid_from: str = None, structured_by: sdmx.model.DataStructureDefinition = None, obs: List[sdmx.model.Observation] = [], series: sdmx.util.DictLike[sdmx.model.SeriesKey, List[sdmx.model.Observation]] = {}, group: sdmx.util.DictLike[sdmx.model.GroupKey, List[sdmx.model.Observation]] = {})[source]¶

Bases: sdmx.model.DataSet

SDMX-IM StructureSpecificDataSet.

action: Optional[sdmx.model.ActionType]¶

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue]¶

group: sdmx.util.DictLike[sdmx.model.GroupKey, List[sdmx.model.Observation]]¶: Map of group key → list of observations. sdmx extension not in the IM.

obs: List[sdmx.model.Observation]¶: All observations in the DataSet.

series: sdmx.util.DictLike[sdmx.model.SeriesKey, List[sdmx.model.Observation]]¶: Map of series key → list of observations. sdmx extension not in the IM.

structured_by: Optional[sdmx.model.DataStructureDefinition]¶

valid_from: Optional[str]¶

class sdmx.model.StructureSpecificTimeSeriesDataSet(*, annotations: List[sdmx.model.Annotation] = [], action: sdmx.model.ActionType = None, attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue] = {}, valid_from: str = None, structured_by: sdmx.model.DataStructureDefinition = None, obs: List[sdmx.model.Observation] = [], series: sdmx.util.DictLike[sdmx.model.SeriesKey, List[sdmx.model.Observation]] = {}, group: sdmx.util.DictLike[sdmx.model.GroupKey, List[sdmx.model.Observation]] = {})[source]¶

Bases: sdmx.model.DataSet

SDMX-IM StructureSpecificTimeSeriesDataSet.

action: Optional[sdmx.model.ActionType]¶

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

attrib: sdmx.util.DictLike[str, sdmx.model.AttributeValue]¶

group: sdmx.util.DictLike[sdmx.model.GroupKey, List[sdmx.model.Observation]]¶: Map of group key → list of observations. sdmx extension not in the IM.

obs: List[sdmx.model.Observation]¶: All observations in the DataSet.

series: sdmx.util.DictLike[sdmx.model.SeriesKey, List[sdmx.model.Observation]]¶: Map of series key → list of observations. sdmx extension not in the IM.

structured_by: Optional[sdmx.model.DataStructureDefinition]¶

valid_from: Optional[str]¶

class sdmx.model.StructureUsage(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None, is_final: bool = None, is_external_reference: bool = None, service_url: str = None, structure_url: str = None, maintainer: Agency = None, structure: sdmx.model.Structure = None)[source]¶

Bases: sdmx.model.MaintainableArtefact

structure: Optional[sdmx.model.Structure]¶

class sdmx.model.TimeDimension(*args, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, concept_identity: sdmx.model.Concept = None, local_representation: sdmx.model.Representation = None, order: int = None)[source]¶

Bases: sdmx.model.DimensionComponent

SDMX-IM TimeDimension.

annotations: List[sdmx.model.Annotation]¶

Annotations of the object.

pandaSDMX implementation: The IM does not specify the name of this feature.

concept_identity: Optional[sdmx.model.Concept]¶

id: str¶: Unique identifier of the object.

local_representation: Optional[sdmx.model.Representation]¶

order: Optional[int]¶

uri: Optional[str]¶: Universal resource identifier that may or may not be resolvable.

urn: Optional[str]¶: Universal resource name. For use in SDMX registries; all registered objects have a URN.

urn_group: Dict¶

sdmx.model.TimeKeyValue¶: alias of sdmx.model.KeyValue

class sdmx.model.TimeRangeValue[source]¶

Bases: sdmx.model.SelectionValue

SDMX-IM TimeRangeValue.

class sdmx.model.UsageStatus(value)¶

Bases: enum.Enum

An enumeration.

conditional = 2¶

mandatory = 1¶

class sdmx.model.VersionableArtefact(*, annotations: List[sdmx.model.Annotation] = [], id: str = '', uri: str = None, urn: str = None, urn_group: Dict = {}, name: sdmx.model.InternationalString =, description: sdmx.model.InternationalString =, version: str = None, valid_from: str = None, valid_to: str = None)[source]¶

Bases: sdmx.model.NameableArtefact

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two VersionableArtefacts are the same if:

NameableArtefact.compare() is True, and
they have the same version.

Parameters: strict (bool, optional) – Passed to compare() and NameableArtefact.compare().

valid_from: Optional[str]¶: Date from which the version is valid.

valid_to: Optional[str]¶: Date from which the version is superseded.

version: Optional[str]¶: A version string following an agreed convention.

sdmx.model.get_class(name, package=None)[source]¶: Return a class object for string cls and package names.

sdmx.model.parent_class(cls)[source]¶

Return the class that contains objects of type cls.

E.g. if cls is PrimaryMeasure, returns MeasureDescriptor.

sdmx.model.value_for_dsd_ref(kind, args, kwargs)[source]¶: Maybe replace a string ‘value_for’ in kwargs with a DSD reference.

`reader`: Parsers for SDMX file formats¶

SDMX-ML¶

sdmx supports the several types of SDMX-ML messages.

SDMXML v2.1 reader.

class sdmx.reader.xml.Reader[source]¶

annotable(cls, elem, **kwargs)[source]¶

Create a AnnotableArtefact of cls from elem and kwargs.

Collects all parsed <com:Annotation>.

content_types: List[str] = ['application/xml', 'application/vnd.sdmx.genericdata+xml', 'application/vnd.sdmx.structure+xml', 'application/vnd.sdmx.structurespecificdata+xml', 'text/xml']¶: List of HTTP content types handled by the reader.

classmethod detect(content)[source]¶

Detect whether the reader can handle content.

Returns: True if the reader can handle the content.
Return type: bool

get_single(cls_or_name: Union[Type, str], id: Optional[str] = None, subclass: bool = False) → Optional[Any][source]¶

Return a reference to an object while leaving it in its stack.

Always returns 1 object. Returns None if no matching object exists, or if 2 or more objects meet the conditions.

If id is given, only return an IdentifiableArtefact with the matching ID.

If cls_or_name is a class and subclass is True; check all objects in the stack cls_or_name or any stack for a subclass of this class.

identifiable(cls, elem, **kwargs)[source]¶: Create a IdentifiableArtefact of cls from elem and kwargs.

maintainable(cls, elem, **kwargs)[source]¶

Create or retrieve a MaintainableArtefact of cls from elem and kwargs.

Following the SDMX-IM class hierachy, maintainable() calls nameable(), which in turn calls identifiable(), etc. (Since no concrete class is versionable but not maintainable, no separate method is created, for better performance). For all of these methods:

Already-parsed items are removed from the stack only if elem is not None.
kwargs (e.g. ‘id’) take precedence over any values retrieved from attributes of elem.

If elem is None, maintainable() returns a MaintainableArtefact with the is_external_reference attribute set to True. Subsequent calls with the same object ID will return references to the same object.

nameable(cls, elem, **kwargs)[source]¶

Create a NameableArtefact of cls from elem and kwargs.

Collects all parsed InternationalString localizations of <com:Name> and <com:Description>.

peek(cls_or_name: Union[Type, str])[source]¶: Get the object at the top of stack cls_or_name without removing it.

pop_all(cls_or_name: Union[Type, str], subclass=False) → Iterable[source]¶

Pop all objects from stack cls_or_name and return.

If cls_or_name is a class and subclass is True; return all objects in the stack cls_or_name or any stack for a subclass of this class.

pop_resolved_ref(cls_or_name: Union[Type, str])[source]¶: Pop a reference to cls_or_name and resolve it.

pop_single(cls_or_name: Union[Type, str])[source]¶: Pop a single object from the stack for cls_or_name and return.

push(stack_or_obj, obj=None)[source]¶: Push an object onto a stack.

read_message(source, dsd: Optional[sdmx.model.DataStructureDefinition] = None) → sdmx.message.Message [source]¶

Read message from source.

Parameters

source (file-like) – Message content.
dsd (DataStructureDefinition, optional) – DSD for aid in reading source.

Returns

An instance of a Message subclass.

Return type

Message

resolve(ref)[source]¶: Resolve the Reference instance ref, returning the referred object.

stash(*stacks)[source]¶: Temporarily hide all objects in the given stacks.

suffixes: List[str] = ['.xml']¶: List of file name suffixes handled by the reader.

unstash()[source]¶

Restore the objects hidden by the last stash() call to their stacks.

Calls to stash() and unstash() should be matched 1-to-1; if the latter outnumber the former, this will raise KeyError.

SDMX-JSON¶

class sdmx.reader.json.Reader[source]¶

Read SDMXJSON 2.1 and expose it as instances from sdmx.model.

content_types: List[str] = ['application/vnd.sdmx.draft-sdmx-json+json', 'draft-sdmx-json', 'text/json']¶: List of HTTP content types handled by the reader.

classmethod detect(content)[source]¶

Detect whether the reader can handle content.

Returns: True if the reader can handle the content.
Return type: bool

read_dataset(root, ds_key)[source]¶

read_message(source, dsd=None)[source]¶

Read message from source.

Parameters

source (file-like) – Message content.
dsd (DataStructureDefinition, optional) – DSD for aid in reading source.

Returns

An instance of a Message subclass.

Return type

Message

read_obs(root, series_key=None, base_key=None)[source]¶

suffixes: List[str] = ['.json']¶: List of file name suffixes handled by the reader.

Reader API¶

sdmx.reader.CTYPE_READER: Mapping[str, Type] = {'application/vnd.sdmx.draft-sdmx-json+json': <class 'sdmx.reader.json.Reader'>, 'application/vnd.sdmx.genericdata+xml': <class 'sdmx.reader.xml.Reader'>, 'application/vnd.sdmx.structure+xml': <class 'sdmx.reader.xml.Reader'>, 'application/vnd.sdmx.structurespecificdata+xml': <class 'sdmx.reader.xml.Reader'>, 'application/xml': <class 'sdmx.reader.xml.Reader'>, 'draft-sdmx-json': <class 'sdmx.reader.json.Reader'>, 'text/json': <class 'sdmx.reader.json.Reader'>, 'text/xml': <class 'sdmx.reader.xml.Reader'>}¶: Mapping from HTTP content type to reader class.

sdmx.reader.READERS: List[Type] = [<class 'sdmx.reader.json.Reader'>, <class 'sdmx.reader.xml.Reader'>]¶: Reader classes

sdmx.reader.SUFFIX_READER: Mapping[str, Type] = {'.json': <class 'sdmx.reader.json.Reader'>, '.xml': <class 'sdmx.reader.xml.Reader'>}¶: Mapping from file path suffix to reader class.

sdmx.reader.detect_content_reader(content)[source]¶

Return a reader class for content.

The BaseReader.detect() method for each class in READERS is called; if a reader signals that it is compatible with content, then that class is returned.

Raises: ValueError – If no reader class matches.

sdmx.reader.get_reader_for_content_type(ctype)[source]¶

Return a reader class for HTTP content type content.

Raises: ValueError – If no reader class matches.

`writer`: Convert `sdmx` objects to other formats¶

`writer.pandas`: Convert to `pandas` objects¶

Changed in version 1.0: sdmx.to_pandas() handles all types of objects, replacing the earlier, separate data2pandas and structure2pd writers.

to_pandas() implements a dispatch pattern according to the type of obj. Some of the internal methods take specific arguments and return varying values. These arguments can be passed to to_pandas() when obj is of the appropriate type:

`sdmx.writer.pandas.write_dataset`(obj[, …])	Convert `DataSet`.
`sdmx.writer.pandas.write_datamessage`(obj, *args)	Convert `DataMessage`.
`sdmx.writer.pandas.write_itemscheme`(obj[, …])	Convert `ItemScheme`.
`sdmx.writer.pandas.write_structuremessage`(obj)	Convert `StructureMessage`.
`sdmx.writer.pandas.DEFAULT_RTYPE`	Default return type for `write_dataset()` and similar methods.

Other objects are converted as follows:

Component

The id attribute of the concept_identity is returned.

DataMessage

The DataSet or data sets within the Message are converted to pandas objects. Returns:

pandas.Series or pandas.DataFrame, if obj has only one data set.
list of (Series or DataFrame), if obj has more than one data set.

dict

The values of the mapping are converted individually. If the resulting values are str or Series with indexes that share the same name, then they are converted to a Series, possibly with a pandas.MultiIndex. Otherwise, a DictLike is returned.

DimensionDescriptor

The components of the DimensionDescriptor are written.

list

For the following obj, returns Series instead of a list:

a list of Observation: the Observations are written using write_dataset().
a list with only 1 DataSet (e.g. the data attribute of DataMessage): the Series for the single element is returned.
a list of SeriesKey: the key values (but no data) are returned.

NameableArtefact

The name attribute of obj is returned.

sdmx.writer.pandas.DEFAULT_RTYPE = 'rows'¶: Default return type for write_dataset() and similar methods. Either ‘compat’ or ‘rows’. See the ref:HOWTO <howto-rtype>.

sdmx.writer.pandas.write_datamessage(obj: sdmx.message.DataMessage, *args, rtype=None, **kwargs)[source]¶

Convert DataMessage.

Parameters

rtype ('compat' or 'rows', optional) – Data type to return; default DEFAULT_RTYPE. See the HOWTO.
kwargs – Passed to write_dataset() for each data set.

Returns

pandas.Series or pandas.DataFrame – if obj has only one data set.
list of (pandas.Series or pandas.DataFrame) – if obj has more than one data set.

sdmx.writer.pandas.write_dataset(obj: sdmx.model.DataSet, attributes='', dtype=<class 'numpy.float64'>, constraint=None, datetime=False, **kwargs)[source]¶

Convert DataSet.

See the walkthrough for examples of using the datetime argument.

Parameters

obj (DataSet or iterable of Observation) –
attributes (str) –
Types of attributes to return with the data. A string containing zero or more of:
- 'o': attributes attached to each Observation .
- 's': attributes attached to any (0 or 1) SeriesKey associated with each Observation.
- 'g': attributes attached to any (0 or more) GroupKey associated with each Observation.
- 'd': attributes attached to the DataSet containing the Observations.
dtype (str or numpy.dtype or None) – Datatype for values. If None, do not return the values of a series. In this case, attributes must not be an empty string so that some attribute is returned.
constraint (ContentConstraint, optional) – If given, only Observations included by the constraint are returned.
datetime (bool or str or or .Dimension or dict, optional) –
If given, return a DataFrame with a DatetimeIndex or PeriodIndex as the index and all other dimensions as columns. Valid datetime values include:
- bool: if True, determine the time dimension automatically by detecting a TimeDimension.
- str: ID of the time dimension.
- Dimension: the matching Dimension is the time dimension.
- dict: advanced behaviour. Keys may include:
  - dim (Dimension or str): the time dimension or its ID.
  - axis ({0 or ‘index’, 1 or ‘columns’}): axis on which to place the time dimension (default: 0).
  - freq (True or str or Dimension): produce pandas.PeriodIndex. If str, the ID of a Dimension containing a frequency specification. If a Dimension, the specified dimension is used for the frequency specification.
    
    Any Dimension used for the frequency specification is does not appear in the returned DataFrame.

Returns

pandas.DataFrame –
- if attributes is not '', a data frame with one row per Observation, value as the first column, and additional columns for each attribute;
- if datetime is given, various layouts as described above; or
- if _rtype (passed from write_datamessage()) is ‘compat’, various layouts as described in the HOWTO.
pandas.Series with pandas.MultiIndex – Otherwise.

sdmx.writer.pandas.write_itemscheme(obj: sdmx.model.ItemScheme, locale='en')[source]¶

Convert ItemScheme.

Parameters: locale (str, optional) – Locale for names to return.
Returns
Return type: pandas.Series

sdmx.writer.pandas.write_structuremessage(obj: sdmx.message.StructureMessage, include=None, **kwargs)[source]¶

Convert StructureMessage.

Parameters

obj (StructureMessage) –
include (iterable of str or str, optional) – One or more of the attributes of the StructureMessage ( ‘category_scheme’, ‘codelist’, etc.) to transform.
kwargs – Passed to write() for each attribute.

Returns

Keys are StructureMessage attributes; values are pandas objects.

Return type

DictLike

Todo

Support selection of language for conversion of InternationalString.

`writer.xml`: Write to SDMX-ML¶

New in version 1.1.

See to_xml().

`session`: Access SDMX REST web services¶

class sdmx.session.Session(timeout=30.1, **kwargs)[source]¶

requests.Session subclass with optional caching.

If requests_cache is installed, this class caches responses.

Parameters: timeout (float) – Timeout in seconds, used for every request.
Other Parameters: kwargs – Values for any attributes of requests.Session, e.g. proxies, stream, or verify.

class sdmx.session.ResponseIO(response, tee=None)[source]¶

Buffered wrapper for requests.Response with optional file output.

ResponseIO wraps a requests.Response object’s ‘content’ attribute, providing a file-like object from which bytes can be read() incrementally.

Parameters

response (requests.Response) – HTTP response to wrap.
tee (binary, writable io.BufferedIOBase, defaults to io.BytesIO()) – tee is exposed as self.tee and not closed explicitly.

`source`: Features of SDMX data sources¶

This module defines Source and some utility functions. For built-in subclasses of Source used to provide sdmx’s built-in support for certain data sources, see Data sources.

class sdmx.source.Source(*, id: str, url: str, name: str, headers: Dict[str, Any] = {}, data_content_type: sdmx.source.DataContentType = <DataContentType.XML: 1>, supports: Dict[Union[str, sdmx.util.Resource], bool] = {<Resource.data: 'data'>: True})[source]¶

SDMX-IM RESTDatasource.

This class describes the location and features supported by an SDMX data source. Subclasses may override the hooks in order to handle specific features of different REST web services:

`handle_response`(response, content)	Handle response content of unknown type.
`finish_message`(message, request, **kwargs)	Postprocess retrieved message.
`modify_request_args`(kwargs)	Modify arguments used to build query URL.

data_content_type: sdmx.source.DataContentType¶: DataContentType indicating the type of data returned by the source.

finish_message(message, request, **kwargs)[source]¶

Postprocess retrieved message.

This hook is called by Client.get() after a Message object has been successfully parsed from the query response.

See estat.Source.finish_message() for an example implementation.

handle_response(response, content)[source]¶

Handle response content of unknown type.

This hook is called by Client.get() only when the content cannot be parsed as XML or JSON.

See estat.Source.handle_response() and sgr.Source.handle_response() for example implementations.

id: str¶: ID of the data source

modify_request_args(kwargs)[source]¶

Modify arguments used to build query URL.

This hook is called by Client.get() to modify the keyword arguments before the query URL is built.

The default implementation handles requests for ‘structure-specific data’ by adding an HTTP ‘Accepts:’ header when a ‘dsd’ is supplied as one of the kwargs.

See sgr.Source.modify_request_args() for an example override.

Returns
Return type: None

name: str¶: Human-readable name of the data source

supports: Dict[Union[str, sdmx.util.Resource], bool]¶

Mapping from Resource to bool indicating support for SDMX REST API features. Two additional keys are valid:

'preview'=True if the source supports ?detail=serieskeysonly. See preview_data().
'structure-specific data'=True if the source can return structure- specific data messages.

url: str¶: Base URL for queries

sdmx.source.list_sources()[source]¶

Return a sorted list of valid source IDs.

These can be used to create Client instances.

sdmx.source.load_package_sources()[source]¶: Discover all sources listed in sources.json.

`util`: Utilities¶

class sdmx.util.DictLike[source]¶

Bases: collections.OrderedDict, MutableMapping[sdmx.util.KT, sdmx.util.VT]

Container with features of a dict & list, plus attribute access.

compare(other, strict=True)[source]¶

Return True if self is the same as other.

Two DictLike instances are identical if they contain the same set of keys, and corresponding values compare equal.

Parameters: strict (bool, optional) – Passed to compare() for the values.

class sdmx.util.Resource(value)[source]¶

Bases: str, enum.Enum

Enumeration of SDMX REST API endpoints.

`Enum` member	`sdmx.model` class
`categoryscheme`	`CategoryScheme`
`codelist`	`Codelist`
`conceptscheme`	`ConceptScheme`
`data`	`DataSet`
`dataflow`	`DataflowDefinition`
`datastructure`	`DataStructureDefinition`
`provisionagreement`	`ProvisionAgreement`

classmethod from_obj(obj)[source]¶: Return an enumeration value based on the class of obj.

sdmx.util.compare(attr, a, b, strict: bool) → bool [source]¶

Return True if a.attr == b.attr.

If strict is False, None is permissible as a or b; otherwise,

sdmx.util.direct_fields(cls) → Mapping[str, pydantic.fields.ModelField][source]¶

Return the pydantic fields defined on obj or its class.

This is like the __fields__ attribute, but excludes the fields defined on any parent class(es).

sdmx.util.get_args(tp) → Tuple[Any, …][source]¶: For Python <3.8.

API reference¶

Top-level methods and classes¶

`message`: SDMX messages¶

`model`: SDMX Information Model¶

`reader`: Parsers for SDMX file formats¶

SDMX-ML¶

SDMX-JSON¶

Reader API¶

`writer`: Convert `sdmx` objects to other formats¶

`writer.pandas`: Convert to `pandas` objects¶

`writer.xml`: Write to SDMX-ML¶

`session`: Access SDMX REST web services¶

`source`: Features of SDMX data sources¶

`util`: Utilities¶

sdmx

Navigation

Related Topics

API reference¶

Top-level methods and classes¶

message: SDMX messages¶

model: SDMX Information Model¶

reader: Parsers for SDMX file formats¶

SDMX-ML¶

SDMX-JSON¶

Reader API¶

writer: Convert sdmx objects to other formats¶

writer.pandas: Convert to pandas objects¶

writer.xml: Write to SDMX-ML¶

session: Access SDMX REST web services¶

source: Features of SDMX data sources¶

util: Utilities¶

`message`: SDMX messages¶

`model`: SDMX Information Model¶

`reader`: Parsers for SDMX file formats¶

`writer`: Convert `sdmx` objects to other formats¶

`writer.pandas`: Convert to `pandas` objects¶

`writer.xml`: Write to SDMX-ML¶

`session`: Access SDMX REST web services¶

`source`: Features of SDMX data sources¶

`util`: Utilities¶