### Install sdmx1 with optional dependencies

Source: https://sdmx1.readthedocs.io/en/latest/install

Installs sdmx1 along with specified optional dependencies for extended functionality. For example, installing with 'cache' enables caching features.

```bash
pip install sdmx[cache]
```

```bash
pip install sdmx[docs]
```

```bash
pip install sdmx[tests]
```

--------------------------------

### Install and Run Tests

Source: https://sdmx1.readthedocs.io/en/latest/install

Installs the sdmx1 package with optional test dependencies and runs the tests from the package directory.

```bash
pip install "sdmx1[tests]"
cd sdmx1
pytest
```

--------------------------------

### Install sdmx1 from source with optional dependencies

Source: https://sdmx1.readthedocs.io/en/latest/install

Installs sdmx1 from source, including specified optional dependencies. This allows for development with extended features.

```bash
pip install --editable .[cache]
```

```bash
pip install --editable .[docs]
```

```bash
pip install --editable .[tests]
```

--------------------------------

### Install sdmx1 with pip

Source: https://sdmx1.readthedocs.io/en/latest/install

Installs the sdmx1 package using pip. This is the primary method for installing the library for general use.

```bash
pip install sdmx
```

--------------------------------

### SDMX How-To Guides

Source: https://sdmx1.readthedocs.io/en/latest/index

Practical guides on using the SDMX library for various tasks, including data generation, validation, access, logging, and format conversion.

```APIDOC
How-to: Generate SDMX-ML from Python objects
Description: Guide on creating SDMX-ML files from Python objects.
URL: https://sdmx1.readthedocs.io/en/latest/howto/create.html

How-to: Validate SDMX-ML against official schemas
Description: Instructions for validating SDMX-ML files using official schemas.
URL: https://sdmx1.readthedocs.io/en/latest/howto/validate.html

How-to: Access other SDMX data sources
Description: Guide on connecting to and retrieving data from external SDMX data sources.
URL: https://sdmx1.readthedocs.io/en/latest/howto.html#access-other-sdmx-data-sources

How-to: Control logging
Description: Instructions on how to manage and control logging within the SDMX library.
URL: https://sdmx1.readthedocs.io/en/latest/howto.html#control-logging

How-to: Use the ‘references’ query parameter
Description: Explanation of how to use the 'references' query parameter for data retrieval.
URL: https://sdmx1.readthedocs.io/en/latest/howto.html#use-the-references-query-parameter

How-to: Use category schemes to explore data
Description: Guide on utilizing category schemes for data exploration.
URL: https://sdmx1.readthedocs.io/en/latest/howto.html#use-category-schemes-to-explore-data

How-to: Select data frame layouts returned by to_pandas()
Description: Instructions on choosing specific data frame layouts when converting SDMX data to pandas DataFrames.
URL: https://sdmx1.readthedocs.io/en/latest/howto.html#select-data-frame-layouts-returned-by-to_pandas

How-to: Convert SDMX data to other formats
Description: Guide on converting SDMX data into various other data formats.
URL: https://sdmx1.readthedocs.io/en/latest/howto.html#convert-sdmx-data-to-other-formats
```

--------------------------------

### SDMX How-to Guides

Source: https://sdmx1.readthedocs.io/en/latest/glossary

Guides on how to perform specific tasks with the sdmx1 library, including generating SDMX-ML from Python objects and validating SDMX-ML against official schemas.

```APIDOC
Generate SDMX-ML from Python objects:
  Instructions on creating SDMX-ML files from Python data structures.

Validate SDMX-ML against official schemas:
  Steps for validating SDMX-ML files using official schemas.
```

--------------------------------

### Install sdmx1 from source with pip

Source: https://sdmx1.readthedocs.io/en/latest/install

Installs the sdmx1 package directly from its source code using pip. This is useful for installing from a local copy or a specific version.

```bash
pip install .
```

--------------------------------

### SDMX How-to Guides

Source: https://sdmx1.readthedocs.io/en/latest/sources

Guides on how to perform common tasks with the sdmx library, including generating SDMX-ML from Python objects and validating SDMX-ML against official schemas.

```APIDOC
How to:
  - create.html: Generate SDMX-ML from Python objects.
  - validate.html: Validate SDMX-ML against official schemas.
```

--------------------------------

### Install sdmx1 from source with editable flag

Source: https://sdmx1.readthedocs.io/en/latest/install

Installs sdmx1 from source in editable mode. This is recommended for development as changes to the source code are immediately reflected without reinstallation.

```bash
pip install --editable .
```

--------------------------------

### Pre-commit Hooks Installation

Source: https://sdmx1.readthedocs.io/en/latest/dev

Installs pre-commit hooks for Git to automatically ensure code compliance with style guides before each commit.

```git
pre-commit install
```

--------------------------------

### Pytest Help

Source: https://sdmx1.readthedocs.io/en/latest/install

Displays available command-line options for pytest to control test execution.

```bash
pytest --help
```

--------------------------------

### Add Source Configuration Example

Source: https://sdmx1.readthedocs.io/en/latest/sources

Example of data structures used with the `add_source()` function, specifying data content type and supported resources for different data sources.

```json
[
{
"id":"ABS",
"data_content_type":"JSON"
},
{
"id":"UNESCO",
"supported":{"datastructure":false}
}
]
```

