confease 1.0.0__tar.gz

confease-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Docs
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Build and deploy documentation
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install Hatch
+        run: python -m pip install --upgrade hatch
+
+      - name: Build docs
+        run: hatch run docs:build
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/_build/html
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

confease-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build and publish distribution packages
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/confease
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install release tooling
+        run: python -m pip install --upgrade hatch twine
+
+      - name: Build sdist and wheel
+        run: hatch build
+
+      - name: Check distribution metadata
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+      - name: Generate SHA256 checksums
+        run: sha256sum dist/* > dist/checksums.txt
+
+      - name: Upload artifacts to GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true

confease-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+build/
+dist/
+*.egg-info/
+
+docs/_build/

confease-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: hatch run ruff check .
+        language: system
+        pass_filenames: false
+
+      - id: mypy
+        name: mypy
+        entry: hatch run mypy src
+        language: system
+        pass_filenames: false
+
+      - id: pytest
+        name: pytest
+        entry: hatch run pytest
+        language: system
+        pass_filenames: false

confease-1.0.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# 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 this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-08-13
+
+### Added
+
+- Add the `Confease` configuration container with defaults, user/system files, environment variables, and `argparse.Namespace` source loading.
+- Add configurable source precedence with CLI, environment, system, user, and default origins.
+- Add typed configuration persistence for YAML, JSON, TOML, CSV, INI-family formats, and XML.
+- Add one-level nested configuration keys with dotted leaf access and section snapshots.
+- Add indexed access and assignment through `conf[key]` and `conf[key] = value`.
+- Add safe config-file editing through a blocking `TextEditor` and `Confease.edit_file()` draft-validation workflow.
+- Add release, documentation deployment, and pre-commit automation for package maintenance.
+
+### Changed
+
+- Preserve original Python value types instead of stringifying `Confitem.value`.
+- Store CSV and INI-family scalar values as YAML text so common Python values round-trip across flat formats.
+- Keep defaults memory-only unless callers explicitly save the full effective configuration with `save(user_only=False)`.
+- Treat nested-capable parsers as nested mappings while CSV persists flat dotted keys with a `key,value` header.
+
+### Documentation
+
+- Add practical README guidance for installation, quickstart usage, precedence, nested keys, environment variables, supported file formats, and editor workflows.
+- Add Sphinx documentation with user guides, parser/file-format guidance, troubleshooting notes, and autodoc-based API reference pages.
+
+### Tests
+
+- Add focused coverage for core configuration behavior, parser round-tripping, source precedence, persistence, indexed access, and editor safety.

confease-1.0.0/LICENSE

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

confease-1.0.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: confease
+Version: 1.0.0
+Summary: Small Python configuration helper with predictable source precedence
+Project-URL: Repository, https://github.com/octanima-labs/confease
+Project-URL: Documentation, https://octanima-labs.github.io/confease
+Project-URL: Issues, https://github.com/octanima-labs/confease/issues
+Author-email: octanima-labs <34071457+octanima-labs@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: 2ning
+Requires-Dist: pyyaml
+Requires-Dist: tomli-w
+Description-Content-Type: text/markdown
+
+# confease
+
+`confease` is a small Python configuration helper for applications that need predictable precedence across defaults, configuration files, environment variables, and CLI arguments.
+
+Use it when you want one shared configuration object that can load user and system config files, accept `argparse` overrides, read typed environment values, and persist user preferences without building a full settings framework.
+
+> Status: `confease` is an alpha prototype. The public API is intentionally small, but behavior may still change before a stable release.
+
+## Installation
+
+When published, install from PyPI:
+
+```bash
+pip install confease
+```
+
+For local development from this repository:
+
+```bash
+git clone https://github.com/octanima-labs/confease.git
+cd confease
+hatch run pytest
+```
+
+The package requires Python 3.11 or newer.
+
+## Quickstart
+
+Create one shared configuration object near your application entry point:
+
+```python
+from argparse import ArgumentParser
+
+from confease import Confease
+
+parser = ArgumentParser()
+parser.add_argument("--debug", dest="DEBUG", action="store_true")
+parser.add_argument("--database-host", dest="database", action="store_const", const={"host": "db.internal"})
+args = parser.parse_args()
+
+conf = Confease(
+    "~/.config/my-app/conf.yaml",
+    APP_DIR="~/Apps",
+    DEBUG=False,
+    database={"host": "localhost", "port": 5432},
+)
+
+conf.load_sources(args, "/etc/my-app/conf.yaml")
+```
+
+Read values with `get()` or indexed access:
+
+```python
+conf.get("APP_DIR")          # "~/Apps"
+conf["APP_DIR"]             # "~/Apps"
+conf.get("MISSING")          # None
+conf["MISSING"]             # None
+conf.get("DEBUG", cast=bool) # False
+```
+
+Update values with `set()` or indexed assignment:
+
+```python
+conf.set("DEBUG", True)
+conf["APP_DIR"] = "/srv/app"
+conf.save()
+```
+
+By default, `save()` writes only user-origin values. Use `save(user_only=False)` when you want to persist the full effective configuration, including defaults and overrides.
+
+## Nested Keys
+
+`Confease` supports one nested level. Internally, nested leaves are stored as dotted keys:
+
+```python
+conf.set("database", {"host": "localhost", "port": 5432})
+
+conf.get("database.host")    # "localhost"
+conf["database.host"]        # "localhost"
+conf.get("database")         # {"host": "localhost", "port": 5432}
+conf["database"]["host"]     # "localhost"
+```
+
+Section access returns a plain snapshot dictionary. Missing subkeys raise `KeyError`, so write nested values through dotted keys or `set()`:
+
+```python
+conf["database.port"] = 5433
+```
+
+## Source Precedence
+
+By default, sources are resolved in this order:
+
+```text
+CLI > ENV > SYS > USR > DEF
+```
+
+Origins mean:
+
+- `CLI`: values from an `argparse.Namespace` passed to `load_sources()` or `reload_cli()`.
+- `ENV`: known environment variables loaded by `reload_env()`.
+- `SYS`: config files outside the current user home directory.
+- `USR`: config files inside the current user home directory and values assigned with `set()`.
+- `DEF`: defaults passed as keyword arguments to `Confease(...)`.
+
+Customize precedence with `preference`:
+
+```python
+conf = Confease("conf.yaml", preference=["env", "cli", "user", "default"])
+conf.load_sources(args, "conf.yaml", preference=["cli", "env", "user", "default"])
+```
+
+Omitted origins are appended after the origins you provide.
+
+## Environment Variables
+
+`reload_env()` only imports environment variables whose keys are already known from defaults or loaded files. Values are parsed with `yaml.safe_load`, so common scalar text recovers Python types:
+
+```bash
+export DEBUG=true
+export PORT=5432
+```
+
+```python
+conf = Confease(DEBUG=False, PORT=8000)
+conf.reload_env()
+
+conf["DEBUG"] # True
+conf["PORT"]  # 5432
+```
+
+## File Formats
+
+The parser is inferred from the path suffix when `parser=None` is used, or you can pass a parser class explicitly.
+
+Supported suffixes:
+
+- `.yaml`, `.yml`
+- `.json`
+- `.toml`
+- `.ini`, `.cfg`, `.conf`, `.config`
+- `.xml`
+- `.csv`
+
+```python
+from confease import Confease, Json
+
+yaml_conf = Confease("conf.yaml", parser=None)
+json_conf = Confease("conf.json", parser=Json)
+```
+
+YAML, JSON, TOML, INI, and XML persist one-level nested sections. CSV persists flat dotted keys with a `key,value` header.
+
+## Edit Config Files
+
+`edit_file()` opens a temporary draft in a blocking text editor, validates the edited content with the active parser, and only then replaces the real config file:
+
+```python
+from confease import TextEditor
+
+conf.editor = TextEditor("code")
+conf.edit_file(user_only=True)
+```
+
+Invalid edited content raises an error and leaves the previous file and in-memory values unchanged.
+
+## Documentation
+
+- Documentation: <https://octanima-labs.github.io/confease>
+- Repository: <https://github.com/octanima-labs/confease>
+- Issues: <https://github.com/octanima-labs/confease/issues>
+
+## License
+
+MIT

confease-1.0.0/README.md

@@ -0,0 +1,175 @@
+# confease
+
+`confease` is a small Python configuration helper for applications that need predictable precedence across defaults, configuration files, environment variables, and CLI arguments.
+
+Use it when you want one shared configuration object that can load user and system config files, accept `argparse` overrides, read typed environment values, and persist user preferences without building a full settings framework.
+
+> Status: `confease` is an alpha prototype. The public API is intentionally small, but behavior may still change before a stable release.
+
+## Installation
+
+When published, install from PyPI:
+
+```bash
+pip install confease
+```
+
+For local development from this repository:
+
+```bash
+git clone https://github.com/octanima-labs/confease.git
+cd confease
+hatch run pytest
+```
+
+The package requires Python 3.11 or newer.
+
+## Quickstart
+
+Create one shared configuration object near your application entry point:
+
+```python
+from argparse import ArgumentParser
+
+from confease import Confease
+
+parser = ArgumentParser()
+parser.add_argument("--debug", dest="DEBUG", action="store_true")
+parser.add_argument("--database-host", dest="database", action="store_const", const={"host": "db.internal"})
+args = parser.parse_args()
+
+conf = Confease(
+    "~/.config/my-app/conf.yaml",
+    APP_DIR="~/Apps",
+    DEBUG=False,
+    database={"host": "localhost", "port": 5432},
+)
+
+conf.load_sources(args, "/etc/my-app/conf.yaml")
+```
+
+Read values with `get()` or indexed access:
+
+```python
+conf.get("APP_DIR")          # "~/Apps"
+conf["APP_DIR"]             # "~/Apps"
+conf.get("MISSING")          # None
+conf["MISSING"]             # None
+conf.get("DEBUG", cast=bool) # False
+```
+
+Update values with `set()` or indexed assignment:
+
+```python
+conf.set("DEBUG", True)
+conf["APP_DIR"] = "/srv/app"
+conf.save()
+```
+
+By default, `save()` writes only user-origin values. Use `save(user_only=False)` when you want to persist the full effective configuration, including defaults and overrides.
+
+## Nested Keys
+
+`Confease` supports one nested level. Internally, nested leaves are stored as dotted keys:
+
+```python
+conf.set("database", {"host": "localhost", "port": 5432})
+
+conf.get("database.host")    # "localhost"
+conf["database.host"]        # "localhost"
+conf.get("database")         # {"host": "localhost", "port": 5432}
+conf["database"]["host"]     # "localhost"
+```
+
+Section access returns a plain snapshot dictionary. Missing subkeys raise `KeyError`, so write nested values through dotted keys or `set()`:
+
+```python
+conf["database.port"] = 5433
+```
+
+## Source Precedence
+
+By default, sources are resolved in this order:
+
+```text
+CLI > ENV > SYS > USR > DEF
+```
+
+Origins mean:
+
+- `CLI`: values from an `argparse.Namespace` passed to `load_sources()` or `reload_cli()`.
+- `ENV`: known environment variables loaded by `reload_env()`.
+- `SYS`: config files outside the current user home directory.
+- `USR`: config files inside the current user home directory and values assigned with `set()`.
+- `DEF`: defaults passed as keyword arguments to `Confease(...)`.
+
+Customize precedence with `preference`:
+
+```python
+conf = Confease("conf.yaml", preference=["env", "cli", "user", "default"])
+conf.load_sources(args, "conf.yaml", preference=["cli", "env", "user", "default"])
+```
+
+Omitted origins are appended after the origins you provide.
+
+## Environment Variables
+
+`reload_env()` only imports environment variables whose keys are already known from defaults or loaded files. Values are parsed with `yaml.safe_load`, so common scalar text recovers Python types:
+
+```bash
+export DEBUG=true
+export PORT=5432
+```
+
+```python
+conf = Confease(DEBUG=False, PORT=8000)
+conf.reload_env()
+
+conf["DEBUG"] # True
+conf["PORT"]  # 5432
+```
+
+## File Formats
+
+The parser is inferred from the path suffix when `parser=None` is used, or you can pass a parser class explicitly.
+
+Supported suffixes:
+
+- `.yaml`, `.yml`
+- `.json`
+- `.toml`
+- `.ini`, `.cfg`, `.conf`, `.config`
+- `.xml`
+- `.csv`
+
+```python
+from confease import Confease, Json
+
+yaml_conf = Confease("conf.yaml", parser=None)
+json_conf = Confease("conf.json", parser=Json)
+```
+
+YAML, JSON, TOML, INI, and XML persist one-level nested sections. CSV persists flat dotted keys with a `key,value` header.
+
+## Edit Config Files
+
+`edit_file()` opens a temporary draft in a blocking text editor, validates the edited content with the active parser, and only then replaces the real config file:
+
+```python
+from confease import TextEditor
+
+conf.editor = TextEditor("code")
+conf.edit_file(user_only=True)
+```
+
+Invalid edited content raises an error and leaves the previous file and in-memory values unchanged.
+
+## Documentation
+
+- Documentation: <https://octanima-labs.github.io/confease>
+- Repository: <https://github.com/octanima-labs/confease>
+- Issues: <https://github.com/octanima-labs/confease/issues>
+
+## License
+
+MIT

confease-1.0.0/docs/api/core.rst

@@ -0,0 +1,49 @@
+Core API
+========
+
+.. currentmodule:: confease
+
+The core API is centered on :class:`Confease`, a configuration container that stores :class:`Confitem` values with an origin and resolves conflicts through configurable precedence.
+
+Origins
+-------
+
+.. data:: CLI
+
+   Origin name for values loaded from command-line arguments.
+
+.. data:: ENV
+
+   Origin name for values loaded from environment variables.
+
+.. data:: SYS
+
+   Origin name for values loaded from configuration files outside the current user's home directory.
+
+.. data:: USR
+
+   Origin name for values loaded from user configuration files or assigned through :meth:`Confease.set`.
+
+.. data:: DEF
+
+   Origin name for defaults passed to :class:`Confease`.
+
+.. data:: ORIGINS
+
+   Ordered list of all supported origin names.
+
+Confease
+--------
+
+.. autoclass:: Confease
+   :members:
+   :special-members: __getitem__, __setitem__
+   :exclude-members: __weakref__
+
+Confitem
+--------
+
+.. autoclass:: Confitem
+   :members:
+   :special-members: __eq__, __repr__, __str__
+   :exclude-members: __weakref__

confease-1.0.0/docs/api/index.rst

@@ -0,0 +1,12 @@
+API Reference
+=============
+
+This reference documents the public ``confease`` API and the parser classes exposed by the package.
+
+API descriptions are generated from source docstrings with Sphinx autodoc, Napoleon, and ``sphinx-autodoc-typehints``. Treat the docstrings in ``src/confease/`` as the canonical API comments, and keep this section focused on navigation and high-level grouping.
+
+.. toctree::
+   :maxdepth: 2
+
+   core
+   parsers