duho 0.1.0__tar.gz

duho-0.1.0/.gitignore

@@ -0,0 +1,139 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project-specific
+.agents/
+.claude/
+CLAUDE*
+AGENTS.md
+
+# Benchmark run outputs (local, machine-specific)
+benchmarks/results/

duho-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-14
+
+Initial release.
+
+### Added
+
+- **Declarative `Args` classes** — define a CLI by annotating class fields. The
+  field's docstring becomes its help text and a following tuple literal declares
+  its flags (`("--name", "-n")`); with no tuple, the flag is derived from the
+  field name (`dry_run` → `--dry-run`).
+- **Type-driven conversion** from annotations: `str`/`int`/`float`/`bool`,
+  `typing.Literal` (→ `choices`), `enum.Enum` (members matched by name),
+  `list[T]` (repeated or space-separated), `Optional[T]`, and `Union[A, B]`
+  (including PEP 604 `A | B` on 3.10+). Enums inside a `Union`/`Optional` are
+  matched by member name, consistently with bare enum fields.
+- **Positional arguments** — a flag tuple with no leading dash (`("source",)`);
+  a positional with a default becomes optional (`nargs="?"`).
+- **Full argparse passthrough** via `Arg[T, NS(...)]` — `action`, `nargs`,
+  `const`, `metavar`, `dest`, `choices`, and any other `add_argument` keyword,
+  plus `NS(conflicts="group")` for mutually exclusive groups.
+- **Argument helpers**: `Count()`, `Append()`, `Const()`, `Choice()`, `Extend()`,
+  and the `UpdateAction` action.
+- **Entry points**: `duho.parser(cls)` builds a parser; `duho.parse(spec, argv)`
+  builds and parses in one call — passing an *instance* layers CLI overrides on
+  top of its field values (CLI > instance > class default) and returns a new
+  instance without mutating the original.
+- **Command dispatch**: `duho.main(cls, argv=None)` builds, parses, sets up
+  logging, and calls the selected instance's `__run__()`. `_subcommands_` builds
+  nested subparser trees automatically and dispatches to the deepest selected
+  class.
+- **Layered defaults**: per-field environment variables via `NS(env="VAR")` and
+  TOML config files via `_config_` / `config=`, with the precedence ladder
+  CLI > env > config > class default. Any layer supplying a value also
+  un-requires that field. `duho.value_sources(parsed)` reports which layer won
+  for each field.
+- **`--version`**: set `_version_` to a string, or to `duho.AUTO` to resolve it
+  from installed package metadata (`_distribution_` overrides the distribution
+  name). When the distribution isn't installed, no `--version` flag is added
+  rather than printing a bogus version.
+- **Shell completion**: opt in with `_completion_ = True` to add
+  `--print-completion {bash,zsh,fish}`, or call `duho.print_completion()`.
+  Scripts are generated statically — no runtime dependency and no re-invoking
+  your program on every keypress.
+- **`LoggingArgs`** preset — `-v`/`-q` counted verbosity (offsetting, clamped at
+  each end of the scale), `--loglevel` for global or per-module levels, colored
+  stderr output (optional `colorama`), and a `TRACE` level.
+- Type hints ship with the package (`py.typed`).
+
+### Notes
+
+- Zero required runtime dependencies. Optional extras: `colorama` (colored
+  logging) and `config` (TOML on Python 3.9/3.10, where `tomllib` isn't stdlib).
+- Supports Python 3.9 through 3.13.
+
+[Unreleased]: https://github.com/jose-pr/duho/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jose-pr/duho/releases/tag/v0.1.0

duho-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to Duho
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/jose-pr/duho.git
+cd duho
+
+# Create a virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode with test dependencies
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+Run with coverage:
+
+```bash
+pytest --cov=src/duho tests/
+```
+
+## Running Benchmarks
+
+```bash
+python -m benchmarks.bench_parsing
+```
+
+## Code Style
+
+- Follow PEP 8
+- Use type hints
+- Keep functions focused and well-named
+
+## Commit Guidelines
+
+Follow the format: `type: description`
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation
+- `test:` Test additions/improvements
+- `chore:` Build, CI, or tooling changes
+
+Examples:
+- `feat: add shell completion support`
+- `fix: handle union types with None correctly`
+- `docs: add subcommand examples`
+
+## Pull Request Process
+
+1. Create a feature branch: `git checkout -b feature/my-feature`
+2. Make your changes and add tests
+3. Run `pytest` to ensure all tests pass
+4. Commit with a clear message (see guidelines above)
+5. Push to your fork and open a pull request
+
+## Reporting Issues
+
+When reporting bugs, please include:
+- Python version
+- Duho version
+- Minimal code example that reproduces the issue
+- Expected vs. actual behavior
+
+## Questions?
+
+Open a discussion or issue on GitHub!

duho-0.1.0/LICENSE

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