--------------------------------

### Install SDMX-ML Schemas - sdmx.install_schemas

Source: https://sdmx1.readthedocs.io/en/latest/api

Downloads and installs SDMX-ML XML Schema documents for XML validation. Users can specify a schema directory and the SDMX-ML version.

```APIDOC
sdmx.install_schemas(_schema_dir: Path | None = None, _version: str | Version = Version.2.1) -> Path

  Install SDMX-ML XML Schema documents for use with validate_xml().

  Parameters:
    schema_dir (Path, optional): The directory where XSD schemas will be downloaded to. Default: a subdirectory named sdmx/_version_ within the platformdirs.user_cache_path().
    version (str or Version, optional): The SDMX-ML schema version to install. One of Version["2.1"] (default), Version["3.0.0"], or str equivalent.

  Returns:
    The path containing the installed schemas. If schema_dir is given, the return value is identical to the parameter.
```

--------------------------------

### Run All Tests (including network)

Source: https://sdmx1.readthedocs.io/en/latest/install

Runs all tests, including those that require network access to retrieve data.

```bash
pytest --runslow
```

--------------------------------

### SDMX How-to Guides Navigation

Source: https://sdmx1.readthedocs.io/en/latest/whatsnew

Offers guidance on specific tasks using the sdmx library, such as generating SDMX-ML and validating SDMX-ML against schemas.

```APIDOC
How to…:
  - Generate SDMX-ML from Python objects: https://sdmx1.readthedocs.io/en/latest/howto/create.html
  - Validate SDMX-ML against official schemas: https://sdmx1.readthedocs.io/en/latest/howto/validate.html
```

--------------------------------

### Eurostat and ECB SDMX Resources

Source: https://sdmx1.readthedocs.io/en/latest/resources

Links to resources provided by Eurostat and the European Central Bank (ECB) for learning and using SDMX, including guides, tutorials, and REST service examples.

```APIDOC
Eurostat & ECB SDMX Resources:
  Eurostat SDMX InfoSpace: https://ec.europa.eu/eurostat/web/sdmx-infospace/welcome
    - Description: Offers guides and tutorials for SDMX, from beginner to advanced.
  ECB SDMX REST Service Help: https://sdw-wsrest.ecb.europa.eu/help/
    - Description: Provides examples for the ECB's SDMX REST service.
```

--------------------------------

### Generate SDMX-ML from Python Objects

Source: https://sdmx1.readthedocs.io/en/latest/example

Guides on generating SDMX-ML files directly from Python objects, simplifying data exchange.

```APIDOC
Generate SDMX-ML from Python objects:
  How-to guide for creating SDMX-ML files from Python data structures.
```

--------------------------------

### IMF SDMX Central Web Services Guide

Source: https://sdmx1.readthedocs.io/en/latest/sources

API documentation for the IMF SDMX Central Web Services, supporting SDMX-ML and SDMX-JSON. This guide outlines the RESTful web service capabilities for querying structures.

```APIDOC
IMF SDMX Central Web Services Guide (Published 10/17/2019)

Base URL for SDMX 2.1 (SDMX-REST 1.x) API: https://sdmxcentral.imf.org/ws/public/sdmxapi/rest
Base URL for SDMX 3.0.0 (SDMX-REST 2.x) API: https://sdmxcentral.imf.org/sdmx/v2

This source is intended for querying structures only.

Supported Formats:
- SDMX-ML 2.1
- SDMX-JSON 1.0.0

Example Query (SDMX 2.1): Accessing data flow structures.
GET /datastructure/{agencyId}/{resourceType}/{resourceId}/{version}

Example Query (SDMX 3.0.0): Accessing code lists.
GET /codelist/{agencyId}/{resourceId}/{version}

Note: Specific endpoints and parameters may vary based on the SDMX version and the registry's implementation.
```

--------------------------------

### SDMX Testing Utilities

Source: https://sdmx1.readthedocs.io/en/latest/dev

Provides functions and fixtures for testing SDMX related code. Includes session setup, response handling, and data path utilities.

```python
from sdmx.testing import pytest_sessionstart, session_with_pytest_cache, session_with_stored_responses, specimen, test_data_path, testsource
```

--------------------------------

### Configure Client with Caching

Source: https://sdmx1.readthedocs.io/en/latest/walkthrough

Initializes an SDMX client with caching enabled using the requests_cache library. This example configures the cache backend to SQLite, enables fast saving, and sets an expiration time of 10 minutes (600 seconds).

```python
ecb_with_cache = sdmx.Client(
    "ECB",
    backend="sqlite",
    fast_save=True,
    expire_after=600,
)
```

--------------------------------

### How to Generate and Validate SDMX-ML

Source: https://sdmx1.readthedocs.io/en/latest/genindex

Guides on how to generate SDMX-ML from Python objects and how to validate SDMX-ML against official schemas using the sdmx1 library.

```APIDOC
Generate SDMX-ML from Python objects:
  Instructions on creating SDMX-ML files from Python data structures.
  URL: https://sdmx1.readthedocs.io/en/latest/howto/create.html

Validate SDMX-ML against official schemas:
  Guidance on validating SDMX-ML files using provided schemas.
  URL: https://sdmx1.readthedocs.io/en/latest/howto/validate.html
```

