Skip to content

Python SDK

The Python SDK section is the entry point for Python developers integrating un-comtrade-sdk into a script, application, or pipeline. The SDK is designed for idiomatic Python — type hints end-to-end, frozen dataclasses for every model, context managers for resource cleanup, and a single lazy entry point (ComtradeClient) that opens five service facades.

Path

Guide Audience What it covers
Metadata Python developers Country / partner / HS-code catalogues, the metadata cache, the refresh flow.
Trade Python developers Annual / monthly flows, tariffline, world totals, partner breakdowns, the pagination engine.
Analytics Data analysts, Python developers Country / partner / commodity / time-series / balance / comparison analytics on top of CanonicalDataset.
ETL Python developers Pipeline composition, stage orchestration, configuration injection.
Storage Python developers CSV / JSON / Parquet / DuckDB writers and readers; cross-backend round-trip equality.

Idiomatic patterns

Single entry point, five facades

from un_comtrade import ComtradeClient

with ComtradeClient() as client:
    client.metadata         # MetadataService
    client.trade            # TradeService
    client.analytics        # AnalyticsEngine
    client.etl              # ETLFacade
    client.storage          # StorageRegistry

Each facade is a per-client singleton; constructing the client multiple times yields independent state. The five facades never talk to the network until you call a method on them.

Typed return values

Every public method returns a typed object:

  • client.metadata.get_countries() → list[Country]
  • client.trade.get_exports(...) → CanonicalDataset
  • client.analytics.top_partners(...) → tuple[PartnerRankingRow, ...]

Monetary values are Decimal; dates are ISO-8601 strings; enums are frozenset. No raw upstream JSON ever leaks into your code.

Error handling

Every public method raises ComtradeError (or a subclass) on upstream failure. The standard pattern:

from un_comtrade import ComtradeClient
from un_comtrade.exceptions import ComtradeError

try:
    with ComtradeClient() as client:
        result = client.trade.get_exports(reporter_code=699, period="2022")
except ComtradeError as exc:
    print(f"un-comtrade error: {exc}")

The exception hierarchy is documented in the API → Exceptions reference.

Configuration injection

The Configuration dataclass controls every knob:

from un_comtrade import ComtradeClient
from un_comtrade.config import Configuration

config = Configuration(
    api_key="your-key",
    retry_attempts=3,                # ADR-0008
    timeout_seconds=30,              # ADR-0011
    cache_dir="/srv/un_comtrade/cache",
    cache_ttl_seconds=86400 * 7,
)

with ComtradeClient(config) as client:
    ...

The full configuration surface is in the API → Models reference.

  • Metadata — reference catalogues.
  • Trade — annual / monthly trade flows.
  • Analytics — typed analytics functions.
  • ETL — pipeline composition.
  • Storage — persistence backends.

Next steps