canopee 0.0.2__tar.gz

canopee-0.0.2/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.3
+Name: canopee
+Version: 0.0.2
+Summary: A type-safe python configuration library
+Author: Alexandre Mayerowitz
+Author-email: Alexandre Mayerowitz <alexandre.mayerowitz@gmail.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: tomli-w>=1.2.0
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/mayeroa/canopee
+Project-URL: Homepage, https://mayeroa.github.io/canopee/
+Project-URL: Documentation, https://mayeroa.github.io/canopee/
+Project-URL: Issues, https://github.com/mayeroa/canopee/issues
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <h1>🌲 Canopee</h1>
+  <p><strong>A type-safe, fluent configuration library for Python 3.11+.</strong></p>
+  <p>
+    <a href="https://pypi.org/project/canopee/"><img src="https://img.shields.io/pypi/v/canopee.svg" alt="PyPI version"></a>
+    <a href="https://pypi.org/project/canopee/"><img src="https://img.shields.io/pypi/pyversions/canopee.svg" alt="Python versions"></a>
+    <a href="https://github.com/canopee-py/canopee/actions"><img src="https://img.shields.io/github/actions/workflow/status/canopee-py/canopee/ci.yml?branch=main" alt="CI Status"></a>
+  </p>
+</div>
+
+---
+
+**Canopee** is a production-ready configuration library that treats Python as the ultimate config DSL. 
+
+Built on top of Pydantic v2, it removes the brittleness of YAMLs, silent mutation footguns, and metaclass magic, giving you IDE autocomplete, instant validation, and elegant hyperparameter sweeping out of the box.
+
+## 🌟 Why Canopee?
+
+* **Always Valid**: Configs are validated precisely at construction. No runtime surprises.
+* **Immutable**: `ConfigBase` objects are `frozen=True`. They can be hashed, cached, and safely passed across threads.
+* **Type-Safe Evolution**: Evolve new variants purely with Python keywords via the `.evolve(**kwargs)` method.
+* **First-Class Sweeps**: Define hyperparameter search spaces directly over your types, using strategies like *grid*, *random*, or *optuna*.
+* **Symmetric I/O**: Naturally save and load instances via `.toml`, `.yaml`, or `.json` extensions natively, or inject CLI/Env overrides securely.
+
+## 🚀 Quickstart
+
+### Installation
+```bash
+pip install canopee
+```
+
+### Basic Usage
+
+Subclass `ConfigBase` as you would any Pydantic model. 
+
+```python
+from canopee import ConfigBase
+from pydantic import computed_field
+
+class TrainingConfig(ConfigBase):
+    learning_rate: float = 1e-3
+    epochs: int = 20
+    batch_size: int = 128
+
+    @computed_field
+    @property
+    def total_steps(self) -> int:
+        return self.epochs * (10_000 // self.batch_size)
+
+# 1. Instantiate (validated instantly)
+cfg = TrainingConfig()
+
+# 2. Evolve (returns a new modified frozen instance, IDE autocomplete works perfectly!)
+fast_cfg = cfg.evolve(epochs=5, learning_rate=5e-3)
+
+# Computed fields naturally update based on the new instance values
+print(fast_cfg.total_steps)
+
+# 3. Save it to disk (JSON, TOML, YAML supported out-of-the-box)
+fast_cfg.save("experiment.toml")
+```
+
+### Sweeps
+
+Native support for generating massive, reproducible configuration variants.
+
+```python
+from canopee.sweep import Sweep, log_uniform, choice
+
+def train(cfg: TrainingConfig) -> float:
+    # return accuracy metric here
+    return 0.95
+
+best_cfg = (
+    Sweep(TrainingConfig())
+    .vary("learning_rate", log_uniform(1e-5, 1e-1))
+    .vary("batch_size", choice(32, 64, 128))
+    .strategy("random", n_samples=20, seed=42)
+    .run(train)
+    .best(minimize=False)
+)
+```
+
+## 📖 Documentation
+
+The full documentation—including Guides on advanced `ConfigStore` registries and `cli/env` Source merging—can be generated by running:
+
+```bash
+uv run zensical serve
+```