--------------------------------

### sdmx.Client URL Construction and GET Method

Source: https://sdmx1.readthedocs.io/en/latest/implementation

Explains how the sdmx.Client class constructs URLs using URL subclasses like v21.URL and v30.URL. The Client.get() method automatically handles HTTP headers like 'Accept' and allows for custom query parameters and headers.

```python
from sdmx import Client

# Example of using Client.get()
# client = Client()
# data = client.get(resource_type='data', dataflow='...', params={'key': 'value'})

# Client.get() automatically adds 'Accept: application/vnd.sdmx.structurespecificdata+xml;' when structure= is provided.
# Query parameters and headers can be specified via Client.get(params={...}, headers={...}).
```

--------------------------------

### Accessing SDMX Data Sources via URL

Source: https://sdmx1.readthedocs.io/en/latest/howto

Demonstrates how to create an sdmx.Client and use the get() method with a URL to access SDMX data sources. This method is useful for data sources not explicitly listed in the provided sources.json file.

```python
import sdmx
c = sdmx.Client()
c.get(url='https://sdmx.example.org/path/to/webservice', ...)
```

--------------------------------

### SDMX API: Client class enhancements

Source: https://sdmx1.readthedocs.io/en/latest/whatsnew

The `Client` class now accepts an optional `session=...` keyword argument, allowing users to provide a pre-configured session. This is part of a simplification effort where `Session` now inherits directly from `requests_cache.session.CacheMixin` when installed.

```python
from sdmx import Client
from requests_cache import CachedSession

# Example usage with a custom session:
my_session = CachedSession('my_cache')
client = Client("wb", session=my_session)
```

--------------------------------

### SDMX Library API Modules

Source: https://sdmx1.readthedocs.io/en/latest/api

Overview of the sdmx library's API modules, including their purpose and links to detailed documentation. This section serves as a high-level guide to the library's structure.

```APIDOC
sdmx.model:
  SDMX Information Model. Provides classes and structures for representing SDMX data and metadata.
  See: https://sdmx1.readthedocs.io/en/latest/api/model.html

sdmx.reader:
  Read SDMX file formats. Handles parsing various SDMX file formats into Python objects.
  See: https://sdmx1.readthedocs.io/en/latest/api/reader.html

sdmx.writer:
  Write/convert sdmx objects. Enables the creation and conversion of SDMX objects to different formats.
  See: https://sdmx1.readthedocs.io/en/latest/api/writer.html

sdmx.source:
  Data sources. Information related to data sources used by the sdmx library.
  See: https://sdmx1.readthedocs.io/en/latest/sources.html

sdmx.compare:
  Compare SDMX artefacts. Functionality for comparing different SDMX artefacts.
  See: https://sdmx1.readthedocs.io/en/latest/api.html#module-sdmx.compare

sdmx.format:
  SDMX file formats. Details about supported SDMX file formats.
  See: https://sdmx1.readthedocs.io/en/latest/api.html#module-sdmx.format

sdmx.message:
  SDMX messages. Handling and representation of SDMX messages.
  See: https://sdmx1.readthedocs.io/en/latest/api.html#module-sdmx.message

sdmx.rest:
  SDMX-REST standard. Interface for interacting with SDMX-RESTful web services.
  See: https://sdmx1.readthedocs.io/en/latest/api.html#module-sdmx.rest

sdmx.session:
  HTTP sessions and responses. Manages HTTP sessions for interacting with web services.
  See: https://sdmx1.readthedocs.io/en/latest/api.html#session-http-sessions-and-responses

sdmx.urn:
  Uniform Resource Names (URNs) for SDMX objects. Utilities for working with SDMX URNs.
  See: https://sdmx1.readthedocs.io/en/latest/api.html#module-sdmx.urn

sdmx.util:
  Utilities and internals. Helper functions and internal utilities for the sdmx library.
  See: https://sdmx1.readthedocs.io/en/latest/api.html#module-sdmx.util
```

--------------------------------

### SDMX File Reading Example

Source: https://sdmx1.readthedocs.io/en/latest/license

Shows how to read SDMX files (e.g., SDMX-ML, SDMX-CSV) using the sdmx1 library. This function is essential for ingesting SDMX data into Python for analysis.

```python
from sdmx.reader import read_sdmx

# Assuming 'sdmx_file_path' is the path to your SDMX file
# The reader automatically detects the format (e.g., SDMX-ML, SDMX-CSV)
message = read_sdmx(sdmx_file_path)

# 'message' will be an instance of StructureMessage or DataMessage
# You can then access the data or structure information from it
# For example, to print the number of data sets in a DataMessage:
# if isinstance(message, DataMessage):
#     print(f"Number of data sets: {len(message.data_sets)}")

print("SDMX file reading example structure.")
# Actual code would involve reading a file and processing the returned message object.
```

--------------------------------

### Explore Code Lists from Structure Message

Source: https://sdmx1.readthedocs.io/en/latest/example

Retrieves specific code lists from a downloaded structure message and converts them into pandas Series for easier inspection. This example shows how to get and display code lists for 'AGE', 'SEX', and 'UNIT'.

