mxm-types 0.1.0__tar.gz → 0.2.0__tar.gz

mxm_types-0.2.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: mxm-types
+Version: 0.2.0
+Summary: Shared foundational types and representation adapters for Money Ex Machina.
+License: MIT
+License-File: LICENSE
+Keywords: money-ex-machina,types,typing,timestamps,numpy,pandas,json,pep561
+Author: mxm
+Author-email: contact@moneyexmachina.com
+Requires-Python: >=3.13,<3.15
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: numpy (>=2.4.4,<3.0.0)
+Requires-Dist: pandas (>=3.0.2,<4.0.0)
+Project-URL: Homepage, https://github.com/moneyexmachina/mxm-types
+Project-URL: Issues, https://github.com/moneyexmachina/mxm-types/issues
+Project-URL: Repository, https://github.com/moneyexmachina/mxm-types
+Description-Content-Type: text/markdown
+
+# `mxm-types`
+
+![Version](https://img.shields.io/github/v/release/moneyexmachina/mxm-types)
+![License](https://img.shields.io/github/license/moneyexmachina/mxm-types)
+![Python](https://img.shields.io/badge/python-3.13+-blue)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+
+Shared foundational types and representation adapters for the Money Ex Machina ecosystem.
+
+`mxm-types` provides a small, stable package for cross-package MXM type definitions and canonical representation bridges.
+
+It currently includes:
+
+- general shared aliases and micro-protocols
+- the canonical MXM timestamp substrate
+- explicit pandas boundary adapters for the canonical timestamp model
+
+The package is intentionally representation-focused and domain-agnostic.  
+Domain models and business semantics belong in their respective packages.
+
+## Install
+
+```bash
+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
+
+| Name | Description |
+|------|-------------|
+| `JSONScalar` | `str \| int \| float \| bool \| None` |
+| `JSONValue` | Strict recursive JSON tree: scalars, `list[JSONValue]`, `dict[str, JSONValue]` |
+| `JSONLike` | Permissive tree for accepting general `Sequence` / `Mapping` inputs |
+| `JSONObj` | `Mapping[str, JSONValue]` — preferred for function parameters |
+| `JSONMap` | `dict[str, JSONValue]` — preferred for concrete, mutable results |
+| `HeadersLike` | Canonical alias for HTTP header mappings |
+| `StrPath` | `str \| PathLike[str]` |
+
+### Protocols and TypedDicts
+
+| Name | Description |
+|------|-------------|
+| `KVReadable` | Minimal protocol for objects exposing `get(key, default)` |
+| `CLIFormatOptions` | Optional formatting hints for CLI output (`"plain" \| "rich" \| "json"`) |
+
+### Canonical Timestamp Substrate
+
+| Name | Description |
+|------|-------------|
+| `TSNSScalar` | Canonical MXM timestamp scalar (`np.datetime64[ns]`) |
+| `TSNSArray` | Canonical MXM timestamp array (`ndarray[datetime64[ns]]`) |
+| `Int64Array` | `ndarray[int64]` alias used alongside canonical timestamp bridges |
+| `TS_NS_DTYPE` | Canonical NumPy timestamp dtype constant |
+| `INT64_DTYPE` | Canonical integer dtype constant for epoch nanoseconds |
+| `EPOCH_TS_NS` | Unix epoch constant in canonical MXM timestamp form |
+| `NAT_TS_NS` | Canonical NumPy `NaT` sentinel in `datetime64[ns]` form |
+
+#### Timestamp Predicates and Assertions
+
+| Name | Description |
+|------|-------------|
+| `is_ts_ns` | Predicate for canonical timestamp scalars |
+| `assert_ts_ns` | Assert and return canonical timestamp scalar |
+| `is_nat` | Predicate for canonical `NaT` scalar |
+| `assert_not_nat` | Assert scalar is not `NaT` |
+| `is_ts_ns_array` | Predicate for canonical timestamp arrays |
+| `assert_ts_ns_array` | Assert and return canonical timestamp array |
+| `has_nat` | Detect `NaT` in a canonical timestamp array |
+| `assert_no_nat` | Assert canonical timestamp array contains no `NaT` |
+| `assert_monotonic_increasing_ts_ns_array` | Assert 1D, non-`NaT`, monotonic-increasing canonical timestamp array |
+
+#### Timestamp Bridges
+
+| Name | Description |
+|------|-------------|
+| `ts_ns_from_int` | Construct canonical timestamp from integer epoch nanoseconds |
+| `ts_ns_to_int` | Convert canonical timestamp to integer epoch nanoseconds |
+| `ts_ns_from_str` | Parse canonical UTC string into canonical timestamp |
+| `ts_ns_to_str` | Format canonical timestamp as canonical UTC string |
+
+### Pandas Timestamp Adapters
+
+| Name | Description |
+|------|-------------|
+| `is_pd_timestamp_for_ts_ns` | Predicate for approved pandas scalar normal form |
+| `assert_pd_timestamp_for_ts_ns` | Assert pandas scalar normal form |
+| `is_pd_datetimeindex_for_ts_ns_array` | Predicate for approved pandas array normal form |
+| `assert_pd_datetimeindex_for_ts_ns_array` | Assert pandas array normal form |
+| `ts_ns_from_pd_timestamp` | Convert pandas `Timestamp` to canonical timestamp |
+| `ts_ns_to_pd_timestamp` | Convert canonical timestamp to UTC pandas `Timestamp` |
+| `ts_ns_array_from_pd_datetimeindex` | Convert pandas `DatetimeIndex` to canonical timestamp array |
+| `ts_ns_array_to_pd_datetimeindex` | Convert canonical timestamp array to UTC pandas `DatetimeIndex` |
+
+---
+
+## Usage
+
+### General shared types
+
+```python
+from mxm.types import (
+    JSONLike,
+    JSONObj,
+    JSONValue,
+    StrPath,
+)
+
+def load_metadata(path: StrPath) -> JSONObj:
+    ...
+```
+
+### Canonical timestamp substrate
+
+```python
+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
+
+```python
+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:
+
+```python
+np.datetime64[ns]
+```
+
+Under MXM policy, canonical timestamps:
+
+- are timezone-naive NumPy timestamps interpreted strictly as UTC
+- represent instants on a POSIX-style linear time axis
+- have nanosecond precision
+- use explicit boundary adapters for pandas and other external systems
+
+The canonical textual bridge format is:
+
+```text
+YYYY-MM-DDTHH:MM:SS.fffffffffZ
+```
+
+with exactly 9 fractional digits and mandatory trailing `Z`.
+
+## Design Principles
+
+- **One canonical timestamp model**: shared across MXM packages.
+- **Explicit representation bridges**: conversions to strings, integers, and pandas stay visible.
+- **Representation-focused scope**: this package owns types and adapters, not domain semantics.
+- **Stable cross-package surface**: suitable for low-level shared usage.
+- **Strict static typing**: Pyright-clean, test-covered, and PEP 561 compliant.
+
+## Development
+
+```bash
+poetry install
+poetry run ruff check .
+poetry run black --check .
+poetry run pyright
+poetry run pytest -q
+poetry build
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+

mxm_types-0.2.0/README.md

@@ -0,0 +1,217 @@
+# `mxm-types`
+
+![Version](https://img.shields.io/github/v/release/moneyexmachina/mxm-types)
+![License](https://img.shields.io/github/license/moneyexmachina/mxm-types)
+![Python](https://img.shields.io/badge/python-3.13+-blue)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+
+Shared foundational types and representation adapters for the Money Ex Machina ecosystem.
+
+`mxm-types` provides a small, stable package for cross-package MXM type definitions and canonical representation bridges.
+
+It currently includes:
+
+- general shared aliases and micro-protocols
+- the canonical MXM timestamp substrate
+- explicit pandas boundary adapters for the canonical timestamp model
+
+The package is intentionally representation-focused and domain-agnostic.  
+Domain models and business semantics belong in their respective packages.
+
+## Install
+
+```bash
+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
+
+| Name | Description |
+|------|-------------|
+| `JSONScalar` | `str \| int \| float \| bool \| None` |
+| `JSONValue` | Strict recursive JSON tree: scalars, `list[JSONValue]`, `dict[str, JSONValue]` |
+| `JSONLike` | Permissive tree for accepting general `Sequence` / `Mapping` inputs |
+| `JSONObj` | `Mapping[str, JSONValue]` — preferred for function parameters |
+| `JSONMap` | `dict[str, JSONValue]` — preferred for concrete, mutable results |
+| `HeadersLike` | Canonical alias for HTTP header mappings |
+| `StrPath` | `str \| PathLike[str]` |
+
+### Protocols and TypedDicts
+
+| Name | Description |
+|------|-------------|
+| `KVReadable` | Minimal protocol for objects exposing `get(key, default)` |
+| `CLIFormatOptions` | Optional formatting hints for CLI output (`"plain" \| "rich" \| "json"`) |
+
+### Canonical Timestamp Substrate
+
+| Name | Description |
+|------|-------------|
+| `TSNSScalar` | Canonical MXM timestamp scalar (`np.datetime64[ns]`) |
+| `TSNSArray` | Canonical MXM timestamp array (`ndarray[datetime64[ns]]`) |
+| `Int64Array` | `ndarray[int64]` alias used alongside canonical timestamp bridges |
+| `TS_NS_DTYPE` | Canonical NumPy timestamp dtype constant |
+| `INT64_DTYPE` | Canonical integer dtype constant for epoch nanoseconds |
+| `EPOCH_TS_NS` | Unix epoch constant in canonical MXM timestamp form |
+| `NAT_TS_NS` | Canonical NumPy `NaT` sentinel in `datetime64[ns]` form |
+
+#### Timestamp Predicates and Assertions
+
+| Name | Description |
+|------|-------------|
+| `is_ts_ns` | Predicate for canonical timestamp scalars |
+| `assert_ts_ns` | Assert and return canonical timestamp scalar |
+| `is_nat` | Predicate for canonical `NaT` scalar |
+| `assert_not_nat` | Assert scalar is not `NaT` |
+| `is_ts_ns_array` | Predicate for canonical timestamp arrays |
+| `assert_ts_ns_array` | Assert and return canonical timestamp array |
+| `has_nat` | Detect `NaT` in a canonical timestamp array |
+| `assert_no_nat` | Assert canonical timestamp array contains no `NaT` |
+| `assert_monotonic_increasing_ts_ns_array` | Assert 1D, non-`NaT`, monotonic-increasing canonical timestamp array |
+
+#### Timestamp Bridges
+
+| Name | Description |
+|------|-------------|
+| `ts_ns_from_int` | Construct canonical timestamp from integer epoch nanoseconds |
+| `ts_ns_to_int` | Convert canonical timestamp to integer epoch nanoseconds |
+| `ts_ns_from_str` | Parse canonical UTC string into canonical timestamp |
+| `ts_ns_to_str` | Format canonical timestamp as canonical UTC string |
+
+### Pandas Timestamp Adapters
+
+| Name | Description |
+|------|-------------|
+| `is_pd_timestamp_for_ts_ns` | Predicate for approved pandas scalar normal form |
+| `assert_pd_timestamp_for_ts_ns` | Assert pandas scalar normal form |
+| `is_pd_datetimeindex_for_ts_ns_array` | Predicate for approved pandas array normal form |
+| `assert_pd_datetimeindex_for_ts_ns_array` | Assert pandas array normal form |
+| `ts_ns_from_pd_timestamp` | Convert pandas `Timestamp` to canonical timestamp |
+| `ts_ns_to_pd_timestamp` | Convert canonical timestamp to UTC pandas `Timestamp` |
+| `ts_ns_array_from_pd_datetimeindex` | Convert pandas `DatetimeIndex` to canonical timestamp array |
+| `ts_ns_array_to_pd_datetimeindex` | Convert canonical timestamp array to UTC pandas `DatetimeIndex` |
+
+---
+
+## Usage
+
+### General shared types
+
+```python
+from mxm.types import (
+    JSONLike,
+    JSONObj,
+    JSONValue,
+    StrPath,
+)
+
+def load_metadata(path: StrPath) -> JSONObj:
+    ...
+```
+
+### Canonical timestamp substrate
+
+```python
+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
+
+```python
+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:
+
+```python
+np.datetime64[ns]
+```
+
+Under MXM policy, canonical timestamps:
+
+- are timezone-naive NumPy timestamps interpreted strictly as UTC
+- represent instants on a POSIX-style linear time axis
+- have nanosecond precision
+- use explicit boundary adapters for pandas and other external systems
+
+The canonical textual bridge format is:
+
+```text
+YYYY-MM-DDTHH:MM:SS.fffffffffZ
+```
+
+with exactly 9 fractional digits and mandatory trailing `Z`.
+
+## Design Principles
+
+- **One canonical timestamp model**: shared across MXM packages.
+- **Explicit representation bridges**: conversions to strings, integers, and pandas stay visible.
+- **Representation-focused scope**: this package owns types and adapters, not domain semantics.
+- **Stable cross-package surface**: suitable for low-level shared usage.
+- **Strict static typing**: Pyright-clean, test-covered, and PEP 561 compliant.
+
+## Development
+
+```bash
+poetry install
+poetry run ruff check .
+poetry run black --check .
+poetry run pyright
+poetry run pytest -q
+poetry build
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+

{mxm_types-0.1.0 → mxm_types-0.2.0}/pyproject.toml

@@ -1,11 +1,20 @@
 [tool.poetry]
 name = "mxm-types"
-version = "0.1.0"
-description = "Shared typing primitives for Money Ex Machina."
+version = "0.2.0"
+description = "Shared foundational types and representation adapters for Money Ex Machina."
 authors = ["mxm <contact@moneyexmachina.com>"]
 license = "MIT"
 readme = "README.md"
-keywords = ["money-ex-machina", "typing", "json", "types", "pep561"]
+keywords = [
+  "money-ex-machina",
+  "types",
+  "typing",
+  "timestamps",
+  "numpy",
+  "pandas",
+  "json",
+  "pep561",
+]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
@@ -21,12 +30,14 @@ include = [
 ]
 
 [tool.poetry.urls]
-"Homepage" = "https://github.com/moneyexmachina/"
+"Homepage" = "https://github.com/moneyexmachina/mxm-types"
 "Repository" = "https://github.com/moneyexmachina/mxm-types"
 "Issues" = "https://github.com/moneyexmachina/mxm-types/issues"
 
 [tool.poetry.dependencies]
 python = ">=3.13,<3.15"
+numpy = "^2.4.4"
+pandas = "^3.0.2"
 
 [tool.poetry.group.dev.dependencies]
 ruff = "^0.14.3"

mxm_types-0.2.0/src/mxm/types/__init__.py

@@ -0,0 +1,98 @@
+"""
+Shared foundational types and representation adapters for Money Ex Machina.
+
+This package provides:
+
+- general shared aliases and micro-protocols
+- the canonical MXM timestamp substrate
+- explicit pandas boundary adapters for the canonical timestamp model
+
+The package is intentionally small, stable, and representation-focused.
+Domain semantics and storage-specific adapters belong elsewhere.
+"""
+
+from __future__ import annotations
+
+from .general import (
+    CLIFormatOptions,
+    HeadersLike,
+    JSONLike,
+    JSONMap,
+    JSONObj,
+    JSONScalar,
+    JSONValue,
+    KVReadable,
+    StrPath,
+)
+from .pandas_timestamps import (
+    assert_pd_datetimeindex_for_ts_ns_array,
+    assert_pd_timestamp_for_ts_ns,
+    is_pd_datetimeindex_for_ts_ns_array,
+    is_pd_timestamp_for_ts_ns,
+    ts_ns_array_from_pd_datetimeindex,
+    ts_ns_array_to_pd_datetimeindex,
+    ts_ns_from_pd_timestamp,
+    ts_ns_to_pd_timestamp,
+)
+from .timestamps import (
+    EPOCH_TS_NS,
+    INT64_DTYPE,
+    NAT_TS_NS,
+    TS_NS_DTYPE,
+    Int64Array,
+    TSNSArray,
+    TSNSScalar,
+    assert_monotonic_increasing_ts_ns_array,
+    assert_no_nat,
+    assert_not_nat,
+    assert_ts_ns,
+    assert_ts_ns_array,
+    has_nat,
+    is_nat,
+    is_ts_ns,
+    is_ts_ns_array,
+    ts_ns_from_int,
+    ts_ns_from_str,
+    ts_ns_to_int,
+    ts_ns_to_str,
+)
+
+__all__ = [
+    "EPOCH_TS_NS",
+    "INT64_DTYPE",
+    "NAT_TS_NS",
+    "TS_NS_DTYPE",
+    "CLIFormatOptions",
+    "HeadersLike",
+    "Int64Array",
+    "JSONLike",
+    "JSONMap",
+    "JSONObj",
+    "JSONScalar",
+    "JSONValue",
+    "KVReadable",
+    "StrPath",
+    "TSNSArray",
+    "TSNSScalar",
+    "assert_monotonic_increasing_ts_ns_array",
+    "assert_no_nat",
+    "assert_not_nat",
+    "assert_pd_datetimeindex_for_ts_ns_array",
+    "assert_pd_timestamp_for_ts_ns",
+    "assert_ts_ns",
+    "assert_ts_ns_array",
+    "has_nat",
+    "is_nat",
+    "is_pd_datetimeindex_for_ts_ns_array",
+    "is_pd_timestamp_for_ts_ns",
+    "is_ts_ns",
+    "is_ts_ns_array",
+    "ts_ns_array_from_pd_datetimeindex",
+    "ts_ns_array_to_pd_datetimeindex",
+    "ts_ns_from_int",
+    "ts_ns_from_pd_timestamp",
+    "ts_ns_from_str",
+    "ts_ns_to_int",
+    "ts_ns_to_pd_timestamp",
+    "ts_ns_to_str",
+]

mxm_types-0.1.0/src/mxm/types/__init__.py → mxm_types-0.2.0/src/mxm/types/general.py

@@ -1,8 +1,3 @@
-"""
-Tiny, stable, dependency-free: canonical JSON/path aliases and a micro-protocol
-shared across Money Ex Machina packages.
-"""
-
 from __future__ import annotations
 
 from collections.abc import Mapping, Sequence
@@ -25,6 +20,8 @@ type JSONLike = JSONScalar | Sequence[JSONLike] | Mapping[str, JSONLike]
 type JSONObj = Mapping[str, JSONValue]  # preferred for params (read-only interface)
 type JSONMap = dict[str, JSONValue]  # preferred for concrete, mutable results
 
+type HeadersLike = Mapping[str, str | Sequence[str]]
+
 # Path-like ----------------------------------------------------------------------------
 
 type StrPath = str | PathLike[str]
@@ -43,15 +40,3 @@ class CLIFormatOptions(TypedDict, total=False):
     """Optional CLI format hints used across MXM command outputs."""
 
     format: Literal["plain", "rich", "json"]
-
-
-__all__ = [
-    "CLIFormatOptions",
-    "JSONLike",
-    "JSONMap",
-    "JSONObj",
-    "JSONScalar",
-    "JSONValue",
-    "KVReadable",
-    "StrPath",
-]