mxm-types

Purpose

mxm-types provides shared foundational types and representation adapters for the Money Ex Machina ecosystem.

It defines a small, stable, representation-focused layer for:

• cross-package type definitions
• canonical data representations
• explicit boundary adapters between representations

The package is intentionally domain-agnostic.
Domain models and business semantics belong in their respective packages.

Installation

pip install mxm-types

Overview

mxm-types defines:

• Strict JSON tree types for configuration, metadata, requests, and portable data structures
• Lightweight aliases for common cross-package patterns such as path-like values and HTTP headers
• Micro-protocols for cross-cutting interfaces
• A canonical MXM timestamp substrate based on np.datetime64[ns]
• Explicit representation bridges from canonical MXM timestamps to:
  • integer epoch nanoseconds
  • strict canonical UTC strings
  • pandas Timestamp / DatetimeIndex
• PEP 561 typing support (py.typed included in the wheel)

The package is intentionally small and stable, but it is no longer dependency-free:
the pandas boundary adapter layer depends on pandas.

Public API

The following names form the stable public API of mxm-types.
All other names are private and may change across releases.

General Types

Protocols and TypedDicts

Canonical Timestamp Substrate

Timestamp Predicates and Assertions

Timestamp Bridges

Pandas Timestamp Adapters

Usage

General shared types

from mxm.types import JSONObj, StrPath

def load_metadata(path: StrPath) -> JSONObj:
    ...

Canonical timestamp substrate

from mxm.types import TSNSScalar, assert_not_nat, ts_ns_from_str, ts_ns_to_int

def parse_created_ts(text: str) -> int:
    ts: TSNSScalar = ts_ns_from_str(text)
    ts = assert_not_nat(ts)
    return ts_ns_to_int(ts)

Pandas boundary adapter

import pandas as pd
from mxm.types import ts_ns_array_from_pd_datetimeindex, ts_ns_to_pd_timestamp
from mxm.types.timestamps import ts_ns_from_str

idx = pd.DatetimeIndex(
    ["2026-03-25 10:14:03.123456789", "2026-03-25 10:14:04.123456789"],
    tz="Europe/Amsterdam",
)

arr = ts_ns_array_from_pd_datetimeindex(idx)

ts = ts_ns_from_str("2026-03-25T10:14:03.123456789Z")
pd_ts = ts_ns_to_pd_timestamp(ts)

Timestamp Design

MXM adopts a single canonical internal timestamp representation:

np.datetime64[ns]

Canonical timestamps:

• are timezone-naive NumPy timestamps interpreted as UTC
• represent instants on a linear time axis
• have nanosecond precision
• use explicit boundary adapters for external systems

Canonical string format:

YYYY-MM-DDTHH:MM:SS.fffffffffZ

Design Principles

• Single canonical representation
• Explicit boundary adapters
• Representation-focused scope
• Stable cross-package surface
• Strict static typing

Development

make check

License

MIT License. See LICENSE.