```python
for cl in "ESTAT:AGE(11.0)", "ESTAT:SEX(1.13)", "ESTAT:UNIT(61.0)":
    print(sdmx.to_pandas(sm.get(cl)))

```

--------------------------------

### SDMX Workflow Steps

Source: https://sdmx1.readthedocs.io/en/latest/walkthrough

Outlines the typical steps involved in working with statistical data using the sdmx library, from choosing a data provider to analyzing the downloaded data.

```python
1. Choose a data provider.
   sdmx provides a built-in list of Data sources.
2. Investigate _what data is available_.
   Using sdmx, download the catalogue of data flows available from the data provider and select a data flow for further inspection.
3. Understand _what form_ the data comes in.
   Using sdmx, download structure and metadata on the selected data flow and the data it contains, including the data structure definition, concepts, code lists and content constraints.
4. Decide _what data is required_.
   Using sdmx, analyze the structural metadata, by directly inspecting objects or converting them to pandas types.
5. Download the actual data.
   Using sdmx, specify the needed portions of the data from the data flow by constructing a selection (‘key’) of series and a period/time range. Then, retrieve the data using Client.get().
6. Analyze or manipulate the data.
   Convert to pandas types using sdmx.to_pandas() and use the result in further Python code and scripts.
```

--------------------------------

### ComponentList Methods

Source: https://sdmx1.readthedocs.io/en/latest/api/model

Provides methods for extending, getting, and getting or creating components within a ComponentList. The getdefault method automatically populates the Dimension.order attribute.

```python
class ComponentList:
    auto_order: int

    def extend(self, _values: Iterable) -> None:
        """Extend components with _values."""
        pass

    def get(self, _id) -> CT:
        """Return the component with the given _id."""
        pass

    def getdefault(self, _id, _cls=None, **kwargs) -> CT:
        """Return or create the component with the given _id."""
        pass
```

--------------------------------

### SDMX Release Process Steps

Source: https://sdmx1.readthedocs.io/en/latest/dev

Outlines the steps involved in releasing a new version of the SDMX library, including version control, documentation updates, testing on TestPyPI, and final deployment to PyPI.

```bash
# 1. Create a new branch
# git checkout -b release/vX.Y.Z

# 2. Edit doc/whatsnew.rst
# Add new version heading

# 3. Commit changes
# git commit -m "Mark vX.Y.Z in doc/whatsnew"

# 4. Tag and push release candidate
# git tag -a vX.Y.ZrcN -m "Release candidate X.Y.Z N"
# git push origin vX.Y.ZrcN

# 5. Open a pull request for release
# Title: "Release vX.Y.Z"

# 6. Merge the PR (rebase and merge)
# git merge --no-ff <pr-branch>

# 7. (Optional) Tag the final release and push
# git tag -a vX.Y.Z -m "Release X.Y.Z"
# git push origin vX.Y.Z

# 8. Mark release on GitHub
# https://github.com/khaeru/sdmx/releases

# 9. Verify distribution on PyPI
# https://pypi.org/project/sdmx1/
```

--------------------------------

### SDMX v3.0 RangePeriod Class

Source: https://sdmx1.readthedocs.io/en/latest/api/model

Represents a time range period in SDMX v3.0, inheriting from TimeRangeValue. It includes attributes for validity start and end, and period start and end.

```APIDOC
sdmx.model.v30.RangePeriod:
  Bases: sdmx.model.v30.TimeRangeValue
  Attributes:
    _valid_from: Type: str or None.
    _valid_to: Type: str or None.
    start: Type: sdmx.model.common.StartPeriod or None.
    end: Type: sdmx.model.common.EndPeriod or None.
```

--------------------------------

### SDMX Python Contribution and Help

Source: https://sdmx1.readthedocs.io/en/latest/index

Guidelines for contributing to the sdmx Python project and seeking help. This includes reporting bugs, suggesting features, and asking usage questions.

```APIDOC
Contributing and Getting Help:

Usage Questions ('How do I?'):
  - Ask on Stack Overflow with tags [sdmx] [python].

Bug Reports & Feature Suggestions:
  - Report on GitHub.
  - View source code on GitHub.

Older Resources:
  - sdmx-python Google Group for historical questions.
```

--------------------------------

### SDMX Source Listing and Loading

Source: https://sdmx1.readthedocs.io/en/latest/sources

Functions for listing available SDMX sources and loading sources from packages.

```APIDOC
sdmx.source.list_sources()
  - Lists all available SDMX sources.

sdmx.source.load_package_sources()
  - Loads SDMX sources from installed packages.
```

--------------------------------

### Create SDMX-ML Messages Tutorial

Source: https://sdmx1.readthedocs.io/en/latest/whatsnew

Introduces a tutorial on creating SDMX-ML messages from pure Python objects, simplifying the process of generating SDMX messages.

```python
Feature: Add a brief tutorial on creating SDMX-ML messages from pure Python objects (#23, PR #24)
```

--------------------------------

### Install SDMX Schemas

Source: https://sdmx1.readthedocs.io/en/latest/howto/validate

Installs official SDMX-ML schema files for validation. Defaults to version 2.1, but can be specified for other versions like 3.0. This function downloads and caches the schemas locally, and only needs to be run once per version.

