conclude 1.0.0__tar.gz → 1.0.2__tar.gz

{conclude-1.0.0 → conclude-1.0.2}/.gitignore

@@ -19,6 +19,12 @@ htmlcov/
 # Build artifacts
 build/
 dist/
+*.tgz
+*.tsbuildinfo
+
+# Node
+node_modules/
+.verdaccio-storage/
 
 # Virtual environments
 .venv/

conclude-1.0.2/CHANGELOG.md

@@ -0,0 +1,67 @@
+# 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.2] - 2026-09-26
+
+### Fixed
+
+- Python tree is now under `python/` to match `node/` tree.
+
+## [1.0.1] - 2026-09-20
+
+### Fixed
+
+- `.env` files, and dotenv-format developer files, are now read as UTF-8 on
+  every platform, and a leading byte-order mark is ignored. Previously the
+  platform's default text encoding was used, which garbled non-ASCII values
+  on Windows, and a byte-order mark (which some Windows editors add) made
+  the first variable silently disappear.
+
+### Changed
+
+- The package's OS classifier is now `Operating System :: Unix` rather than
+  `OS Independent`: the tests run on Linux, and the paths conclude uses
+  (`~/.config`, `/etc`) are Unix conventions.
+- The source distribution no longer includes `uv.lock` or `.github/`.
+
+## [1.0.0] - 2026-09-20
+
+First public release.
+
+### Added
+
+- **Inference from one dict.** `App(name, defaults)` infers each setting's
+  environment variable, config-file key, CLI flag, caster and formatter
+  from its name, type and default. `opt(type)` declares a typed setting
+  that starts out unset.
+- **Layered resolution:** `defaults < system < user < project < env <
+  developer < CLI`, with per-key casting at every layer.
+- **Config files:** user (`~/.config/<name>/config.toml`) and project
+  (`./.config.toml`, plus `.config.*.toml` siblings, configurable or
+  disabled with `config_cwd_aux_pattern`) files; an opt-in system-wide
+  `/etc/<name>/config.toml`; two-level `[PARENT]` / `[PARENT.CHILD]`
+  tables; a positional shorthand that picks a table.
+- **`.env` fallback** beneath real environment variables (opt-in).
+  `dotenv_require_gitignored=True` holds it to the developer file's
+  gitignore guard, and `App.dotenv_status()` reports its state.
+- **Developer config layer** (opt-in via `pyproject_path`): a private,
+  gitignored, project-local file named by `pyproject.toml`'s
+  `tool.conclude.developer.config` that beats ambient environment
+  variables and loses to the CLI. The file is TOML if its name ends in
+  `.toml` and dotenv otherwise (say `.env.local`, keyed by the app's
+  environment variable names, so it can be shared with docker compose or
+  direnv). It is applied only when the file exists, sits in a git working
+  tree, and is covered by its ignore rules, checked with the optional
+  `pathspec` extra: `pip install 'conclude[gitignore]'`.
+  `<NAME>_DEVELOPER_CONFIG=off` is a kill switch, and
+  `App.developer_status()` reports the layer's state and reason as data.
+- **`describe_sources()`** for `--help`, listing every source and, for the
+  developer layer and a strict `.env`, whether it is active and why not.
+- **Generated templates and docs:** `format_env()`, `format_toml()` and
+  `format_cli()` render every setting next to its default.
+- **`--print-invocation`** and `format_invocation()`: reproduce a resolved
+  configuration as a command line.
+- Standard library only; fully typed (`py.typed`); Python 3.11 and newer.

{conclude-1.0.0 → conclude-1.0.2}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: conclude
-Version: 1.0.0
+Version: 1.0.2
 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: Documentation, https://github.com/tanakapayam/conclude/blob/main/docs/python/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
+Project-URL: Changelog, https://github.com/tanakapayam/conclude/blob/main/python/CHANGELOG.md
 Author: Payam Tanaka
 License-Expression: MIT
 License-File: LICENSE
