mxm-types 0.1.0__tar.gz

mxm_types-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Money Ex Machina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights  
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+copies of the Software, and to permit persons to whom the Software is  
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all  
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE  
+SOFTWARE.

mxm_types-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: mxm-types
+Version: 0.1.0
+Summary: Shared typing primitives for Money Ex Machina.
+License: MIT
+License-File: LICENSE
+Keywords: money-ex-machina,typing,json,types,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
+Project-URL: Homepage, https://github.com/moneyexmachina/
+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 typing primitives for the Money Ex Machina ecosystem.
+
+`mxm-types` provides a canonical, dependency-free set of JSON/path aliases and micro-protocols used across MXM packages.  
+It is intentionally small, stable, and domain-agnostic. All domain models live in their respective packages.
+
+## Install
+
+```bash
+pip install mxm-types
+```
+
+## Overview
+
+`mxm-types` defines:
+
+- **Strict JSON tree types** for use across configuration, metadata, requests, and portable data structures.
+- **Lightweight aliases** for common patterns (e.g., path-like values).
+- **Micro-protocols** for cross-cutting interfaces (e.g., objects with a `get` method).
+- **PEP 561 typing support** (`py.typed` included in the wheel).
+
+The package has **no runtime dependencies**.
+
+## Public API
+
+The following names form the stable public API of `mxm-types`.  
+All other names are private and may change across releases.
+
+### JSON 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 |
+
+### Paths
+
+| Name       | Description |
+|------------|-------------|
+| `StrPath`  | `str \| PathLike[str]` |
+
+### Protocols and TypedDicts
+
+| Name               | Description |
+|--------------------|-------------|
+| `KVReadable`       | Minimal protocol: objects exposing a `get(key, default)` method |
+| `CLIFormatOptions` | Optional formatting hints for CLI output (`"plain" \| "rich" \| "json"`) |
+
+---
+
+## Usage
+
+```python
+from mxm.types import (
+    JSONValue,
+    JSONObj,
+    JSONMap,
+    StrPath,
+    KVReadable,
+    CLIFormatOptions,
+)
+
+def load_metadata(path: StrPath) -> JSONObj:
+    ...
+```
+
+For permissive JSON acceptance (e.g., reading config from arbitrary Python structures):
+
+```python
+from mxm.types import JSONLike
+
+def normalise(data: JSONLike) -> JSONValue:
+    ...
+```
+
+## Design Principles
+
+- **Minimal surface**: only house-style primitives, no domain models.  
+- **Dependency-free**: safe to import everywhere, including low-level layers.  
+- **PEP 695 `type` aliases**: modern, expressive, static-typing-friendly.  
+- **Strict JSON encouraged**: permissive types optional and explicit.  
+
+## Development
+
+```bash
+poetry install
+poetry run ruff check .
+poetry run pyright
+poetry run pytest -q
+poetry build
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+

mxm_types-0.1.0/README.md

@@ -0,0 +1,104 @@
+# `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 typing primitives for the Money Ex Machina ecosystem.
+
+`mxm-types` provides a canonical, dependency-free set of JSON/path aliases and micro-protocols used across MXM packages.  
+It is intentionally small, stable, and domain-agnostic. All domain models live in their respective packages.
+
+## Install
+
+```bash
+pip install mxm-types
+```
+
+## Overview
+
+`mxm-types` defines:
+
+- **Strict JSON tree types** for use across configuration, metadata, requests, and portable data structures.
+- **Lightweight aliases** for common patterns (e.g., path-like values).
+- **Micro-protocols** for cross-cutting interfaces (e.g., objects with a `get` method).
+- **PEP 561 typing support** (`py.typed` included in the wheel).
+
+The package has **no runtime dependencies**.
+
+## Public API
+
+The following names form the stable public API of `mxm-types`.  
+All other names are private and may change across releases.
+
+### JSON 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 |
+
+### Paths
+
+| Name       | Description |
+|------------|-------------|
+| `StrPath`  | `str \| PathLike[str]` |
+
+### Protocols and TypedDicts
+
+| Name               | Description |
+|--------------------|-------------|
+| `KVReadable`       | Minimal protocol: objects exposing a `get(key, default)` method |
+| `CLIFormatOptions` | Optional formatting hints for CLI output (`"plain" \| "rich" \| "json"`) |
+
+---
+
+## Usage
+
+```python
+from mxm.types import (
+    JSONValue,
+    JSONObj,
+    JSONMap,
+    StrPath,
+    KVReadable,
+    CLIFormatOptions,
+)
+
+def load_metadata(path: StrPath) -> JSONObj:
+    ...
+```
+
+For permissive JSON acceptance (e.g., reading config from arbitrary Python structures):
+
+```python
+from mxm.types import JSONLike
+
+def normalise(data: JSONLike) -> JSONValue:
+    ...
+```
+
+## Design Principles
+
+- **Minimal surface**: only house-style primitives, no domain models.  
+- **Dependency-free**: safe to import everywhere, including low-level layers.  
+- **PEP 695 `type` aliases**: modern, expressive, static-typing-friendly.  
+- **Strict JSON encouraged**: permissive types optional and explicit.  
+
+## Development
+
+```bash
+poetry install
+poetry run ruff check .
+poetry run pyright
+poetry run pytest -q
+poetry build
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

mxm_types-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[tool.poetry]
+name = "mxm-types"
+version = "0.1.0"
+description = "Shared typing primitives for Money Ex Machina."
+authors = ["mxm <contact@moneyexmachina.com>"]
+license = "MIT"
+readme = "README.md"
+keywords = ["money-ex-machina", "typing", "json", "types", "pep561"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+packages = [{ include = "mxm", from = "src" }]
+include = [
+  { path = "LICENSE" },
+  { path = "src/mxm/types/py.typed", format = "wheel" },
+]
+
+[tool.poetry.urls]
+"Homepage" = "https://github.com/moneyexmachina/"
+"Repository" = "https://github.com/moneyexmachina/mxm-types"
+"Issues" = "https://github.com/moneyexmachina/mxm-types/issues"
+
+[tool.poetry.dependencies]
+python = ">=3.13,<3.15"
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.14.3"
+black = "^25.9.0"
+isort = "^7.0.0"
+ipython = "^9.5.0"
+pytest = "^8.4.2"
+pyright = "^1.1.407"
+
+[tool.poetry.scripts]
+# (none)
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+exclude = ["build", "dist", ".venv"]
+
+[tool.ruff.lint]
+select = ["E","F","B","UP","C90","RUF"]
+ignore = ["E203","E501","I001","I002"]
+
+[tool.black]
+line-length = 88
+target-version = ["py313"]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+known_first_party = ["mxm"]
+combine_as_imports = true
+force_sort_within_sections = true
+lines_between_types = 1
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = ["src"]

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

@@ -0,0 +1,57 @@
+"""
+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
+from os import PathLike
+from typing import Any, Protocol, TypedDict, runtime_checkable
+from typing import Literal  # stricter options for CLIFormatOptions.format
+
+# JSON types ---------------------------------------------------------------------------
+
+# Scalars exactly representable in JSON (+ None)
+type JSONScalar = str | int | float | bool | None
+
+# Strict JSON: only list/dict at inner nodes. Best for real JSON round-trips.
+type JSONValue = JSONScalar | list[JSONValue] | dict[str, JSONValue]
+
+# Permissive JSON-like: accept any Sequence/Mapping at inner nodes (for inputs).
+type JSONLike = JSONScalar | Sequence[JSONLike] | Mapping[str, JSONLike]
+
+# Top-level mapping conveniences
+type JSONObj = Mapping[str, JSONValue]  # preferred for params (read-only interface)
+type JSONMap = dict[str, JSONValue]  # preferred for concrete, mutable results
+
+# Path-like ----------------------------------------------------------------------------
+
+type StrPath = str | PathLike[str]
+
+# Minimal shared protocol(s) -----------------------------------------------------------
+
+
+@runtime_checkable
+class KVReadable(Protocol):
+    """Any mapping-like with a `get` method (without requiring full Mapping)."""
+
+    def get(self, key: str, default: Any = ...) -> Any: ...
+
+
+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",
+]