```python
import sdmx

sdmx.install_schemas()
# Output: PosixPath('/home/docs/.cache/sdmx/2.1')

# or for version 3.0
sdmx.install_schemas(version="3.0")
# Output: PosixPath('/home/docs/.cache/sdmx/3.0.0')
```

--------------------------------

### UNICEF SDMX-ML Structure Message Example

Source: https://sdmx1.readthedocs.io/en/latest/sources

Provides an example of an SDMX-ML structure message received from the UNICEF API, highlighting the structureID and namespace. It also notes a discrepancy between the reported structure ID and the actual DSD ID.

```xml
<mes:StructurestructureID="UNICEF_GLOBAL_DATAFLOW_1_0"namespace="urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=UNICEF:GLOBAL_DATAFLOW(1.0):ObsLevelDim:TIME_PERIOD"dimensionAtObservation="TIME_PERIOD">
<com:StructureUsage>
<RefagencyID="UNICEF"id="GLOBAL_DATAFLOW"version="1.0"/>
</com:StructureUsage>
</mes:Structure>
```

--------------------------------

### Accessing AR1 Data with SDMX Client

Source: https://sdmx1.readthedocs.io/en/latest/sources

Demonstrates how to use the SDMX Client to fetch data from the AR1 source, which provides SDMX-ML files. It shows both direct client initialization for AR1 and a general client approach for accessing a specific URL.

```python
c = sdmx.Client("AR1")
# The URL https://sdds.indec.gob.ar/files/data/IND.XML
dm = c.data("IND.XML")
```

```python
c = sdmx.Client()
dm = c.get(url="https://sdds.indec.gob.ar/files/data/IND.XML")
```

--------------------------------

### SDMX Client Data Query with Key and Parameters

Source: https://sdmx1.readthedocs.io/en/latest/walkthrough

Shows how to query SDMX data using the `sdmx` library. It demonstrates constructing a key for filtering by dimensions and setting parameters for time periods, then retrieving data using `Client.get()`.

```python
import sdmx

ecb = sdmx.Client("ECB", backend="memory")
key = dict(CURRENCY=["USD", "JPY"])
params = dict(startPeriod="2016")
data_msg = ecb.data("EXR", key=key, params=params)

# Generic data was returned
print(data_msg.response.headers["content-type"])
```

--------------------------------

### HAS_REQUESTS_CACHE Variable

Source: https://sdmx1.readthedocs.io/en/latest/dev

A boolean flag indicating whether the 'requests_cache' library is installed and available for use.

```APIDOC
HAS_REQUESTS_CACHE _= True_
```

--------------------------------

### Get Codelist Length

Source: https://sdmx1.readthedocs.io/en/latest/walkthrough

Retrieves and prints the total number of items in a specific codelist (CL_CURRENCY).

```python
len(exr_msg.codelist.CL_CURRENCY)
```

--------------------------------

### SDMX Utility and Configuration Options

Source: https://sdmx1.readthedocs.io/en/latest/genindex

Documentation for utility functions and configuration options within the SDMX library, including verbose output settings and request verification.

```APIDOC
sdmx.compare.Options.verbose
  Option to enable verbose output during comparisons.

sdmx.util.requests.SessionAttrs.verify
  Attribute for verifying SSL certificates in requests.
```

--------------------------------

### Initialize SDMX Client

Source: https://sdmx1.readthedocs.io/en/latest/example

Creates an SDMX client instance to interact with a specific data provider (Eurostat in this case). This client is used for subsequent data and structure queries.

```python
import sdmx

estat = sdmx.Client("ESTAT")
```

--------------------------------

### Get Single Element from Iterator with sdmx.util.only

Source: https://sdmx1.readthedocs.io/en/latest/dev

Returns the single element from an iterator, or None if the iterator is empty.

```python
sdmx.util.only(_iterator :[Iterator]) → [Any]
    Return the only element of iterator, or None.
```

--------------------------------

### Instantiate SDMX Client

Source: https://sdmx1.readthedocs.io/en/latest/walkthrough

Creates an instance of the sdmx.Client to connect to a specified data source, such as the European Central Bank (ECB). Multiple clients can be instantiated for different web services.

```python
import sdmx

ecbo = sdmx.Client("ECB")
```

--------------------------------

### SDMX Implementation Principles

Source: https://sdmx1.readthedocs.io/en/latest/implementation

Explains the core principles of the sdmx library's implementation of SDMX standards, focusing on precision, Pythonic conventions, and handling of standard variations.

```python
Classes and their attributes have the names, types, cardinality, and directionality given in the standard.
Where the standard has non-Pythonic names (for instance, “dimensionAtObservation”), sdmx follows the PEP-8 naming conventions (for instance, “dimension_at_observation” for a class attribute).
Where the standard is ambiguous or imprecise itself, implementation (for instance, naming) choices in sdmx are clearly labelled.
Extensions, additional features, and conveniences in sdmx that do not appear in the standards are clearly labeled.
All behaviour visible “in the wild”—that is, from publicly available data sources and files—is either:
  supported, if it is verifiably standards-compliant, or
  tolerated if otherwise, so long as this does not complicate the implementation of standards. Non-standard content is flagged using log messages and by other means.
```

--------------------------------

### SDMX ItemScheme Usage Example

Source: https://sdmx1.readthedocs.io/en/latest/api/model

