confargs 0.2.0__tar.gz

confargs-0.2.0/.gitattributes

@@ -0,0 +1,29 @@
+# Normalize all text files to LF on checkout and commit.
+* text=auto eol=lf
+
+# Explicit text file declarations.
+*.py      text eol=lf
+*.pyi     text eol=lf
+*.toml    text eol=lf
+*.cfg     text eol=lf
+*.ini     text eol=lf
+*.yml     text eol=lf
+*.yaml    text eol=lf
+*.md      text eol=lf
+*.rst     text eol=lf
+*.txt     text eol=lf
+*.json    text eol=lf
+*.sh      text eol=lf
+.gitignore     text eol=lf
+.gitattributes text eol=lf
+py.typed       text eol=lf
+
+# Binary files (never normalized).
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.ico  binary
+*.whl  binary
+*.gz   binary
+*.zip  binary

confargs-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Pin uv for reproducible CI; bump deliberately.
+  UV_VERSION: "0.12.7"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      UV_PYTHON: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+      - name: Sync (locked)
+        run: uv sync --locked
+      - name: Ruff (lint)
+        run: uv run ruff check .
+      - name: Ruff (format check)
+        run: uv run ruff format --check .
+      - name: Mypy
+        run: uv run mypy
+
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    env:
+      # setup-uv@v3 has no `python-version` input, so uv picks the interpreter
+      # from UV_PYTHON (downloading it if needed) for each matrix entry.
+      UV_PYTHON: ${{ matrix.python-version }}
+    strategy:
+      fail-fast: false
+      # Test every supported Python on Linux; on the costlier Windows runners
+      # cover only the oldest and newest supported versions.
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python-version: "3.10"
+          - os: windows-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+      - name: Sync (locked)
+        run: uv sync --locked
+      - name: Run tests
+        run: uv run pytest --cov=confargs --cov-report=xml

confargs-0.2.0/.github/workflows/pr-title.yml

@@ -0,0 +1,35 @@
+name: PR Title Check
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  lint-pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          requireScope: false
+          subjectPattern: ^.+$
+          subjectPatternError: |
+            PR title must follow the Conventional Commits format:
+            type: description
+            Example: feat: add eager option support

confargs-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish
+
+# Automated releases are handled by release-please (.github/workflows/release-please.yml),
+# which builds and publishes on release creation. This workflow is a manual
+# fallback for publishing a release out-of-band.
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Required for PyPI trusted publishing (OIDC); no API token needed.
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

confargs-0.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,41 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Required for PyPI trusted publishing (OIDC); no API token needed.
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

confargs-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# uv: the lockfile is committed for reproducible installs and CI caching.
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

confargs-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+default_language_version:
+  python: python3
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.5
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.3.1
+    hooks:
+      - id: mypy
+        additional_dependencies: ["tomli>=2.0"]
+        pass_filenames: false
+        args: [--config-file=pyproject.toml]

confargs-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

