clevis 0.1.0__py3-none-any.whl

clevis/__init__.py

@@ -0,0 +1,359 @@
+"""
+Clevis - Configuration management for Python projects.
+
+Provides dataclass-based configuration with TOML file support,
+environment variable interpolation, and CLI argument generation.
+
+TOML Parser Selection (priority order):
+  1. envtoml  - Env var interpolation (${VAR}) - install: pip install clevis[envtoml]
+  2. tomlev   - Tomlev parser - install: pip install clevis[tomlev]
+  3. tomli    - Pure Python TOML - install: pip install clevis[tomli]
+  4. tomllib  - Stdlib (Python 3.11+) - no extras needed
+"""
+
+import argparse
+import functools
+from collections.abc import Callable
+from dataclasses import Field, fields, is_dataclass
+from pathlib import Path
+from typing import Any, get_args
+
+from dacite import from_dict
+from dacite.exceptions import DaciteError, MissingValueError, WrongTypeError
+
+__version__ = "0.1.0"
+
+
+# TOML Parser Selection
+# ---------------------
+# Tries parsers in this order: envtoml > tomlev > tomli > tomllib
+
+
+def _get_toml_parser() -> Callable[[Any], dict[str, Any]]:
+  """
+  Get the appropriate TOML parser based on installed packages.
+
+  Priority: envtoml > tomlev > tomli > tomllib (stdlib)
+
+  Returns:
+      A function that loads TOML from a file object
+
+  Raises:
+      ImportError: If no TOML parser is available
+  """
+  # envtoml: supports ${VAR} interpolation
+  try:
+    import envtoml
+
+    return envtoml.load
+  except ImportError:
+    pass
+
+  # tomlev: supports ${VAR|default} interpolation
+  try:
+    import tomllib  # type: ignore[import-not-found]
+    from tomlev.env_loader import expandvars  # type: ignore[attr-defined]
+
+    def load_with_tomlev(file: Any) -> dict[str, Any]:
+      content = file.read()
+      if isinstance(content, bytes):
+        content = content.decode("utf-8")
+      expanded = expandvars(content)
+      return tomllib.loads(expanded)  # type: ignore[no-any-return]
+
+    return load_with_tomlev
+  except ImportError:
+    pass
+
+  # tomli: pure Python TOML (Python 3.10)
+  try:
+    import tomli
+
+    return tomli.load
+  except ImportError:
+    pass
+
+  # tomllib: stdlib (Python 3.11+)
+  try:
+    import tomllib
+
+    return tomllib.load  # type: ignore[no-any-return]
+  except ImportError:
+    pass
+
+  raise ImportError(
+    "No TOML parser available.\n\n"
+    "Install one of:\n"
+    "  pip install clevis[tomli]      # Python 3.10\n"
+    "  pip install clevis[envtoml]    # Env var interpolation\n"
+    "  pip install clevis[tomlev]     # Env var with defaults\n\n"
+    "Note: Python 3.11+ has built-in tomllib (no extras needed)"
+  )
+
+
+# Module-level parser (loaded once)
+_toml_load: Callable[[Any], dict[str, Any]] | None = None
+
+
+def _load_toml(file: Any) -> dict[str, Any]:
+  """
+  Load TOML from a file object using the selected parser.
+
+  Args:
+      file: File object opened in binary mode
+
+  Returns:
+      Dictionary of parsed TOML data
+  """
+  global _toml_load
+  if _toml_load is None:
+    _toml_load = _get_toml_parser()
+  return _toml_load(file)
+
+
+class ConfigError(Exception):
+  """Raised when configuration is missing or invalid."""
+
+  def __init__(self, message: str, field_path: str, config_name: str):
+    self.message = message
+    self.field_path = field_path
+    self.config_name = config_name
+    super().__init__(self._format_message())
+
+  def _format_message(self) -> str:
+    """Format a helpful error message with actionable suggestions."""
+    lines = [f"\n{'=' * 70}"]
+    lines.append("Configuration Error")
+    lines.append(f"{'=' * 70}\n")
+
+    lines.append(f"Field: {self.field_path}")
+    lines.append(f"Issue: {self.message}\n")
+
+    lines.append("Provide this value in one of these ways:\n")
+
+    # Project config
+    lines.append(f"  1. Project config: ./{self.config_name}.toml")
+    parts = self.field_path.split(".")
+    if len(parts) == 1:
+      lines.append(f'     {parts[0]} = "your_value"')
+    else:
+      lines.append(f"     [{parts[0]}]")
+      lines.append(f'     {".".join(parts[1:])} = "your_value"')
+    lines.append("")
+
+    # User config
+    lines.append(f"  2. User config: ~/.{self.config_name}.toml")
+    lines.append("     (same format as above)\n")
+
+    # CLI argument (use dashes for dots and underscores)
+    cli_arg = "--" + self.field_path.replace(".", "-").replace("_", "-")
+    lines.append(f"  3. CLI argument: {cli_arg} <value>\n")
+
+    lines.append(f"{'=' * 70}")
+    return "\n".join(lines)
+
+
+def unpack_type(type_def: type) -> type:
+  """
+  Given a type, if a union type, return the not-None type (dataclass).
+
+  For Optional[T] or T | None, returns T.
+  For non-union types, returns the type as-is.
+
+  Args:
+      type_def: The type to unpack
+
+  Returns:
+      The non-None type from a union, or the type itself
+
+  Raises:
+      ValueError: If union has more than 2 types (not supported yet)
+  """
+  types = get_args(type_def)
+  # not a union type
+  if len(types) == 0:
+    return type_def
+  # <type> | None is only supported combination
+  if len(types) > 2:
+    raise ValueError("Complex unions not supported")
+  return types[0] if types[1] is type(None) else types[1]  # type: ignore[no-any-return]
+
+
+def list_fields(clz: type, path: list[str] | None = None) -> list[tuple[Field[Any], list[str]]]:
+  """
+  Recursively flatten and list all properties in nested dataclasses.
+
+  Args:
+      clz: The dataclass to inspect
+      path: Current path in the hierarchy
+
+  Yields:
+      Tuples of (field, path) for each leaf field
+  """
+  path = [] if not path else path
+  result = []
+  for f in fields(clz):
+    concrete_type = unpack_type(f.type)  # type: ignore[arg-type]
+    if is_dataclass(concrete_type):
+      result.extend(list_fields(concrete_type, path=path + [f.name]))
+    else:
+      result.append((f, path))
+  return result
+
+
+def get_args_config(clz: type, args: list[str] | None = None) -> dict[str, Any]:
+  """
+  Construct an argparse parser from a dataclass hierarchy.
+
+  Creates CLI arguments for each leaf field in the dataclass,
+  using dashed notation for nested fields (e.g., --database-host).
+
+  Args:
+      clz: The dataclass type to generate parser for
+      args: Optional list of CLI arguments (defaults to sys.argv[1:])
+
+  Returns:
+      Dictionary of parsed arguments with dotted keys
+      Unprovided arguments have None values
+  """
+  parser = argparse.ArgumentParser()
+  for f, path in list_fields(clz):
+    name = ".".join(path + [f.name])  # concatenate intermediate classes with "."
+    # Convert both dots and underscores to dashes for CLI args
+    cli_name = name.replace(".", "-").replace("_", "-")
+    arg = functools.partial(
+      parser.add_argument,
+      f"--{cli_name}",
+      dest=name,  # name with dots
+      default=None,  # Use None so TOML values aren't overridden
+      help=f"provide {name}",
+    )
+    # complete partial: boolean switch of store value
+    concrete_type = unpack_type(f.type)  # type: ignore[arg-type]
+    if concrete_type is bool:
+      _ = arg(action="store_true")
+    else:
+      _ = arg(type=concrete_type)
+
+  return vars(parser.parse_args(args))
+
+
+def apply_to_dict(args: dict[str, Any], dct: dict[str, Any]) -> None:
+  """
+  Apply dotted command line arguments to a nested dictionary.
+
+  Modifies the dictionary in-place, creating nested structure as needed.
+
+  Args:
+      args: Dictionary with dotted keys (e.g., "database.host")
+      dct: Target dictionary to modify
+  """
+  for key, value in args.items():
+    if value is not None:  # default optional value, can't be set through command line
+      parts = key.split(".")
+      final_key = parts.pop()
+      # follow path into hierarchy
+      scope = dct
+      for step in parts:
+        try:
+          scope = scope[step]  # follow
+        except KeyError:
+          scope[step] = {}  # create missing
+          scope = scope[step]
+      # set value
+      scope[final_key] = value  # upsert key=value
+
+
+def get_config(
+  data_class: type,
+  name: str = "project",
+  user: bool = True,
+  project: bool = True,
+  args: list[str] | None = None,
+) -> Any:
+  """
+  Load configuration from TOML files and CLI arguments.
+
+  Merges configuration from (in order of precedence):
+  1. CLI arguments (highest priority)
+  2. Project-level TOML: ./{name}.toml
+  3. User-level TOML: ~/.{name}.toml
+  4. Dataclass defaults (lowest priority)
+
+  TOML Parser Selection:
+      Automatically selects parser based on installed extras:
+      - envtoml: Supports ${VAR} interpolation - pip install clevis[envtoml]
+      - tomlev: Alternative parser - pip install clevis[tomlev]
+      - tomli: Pure Python - pip install clevis[tomli]
+      - tomllib: Python 3.11+ stdlib (no extras needed)
+
+  Args:
+      data_class: The dataclass type to populate
+      name: Configuration file name (without .toml extension)
+      user: Whether to load user-level config(~/.{name}.toml)
+      project: Whether to load project-level config (./{name}.toml)
+      args: Optional list of CLI arguments (defaults to sys.argv[1:])
+
+  Returns:
+      An instance of the dataclass with merged configuration
+
+  Raises:
+      ConfigError: If required fields are missing or values have wrong type
+      ImportError: If no TOML parser is available
+  """
+  cfg: dict[str, Any] = {}
+
+  # Load user-level config
+  if user:
+    user_path = Path.home() / f".{name}.toml"
+    if user_path.exists():
+      cfg.update(_load_toml(user_path.open("rb")))
+
+  # Load project-level config
+  if project:
+    project_path = Path.cwd() / f"{name}.toml"
+    if project_path.exists():
+      cfg.update(_load_toml(project_path.open("rb")))
+
+  # Get CLI args based on dataclass hierarchy
+  cli_args = get_args_config(data_class, args)
+
+  # Merge CLI args into config
+  apply_to_dict(cli_args, cfg)
+
+  # Convert dict to dataclass
+  try:
+    return from_dict(data_class=data_class, data=cfg)
+  except MissingValueError as e:
+    # Extract field path from dacite error message
+    # Format: 'missing value for field "database.host"'
+    error_msg = str(e)
+    if '"' in error_msg:
+      field_path = error_msg.split('"')[1]
+    else:
+      field_path = error_msg
+    raise ConfigError(
+      message="Required field has no value",
+      field_path=field_path,
+      config_name=name,
+    ) from None
+  except WrongTypeError as e:
+    # Extract field path and type info from dacite error
+    error_msg = str(e)
+    if '"' in error_msg:
+      field_path = error_msg.split('"')[1]
+    else:
+      field_path = error_msg
+    raise ConfigError(
+      message="Wrong type for field",
+      field_path=field_path,
+      config_name=name,
+    ) from None
+  except DaciteError as e:
+    # Catch any other dacite errors
+    raise ConfigError(
+      message=str(e),
+      field_path="unknown",
+      config_name=name,
+    ) from None
+