Demonstrates how to create an ItemScheme, add an Item to it, and access the item using different methods.

```python
>>> 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
```

--------------------------------

### Migration Guidance

Source: https://sdmx1.readthedocs.io/en/latest/whatsnew

Provides instructions for migrating from older versions, including changes in reversing pandas Series and the replacement of specific arguments in writer functions.

```python
# For reversing a pandas Series:
# Old way: writer.write(..., reverse_obs=True)
# New way: s.iloc[::-1]

# For sdmx.writer.pandas.write_dataset:
# Replace 'parse_time' and 'fromfreq' with 'datetime'
# Example: write_dataset(dataset, datetime=True)
```

--------------------------------

### SDMX v2.1 RangePeriod Class

Source: https://sdmx1.readthedocs.io/en/latest/api/model

Represents a time range with a start and end period in SDMX 2.1. It inherits from TimeRangeValue.

```python
class sdmx.model.v21.RangePeriod(_start :[sdmx.model.common.StartPeriod], _end :[sdmx.model.common.EndPeriod]):
    """Represents a time range with start and end periods."""
    
    end _:[ EndPeriod]
    start _:[ StartPeriod]
```

--------------------------------

### SDMX Resource Class Method

Source: https://sdmx1.readthedocs.io/en/latest/genindex

Documentation for the class_name class method in sdmx.Resource, used to get the name of an SDMX resource class.

```APIDOC
sdmx.Resource:
  class_name():
    Description: Returns the name of the SDMX resource class.
    Returns: The class name as a string.
```

--------------------------------

### Get Data Source - sdmx.get_source

Source: https://sdmx1.readthedocs.io/en/latest/api

Retrieves a Source object based on its ID. The ID matching is case-insensitive.

```APIDOC
sdmx.get_source(_id: str) -> Source

  Return the Source with the given id.
  id is matched case-insensitively.
```

--------------------------------

### SDMX Development Modules

Source: https://sdmx1.readthedocs.io/en/latest/genindex

Documentation for development-related modules, including testing utilities and request handling.

```python
# sdmx.testing
# Utilities for testing SDMX components.

# sdmx.testing.data
# Test data utilities.

# sdmx.testing.report
# Reporting utilities for tests.

# sdmx.util.requests
# Utilities for handling HTTP requests.
```

--------------------------------

### SDMX URN and Format Utilities

Source: https://sdmx1.readthedocs.io/en/latest/genindex

Documentation for functions related to SDMX URN generation and matching, as well as media type handling. This includes the `make` and `match` functions for URNs and the `MediaType` class for managing media types.

```APIDOC
sdmx.urn.make():
  Function to generate an SDMX URN.

sdmx.urn.match():
  Function to match an SDMX URN.

sdmx.format.MediaType.match():
  Method of MediaType to match a media type.

sdmx.format.MEDIA_TYPES:
  Constant containing a collection of predefined media types.
```

--------------------------------

### sdmx1 Initial Release

Source: https://sdmx1.readthedocs.io/en/latest/whatsnew

Details the initial release of the sdmx1 project, marking the beginning of its development.

```en
v0.1 (2014-09)
  * Initial release
```

--------------------------------

### MetadataReport Convenience Methods

Source: https://sdmx1.readthedocs.io/en/latest/whatsnew

New convenience methods get(), get_value(), and ReportedAttribute.get_child() are added to MetadataReport for easier data retrieval.

```python
from sdmx.model.v21 import MetadataReport, ReportedAttribute

# Example usage (conceptual)
# report = MetadataReport()
# value = report.get_value(key='some_key')
# attribute = ReportedAttribute()
# child = attribute.get_child(child_key='some_child_key')
```

--------------------------------

### SDMX Utility and Source Components

Source: https://sdmx1.readthedocs.io/en/latest/genindex

Documentation for utility functions and source-specific classes, such as SessionAttrs and HTTPSAdapter.

```APIDOC
sdmx.util.requests.SessionAttrs.hooks:
  Attribute of the SessionAttrs class.
  Likely related to request hooks for session management.

HTTPSAdapter (class in sdmx.source.oecd_json):
  An HTTPS adapter class specific to the OECD JSON source.
```

--------------------------------

### OECD_JSON Client and Adapter

Source: https://sdmx1.readthedocs.io/en/latest/sources

Information on the `Client` and `HTTPSAdapter` for the OECD SDMX-JSON source.

```APIDOC
sdmx.source.oecd_json.Client()
  - Initializes a client for accessing OECD SDMX-JSON data.
  - Parameters: None explicitly mentioned.
  - Returns: An instance of the OECD JSON client.

sdmx.source.oecd_json.HTTPSAdapter
  - An HTTP adapter for handling requests to the OECD SDMX-JSON endpoint.
  - Inherits from a base adapter class, likely providing request/response handling.
  - Methods: Likely includes methods for sending requests and processing responses.
```

--------------------------------

### CacheMixin request() Method

Source: https://sdmx1.readthedocs.io/en/latest/dev

This method prepares and sends an HTTP request, handling caching operations automatically. It is used internally by other method-specific functions (get, post, etc.).

