Python SDK Reference

Complete API reference for the odse Python package. Install with pip install odse.

import odse
print(odse.__version__)  # "0.4.0"

Transform

transform(data, source, asset_id=None, timezone=None, **kwargs)

Transform OEM data to ODS-E records.

Returns: List[Dict[str, Any]] — list of ODS-E records.

Raises: ValueError if source is not recognized.

Supported sources:

Example:

from odse import transform

# OEM-specific
rows = transform("huawei_export.csv", source="huawei", asset_id="SITE-001")

# Generic CSV with column mapping
rows = transform("scada.csv", source="csv", mapping={
    "timestamp": "Timestamp",
    "kWh": "Energy_kWh",
    "asset_id": "SiteTag",
})

transform_stream(data, source, **kwargs)

Streaming variant of transform(). Yields records one at a time for memory-bounded processing of large files.

Yields: Dict[str, Any] — one ODS-E record at a time.

Example:

from odse import transform_stream

for record in transform_stream("large_export.csv", source="huawei"):
    process(record)

Generic CSV mapping Format

The mapping argument for source="csv" can be a dict or a path to a JSON/YAML file:

Validate

validate(data, level="schema", capacity_kw=None, latitude=None, longitude=None, profile=None)

Validate a single ODS-E record.

Returns: ValidationResult

@dataclass
class ValidationResult:
    is_valid: bool
    errors: List[ValidationError]
    warnings: List[ValidationError]
    level: str

@dataclass
class ValidationError:
    path: str       # JSONPath, e.g., "$.timestamp"
    message: str    # Human-readable description
    code: str       # Machine-readable code (see below)

Error codes:

Example:

from odse import validate

result = validate({
    "timestamp": "2026-02-09T14:00:00Z",
    "kWh": 5.0,
    "error_type": "normal",
})
print(result.is_valid)  # True

validate_file(file_path, level="schema", **kwargs)

Validate a JSON file containing an ODS-E record.

Returns: ValidationResult

validate_batch(records, level="schema", profile=None, **kwargs)

Validate a list of records and return aggregate results.

Returns: BatchValidationResult

@dataclass
class BatchValidationResult:
    total: int                              # Total records validated
    valid: int                              # Records that passed
    invalid: int                            # Records that failed
    errors: List[Tuple[int, ValidationError]]  # (record_index, error) pairs
    summary: str                            # Human-readable summary string

Example:

from odse import validate_batch

result = validate_batch(records, level="semantic", capacity_kw=10.0)
print(result.summary)  # "3/3 valid (schema)"

PROFILES

Dictionary of available conformance profiles. Keys are profile names, values are dicts with required_fields and field_constraints.

from odse import PROFILES

print(list(PROFILES.keys()))
# ['bilateral', 'wheeling', 'sawem_brp', 'municipal_recon']

Enrich

enrich(rows, context=None, *, override=False)

Inject market context metadata into ODS-E records.

Returns: List[Dict] — the same list, modified in place.

Behavior:

• override=False (default): existing fields in each record are preserved.
• override=True: context values overwrite existing fields.
• None or {} context: returns rows unchanged (no-op).

Example:

from odse import transform, enrich

rows = transform("data.csv", source="huawei")
enriched = enrich(rows, {
    "seller_party_id": "nersa:gen:SOLARPK-001",
    "settlement_type": "bilateral",
    "tariff_currency": "ZAR",
})

Output

to_json(records, output_path)

Write records as newline-delimited JSON (JSONL).

to_csv(records, output_path)

Write records as CSV with ODS-E field names as headers.

to_parquet(records, output_path, partition_by=None, mode="overwrite")

Write partitioned Parquet files. Requires pip install odse[parquet] (pyarrow + pandas).

Automatically derives year, month, day, hour fields from timestamp for partitioning.

Example:

from odse import to_parquet

to_parquet(records, "output/lake/", partition_by=["asset_id", "year", "month", "day"])
# Creates: output/lake/asset_id=SITE-001/year=2026/month=02/day=09/part-00000.parquet

to_dataframe(records)

Convert records to a pandas DataFrame with canonical dtypes. Requires pip install odse[dataframe].

Returns: pandas.DataFrame with timestamp as datetime64[ns, UTC] and kWh as float64.

CLI

The odse command-line tool is installed with pip install odse.

odse transform

odse transform --source SOURCE --input FILE [options]

odse validate

odse validate --input FILE [options]

Output: JSON report to stdout with total, passed, failed, errors, warnings.

Exit code: 0 if all records pass, 1 if any fail.

odse version

Print the installed ODS-E version.

odse --version

Print version in odse X.Y.Z format.

Related Docs

• Architecture & Core Concepts — Mental model and data flow
• Get Started — 5-minute quickstart
• CLI Walkthrough — Every CLI command with examples
• Schema Reference — Field-level definitions