clevis-0.1.0.dist-info/METADATA

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: clevis
+Version: 0.1.0
+Summary: Configuration management for Python projects with dataclass-based schemas
+Project-URL: Homepage, https://github.com/christophevg/clevis
+Project-URL: Documentation, https://clevis.readthedocs.io
+Project-URL: Repository, https://github.com/christophevg/clevis
+Author-email: Christophe Van Ginneken <christophe@christophe.vg>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: argparse,cli,configuration,dataclass,toml
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: dacite
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: tox; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2.0.0; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0.0; extra == 'docs'
+Provides-Extra: envtoml
+Requires-Dist: envtoml; extra == 'envtoml'
+Provides-Extra: tomlev
+Requires-Dist: tomlev; extra == 'tomlev'
+Provides-Extra: tomli
+Requires-Dist: tomli; extra == 'tomli'
+Description-Content-Type: text/markdown
+
+# Clevis
+
+[![PyPI][pypi-badge]][pypi]
+[![Python][python-badge]][python]
+[![CI][ci-badge]][ci]
+[![Coverage][coverage-badge]][coverage]
+[![License][license-badge]][license]
+[![Agentic][agentic-badge]][agentic]
+
+> Configuration management for Python projects with dataclass-based schemas
+
+Clevis provides type-safe configuration management for Python applications:
+
+- **Dataclass schemas** — Define config structure with Python dataclasses
+- **TOML support** — Load from `.toml` files
+- **Env vars** — `${VAR}` interpolation (with envtoml/tomlev)
+- **CLI generation** — Auto-generate argparse from dataclass
+- **Layered config** — User config < project config < CLI args
+
+## About the Name
+
+A **clevis** is a U-shaped mechanical fastener that connects components while allowing pivoting. It's used in everything from agricultural equipment to aerospace control systems — a simple, robust connector that provides flexibility without compromising strength.
+
+This library follows the same principle: it **connects** multiple configuration sources (TOML files, environment variables, CLI arguments) into a single, cohesive interface. Just as a mechanical clevis allows articulation, Clevis allows your configuration to flex and adapt — user-level defaults, project-level settings, and runtime overrides all pivot around a single dataclass schema.
+
+## Quick Start
+
+```bash
+# Install (Python 3.11+)
+pip install clevis
+
+# Or with env var support
+pip install clevis[envtoml]
+```
+
+```python
+from dataclasses import dataclass
+from clevis import get_config
+
+@dataclass
+class Config:
+    name: str = "MyApp"
+    debug: bool = False
+
+config = get_config(Config, name="app")
+```
+
+## Installation
+
+Choose your TOML parser based on needs:
+
+| Extra | Features | Use When |
+|-------|----------|----------|
+| *(none)* | Stdlib `tomllib` | Python 3.11+, minimal deps |
+| [`tomli`][tomli] | Pure Python TOML | Python 3.10 compatibility |
+| [`envtoml`][envtoml] | `${VAR}` interpolation | Environment-based config |
+| [`tomlev`][tomlev] | `${VAR\|default}` syntax | Env vars with defaults |
+
+```bash
+# Python 3.11+ - no extras needed
+pip install clevis
+
+# Python 3.10
+pip install clevis[tomli]
+
+# Environment variable support
+pip install clevis[envtoml]
+```
+
+## Usage
+
+### Define Your Config
+
+```python
+from dataclasses import dataclass, field
+
+@dataclass
+class DatabaseConfig:
+    host: str = "localhost"
+    port: int = 5432
+    user: str | None = None
+    password: str | None = None
+
+@dataclass
+class AppConfig:
+    name: str = "MyApp"
+    debug: bool = False
+    database: DatabaseConfig = field(default_factory=DatabaseConfig)
+```
+
+### Load Configuration
+
+```python
+from clevis import get_config
+
+# Load from ~/.myapp.toml and ./myapp.toml
+config = get_config(AppConfig, name="myapp")
+```
+
+Configuration layers (lowest to highest priority):
+
+1. **Dataclass defaults**
+2. **User-level TOML** — `~/.{name}.toml`
+3. **Project-level TOML** — `./{name}.toml`
+4. **CLI arguments** — `--database-host`, `--debug`
+
+### TOML Files
+
+Create `myapp.toml`:
+
+```toml
+name = "Production App"
+debug = true
+
+[database]
+host = "db.example.com"
+port = 5432
+```
+
+With env var support (`clevis[envtoml]` or `clevis[tomlev]`):
+
+```toml
+[database]
+password = "${DB_PASSWORD}"        # envtoml
+host = "${DB_HOST|localhost}"       # tomlev (with default)
+```
+
+### CLI Arguments
+
+Clevis auto-generates CLI arguments:
+
+```bash
+python app.py --database-host localhost
+python app.py --database-port 5432
+python app.py --debug
+```
+
+Nested dataclasses become dashed arguments: `database.host` → `--database-host`
+
+## Testing
+
+```bash
+# Run tests
+make test
+
+# Run with coverage
+make test-cov
+```
+
+## API Reference
+
+### `get_config(data_class, name="project", user=True, project=True, args=None)`
+
+Load configuration from TOML files and CLI arguments.
+
+**Parameters:**
+- `data_class` — The dataclass type to populate
+- `name` — Config file name (without `.toml`)
+- `user` — Load user-level config (`~/.{name}.toml`)
+- `project` — Load project-level config (`./{name}.toml`)
+- `args` — CLI arguments (defaults to `sys.argv[1:]`)
+
+**Returns:** Instance of the dataclass with merged configuration
+
+**Raises:**
+- `ConfigError` — Missing required fields or wrong types
+- `ImportError` — No TOML parser available
+
+## Error Messages
+
+Clevis provides helpful, actionable errors:
+
+```
+======================================================================
+Configuration Error
+======================================================================
+
+Field: database.host
+Issue: Required field has no value
+
+Provide this value in one of these ways:
+
+  1. Project config: ./project.toml
+     [database]
+     host = "your_value"
+
+  2. User config: ~/.project.toml
+     (same format as above)
+
+  3. CLI argument: --database-host <value>
+
+======================================================================
+```
+
+## Acknowledgments
+
+Clevis builds on excellent work from the Python community:
+
+- **[tomllib](https://docs.python.org/3/library/tomllib.html)** — Python 3.11+ stdlib
+- **[tomli](https://github.com/hukkin/tomli)** — Pure Python TOML 1.0
+- **[envtoml](https://github.com/sank8m/envtoml)** — Env var interpolation
+- **[tomlev](https://github.com/thesimj/tomlev)** — Env vars with defaults
+- **[dacite](https://github.com/konradhalas/dacite)** — Dict-to-dataclass conversion
+
+## License
+
+MIT
+
+[pypi]: https://pypi.org/project/clevis/
+[pypi-badge]: https://img.shields.io/pypi/v/clevis.svg
+[python]: https://www.python.org/
+[python-badge]: https://img.shields.io/badge/Python-3.10+-blue.svg
+[ci]: https://github.com/christophevg/clevis/actions/workflows/test.yml
+[ci-badge]: https://img.shields.io/github/actions/workflow/status/christophevg/clevis/test.yml.svg
+[coverage]: https://coveralls.io/github/christophevg/clevis
+[coverage-badge]: https://img.shields.io/coveralls/github/christophevg/clevis.svg
+[license]: LICENSE
+[license-badge]: https://img.shields.io/github/license/christophevg/clevis.svg
+[agentic]: https://christophe.vg/about/Agentic-Workflow
+[agentic-badge]: https://img.shields.io/badge/workflow-agentic-blueviolet?style=flat-square
+[tomli]: https://github.com/hukkin/tomli
+[envtoml]: https://github.com/sank8m/envtoml
+[tomlev]: https://github.com/thesimj/tomlev

clevis-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+clevis/__init__.py,sha256=_XKFN1QDr6ldIBEtR4cF5M4Ysgj4V3Wcn_Pr641vSp4,10611
+clevis/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clevis-0.1.0.dist-info/METADATA,sha256=6Y0d1Dlvj9PueqU6WtO-XGbIQScMeu-irsAlkLCEzUQ,7811
+clevis-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+clevis-0.1.0.dist-info/licenses/LICENSE,sha256=HZGWgZq6Gti1o1soHE3jmA5UNMVv3gRkPSmOuJz5fdY,1080
+clevis-0.1.0.dist-info/RECORD,,

clevis-0.1.0.dist-info/WHEEL

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

clevis-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christophe Van Ginneken
+
+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.