Read SDMX file formats

SDMX-ML

sdmx.reader.xml supports the several types of SDMX-ML messages.

Implementation details:

• The collections of StructureMessage (e.g. StructureMessage.codelist) are implemented by sdmx as DictLike, with str keys, for convenience; the standard would imply these could be other collections, such as a simple list. The format of the keys in each collection depends on the content of the message parsed by reader.xml:

  • Simply {object.id} (IdentifiableArtefact.id) of the contained objects, if these are unique;

  • Otherwise {maintainer.id}:{object.id} (using the Agency id) if these are unique;

  • Otherwise {maintainer.id}:{object.id}({object.version}) (using the VersionableArtefact.version).

  This ensures that all objects in a parsed message are accessible.

exception sdmx.reader.xml.XMLParseError

xml.Reader is unable to parse a message.

SDMX-ML v2.1 reader.

class sdmx.reader.xml.v21.Reader

SDMX-ML 2.1 reader.

class Reference(reader, elem, cls_hint=None)

format: ClassVar['types.ModuleType'] = <module 'sdmx.format.xml.v21' from '/home/docs/checkouts/readthedocs.org/user_builds/sdmx1/envs/stable/lib/python3.12/site-packages/sdmx/format/xml/v21.py'>

Reference to the module defining the format read.

media_types: ClassVar[List[MediaType]] = [application/vnd.sdmx.generic+xml; version=2.1, application/vnd.sdmx.genericdata+xml; version=2.1, application/vnd.sdmx.genericmetadata+xml; version=2.1, application/vnd.sdmx.generictimeseriesdata+xml; version=2.1, application/vnd.sdmx.schema+xml; version=2.1, application/vnd.sdmx.structure+xml; version=2.1, application/vnd.sdmx.structurespecificdata+xml; version=2.1, application/vnd.sdmx.structurespecificmetadata+xml; version=2.1, application/vnd.sdmx.structurespecifictimeseriesdata+xml; version=2.1, application/xml; version=2.1, text/xml; version=2.1]

List of media types handled by the reader.

model: ClassVar['types.ModuleType'] = <module 'sdmx.model.v21' from '/home/docs/checkouts/readthedocs.org/user_builds/sdmx1/envs/stable/lib/python3.12/site-packages/sdmx/model/v21.py'>

Reference to the module defining the information model read.

xml_version: ClassVar[Version] = 2.1

SDMX-ML version handled by this reader.

class sdmx.reader.xml.v21.Reference(reader, elem, cls_hint=None)

sdmx.reader.xml.v21.add_mds_events(reader: Reader, mds: MetadataStructureDefinition)

Add parser events for structure-specific metadata.

SDMX-ML 3.0.0 reader.

class sdmx.reader.xml.v30.Reader

SDMX-ML 3.0 reader.

class Reference(reader, elem, cls_hint=None)

Parse SDMX-ML 3.0 references.

format: ClassVar['types.ModuleType'] = <module 'sdmx.format.xml.v30' from '/home/docs/checkouts/readthedocs.org/user_builds/sdmx1/envs/stable/lib/python3.12/site-packages/sdmx/format/xml/v30.py'>

Reference to the module defining the format read.

media_types: ClassVar[List[MediaType]] = [application/vnd.sdmx.data+xml; version=3.0.0, application/vnd.sdmx.structure+xml; version=3.0.0]

List of media types handled by the reader.

model: ClassVar['types.ModuleType'] = <module 'sdmx.model.v30' from '/home/docs/checkouts/readthedocs.org/user_builds/sdmx1/envs/stable/lib/python3.12/site-packages/sdmx/model/v30.py'>

Reference to the module defining the information model read.

xml_version: ClassVar[Version] = 3

SDMX-ML version handled by this reader.

class sdmx.reader.xml.v30.Reference(reader, elem, cls_hint=None)

Parse SDMX-ML 3.0 references.

SDMX-JSON

SDMX-JSON v2.1 reader

class sdmx.reader.json.Reader

Read SDMX-JSON and expose it as instances from sdmx.model.

classmethod detect(content)

Detect whether the reader can handle content.

Returns:

True if the reader can handle the content.

Return type:

bool

media_types: ClassVar[List[MediaType]] = [application/vnd.sdmx.data+json; version=1.0.0, application/vnd.sdmx.structure+json; version=1.0.0, application/vnd.sdmx.draft-sdmx-json+json; version=1.0.0, draft-sdmx-json; version=1.0.0, text/json; version=1.0.0]

List of media types handled by the reader.

read_dataset(root, ds_key)

read_message(source, structure=None, **kwargs)

Read message from source.

Parameters:

• source (file-like) – Message content.

• structure – DataStructure or MetadataStructure for aid in reading source.

Returns:

An instance of a Message subclass.

Return type:

Message

read_obs(root, series_key=None, base_key=None)

suffixes: ClassVar[List[str]] = ['.json']

List of file name suffixes handled by the reader.

SDMX-CSV

class sdmx.reader.csv.Reader

Stub (incomplete) implementation of a SDMX-CSV reader.

media_types: ClassVar[List[MediaType]] = [application/vnd.sdmx.data+csv; version=1.0.0, application/vnd.sdmx.metadata+csv; version=2.0.0]

List of media types handled by the reader.

read_message(source, dsd=None)

Not implemented.

suffixes: ClassVar[List[str]] = ['.csv']

List of file name suffixes handled by the reader.

Reader API

sdmx.reader.READERS = [<class 'sdmx.reader.json.Reader'>, <class 'sdmx.reader.xml.Reader'>]

Reader classes

sdmx.reader.detect_content_reader(content)

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_media_type(value)

Return a reader class for HTTP content/media type value.

Raises:

ValueError – If no reader class matches.

See also

BaseReader.media_type

sdmx.reader.get_reader_for_path(path)

Return a reader class for file path.

Raises:

ValueError – If no reader class matches.

See also

BaseReader.suffixes

sdmx.reader.read_sdmx(filename_or_obj, format=None, **kwargs)

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)

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

class sdmx.reader.base.BaseReader

classmethod detect(content: bytes) → bool

Detect whether the reader can handle content.

Returns:

True if the reader can handle the content.

Return type:

bool

classmethod handles_media_type(value: str) → bool

True if the reader can handle content/media type value.

media_types: ClassVar[List[MediaType]] = []

List of media types handled by the reader.

abstract read_message(source, structure: sdmx.model.common.Structure | None = None, **kwargs)

Read message from source.

Parameters:

• source (file-like) – Message content.

• structure – DataStructure or MetadataStructure for aid in reading source.

Returns:

An instance of a Message subclass.

Return type:

Message

suffixes: ClassVar[List[str]] = []

List of file name suffixes handled by the reader.

classmethod supports_suffix(value: str) → bool

True if the reader can handle files with suffix value.