canopee-0.0.2/README.md

@@ -0,0 +1,90 @@
+<div align="center">
+  <h1>🌲 Canopee</h1>
+  <p><strong>A type-safe, fluent configuration library for Python 3.11+.</strong></p>
+  <p>
+    <a href="https://pypi.org/project/canopee/"><img src="https://img.shields.io/pypi/v/canopee.svg" alt="PyPI version"></a>
+    <a href="https://pypi.org/project/canopee/"><img src="https://img.shields.io/pypi/pyversions/canopee.svg" alt="Python versions"></a>
+    <a href="https://github.com/canopee-py/canopee/actions"><img src="https://img.shields.io/github/actions/workflow/status/canopee-py/canopee/ci.yml?branch=main" alt="CI Status"></a>
+  </p>
+</div>
+
+---
+
+**Canopee** is a production-ready configuration library that treats Python as the ultimate config DSL. 
+
+Built on top of Pydantic v2, it removes the brittleness of YAMLs, silent mutation footguns, and metaclass magic, giving you IDE autocomplete, instant validation, and elegant hyperparameter sweeping out of the box.
+
+## 🌟 Why Canopee?
+
+* **Always Valid**: Configs are validated precisely at construction. No runtime surprises.
+* **Immutable**: `ConfigBase` objects are `frozen=True`. They can be hashed, cached, and safely passed across threads.
+* **Type-Safe Evolution**: Evolve new variants purely with Python keywords via the `.evolve(**kwargs)` method.
+* **First-Class Sweeps**: Define hyperparameter search spaces directly over your types, using strategies like *grid*, *random*, or *optuna*.
+* **Symmetric I/O**: Naturally save and load instances via `.toml`, `.yaml`, or `.json` extensions natively, or inject CLI/Env overrides securely.
+
+## 🚀 Quickstart
+
+### Installation
+```bash
+pip install canopee
+```
+
+### Basic Usage
+
+Subclass `ConfigBase` as you would any Pydantic model. 
+
+```python
+from canopee import ConfigBase
+from pydantic import computed_field
+
+class TrainingConfig(ConfigBase):
+    learning_rate: float = 1e-3
+    epochs: int = 20
+    batch_size: int = 128
+
+    @computed_field
+    @property
+    def total_steps(self) -> int:
+        return self.epochs * (10_000 // self.batch_size)
+
+# 1. Instantiate (validated instantly)
+cfg = TrainingConfig()
+
+# 2. Evolve (returns a new modified frozen instance, IDE autocomplete works perfectly!)
+fast_cfg = cfg.evolve(epochs=5, learning_rate=5e-3)
+
+# Computed fields naturally update based on the new instance values
+print(fast_cfg.total_steps)
+
+# 3. Save it to disk (JSON, TOML, YAML supported out-of-the-box)
+fast_cfg.save("experiment.toml")
+```
+
+### Sweeps
+
+Native support for generating massive, reproducible configuration variants.
+
+```python
+from canopee.sweep import Sweep, log_uniform, choice
+
+def train(cfg: TrainingConfig) -> float:
+    # return accuracy metric here
+    return 0.95
+
+best_cfg = (
+    Sweep(TrainingConfig())
+    .vary("learning_rate", log_uniform(1e-5, 1e-1))
+    .vary("batch_size", choice(32, 64, 128))
+    .strategy("random", n_samples=20, seed=42)
+    .run(train)
+    .best(minimize=False)
+)
+```
+
+## 📖 Documentation
+
+The full documentation—including Guides on advanced `ConfigStore` registries and `cli/env` Source merging—can be generated by running:
+
+```bash
+uv run zensical serve
+```

