mxm-types 0.1.0__py3-none-any.whl

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",
+]

mxm_types-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+mxm/types/__init__.py,sha256=lXmThrbVQq3x7_CWQLSvrcifU9BkCq-4v91Fuf_j4J4,1791
+mxm/types/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mxm_types-0.1.0.dist-info/METADATA,sha256=AhpdeDziLM5O5u9o9xgjIP95HPi3G3gux9tP8XUSAjo,3938
+mxm_types-0.1.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+mxm_types-0.1.0.dist-info/licenses/LICENSE,sha256=xq8z6L9uQsxwFsDj_rw0gXHSqp5V--ukyKkts-q4Zsc,1101
+mxm_types-0.1.0.dist-info/RECORD,,

mxm_types-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

mxm_types-0.1.0.dist-info/licenses/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.