confargs-0.2.0/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to **confargs** are documented here.
+
+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/spec/v2.0.0.html).
+
+> **Pre-1.0 note:** while the version is `0.x.y`, the public API is still
+> stabilising. Minor (`0.X.0`) releases may include breaking changes; patch
+> (`0.x.Y`) releases are reserved for backwards-compatible fixes.
+
+## [0.2.0](https://github.com/MarketSquare/confargs/compare/v0.1.0...v0.2.0) (2026-08-28)
+
+
+### Features
+
+* add argconfig-demo console entry-point ([d0249d8](https://github.com/MarketSquare/confargs/commit/d0249d83c0d37ab1e71d10ef41d4a9d79ad80b0a))
+* add ConfigurationProcessor, Namespace and discovery controls ([8395145](https://github.com/MarketSquare/confargs/commit/83951450a7b9b81d6f47bb72cd2b0da64f61a373))
+* add core option model and ArgConfig base ([a5e1c4d](https://github.com/MarketSquare/confargs/commit/a5e1c4d15c0bc6a4d1a4ce79a7cd69a12c6361a5))
+* add eager options and argument-file expansion ([b6837bd](https://github.com/MarketSquare/confargs/commit/b6837bd4fda7c10efccb4bacd5fab420475ca7f9))
+* add environment-variable source ([8b34439](https://github.com/MarketSquare/confargs/commit/8b34439eb153be00fd443eff0dcaba4ced96b4f2))
+* add minimal command-line tokenizer ([e2c07bd](https://github.com/MarketSquare/confargs/commit/e2c07bd00c4ea8b3cb4f793b37b041dbce90ffd0))
+* add TOML loading and config file discovery ([3e8171c](https://github.com/MarketSquare/confargs/commit/3e8171c18b3da3e49b658453fb7dc1a785ddfddf))
+* add type resolution and value coercion ([3976797](https://github.com/MarketSquare/confargs/commit/397679794170b008feb256d320b72022069c0450))
+* generate help text from docstrings ([13cd88c](https://github.com/MarketSquare/confargs/commit/13cd88c1738ebc480ef2575072140b431f70294a))
+* support boolean flag negation with --no- prefix ([3d44e05](https://github.com/MarketSquare/confargs/commit/3d44e05746bfa050dbb436160b61c83564b21aab))
+* validate config keys with strict_config mode ([f707858](https://github.com/MarketSquare/confargs/commit/f7078587200155f8122c725f9dc8b30fa4cec64e))
+
+
+### Documentation
+
+* add publishing workflow, example and expanded README ([6f266d8](https://github.com/MarketSquare/confargs/commit/6f266d88cebdd66f55833eae7badecb0ab837cae))
+* make examples/ a self-contained runnable example ([73a0948](https://github.com/MarketSquare/confargs/commit/73a094831a85cd0e86a00b570fd03e2f4cbc608d))
+
+
+### Build System
+
+* single-source version and add CHANGELOG ([690efd9](https://github.com/MarketSquare/confargs/commit/690efd9b7017270a262ab13d75641891c73ca959))
+
+## [Unreleased]
+
+### Changed
+
+- Renamed the distribution and import package from `argconfig` to **`confargs`**
+  (the `argconfig` name was already taken on PyPI). The `ArgConfig` base class
+  keeps its name.
+
+### Added
+
+- Eager options (`@option(is_eager=True)`): resolved before every other source,
+  directly against `argv`. An eager option's method returns tokens that replace
+  its own arguments, enabling argument-file expansion.
+- `confargs.split_argument_file` / `confargs.read_argument_file` helpers that
+  parse Robot Framework-style argument files (comment lines, `name value` and
+  `name=value` forms) into argv tokens, including nested argument files.
+
+## [0.1.0] - 2026-08-28
+
+Initial development release.
+
+### Added
+
+- Declarative option model: options are methods on an `ArgConfig` subclass
+  decorated with `@option`, receiving the raw value and returning the final one.
+- `ConfigurationProcessor` that merges sources with precedence
+  **CLI > environment variables > nearest TOML > user-directory TOML > default**
+  and returns an immutable `Namespace` (attribute and item access).
+- Minimal command-line tokenizer: long/short options, `--opt=value`, attached
+  and combined short flags, repeatable list options, `--` terminator and
+  positional collection.
+- Boolean flag negation via `--no-<flag>`.
+- Type coercion from strings and native TOML values (`str`, `int`, `float`,
+  `bool`, `list[...]`, `Optional`).
+- TOML discovery that walks up to the `.git` project root, with `--config`,
+  `--no-config` and `--ignore-git` controls and a per-user config fallback.
+- `strict_config` mode (default on) that rejects unknown or cli-only keys in a
+  config section.
+- Environment-variable source via explicit `envvar=` or `auto_env_vars`.
+- Help generation from class and option docstrings; built-in `--help`.
+- `confargs-demo` console entry-point and runnable example.
+- Tooling: uv project, ruff, mypy (strict), pytest, pre-commit, CI matrix
+  (Python 3.10-3.13 on Linux and Windows) and a PyPI trusted-publishing
+  workflow.
+
+[Unreleased]: https://github.com/MarketSquare/confargs/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/MarketSquare/confargs/releases/tag/v0.1.0

confargs-0.2.0/LICENSE

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

confargs-0.2.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.5
+Name: confargs
+Version: 0.2.0
+Summary: Declarative CLI argument parser that merges command line, TOML config files, and environment variables.
+Project-URL: Homepage, https://github.com/MarketSquare/confargs
+Project-URL: Repository, https://github.com/MarketSquare/confargs
+Project-URL: Issues, https://github.com/MarketSquare/confargs/issues
+Author: confargs contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: argparse,arguments,cli,configuration,toml
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# confargs
+
+> ⚠️ Early development. APIs may change.
+
+**confargs** is a small, declarative CLI argument parser for Python 3.10+ that
+merges configuration from three sources into one result:
+
+1. **Command line** arguments (`--log out.html`, `-l NONE`)
+2. **Environment variables** (per-option or auto-generated)
+3. **TOML config files** (discovered by walking up from the current directory,
+   `pyproject.toml`-style)
+
+You describe options as **methods** on a class. Each method receives the raw
+value from whichever source supplied it, performs any parsing/validation you
+like, and returns the final value. confargs handles discovery, precedence and
+basic type coercion; your code owns the domain logic.
+
+```python
+import confargs
+from confargs import ArgConfig
+
+
+class MyArgs(ArgConfig):
+    """My CLI tool.
+
+    Longer description shown in --help.
+    """
+
+    name = "mytool"
+
+    @confargs.option
+    def log(self, value: str | None = "log.html") -> str | None:
+        """HTML log file. Disable with the special value 'NONE'."""
+        if value == "NONE":
+            return None
+        return value
+
+    @confargs.option(names="--console/-c")
+    def console(self, value: str = "verbose") -> str:
+        choices = ["verbose", "dotted", "quiet", "none"]
+        if value not in choices:
+            raise confargs.OptionValueError(f"console must be one of {choices}")
+        return value
+
+
+config = confargs.ConfigurationProcessor(MyArgs).process()
+print(config.log, config.console)
+```
+
+## Precedence
+
+Highest wins: **CLI > environment variables > nearest TOML > user-directory TOML > option default**.
+
+## Configuration sources
+
+### TOML files
+
+Config is read from a table named after your tool. By default that is
+`[tool.<name>]` (e.g. `[tool.mytool]`); override it with
+`default_config_section = "tool.custom"`. The file names searched are set with
+`config_names` (default `["pyproject.toml"]`). Both `dashed-keys` and
+`snake_case_keys` are accepted.
+
+```toml
+[tool.mytool]
+log = "results.html"
+console = "dotted"
+tags = ["ci", "nightly"]
+```
+
+**Discovery** walks up from the current directory looking for those files and
+stops at the project root (a directory containing `.git`). If nothing is found,
+a per-user config directory is consulted (`%APPDATA%\<name>` on Windows,
+`$XDG_CONFIG_HOME/<name>` otherwise). Discovery is controlled by built-in,
+CLI-only options:
+
+- `--config PATH` — use only this file, skip discovery.
+- `--no-config` — ignore config files entirely.
+- `--ignore-git` — keep searching above the `.git` project root.
+
+By default (`strict_config = True`) unknown keys — and any `cli_only` option —
+found in the config section raise an error, which catches typos early. Set
+`strict_config = False` on your class to silently ignore them instead.
+
+### Environment variables
+
+Set a name per option with `@option(envvar="MYTOOL_LOG")`, or enable
+`auto_env_vars = True` on the class to expose every non-`cli_only` option as
+`<NAME>_<OPTION>` (e.g. `MYTOOL_CONSOLE`).
+
+### CLI-only options
+
+Options marked `@option(cli_only=True)` are never read from TOML or the
+environment — use this for switches that control the tool run itself (the
+built-in discovery options above are defined this way).
+
+## Options in depth
+
+- Long names come from the method name (`dry_run` → `--dry-run`); a short name
+  is derived from the first letter when it is still free. Override with
+  `names="--console/-c"`.
+- The value type is taken from the `value` parameter annotation. `bool` becomes
+  a flag; `list[...]` becomes a repeatable option; `int`/`float`/`str` are
+  coerced from strings. Your method receives the coerced value and returns the
+  final one — raise `confargs.OptionValueError` to reject it.
+- Boolean options can be negated on the command line: `--verbose` sets it to
+  `True`, `--no-verbose` sets it to `False`.
+
+### Eager options and argument files
+
+Mark an option `is_eager=True` to resolve it *before* every other source,
+directly against `argv`. The method's return value — an iterable of tokens or
+`None` — replaces the option's own arguments, so it can inject more options.
+This is how an `--argumentfile` option expands a file (Robot Framework style)
+into extra arguments, including nested argument files:
+
+```python
+from confargs import ArgConfig, option, read_argument_file
+
+
+class Args(ArgConfig):
+    @option(names="--argumentfile/-A", cli_only=True, is_eager=True)
+    def argumentfile(self, value: str | None = None) -> list[str] | None:
+        return read_argument_file(value) if value else None
+```
+
+`ConfigurationProcessor(Args, argv=[...])` accepts an explicit argument list;
+when omitted it falls back to `sys.argv[1:]`.
+
+## Example
+
+A complete, self-contained example lives in [`examples/demo.py`](examples/demo.py)
+(with a sample [`examples/example.args`](examples/example.args) and
+[`examples/README.md`](examples/README.md)). It's a single copy-pasteable file
+showing value options, `--no-` flag negation, environment variables and an
+eager `--argumentfile`. Run it from a checkout without installing anything:
+
+```bash
+uv run python examples/demo.py --who Ada --repeat 3
+uv run python examples/demo.py -A examples/example.args
+uv run python examples/demo.py --help
+```
+
+Separately, the packaged [`confargs.demo`](src/confargs/demo.py) module is
+installed as the `confargs-demo` console script via `[project.scripts]`:
+
+```bash
+uv run confargs-demo --console quiet --retries 5
+uv run confargs-demo --help
+```
+
+To ship your own tool, point a console script at a `main()` that runs the
+processor, for example in `pyproject.toml`:
+
+```toml
+[project.scripts]
+mytool = "mytool.cli:main"
+```
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                 # create the environment
+uv run pytest           # run the tests
+uv run ruff check       # lint
+uv run ruff format      # format
+uv run mypy             # type-check
+pre-commit install      # enable git hooks
+```
+
+## Publishing
+
+Releases are published to PyPI by `.github/workflows/publish.yml` when a GitHub
+Release is published. It uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC), so no API token is stored in the repository — configure the project as a
+trusted publisher on PyPI (workflow `publish.yml`, environment `pypi`) once.
+
+## Versioning
+
+confargs follows [Semantic Versioning](https://semver.org/). The version is
+single-sourced from `__version__` in `src/confargs/__init__.py` (hatchling reads
+it at build time). While the project is `0.x.y` the API is still stabilising, so
+minor releases may include breaking changes. Notable changes are recorded in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+Releases are automated with
+[release-please](https://github.com/googleapis/release-please): merging
+[Conventional Commits](https://www.conventionalcommits.org/) to `main` keeps an
+open release PR that bumps `__version__`, updates the changelog and, once merged,
+tags the release and publishes to PyPI. Pre-1.0, breaking changes bump the minor
+version (`bump-minor-pre-major`).
+
+## License
+
+MIT