```APIDOC
CacheMixin:
  request(_method: str, _url: str, *args, headers: MutableMapping[str, str] | None = None, expire_after: None | int | float | str | datetime | timedelta = None, only_if_cached: bool = False, refresh: bool = False, force_refresh: bool = False, **kwargs) -> OriginalResponse | CachedResponse
    - Sends an HTTP request with caching.
    - Parameters:
      - _method: The HTTP method to use (e.g., 'GET', 'POST').
      - _url: The URL to send the request to.
      - *args: Variable length argument list.
      - headers: Optional headers to include in the request.
      - expire_after: Cache expiration time.
      - only_if_cached: If True, only return cached responses.
      - refresh: If True, refresh the cache.
      - force_refresh: If True, force a cache refresh.
      - **kwargs: Additional keyword arguments passed to requests.Session.request().
    - Returns: An OriginalResponse or CachedResponse object.
```

--------------------------------

### SDMX Model Attributes: valid_from

Source: https://sdmx1.readthedocs.io/en/latest/genindex

Documentation for the 'valid_from' attribute across different SDMX model classes, indicating the start of validity for an artefact or data component.

```APIDOC
sdmx.model.common.BaseDataSet.valid_from:
  Attribute indicating the start of validity for a dataset.

sdmx.model.common.HierarchicalCode.valid_from:
  Attribute indicating the start of validity for a hierarchical code.

sdmx.model.common.VersionableArtefact.valid_from:
  Attribute indicating the start of validity for a versionable artefact.

sdmx.model.v30.DataKey.valid_from:
  Attribute indicating the start of validity for a v3.0 data key.

sdmx.model.v30.MetadataSet.valid_from:
  Attribute indicating the start of validity for a v3.0 metadata set.

sdmx.model.v30.SelectionValue.valid_from:
  Attribute indicating the start of validity for a v3.0 selection value.
```

--------------------------------

### SDMX Python Development Guidelines

Source: https://sdmx1.readthedocs.io/en/latest/index

Information on the development practices for the sdmx Python library, including code style, testing, and release procedures.

```APIDOC
Development:

Code Style:
  - Follow specified code style guidelines.

Testing:
  - Information on how to run tests.

Releasing:
  - Procedures for releasing new versions.

Internal Code Reference:
  - Details on the internal structure of the code.

Inline TODOs:
  - Notes on pending tasks within the code.
```

--------------------------------

### SDMX Reader Functions

Source: https://sdmx1.readthedocs.io/en/latest/api/reader

Provides functions for interacting with SDMX data readers. Includes getting a reader based on a file path and reading SDMX messages.

```APIDOC
get_reader_for_path(path: str)
  Get a reader for the given path.

read_sdmx(source, **kwargs)
  Read an SDMX message from a source.

to_sdmx(obj, **kwargs)
  Convert an object to an SDMX message.
```

--------------------------------

### SDMX Source Handler Methods

Source: https://sdmx1.readthedocs.io/en/latest/genindex

Documentation for handler methods used in SDMX source implementations, including sdmx.source.estat, sdmx.source.sgr, and the base sdmx.source.Source class.

```apidoc
sdmx.source.estat.handle_references_param()
  - Handles reference parameters in the estat source.

sdmx.source.estat.Source.handle_response()
  - Handles responses from the estat source.

sdmx.source.sgr.Source.handle_response()
  - Handles responses from the sgr source.

sdmx.source.Source.handle_response()
  - Handles generic responses from a source.
```

--------------------------------

### SDMX Comparison and Naming Conventions

Source: https://sdmx1.readthedocs.io/en/latest/genindex

Documentation for methods and attributes related to comparing SDMX objects and defining naming conventions, including visited status and VTL-related naming.

```APIDOC
sdmx.compare.Options.visited()
  Method to check if an object has been visited during comparison.

sdmx.model.common.NamePersonalisation.vtl_default_name
  Attribute for VTL default naming conventions.

sdmx.model.common.CustomType.vtl_literal_format
  Attribute defining the literal format for VTL types.

sdmx.message.StructureMessage.vtl_mapping_scheme
  Attribute in StructureMessage related to VTL mapping schemes.

sdmx.model.common.TransformationScheme.vtl_mapping_scheme
  Attribute in TransformationScheme related to VTL mapping schemes.

sdmx.model.common.CustomType.vtl_scalar_type
  Attribute defining the scalar type for VTL custom types.
```

--------------------------------

### Read SDMX from Local Files

Source: https://sdmx1.readthedocs.io/en/latest/walkthrough

Demonstrates how to read SDMX messages from local files using the `read_sdmx` function. It includes an example of using a `SpecimenCollection` to access test data.

```python
from sdmx.testing import SpecimenCollection

specimen = SpecimenCollection("/path/to/sdmx-test-data")

with specimen("ECB_EXR/ng-ts.xml") as f:
    sdmx.read_sdmx(f)
```

--------------------------------

### Fetch Dataflow using SDMX Client (COMP)

Source: https://sdmx1.readthedocs.io/en/latest/sources

Initializes the SDMX client for the COMP Directorate General and retrieves available dataflows. This demonstrates basic interaction with the SDMX library for data discovery.

```python
COMP = sdmx.Client("COMP")
sm = COMP.dataflow()
print(sm.dataflow)
```

--------------------------------

### installed_schemas Fixture for Schema Management

