clevis 0.1.0__tar.gz

clevis-0.1.0/.claude/settings.local.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git pull *)",
+      "Bash(gh pr *)",
+      "Bash(gh issue *)",
+      "Bash(uv run *)",
+      "Bash(git commit *)",
+      "Bash(uv sync *)",
+      "Bash(make typecheck *)",
+      "Bash(make check *)",
+      "Bash(git push *)",
+      "Bash(make build *)",
+      "Bash(git tag *)",
+      "Bash(make help *)",
+      "Bash(make publish *)"
+    ]
+  }
+}

clevis-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: Test
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest -v --cov=src --cov-report=xml
+
+      - name: Upload coverage to Coveralls
+        uses: coverallsapp/github-action@v2
+        if: matrix.python-version == '3.11'
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

clevis-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info/
+
+# Virtual environments
+.venv
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+
+# Documentation
+docs/_build/

clevis-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

clevis-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

clevis-0.1.0/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.

clevis-0.1.0/Makefile

@@ -0,0 +1,71 @@
+-include ~/.claude/Makefile
+
+.PHONY: help env-dev env-run test test-cov test-all run format lint typecheck check build pre-publish publish publish-test clean clean-all
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+env-dev: ## Install all dependencies (dev + docs)
+	uv sync --all-extras
+
+env-run: ## Install runtime dependencies only
+	uv sync --no-dev
+
+test: ## Run tests (usage: make test TEST=file|file:test_name)
+	@if [ -n "$(TEST)" ]; then \
+		uv run pytest $(TEST); \
+	else \
+		uv run pytest; \
+	fi
+
+test-cov: ## Run tests with coverage
+	uv run pytest --cov=src --cov-report=html
+
+test-all: ## Run tests on all Python versions
+	uv run tox
+
+run: ## Run the example application
+	uv run python main.py
+
+format: ## Format code and fix linting issues
+	uv run ruff format src/
+	uv run ruff check --fix src/
+
+lint: ## Check code for linting issues
+	uv run ruff check src/
+
+typecheck: ## Run type checking
+	uv run mypy src/
+
+check: format lint typecheck test ## Run all quality checks
+
+build: ## Build distribution packages
+	uv build
+
+pre-publish: check ## Pre-publication checks (run before publishing)
+	@echo "Checking for relative image paths in README..."
+	@grep -n '!\[.*](media/' README.md && (echo "ERROR: Relative image paths found - use raw GitHub URLs for PyPI"; exit 1) || echo "OK: No relative image paths"
+	@echo "Checking version sync..."
+	@VERSION_PY=$$(grep '^version =' pyproject.toml | cut -d'"' -f2); \
+	VERSION_INIT=$$(grep '^__version__ = ' src/clevis/__init__.py | cut -d'"' -f2); \
+	if [ "$$VERSION_PY" != "$$VERSION_INIT" ]; then \
+		echo "ERROR: Version mismatch - pyproject.toml ($$VERSION_PY) vs __init__.py ($$VERSION_INIT)"; \
+		exit 1; \
+	fi; \
+	echo "OK: Versions match ($$VERSION_PY)"
+	@echo "Pre-publication checks passed"
+
+publish: clean build ## Publish to PyPI (runs pre-publish checks)
+	@$(MAKE) pre-publish
+	uv run twine upload dist/*
+
+publish-test: build ## Publish to TestPyPI
+	uv run twine upload --repository testpypi dist/*
+
+clean: ## Remove build artifacts
+	rm -rf dist/ *.egg-info .pytest_cache .coverage htmlcov/ .mypy_cache .ruff_cache
+
+clean-all: clean ## Remove virtualenv and lock file
+	rm -rf .venv uv.lock
+
+

clevis-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,223 @@
+# 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