@@ -14,7 +14,7 @@ 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: Operating System :: Unix
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
@@ -92,7 +92,7 @@ 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).
+[How conclude compares](https://github.com/tanakapayam/conclude/blob/main/docs/python/comparison.md).
 
 ## Design principles
 
@@ -195,28 +195,28 @@ app = conclude.App(
 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).
+says why. Details: [the `.env` file](https://github.com/tanakapayam/conclude/blob/main/docs/python/guide.md#6-local-development-a-env-file), [the developer file](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  starts out unset ([guide, section 1](https://github.com/tanakapayam/conclude/blob/main/docs/python/guide.md#1-the-bare-minimum), [section 3](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  table per recipient/deck/profile ([section 4](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  ([section 5](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  beneath real environment variables ([section 6](https://github.com/tanakapayam/conclude/blob/main/docs/python/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/python/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)).
+  environment variables ([section 8](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  why a given one isn't ([section 9](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  ([section 10](https://github.com/tanakapayam/conclude/blob/main/docs/python/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.
@@ -237,16 +237,16 @@ pip install 'conclude[gitignore]'
 
 ## Documentation
 
-- [Guide](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md) -- builds a small CLI, `remind`, one
+- [Guide](https://github.com/tanakapayam/conclude/blob/main/docs/python/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
+- [Reference](https://github.com/tanakapayam/conclude/blob/main/docs/python/reference.md) -- every class, method, and
   module.
-- [Changelog](https://github.com/tanakapayam/conclude/blob/main/CHANGELOG.md).
+- [Changelog](https://github.com/tanakapayam/conclude/blob/main/python/CHANGELOG.md).
 
 ## Development
 
 ```
-uv sync
+uv sync --locked  # fails if uv.lock is out of date; `uv lock` refreshes it
 uv run pytest
 uv run ruff check . && uv run ruff format --check .
 uv run mypy

{conclude-1.0.0 → conclude-1.0.2}/README.md

@@ -61,7 +61,7 @@ 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).
+[How conclude compares](https://github.com/tanakapayam/conclude/blob/main/docs/python/comparison.md).
 
 ## Design principles
 
@@ -164,28 +164,28 @@ app = conclude.App(
 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).
+says why. Details: [the `.env` file](https://github.com/tanakapayam/conclude/blob/main/docs/python/guide.md#6-local-development-a-env-file), [the developer file](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  starts out unset ([guide, section 1](https://github.com/tanakapayam/conclude/blob/main/docs/python/guide.md#1-the-bare-minimum), [section 3](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  table per recipient/deck/profile ([section 4](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  ([section 5](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  beneath real environment variables ([section 6](https://github.com/tanakapayam/conclude/blob/main/docs/python/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/python/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)).
+  environment variables ([section 8](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  why a given one isn't ([section 9](https://github.com/tanakapayam/conclude/blob/main/docs/python/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)).
+  ([section 10](https://github.com/tanakapayam/conclude/blob/main/docs/python/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.
@@ -206,16 +206,16 @@ pip install 'conclude[gitignore]'
 
 ## Documentation
 
-- [Guide](https://github.com/tanakapayam/conclude/blob/main/docs/guide.md) -- builds a small CLI, `remind`, one
+- [Guide](https://github.com/tanakapayam/conclude/blob/main/docs/python/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
+- [Reference](https://github.com/tanakapayam/conclude/blob/main/docs/python/reference.md) -- every class, method, and
   module.
-- [Changelog](https://github.com/tanakapayam/conclude/blob/main/CHANGELOG.md).
+- [Changelog](https://github.com/tanakapayam/conclude/blob/main/python/CHANGELOG.md).
 
 ## Development
 
 ```
-uv sync
+uv sync --locked  # fails if uv.lock is out of date; `uv lock` refreshes it
 uv run pytest
 uv run ruff check . && uv run ruff format --check .
 uv run mypy

conclude-1.0.2/RELEASING.md

@@ -0,0 +1,56 @@
+# Releasing conclude (Python)
+
+```
+release published (tag python-v<version>)
+   |
+   v
+ ci ---> build ---> publish-testpypi   (workflow_dispatch, target testpypi: a dry run)
+          |          |
+          |          +-> publish-pypi   waits for a reviewer to approve the `pypi`
+          |                             environment, then publishes with trusted
+          |                             publishing (no stored token)
+          |
+          +-- one sdist + wheel, built once, uploaded as an artifact and promoted unchanged
+```
+
+TestPyPI is the dry run here (there is no separate staging registry, unlike the Node
+package's GitHub Packages stage): `workflow_dispatch` with `target: testpypi` builds,
+checks, and publishes to TestPyPI, and installs nothing back automatically -- try it
+yourself with `pip install -i https://test.pypi.org/simple/ conclude`. A real release
+(`target: pypi`, or a published GitHub Release) is checked, gated behind a required
+reviewer on the `pypi` environment, then published to PyPI.
+
+## One-time setup
+
+1. **Environments** (repository Settings, Environments):
+   - `testpypi`: no protection needed.
+   - `pypi`: add yourself (or a team) under *Required reviewers*; that is the approval
+     gate.
+2. **Trusted publisher**, on both <https://pypi.org> and <https://test.pypi.org>, for the
+   project `conclude`: this repository, workflow **`python-publish.yml`**, environment
+   `pypi` (`testpypi` on TestPyPI). For a project that does not exist yet, use
+   "Publishing" -> "Add a new pending publisher".
+3. Nothing to store: publishing uses OIDC. No PyPI token exists.
+
+> **If this workflow was ever registered under a different filename** (for example the
+> project's original `publish.yml`, before this repository moved every language into its
+> own top-level directory): trusted publishing is matched by *workflow filename*, so the
+> existing entries on PyPI and TestPyPI must be updated to `python-publish.yml` -- edit
+> them under "Publishing" on each site -- or the next release fails with a permission
+> error, not a helpful one.
+
+## Releasing
+
+1. Bump `__version__` in `src/conclude/__init__.py` (the single source of truth; see
+   `[tool.hatch.version]` in `pyproject.toml`), and the version in
+   `docs/python/comparison.md`'s "Verified" line if it's stale. Put a dated entry in
+   `CHANGELOG.md` (the release is refused while it says *Unreleased*).
+2. Merge to `main`.
+3. Create a GitHub Release from a new tag `python-v<version>` on `main`.
+4. `publish-pypi` waits for a reviewer to **approve the `pypi` deployment**; approve it
+   when you are happy.
+
+## Rehearsing
+
+Actions, Publish, Run workflow, target `testpypi` -- builds, checks, and publishes to
+TestPyPI without touching the `pypi` environment or a real version on PyPI.

{conclude-1.0.0 → conclude-1.0.2}/docs/comparison.md

@@ -3,7 +3,7 @@
 A feature-by-feature comparison with five libraries people often reach
 for instead. **Verified 2026-09-19** against each project's
 documentation and its PyPI metadata; the versions checked are
-conclude 1.0.0, ConfigArgParse 1.7.7, jsonargparse 4.52.0,
+conclude 1.0.2, ConfigArgParse 1.7.7, jsonargparse 4.52.0,
 pydantic-settings 2.15.0, Dynaconf 3.3.5 and python-decouple 3.8.
 
 A dash (--) means no built-in support that the project's documentation