Source: https://sdmx1.readthedocs.io/en/latest/dev

Fixture that ensures schemas are installed locally within a temporary directory. This is useful for testing schema-dependent functionality without relying on external schema sources.

```python
sdmx.testing.installed_schemas(_worker_id_, _mock_gh_api_, _tmp_path_factory_):
    """Fixture that ensures schemas are installed locally in a temporary directory."""
    pass
```

--------------------------------

### BBK Source Class and Methods

Source: https://sdmx1.readthedocs.io/en/latest/sources

Details the sdmx.source.bbk.Source class for the German Federal Bank, including workarounds for non-standard web service behavior and request argument modification.

```python
class sdmx.source.bbk.Source:
    """Work around non-standard behaviour of the BBK: German Federal Bank web service."""

    def modify_request_args(_kwargs_):
        """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.

        Return type:
            None
        """
        pass
```

--------------------------------

### SDMX Test Report Main Function

Source: https://sdmx1.readthedocs.io/en/latest/dev

The main entry point for the SDMX test reporting utility. It collates results from multiple JSON files, optionally starting from a base path.

```python
sdmx.testing.report.main(_base_path :[Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.13)")|[None](https://docs.python.org/3/library/constants.html#None "(in Python v3.13)")=None_)
```

--------------------------------

### SDMX Requests Cache Reduction

Source: https://sdmx1.readthedocs.io/en/latest/whatsnew

Reduces noise in logs when `requests_cache` is not installed. An exception is still raised if the package is missing and cache-related arguments are used with `sdmx.Client`.

```python
import sdmx

try:
    client = sdmx.Client(cache=True) # This might raise an error if requests_cache is not installed
except ImportError:
    print("requests_cache is not installed. Caching is disabled.")
    client = sdmx.Client()
```

--------------------------------

### SDMX Utility Item Structure and Comparison Classes

Source: https://sdmx1.readthedocs.io/en/latest/genindex

API documentation for classes and constants related to item structure and comparison, including sdmx.util.item_structure.OPS and sdmx.compare.Options.

```APIDOC
sdmx.util.item_structure.OPS:
  Constant in module sdmx.util.item_structure

Options:
  Class in sdmx.compare
  Class in sdmx.reader.csv
```

--------------------------------

### SDMX API Reference

Source: https://sdmx1.readthedocs.io/en/latest/index

Provides access to the SDMX library's core functionalities, including comparison tools and file format handling.

```APIDOC
sdmx:
  Top-level methods and classes for SDMX operations.

  compare:
    Compare SDMX artefacts.
    Usage:
      sdmx.compare(obj1, obj2, ...)
    Description:
      Compares two or more SDMX objects for equality or differences.

  format:
    SDMX file formats.
    Usage:
      sdmx.format.parse(file_path, ...)
      sdmx.format.write(obj, file_path, ...)
    Description:
      Handles parsing and writing of SDMX data in various formats (e.g., SDMX-ML, SDMX-JSON).
```

--------------------------------

### SDMX-ML Validation Example

Source: https://sdmx1.readthedocs.io/en/latest/license

Demonstrates how to validate SDMX-ML files against official schemas using the sdmx1 library. This is crucial for ensuring data integrity and compliance with SDMX standards.

```python
from sdmx.api import validate

# Assuming 'sdmx_file_path' is the path to your SDMX-ML file
validation_errors = validate(sdmx_file_path)

if not validation_errors:
    print("SDMX-ML file is valid.")
else:
    print("Validation errors found:")
    for error in validation_errors:
        print(error)
```

--------------------------------

### SDMX ClassFinder API

Source: https://sdmx1.readthedocs.io/en/latest/api/model

Provides methods for finding and accessing SDMX classes within the model. It includes functionalities to get classes by name, manage name mappings, and determine parent classes.

```APIDOC
sdmx.model.common.ClassFinder:
  dir(): For module.__dir__.
  get_class(_name: str | Resource, _package = None) -> type | None: Return a class for name and (optional) package names.
  getattr(_name_): For module.__getattr__.
  module_name: str
  name_map: dict[str, str]
  parent_class(_cls_): Return the class that contains objects of type cls. For example, if cls is PrimaryMeasure, returns v21.MeasureDescriptor.
  parent_map: dict[type, type]
```

--------------------------------

### SDMX Implementation Notes

Source: https://sdmx1.readthedocs.io/en/latest/index

Details on the implementation of the SDMX standard within the library, including standards versions, information models, file formats, and the SDMX-REST web service API.

```APIDOC
Topic: Standards Versions
Description: Information on supported SDMX standards versions.
URL: https://sdmx1.readthedocs.io/en/latest/implementation.html#standards-versions

Topic: Information Model (SDMX-IM)
Description: Details about the SDMX Information Model (SDMX-IM).
URL: https://sdmx1.readthedocs.io/en/latest/implementation.html#information-model-sdmx-im

Topic: File Formats
Description: Information regarding supported file formats for SDMX data.
URL: https://sdmx1.readthedocs.io/en/latest/implementation.html#file-formats

Topic: SDMX-REST Web Service API
Description: Documentation for the SDMX-REST web service API implementation.
URL: https://sdmx1.readthedocs.io/en/latest/implementation.html#sdmx-rest-web-service-api
```