conclude 1.0.0__tar.gz

conclude-1.0.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+# Keeps the SHA-pinned actions in .github/workflows/ current.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

conclude-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,109 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call: # publish.yml runs this before it publishes anything
+
+permissions:
+  contents: read
+
+# Every third-party action is pinned to a full commit SHA (the version is
+# in the trailing comment); .github/dependabot.yml keeps them current.
+
+jobs:
+  test:
+    name: pytest (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install the project and its dev tools (pathspec included)
+        run: uv sync --locked
+      - name: pytest
+        run: uv run pytest -q
+
+  lint:
+    name: ruff and mypy
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up uv and Python 3.11 (the oldest supported version)
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: "3.11"
+      - name: Install the project and its dev tools
+        run: uv sync --locked
+      - name: ruff check
+        run: uv run ruff check .
+      - name: ruff format --check
+        run: uv run ruff format --check .
+      - name: mypy
+        run: uv run mypy
+
+  no-extras:
+    name: pytest with no optional dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up uv and Python 3.13
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: "3.13"
+      - name: Install the package on its own, plus pytest (no pathspec)
+        run: |
+          uv venv "$RUNNER_TEMP/venv-plain"
+          uv pip install --python "$RUNNER_TEMP/venv-plain/bin/python" . pytest
+      - name: pytest (the pathspec-dependent tests skip themselves)
+        run: |
+          "$RUNNER_TEMP/venv-plain/bin/python" -m pytest -q
+
+  build:
+    name: build and twine check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up uv and Python 3.13
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: "3.13"
+      - name: Build the sdist and wheel
+        run: uv build
+      - name: twine check
+        run: uvx twine check --strict dist/*
+      - name: Smoke-test the wheel in a clean environment
+        run: |
+          uv venv "$RUNNER_TEMP/venv-wheel"
+          uv pip install --python "$RUNNER_TEMP/venv-wheel/bin/python" dist/*.whl
+          "$RUNNER_TEMP/venv-wheel/bin/python" - <<'PY'
+          import pathlib
+
+          import conclude
+
+          print("conclude", conclude.__version__)
+          assert (pathlib.Path(conclude.__file__).parent / "py.typed").exists()
+          PY

conclude-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,125 @@
+name: Publish
+
+# One-time setup, before the first run:
+#   1. On https://pypi.org (and https://test.pypi.org), add a trusted publisher
+#      for the project `conclude`: this repository, workflow `publish.yml`,
+#      environment `pypi` (`testpypi` on TestPyPI). For a project that doesn't
+#      exist yet, use "Publishing" -> "Add a new pending publisher".
+#   2. In this repository's Settings -> Environments, create `pypi` and
+#      `testpypi`. Put required reviewers on `pypi` to make a real release
+#      wait for an explicit approval.
+#
+# Then:
+#   - A dry run: Actions -> Publish -> Run workflow -> target `testpypi`.
+#   - A release: publish a GitHub Release whose tag is `v<version>`.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: Where to publish
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    name: CI
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    name: Build the distributions
+    needs: ci
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      TARGET: ${{ github.event_name == 'release' && 'pypi' || inputs.target }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up uv and Python 3.13
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: "3.13"
+      - name: Read the version
+        id: version
+        run: echo "version=$(grep -oP '^__version__ = "\K[^"]+' src/conclude/__init__.py)" >> "$GITHUB_OUTPUT"
+      - name: Check the release is ready (real PyPI only)
+        if: env.TARGET == 'pypi'
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          if [ -n "$TAG" ] && [ "$TAG" != "v$VERSION" ]; then
+            echo "::error::The release tag $TAG does not match the package version v$VERSION."
+            exit 1
+          fi
+          if ! grep -q "^## \[$VERSION\]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no entry for $VERSION."
+            exit 1
+          fi
+          if grep -q "^## \[$VERSION\] - Unreleased" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md still marks $VERSION as Unreleased; put the date on it."
+            exit 1
+          fi
+      - name: Build the sdist and wheel
+        run: uv build
+      - name: twine check
+        run: uvx twine check --strict dist/*
+      - name: Upload the distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/conclude
+    permissions:
+      id-token: write # trusted publishing (OIDC); no API token is stored
+    steps:
+      - name: Download the distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/conclude
+    permissions:
+      id-token: write # trusted publishing (OIDC); no API token is stored
+    steps:
+      - name: Download the distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

conclude-1.0.0/.gitignore

@@ -0,0 +1,29 @@
+# Local configuration / secrets (the names the docs use; never commit these)
+.env
+.env.local
+.developer.toml
+*.local.toml
+
+# Python
+__pycache__/
+*.egg-info/
+*.py[cod]
+
+# Test / type-check / lint caches
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+
+# Virtual environments
+.venv/
+.venv-*/
+venv/
+
+# OS
+.DS_Store

conclude-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-09-20

conclude-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Payam Tanaka
+
+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.

conclude-1.0.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.5
+Name: conclude
+Version: 1.0.0
+Summary: Set up your defaults; conclude infers the env vars, config-file keys, and CLI flags, and resolves them all into one settings object.
+Project-URL: Homepage, https://github.com/tanakapayam/conclude
+Project-URL: Documentation, https://github.com/tanakapayam/conclude/blob/main/docs/guide.md
+Project-URL: Repository, https://github.com/tanakapayam/conclude
+Project-URL: Issues, https://github.com/tanakapayam/conclude/issues
+Project-URL: Changelog, https://github.com/tanakapayam/conclude/blob/main/CHANGELOG.md
+Author: Payam Tanaka
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,config,configuration,dotenv,environment-variables,settings,toml
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: gitignore
+Requires-Dist: pathspec>=0.12; extra == 'gitignore'
+Description-Content-Type: text/markdown
+
+# conclude
+
+A setting that can come from a flag, an environment variable, or a
+config file usually gets written down three times: an argparse flag, an
+environment variable, and a config-file key -- each with its own name,
+its own type conversion, and its own copy of the default. Add a setting
+and you touch three places; rename one and the other two quietly drift.
+
+conclude has you write it once. Set up your defaults; conclude works
+out the rest. You write down a setting's name, its type, and its
+starting value -- as an entry in a plain dict -- and conclude infers
+the environment variable name, the config-file key, the CLI flag, and
+how to cast a raw value from any of those into the right type.
+
+```python
+import conclude
+
+DEFAULTS = {
+    "host": "localhost",
+    "port": 8080,
+    "debug": False,
+    "tags": conclude.opt(list),  # unset by default, but still a list when set
+}
+app = conclude.App("myapp", DEFAULTS)
+
+parser = app.build_arg_parser(prog="myapp")
+namespace = parser.parse_args()
+cli = {k: v for k, v in vars(namespace).items() if v is not None}
+print(app.resolve(cli))
+```
+
+```
+$ MYAPP_PORT=9000 myapp --debug --tags a,b
+{'host': 'localhost', 'port': 9000, 'debug': True, 'tags': ['a', 'b']}
+```
+
+That one dict gave you the CLI flags (`--host`, `--port`, `--debug`,
+`--tags`), the environment variables (`MYAPP_HOST`, `MYAPP_PORT`, ...),
+the config-file keys (a `[myapp]` table in `~/.config/myapp/config.toml`
+or `./.config.toml`), and a caster for each -- with no second list of
+names to keep in sync.
+
+## Where it fits
+
+Configuration libraries tend to start from different things. conclude
+starts from a dict of defaults and derives the rest:
+
+| Package           | Primary abstraction                                                      | Reach for it when...                                                              |
+| ----------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| `argparse`        | CLI parser                                                               | you only need flags                                                               |
+| ConfigArgParse    | argparse plus config files and environment variables                     | you have an argparse CLI and want files and env vars added                        |
+| jsonargparse      | CLI and config built from type hints                                     | your program is functions, classes or dataclasses with type hints                 |
+| python-dotenv     | `.env` loader                                                            | you just need a `.env` in `os.environ`                                            |
+| python-decouple   | individual value reader (env, then file, then default)                   | you read a handful of values, Django-style                                        |
+| pydantic-settings | typed, validated settings model                                          | you want validation, nested models or secret-manager sources                      |
+| Dynaconf          | general-purpose layered configuration system                             | you want named environments, many file formats, or Vault                          |
+| Hydra / OmegaConf | hierarchical, composable configuration                                   | you compose config groups, run sweeps or manage experiments                       |
+| **conclude**      | **defaults → inferred env / TOML / CLI interfaces → layered resolution** | **you want all three interfaces from one dict, and safe private local overrides** |
+
+conclude deliberately does not do schema validation (values are cast,
+not validated), secret-manager backends, YAML or JSON files, or named
+environments; the table says where to look for those. For a dated,
+feature-by-feature comparison, see
+[How conclude compares](https://github.com/tanakapayam/conclude/blob/main/docs/comparison.md).
+
+## Design principles
+
+- **One source of truth.** The defaults dict. Flags, environment
+  variable names, config keys, casters and the generated templates are
+  all derived from it, so they can't drift apart.
+- **Opt in to anything unusual.** The system file, `.env` and the
+  developer file are off until you ask; the user and project files are
+  one `None` from off.
+- **Private files have to prove they're private.** The developer file
+  (and `.env`, if you ask) is read only when git is ignoring it.
+- **Quiet for ordinary situations, loud for broken setups.** A missing
+  local file is normal and silent, and `describe_sources()` explains
+  it; a malformed developer file or a missing `pathspec` raises.
+- **Standard library only.** `pathspec`, for the gitignore check, is an
+  optional extra.
+
+## The layers
+
+```
+1. CLI flags
+2. Developer config file (opt-in; private, gitignored, project-local,
+   TOML or dotenv -- beats the environment)
+3. Environment variables (with an opt-in `.env` file as a fallback)
+4. Config file(s), in this order (each overrides the previous):
+   a. /etc/<app>/config.toml            (system-wide; opt-in, off by default)
+   b. ~/.config/<app>/config.toml       (user-global, overrides system)
+   c. ./.config.toml                    (project-local, overrides user)
+   d. ./.config.*.toml                  (sibling files, sorted by name)
+5. Hardcoded defaults
+```
+
+Or, lowest priority to highest:
+
+```
+defaults < system < user < project < env < developer < CLI
+```
+
+Everything hangs off that one dict: the layers it feeds, and what
+conclude infers from it so you never write any of it twice:
+
+```
+                ┌── CLI
+defaults ───────┼── developer config (explicit opt-in, must be gitignored)
+       │        ├── environment
+       │        ├── .env (explicit opt-in)
+       │        └── config files
+       │
+       └── inference
+             ├── caster
+             ├── formatter
+             ├── CLI name
+             └── environment name
+```
+
+(The layers are listed highest priority first; `defaults` sits beneath
+all of them.) The user and project config files are on by default, and
+each is one `None` away from off. The system file, `.env`, and the
+developer file are off until you ask for them.
+
+## Local files: which one?
+
+Two of the layers are about your own machine, and each comes in two
+formats:
+
+| Format | Below the environment                     | Above the environment                      |
+| ------ | ----------------------------------------- | ------------------------------------------ |
+| TOML   | the system, user and project config files | the developer file, e.g. `.developer.toml` |
+| dotenv | `.env`                                    | the developer file, e.g. `.env.local`      |
+
+- **Non-secret local defaults you're happy to commit** -- use `.env`.
+  A real `export` in the shell still beats it, so it can't override a
+  deployment.
+- **Private values that must win over stray shell exports** (a local
+  `DATABASE_URL`, say) -- use the developer file. Make it TOML if only
+  your app reads it (it gets `[table]`s, including per-recipient ones);
+  make it dotenv, like `.env.local`, if docker compose, direnv or your
+  IDE need the same values.
+- **A private `.env` that stays below the environment** -- use `.env`
+  with `dotenv_require_gitignored=True`.
+
+The developer file's location lives in your committed `pyproject.toml`
+(any name works; the name decides the format, and only `.toml` means
+TOML):
+
+```toml
+[tool.conclude.developer]
+config = ".developer.toml"  # or ".env.local"
+```
+
+```python
+app = conclude.App(
+    "myapp",
+    DEFAULTS,
+    pyproject_path=conclude.AUTO,  # the developer file
+    dotenv_path=conclude.AUTO,  # .env
+)
+```
+
+The developer file is always guarded, and `.env` is when you ask: the
+file is used only if it exists, sits in a git working tree, and is
+gitignored. Otherwise it is skipped quietly, and `describe_sources()`
+says why. Details: [the `.env` file](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#6-local-development-a-env-file), [the developer file](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#8-a-private-developer-config-file).
+
+## What's in it
+
+- **Inference** of casters, formatters, CLI flags, env var names and
+  config keys from the defaults alone; `opt(type)` for a setting that
+  starts out unset ([guide, section 1](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#1-the-bare-minimum), [section 3](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#3-when-inference-isnt-quite-enough-casters-and-formatters)).
+- **Config-file tables**, including a positional shorthand that picks a
+  table per recipient/deck/profile ([section 4](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#4-a-positional-shorthand--per-recipient-config-tables)).
+- **`--print-invocation`** and `App.format_invocation()`: print the
+  command line that reproduces a resolved configuration
+  ([section 5](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#5-debugging-and-documentation---print-invocation)).
+- **A `.env` fallback**, optionally required to be gitignored, sitting
+  beneath real environment variables ([section 6](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#6-local-development-a-env-file)).
+- **A system-wide config file**, the lowest-priority file ([section 7](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#7-machine-wide-defaults-a-system-config-file)).
+- **A private developer file**, TOML or dotenv, that beats ambient
+  environment variables ([section 8](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#8-a-private-developer-config-file)).
+- **`describe_sources()`** for `--help`: which sources are in play, and
+  why a given one isn't ([section 9](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#9-turning-off-a-source-and-telling-the-user)).
+- **Templates and docs generated from your defaults**:
+  `format_env()`, `format_toml()`, `format_cli()`
+  ([section 10](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md#10-generating-docs-and-templates)).
+- Standard library only, fully typed (`py.typed`), Python 3.11+. The
+  gitignore check (developer file, strict `.env`) uses the optional
+  `pathspec` package.
+
+## Install
+
+```
+pip install conclude
+```
+
+The developer config layer (and a `.env` you ask to be held to the same
+standard) needs one small pure-Python dependency, only to check that a
+private file is gitignored:
+
+```
+pip install 'conclude[gitignore]'
+```
+
+## Documentation
+
+- [Guide](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md) -- builds a small CLI, `remind`, one
+  idea at a time.
+- [Reference](https://github.com/tanakapayam/conclude/blob/main/docs/reference.md) -- every class, method, and
+  module.
+- [Changelog](https://github.com/tanakapayam/conclude/blob/main/CHANGELOG.md).
+
+## Development
+
+```
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv build && uvx twine check --strict dist/*
+```
+
+CI runs these same commands on Python 3.11 through 3.14.
+
+## License
+
+MIT -- see [LICENSE](https://github.com/tanakapayam/conclude/blob/main/LICENSE).