canopee-0.0.2/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["uv_build>=0.10.8,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "canopee"
+version = "0.0.2"
+description = "A type-safe python configuration library"
+readme = "README.md"
+authors = [
+    { name = "Alexandre Mayerowitz", email = "alexandre.mayerowitz@gmail.com" },
+]
+requires-python = ">=3.11"
+dependencies = ["pydantic>=2.12.5", "tomli-w>=1.2.0"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Repository = "https://github.com/mayeroa/canopee"
+Homepage = "https://mayeroa.github.io/canopee/"
+Documentation = "https://mayeroa.github.io/canopee/"
+Issues = "https://github.com/mayeroa/canopee/issues"
+
+[dependency-groups]
+click = ["click>=8.3.1"]
+dev = [
+    "mkdocs-material>=9.7.4",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.4",
+    "zensical>=0.0.24",
+]
+ml = ["lightning>=2.6.1", "torch>=2.10.0", "torchvision>=0.25.0"]
+typer = ["typer>=0.24.1"]
+
+[tool.ruff.lint]
+extend-select = [
+    "F",   # Pyflakes rules
+    "W",   # PyCodeStyle warnings
+    "E",   # PyCodeStyle errors
+    "I",   # Sort imports properly
+    "UP",  # Warn if certain things can changed due to newer Python versions
+    "C4",  # Catch incorrect use of comprehensions, dict, list, etc
+    "FA",  # Enforce from __future__ import annotations
+    "ISC", # Good use of string concatenation
+    "ICN", # Use common import conventions
+    "RET", # Good return practices
+    "SIM", # Common simplification rules
+    "TID", # Some good import practices
+    "TC",  # Enforce importing certain types in a TYPE_CHECKING block
+    "PTH", # Use pathlib instead of os.path
+    "TD",  # Be diligent with TODO comments
+    "NPY", # Some numpy-specific things
+]
+
+
+[tool.pytest.ini_options]
+addopts = "--maxfail=1 --cov=canopee"

canopee-0.0.2/src/canopee/__init__.py

@@ -0,0 +1,77 @@
+"""
+canopee
+~~~~~~~
+
+A type-safe, Pydantic-native configuration library with elegant
+composition, immutable configs, and a powerful Sweep engine.
+
+Quick start::
+
+    from canopee import ConfigBase
+    from pydantic import Field, computed_field
+
+    class TrainingConfig(ConfigBase):
+        lr: float = Field(default=1e-3, ge=0.0, le=1.0)
+        epochs: int = 10
+
+        @computed_field
+        @property
+        def warmup_steps(self) -> int:
+            return self.epochs * 100
+
+    cfg = TrainingConfig()
+
+    # Dict / dot-path override:
+    fast = cfg | {"lr": 1e-2, "epochs": 3}
+
+    # Typed keyword override:
+    fast = cfg.evolve(lr=1e-2, epochs=3)
+
+    # Save / load:
+    save(cfg, "run.toml")
+    cfg2 = load(TrainingConfig, "run.toml")
+
+    # String serialization:
+    text = dumps(cfg, "yaml")
+    cfg3 = loads(TrainingConfig, "yaml", text)
+"""
+
+from canopee import sweep as sweep
+from canopee.cli import clify, ArgparseBackend, ClickBackend, TyperBackend
+from canopee.core import ConfigBase, diff, evolve, to_flat
+from canopee.sources import (
+    CLISource,
+    DictSource,
+    EnvSource,
+    FileSource,
+    Source,
+    merge_sources,
+)
+from canopee.serialization import dumps, load, loads, save
+from canopee.store import ConfigStore, global_store
+
+__all__ = [
+    "ConfigBase",
+    "ConfigStore",
+    "global_store",
+    "Source",
+    "EnvSource",
+    "CLISource",
+    "FileSource",
+    "DictSource",
+    "merge_sources",
+    "sweep",
+    "clify",
+    "ArgparseBackend",
+    "ClickBackend",
+    "TyperBackend",
+    "evolve",
+    "diff",
+    "to_flat",
+    "save",
+    "load",
+    "dumps",
+    "loads",
+]
+
+__version__ = "0.1.0"