mxm-config 0.2.5__tar.gz

mxm_config-0.2.5/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_config-0.2.5/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: mxm-config
+Version: 0.2.5
+Summary: MXM configuration loader and context resolver
+License: MIT
+License-File: LICENSE
+Keywords: mxm,configuration,omegaconf,settings
+Author: mxm
+Author-email: contact@moneyexmachina.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Dist: omegaconf (>=2.3.0,<3.0.0)
+Project-URL: Homepage, https://github.com/moneyexmachina/mxm-config
+Project-URL: Issues, https://github.com/moneyexmachina/mxm-config/issues
+Project-URL: Repository, https://github.com/moneyexmachina/mxm-config
+Description-Content-Type: text/markdown
+
+# mxm-config
+
+![Version](https://img.shields.io/github/v/release/moneyexmachina/mxm-config)
+![License](https://img.shields.io/github/license/moneyexmachina/mxm-config)
+![Python](https://img.shields.io/badge/python-3.12+-blue)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+
+## Purpose
+
+`mxm-config` provides a unified way to **install, load, layer, and resolve configuration** across all Money Ex Machina (MXM) packages and applications.  
+It separates configuration from secrets and runtime metadata, enforces deterministic layering, and ensures every run has a transparent, reproducible view of its operating context.
+
+---
+
+## Design Principles
+
+- **Separation of concerns**  
+  - Configuration ≠ secrets ≠ runtime.  
+  - Secrets are handled by [`mxm-secrets`](https://github.com/moneyexmachina/mxm-secrets).  
+  - Runtime metadata will be handled by `mxm-runtime` (planned).  
+
+- **Determinism**  
+  - Configuration is layered in a fixed, documented order.  
+  - Reproducible runs: the same context always produces the same resolved config.  
+
+- **Transparency**  
+  - Configs are plain YAML files, no hidden state.  
+  - Merging order is explicit and testable.  
+
+- **Extensibility**  
+  - Layers are minimal and orthogonal.  
+  - New packages can register defaults without breaking existing ones.  
+
+---
+
+## Configuration Layers
+
+At runtime, configuration is resolved by merging up to six layers in order of precedence (lowest → highest):
+
+1. **`default.yaml`**  
+   Baseline shipped with the package.  
+   *Always present.*
+
+2. **`environment.yaml`**  
+   Deployment mode (`dev`, `prod`, …).  
+   Each environment is a block inside this file.
+
+3. **`machine.yaml`**  
+   Host-specific overrides (paths, mounts, resources).  
+
+4. **`profile.yaml`**  
+   Role or user context (`research`, `trading`, …).  
+
+5. **`local.yaml`**  
+   Local scratchpad for ad-hoc tweaks.  
+   *Ignored by version control.*
+
+6. **Explicit overrides (dict)**  
+   Passed directly in code, applied last.
+
+---
+
+## Installing Configs
+
+Use the installer to copy package-shipped configs into the user’s config root (`~/.config/mxm/` by default, override with `$MXM_CONFIG_HOME`).
+
+```python
+from mxm_config.installer import install_all
+
+install_all("mxm_config.examples.demo_config", target_name="demo")
+```
+
+This creates:
+
+```
+~/.config/mxm/demo/default.yaml
+~/.config/mxm/demo/environment.yaml
+~/.config/mxm/demo/machine.yaml
+~/.config/mxm/demo/profile.yaml
+~/.config/mxm/demo/local.yaml
+```
+
+Any `templates/*.yaml` files shipped with the package will also be installed under `~/.config/mxm/<package>/templates/`.
+
+---
+
+## Loading Configs
+
+```python
+from mxm_config.loader import load_config
+
+cfg = load_config("demo", env="dev", profile="research")
+
+print(cfg.parameters.refresh_interval)
+print(cfg.paths.output)
+```
+
+- Context (`mxm_env`, `mxm_profile`, `mxm_machine`) is injected automatically.  
+- All `${...}` interpolations are resolved before returning.  
+- The returned config is read-only by default.
+
+---
+
+## Example Package
+
+The repo ships a minimal demo package: `mxm_config/examples/demo_config`
+
+- `default.yaml` → valid baseline  
+- `environment.yaml` → defines `dev` and `prod`  
+- `machine.yaml` → overrides per host (`bridge`, `wildling`, `monolith`)  
+- `profile.yaml` → defines `research`, `trading`  
+- `local.yaml` → local overrides (optional, not versioned)
+
+This serves as a test fixture for installers and loaders.
+
+---
+
+## Testing
+
+Tests use `pytest` with `monkeypatch` to isolate config roots and hostnames.
+
+Run with:
+
+```bash
+poetry run pytest
+```
+
+---
+
+## Roadmap
+
+- Config schema validation (via `omegaconf.structured` or pydantic)  
+- CLI tool (`mxm-config install demo`)  
+- Environment variable overrides → auto-mapped into overrides dict  
+- Integration with `mxm-runtime` for provenance tracking  
+- Config hashing for reproducibility and auditability  
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+

mxm_config-0.2.5/README.md

@@ -0,0 +1,142 @@
+# mxm-config
+
+![Version](https://img.shields.io/github/v/release/moneyexmachina/mxm-config)
+![License](https://img.shields.io/github/license/moneyexmachina/mxm-config)
+![Python](https://img.shields.io/badge/python-3.12+-blue)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+
+## Purpose
+
+`mxm-config` provides a unified way to **install, load, layer, and resolve configuration** across all Money Ex Machina (MXM) packages and applications.  
+It separates configuration from secrets and runtime metadata, enforces deterministic layering, and ensures every run has a transparent, reproducible view of its operating context.
+
+---
+
+## Design Principles
+
+- **Separation of concerns**  
+  - Configuration ≠ secrets ≠ runtime.  
+  - Secrets are handled by [`mxm-secrets`](https://github.com/moneyexmachina/mxm-secrets).  
+  - Runtime metadata will be handled by `mxm-runtime` (planned).  
+
+- **Determinism**  
+  - Configuration is layered in a fixed, documented order.  
+  - Reproducible runs: the same context always produces the same resolved config.  
+
+- **Transparency**  
+  - Configs are plain YAML files, no hidden state.  
+  - Merging order is explicit and testable.  
+
+- **Extensibility**  
+  - Layers are minimal and orthogonal.  
+  - New packages can register defaults without breaking existing ones.  
+
+---
+
+## Configuration Layers
+
+At runtime, configuration is resolved by merging up to six layers in order of precedence (lowest → highest):
+
+1. **`default.yaml`**  
+   Baseline shipped with the package.  
+   *Always present.*
+
+2. **`environment.yaml`**  
+   Deployment mode (`dev`, `prod`, …).  
+   Each environment is a block inside this file.
+
+3. **`machine.yaml`**  
+   Host-specific overrides (paths, mounts, resources).  
+
+4. **`profile.yaml`**  
+   Role or user context (`research`, `trading`, …).  
+
+5. **`local.yaml`**  
+   Local scratchpad for ad-hoc tweaks.  
+   *Ignored by version control.*
+
+6. **Explicit overrides (dict)**  
+   Passed directly in code, applied last.
+
+---
+
+## Installing Configs
+
+Use the installer to copy package-shipped configs into the user’s config root (`~/.config/mxm/` by default, override with `$MXM_CONFIG_HOME`).
+
+```python
+from mxm_config.installer import install_all
+
+install_all("mxm_config.examples.demo_config", target_name="demo")
+```
+
+This creates:
+
+```
+~/.config/mxm/demo/default.yaml
+~/.config/mxm/demo/environment.yaml
+~/.config/mxm/demo/machine.yaml
+~/.config/mxm/demo/profile.yaml
+~/.config/mxm/demo/local.yaml
+```
+
+Any `templates/*.yaml` files shipped with the package will also be installed under `~/.config/mxm/<package>/templates/`.
+
+---
+
+## Loading Configs
+
+```python
+from mxm_config.loader import load_config
+
+cfg = load_config("demo", env="dev", profile="research")
+
+print(cfg.parameters.refresh_interval)
+print(cfg.paths.output)
+```
+
+- Context (`mxm_env`, `mxm_profile`, `mxm_machine`) is injected automatically.  
+- All `${...}` interpolations are resolved before returning.  
+- The returned config is read-only by default.
+
+---
+
+## Example Package
+
+The repo ships a minimal demo package: `mxm_config/examples/demo_config`
+
+- `default.yaml` → valid baseline  
+- `environment.yaml` → defines `dev` and `prod`  
+- `machine.yaml` → overrides per host (`bridge`, `wildling`, `monolith`)  
+- `profile.yaml` → defines `research`, `trading`  
+- `local.yaml` → local overrides (optional, not versioned)
+
+This serves as a test fixture for installers and loaders.
+
+---
+
+## Testing
+
+Tests use `pytest` with `monkeypatch` to isolate config roots and hostnames.
+
+Run with:
+
+```bash
+poetry run pytest
+```
+
+---
+
+## Roadmap
+
+- Config schema validation (via `omegaconf.structured` or pydantic)  
+- CLI tool (`mxm-config install demo`)  
+- Environment variable overrides → auto-mapped into overrides dict  
+- Integration with `mxm-runtime` for provenance tracking  
+- Config hashing for reproducibility and auditability  
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

mxm_config-0.2.5/mxm_config/__init__.py

@@ -0,0 +1,50 @@
+"""
+Public API for mxm-config.
+
+This package loads layered configuration for MXM apps and installs standard
+OmegaConf resolvers (e.g., `${cwd:}`, `${env:VAR}`) on import.
+
+Typical usage
+-------------
+    from mxm_config import MXMConfig, load_config, install_all
+
+    # (Optional) Install package config files into ~/.config/mxm/<package>/
+    install_all()
+
+    # Load layered config for your app/package
+    cfg: MXMConfig = load_config(
+        package="mxm-datakraken",
+        env="dev",
+        profile="default",
+    )
+
+    # Use ergonomic dot-notation
+    root = cfg.paths.sources.justetf.root
+    # Or mapping-style access
+    root2 = cfg["paths"]["sources"]["justetf"]["root"]
+
+Notes
+-----
+- Downstream packages should import from `mxm_config` (this module) and type
+  against the `MXMConfig` protocol rather than importing OmegaConf directly.
+- `load_config` returns an object that satisfies `MXMConfig` (backed by
+  OmegaConf DictConfig internally).
+"""
+
+from __future__ import annotations
+
+from mxm_config.api import make_subconfig
+from mxm_config.init_resolvers import register_mxm_resolvers
+from mxm_config.installer import install_all
+from mxm_config.loader import load_config
+from mxm_config.types import MXMConfig
+
+# Register standard MXM resolvers at import time so `${...}` interpolations work globally.
+register_mxm_resolvers()
+
+__all__ = [
+    "MXMConfig",
+    "install_all",
+    "load_config",
+    "make_subconfig",
+]

mxm_config-0.2.5/mxm_config/api.py

@@ -0,0 +1,66 @@
+"""
+Public helpers for working with MXM configuration objects.
+
+This module exposes utilities that produce or transform objects conforming to
+the `MXMConfig` protocol without requiring callers to import OmegaConf.
+
+`make_subconfig` is a tiny factory that turns a plain mapping into an object
+behaving like your app config (supports both attribute and item access), backed
+by OmegaConf `DictConfig` under the hood and typed as `MXMConfig`.
+
+Typical use cases:
+- Build a minimal, self-contained config for a subsystem (e.g., DataIO).
+- Construct tiny configs in unit tests without loading layered YAML.
+- Provide a focused “view” of a larger config tree at a package boundary.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .types import MXMConfig
+
+__all__ = ["make_subconfig"]
+
+
+def make_subconfig(
+    data: Mapping[str, Any],
+    *,
+    readonly: bool = True,
+    resolve: bool = False,
+) -> MXMConfig:
+    """
+    Create an `MXMConfig` from a plain mapping.
+
+    Parameters
+    ----------
+    data
+        Plain nested mapping to convert into a config-shaped object.
+    readonly
+        If True (default), the returned config is set read-only.
+    resolve
+        If True, resolve `${...}` interpolations immediately.
+
+    Returns
+    -------
+    MXMConfig
+        An object supporting both dot and item access. Internally an
+        OmegaConf `DictConfig`, but typed as the protocol to keep OmegaConf
+        out of consumer APIs.
+
+    Notes
+    -----
+    - OmegaConf is imported locally to avoid exposing it to consumers.
+    - Use `resolve=True` if your subconfig contains `${...}` expressions
+      that should be evaluated right away.
+    """
+    # Local import to keep OmegaConf out of public type signatures for consumers.
+    from omegaconf import OmegaConf  # type: ignore
+
+    cfg = OmegaConf.create(dict(data))
+    if resolve:
+        OmegaConf.resolve(cfg)
+    if readonly:
+        OmegaConf.set_readonly(cfg, True)
+    # The returned object satisfies MXMConfig structurally (attr + item access).
+    return cfg

mxm_config-0.2.5/mxm_config/examples/demo_config/default.yaml

@@ -0,0 +1,10 @@
+project: "mxm-config demo"
+version: "0.1.0"
+
+paths:
+  output: "${paths.base_output}/${mxm_env}/${mxm_profile}"
+  logs: "${paths.base_output}/logs/${mxm_env}"
+
+parameters:
+  refresh_interval: "5min"
+  sample_count: 10

mxm_config-0.2.5/mxm_config/examples/demo_config/environment.yaml

@@ -0,0 +1,9 @@
+dev:
+  parameters:
+    sample_count: 1
+    refresh_interval: "1min"
+
+prod:
+  parameters:
+    sample_count: 100
+    refresh_interval: "10min"

mxm_config-0.2.5/mxm_config/examples/demo_config/local.yaml

@@ -0,0 +1,2 @@
+parameters:
+  sample_count: 42

mxm_config-0.2.5/mxm_config/examples/demo_config/machine.yaml

@@ -0,0 +1,11 @@
+bridge:
+  paths:
+    base_output: "/Users/mxm/demo_output"
+
+wildling:
+  paths:
+    base_output: "/mnt/wildling/demo_output"
+
+monolith:
+  paths:
+    base_output: "/srv/monolith/demo_output"

mxm_config-0.2.5/mxm_config/examples/demo_config/profile.yaml

@@ -0,0 +1,8 @@
+research:
+  parameters:
+    refresh_interval: "30min"
+
+trading:
+  parameters:
+    refresh_interval: "5s"
+    sample_count: 999

mxm_config-0.2.5/mxm_config/init_resolvers.py

@@ -0,0 +1,81 @@
+# mxm_config/init_resolvers.py
+"""Registration of standard MXM resolvers for OmegaConf interpolation.
+
+Resolvers provided:
+  - ${cwd:}                 -> current working directory
+  - ${home:}                -> user's home directory
+  - ${env:VAR[,default]}    -> environment variable lookup with optional default
+  - ${timestamp:}           -> ISO timestamp (seconds precision)
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import os as _os
+from typing import Any, Callable, cast
+
+from omegaconf import OmegaConf
+
+# --- Typed resolver functions -------------------------------------------------
+
+
+def _cwd_resolver() -> str:
+    """Return the current working directory."""
+    return _os.getcwd()
+
+
+def _home_resolver() -> str:
+    """Return the user's home directory."""
+    return _os.path.expanduser("~")
+
+
+def _env_resolver(key: str, default: str | None = None) -> str | None:
+    """Resolve an environment variable.
+
+    Args:
+        key: Environment variable name.
+        default: Value to return if the variable is unset.
+
+    Returns:
+        The env var value if set, otherwise `default`.
+    """
+    value = _os.getenv(key)
+    return value if value is not None else default
+
+
+def _timestamp_resolver() -> str:
+    """Return the current timestamp (ISO 8601, seconds precision)."""
+    return _dt.datetime.now().isoformat(timespec="seconds")
+
+
+# --- Public API ---------------------------------------------------------------
+
+
+def register_mxm_resolvers() -> None:
+    """Register MXM resolvers if not already present.
+
+    Notes:
+        We cast the typed callables to `Callable[..., Any]` at registration
+        time because OmegaConf's type hints are permissive and do not model
+        per-resolver signatures precisely.
+    """
+    if not OmegaConf.has_resolver("cwd"):
+        OmegaConf.register_new_resolver(
+            "cwd",
+            cast(Callable[..., Any], _cwd_resolver),
+        )
+    if not OmegaConf.has_resolver("home"):
+        OmegaConf.register_new_resolver(
+            "home",
+            cast(Callable[..., Any], _home_resolver),
+        )
+    if not OmegaConf.has_resolver("env"):
+        OmegaConf.register_new_resolver(
+            "env",
+            cast(Callable[..., Any], _env_resolver),
+        )
+    if not OmegaConf.has_resolver("timestamp"):
+        OmegaConf.register_new_resolver(
+            "timestamp",
+            cast(Callable[..., Any], _timestamp_resolver),
+        )

mxm_config-0.2.5/mxm_config/initializer.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+from mxm_config.resolver import get_config_root
+
+
+def initiate_mxm_configs(
+    config_root: Path | None = None,
+    create_if_missing: bool = True,
+) -> Path:
+    """
+    Resolve and optionally create the MXM config root directory.
+
+    Args:
+        config_root: Optional explicit path to use.
+        create_if_missing: Whether to create the directory if it does not exist.
+
+    Returns:
+        The resolved config root Path.
+    """
+    resolved_root = config_root or get_config_root()
+
+    if create_if_missing:
+        resolved_root.mkdir(parents=True, exist_ok=True)
+
+    return resolved_root

mxm_config-0.2.5/mxm_config/installer.py

@@ -0,0 +1,66 @@
+import shutil
+from importlib.resources import files
+from pathlib import Path
+from typing import List, Optional, cast
+
+from mxm_config.resolver import get_config_root
+
+_CORE_FILES: list[str] = [
+    "default.yaml",
+    "environment.yaml",
+    "machine.yaml",
+    "profile.yaml",
+    "local.yaml",
+]
+
+
+def install_all(
+    package: str,
+    target_root: Optional[Path] = None,
+    target_name: Optional[str] = None,
+    overwrite: bool = False,
+) -> List[Path]:
+    """Install all known config files from a package into ~/.config/mxm/<package>/.
+
+    Args:
+        package: Import path to the package providing config files,
+            e.g. ``"mxm_config.examples.demo_config"``.
+        target_root: Optional override for the mxm config root.
+            Defaults to ``~/.config/mxm``.
+        target_name: Optional override for the subdirectory name under the config root.
+            By default, the last component of the package name is used.
+        overwrite: Whether to overwrite existing files if they already exist.
+
+    Returns:
+        A list of installed file paths.
+    """
+    config_root: Path = target_root if target_root else get_config_root()
+    package_dir: str = target_name or package.split(".")[-1]
+    dst_root: Path = config_root / package_dir
+    dst_root.mkdir(parents=True, exist_ok=True)
+
+    installed: List[Path] = []
+
+    for fname in _CORE_FILES:
+        src = files(package).joinpath(fname)
+        if src.is_file():
+            dst = dst_root / fname
+            if dst.exists() and not overwrite:
+                continue
+            shutil.copy(str(src), str(dst))
+            installed.append(dst)
+
+    src_templates = files(package).joinpath("templates")
+    if src_templates.is_dir():
+        tmpl_root = dst_root / "templates"
+        tmpl_root.mkdir(parents=True, exist_ok=True)
+        for src in src_templates.iterdir():
+            src_path = cast(Path, src)
+            if src_path.suffix == ".yaml":
+                dst = tmpl_root / src_path.name
+                if dst.exists() and not overwrite:
+                    continue
+                shutil.copy(str(src), str(dst))
+                installed.append(dst)
+
+    return installed

mxm_config-0.2.5/mxm_config/loader.py

@@ -0,0 +1,168 @@
+"""
+Configuration loader for MXM apps (layered OmegaConf).
+
+This module composes the final, read-only configuration object for a given
+`package` by merging a standard set of YAML layers located under the MXM
+config root (e.g., `~/.config/mxm/<package>`). Layering order is stable and
+well-defined (low → high precedence):
+
+  1) default.yaml               — always applied if present
+  2) environment.yaml[env]      — the block matching the resolved environment
+  3) machine.yaml[machine]      — the block matching the resolved machine/host
+  4) profile.yaml[profile]      — the block matching the resolved profile
+  5) local.yaml                 — optional, for developer overrides
+  6) overrides (in-memory)      — explicit dict passed to `load_config(...)`
+
+Resolution helpers in `mxm_config.resolver` normalize `env`, `profile`, and
+`machine` (e.g., deriving defaults from environment variables or hostname).
+
+The resulting OmegaConf DictConfig is:
+  - fully resolved (interpolations evaluated),
+  - merged according to the order above,
+  - and set to read-only.
+
+Downstream packages should generally import `load_config` via
+`mxm_config.__init__` and type against the `MXMConfig` protocol instead of
+depending on OmegaConf directly.
+"""
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, Callable, Union, cast
+
+from omegaconf import DictConfig, ListConfig, OmegaConf
+
+from mxm_config.resolver import (
+    get_config_root,
+    resolve_environment,
+    resolve_machine,
+    resolve_profile,
+)
+from mxm_config.types import MXMConfig
+
+Layer = Union[ListConfig, DictConfig]
+
+
+def load_config(
+    package: str,
+    env: str,
+    profile: str,
+    machine: str | None = None,
+    root: Path | None = None,
+    overrides: Mapping[str, Any] | None = None,
+) -> MXMConfig:
+    """
+    Load the MXM configuration by composing layered YAML files.
+
+    The configuration directory is determined by combining the MXM config root
+    (``~/.config/mxm`` by default, or overridden by ``MXM_CONFIG_HOME``) and
+    the given ``package`` name (e.g. ``demo``). This directory is populated
+    when configs are installed using :func:`install_all`.
+
+    Layers are merged in the following order (lowest → highest precedence):
+
+        1. ``default.yaml``          — always applied if present
+        2. ``environment.yaml``      — only the block matching ``env`` is applied
+        3. ``machine.yaml``          — only the block matching current hostname
+        4. ``profile.yaml``          — only the block matching ``profile``
+        5. ``local.yaml``            — applied if present
+        6. explicit overrides dict   — passed via ``overrides`` argument
+
+    Args:
+        package: Name of the config subdirectory under the MXM config root.
+        env: Environment selector (e.g. ``"dev"``, ``"prod"``).
+        profile: Profile selector (e.g. ``"default"``, ``"research"``).
+        machine: Optional explicit machine name override.
+        root: Optional config root path override.
+        overrides: Optional dictionary of overrides applied last.
+
+    Returns:
+        OmegaConf: A frozen OmegaConf config object with all layers
+        merged and interpolated.
+    """
+    base_root = Path(root) if root is not None else get_config_root()
+    cfg_root = base_root / Path(str(package))
+
+    context_cfg = OmegaConf.create(
+        {
+            "mxm_env": resolve_environment(env),
+            "mxm_profile": resolve_profile(profile),
+            "mxm_machine": resolve_machine(machine),
+        }
+    )
+    layers: list[Layer] = [context_cfg]
+
+    default_cfg = _load_yaml_if_exists(cfg_root / "default.yaml")
+    if default_cfg:
+        layers.append(default_cfg)
+
+    env_cfg = _load_block(env, cfg_root / "environment.yaml", resolve_environment)
+    if env_cfg:
+        layers.append(env_cfg)
+
+    machine_cfg = _load_block(machine, cfg_root / "machine.yaml", resolve_machine)
+    if machine_cfg:
+        layers.append(machine_cfg)
+
+    profile_cfg = _load_block(
+        profile, cfg_root / "profile.yaml", resolve_profile, allow_default_skip=True
+    )
+    if profile_cfg:
+        layers.append(profile_cfg)
+
+    local_cfg = _load_yaml_if_exists(cfg_root / "local.yaml")
+    if local_cfg:
+        layers.append(local_cfg)
+
+    if overrides is not None:
+        overrides_cfg: DictConfig = OmegaConf.create(dict(overrides))
+        layers.append(overrides_cfg)
+
+    merged: DictConfig = OmegaConf.merge(*layers)  # type: ignore[assignment]
+    OmegaConf.resolve(merged)
+    OmegaConf.set_readonly(merged, True)
+    return cast(MXMConfig, merged)
+
+
+def _load_block(
+    selector: str | None,
+    path: Path,
+    resolver: Callable[[str | None], str],
+    allow_default_skip: bool = False,
+) -> DictConfig | None:
+    """
+    Resolve and load a configuration block from a YAML file.
+
+    Args:
+        selector: Raw selector value (e.g. env, profile, machine).
+        path: Path to the YAML file.
+        resolver: Function to normalize the selector.
+        allow_default_skip: If True, missing "default" selector will return None
+            instead of raising KeyError (used for profiles).
+
+    Returns:
+        DictConfig block for the selector, or None if skipped.
+
+    Raises:
+        KeyError: If YAML exists but selector not defined.
+    """
+    resolved = resolver(selector)
+
+    if not path.exists():
+        return None
+
+    cfg: DictConfig = OmegaConf.load(path)  # type: ignore[assignment]
+
+    if resolved in cfg:
+        return cfg[resolved]  # type: ignore[index]
+    elif allow_default_skip and resolved == "default":
+        return None
+    else:
+        raise KeyError(
+            f"Selector '{resolved}' not found in {path}. Available: {list(cfg.keys())}"
+        )
+
+
+def _load_yaml_if_exists(path: Path):
+    """Load a YAML file into an OmegaConf config if it exists, else return None."""
+    return OmegaConf.load(path) if path.exists() else None

mxm_config-0.2.5/mxm_config/resolver.py

@@ -0,0 +1,77 @@
+import os
+import socket
+from pathlib import Path
+
+
+def get_config_root() -> Path:
+    """
+    Resolve the MXM config root.
+
+    Precedence:
+      1) MXM_CONFIG_HOME  -> <dir>
+      2) XDG_CONFIG_HOME  -> <dir>/mxm
+      3) HOME             -> <HOME>/.config/mxm
+    """
+    override = os.getenv("MXM_CONFIG_HOME")
+    if override:
+        return Path(override).expanduser()
+
+    xdg = os.getenv("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg).expanduser() / "mxm"
+
+    return Path.home() / ".config" / "mxm"
+
+
+def resolve_environment(env: str | None = None) -> str:
+    """Resolve environment (must be explicitly provided).
+
+    Args:
+        env: The chosen environment (e.g. "dev", "prod").
+
+    Returns:
+        The environment string.
+
+    Raises:
+        ValueError: If env is not provided.
+    """
+    if env is None:
+        raise ValueError("Environment must be specified (e.g. 'dev', 'prod').")
+    return env
+
+
+def resolve_profile(profile: str | None = None) -> str:
+    """Resolve profile (must be explicitly provided).
+
+    Args:
+        profile: The chosen profile (e.g. "research", "trading").
+
+    Returns:
+        The profile string.
+
+    Raises:
+        ValueError: If profile is not provided.
+    """
+    if profile is None:
+        raise ValueError("Profile must be specified (e.g. 'research', 'trading').")
+    return profile
+
+
+def resolve_machine(machine: str | None = None) -> str:
+    """Resolve machine identifier.
+
+    Resolution order:
+        1. Explicit argument
+        2. Environment variable: MXM_MACHINE
+        3. Fallback to system hostname
+    """
+    if machine is not None:
+        return machine
+
+    env_machine = os.getenv("MXM_MACHINE")
+    if env_machine:
+        return env_machine
+    hostname = socket.gethostname().lower()
+    if hostname.endswith(".local"):
+        hostname = hostname[:-6]
+    return hostname

mxm_config-0.2.5/mxm_config/types.py

@@ -0,0 +1,34 @@
+"""
+Lightweight protocol(s) for application configuration objects.
+
+`MXMConfig` is a runtime-agnostic interface that downstream packages can
+type against without importing OmegaConf. It models the two access styles
+we support post-load:
+
+- Attribute access (dot-notation): `cfg.paths.sources.justetf.root`
+- Item access (mapping-style):     `cfg["paths"]["sources"]["justetf"]["root"]`
+
+Any object that implements these (e.g., OmegaConf DictConfig, SimpleNamespace
+with __getitem__ shim, or a small wrapper) will satisfy this protocol.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class MXMConfig(Protocol):
+    """Opaque app config supporting attribute and item access.
+
+    Notes
+    -----
+    - This is intentionally minimal. Do not add OmegaConf-specific methods.
+    - Keep it broad so tests can pass lightweight stand-ins.
+    """
+
+    # Attribute access: cfg.foo
+    def __getattr__(self, key: str) -> Any: ...
+
+    # Item access: cfg["foo"]
+    def __getitem__(self, key: str) -> Any: ...

mxm_config-0.2.5/pyproject.toml

@@ -0,0 +1,68 @@
+[tool.poetry]
+name = "mxm-config"
+version = "0.2.5"
+description = "MXM configuration loader and context resolver"
+authors = ["mxm <contact@moneyexmachina.com>"]
+license = "MIT"
+readme = "README.md"
+keywords = ["mxm", "configuration", "omegaconf", "settings"]
+exclude = ["dist/*", "build/*", "*.egg-info/*", ".venv/*"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+packages = [{ include = "mxm_config" }]
+include = [
+  "LICENSE",
+  "mxm_config/examples/demo_config/*.yaml",
+  "mxm_config/py.typed",
+]
+[tool.poetry.urls]
+"Homepage" = "https://github.com/moneyexmachina/mxm-config"
+"Repository" = "https://github.com/moneyexmachina/mxm-config"
+"Issues" = "https://github.com/moneyexmachina/mxm-config/issues"
+[tool.poetry.dependencies]
+python = ">=3.12,<4.0"
+omegaconf = ">=2.3.0,<3.0.0"
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.13.0"
+black = "^25.1.0"
+isort = "^6.0.1"
+ipython = "^9.5.0"
+pytest = "^8.4.2"
+
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+select = ["E", "F", "B", "ANN"]
+ignore = ["ANN101", "ANN102"]
+exclude = ["build", "dist", ".venv"]
+
+[tool.black]
+line-length = 88
+target-version = ["py312"]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+known_first_party = ["mxm_config"]
+known_third_party = ["omegaconf"]
+combine_as_imports = true
+
+[tool.pyright]
+typeCheckingMode = "strict"
+include = ["mxm_config"]
+exclude = ["build", "dist", "docs", ".venv"]
+pythonVersion = "3.12"
+pythonPlatform = "All"
+reportMissingImports = "error"
+reportMissingTypeStubs = "warning"