tomlstack 0.1.2__tar.gz

tomlstack-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test-and-build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.11", "3.12", "3.13", "3.14" ]
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -e ".[dev]"
+
+    - name: Lint
+      if: matrix.python-version == '3.11'
+      run: |
+        ruff check .
+        ruff format --check .
+
+    - name: Type check
+      if: matrix.python-version == '3.11'
+      run: mypy
+
+    - name: Run tests
+      if: matrix.python-version != '3.11'
+      run: python -m pytest -q
+
+    - name: Run tests with coverage
+      if: matrix.python-version == '3.11'
+      run: python -m pytest --cov=tomlstack --cov-report=term-missing --cov-report=xml
+
+    - name: Upload coverage artifact
+      if: matrix.python-version == '3.11'
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-xml
+        path: coverage.xml
+
+    - name: Build package
+      if: matrix.python-version == '3.11'
+      run: python -m build

tomlstack-0.1.2/.github/workflows/publish-pypi.yml

@@ -0,0 +1,72 @@
+name: Publish PyPI
+
+on:
+  push:
+    tags:
+    - "v*"
+
+jobs:
+  publish:
+    if: ${{ !contains(github.ref_name, 'rc') }}
+    runs-on: ubuntu-latest
+    environment: PyPI
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install build and test tools
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -e ".[test]"
+        python -m pip install build twine
+
+    - name: Run tests
+      run: python -m pytest -q
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check distribution metadata
+      run: python -m twine check dist/*
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+    - name: Generate changelog
+      id: changelog
+      run: |
+        if git describe --tags --abbrev=0 "${GITHUB_REF_NAME}^" >/dev/null 2>&1; then
+          PREV_TAG="$(git describe --tags --abbrev=0 "${GITHUB_REF_NAME}^")"
+          {
+            echo "CHANGELOG<<EOF"
+            git log --pretty=format:'- %s (%h)' "${PREV_TAG}..${GITHUB_REF_NAME}"
+            echo
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+        else
+          {
+            echo "CHANGELOG<<EOF"
+            echo "Initial release ${GITHUB_REF_NAME}."
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v2
+      with:
+        tag_name: ${{ github.ref_name }}
+        name: ${{ github.ref_name }}
+        body: ${{ steps.changelog.outputs.CHANGELOG }}
+        files: |
+          dist/*

tomlstack-0.1.2/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,45 @@
+name: Publish TestPyPI
+
+on:
+  push:
+    tags:
+    - "v*rc*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: TestPyPI
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install build and test tools
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -e ".[test]"
+        python -m pip install build twine
+
+    - name: Run tests
+      run: python -m pytest -q
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check distribution metadata
+      run: python -m twine check dist/*
+
+    - name: Publish to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/

tomlstack-0.1.2/.gitignore

@@ -0,0 +1,159 @@
+# 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/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# 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
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__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/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+
+# custom
+
+.vscode/*
+# hatch-vcs generated version file
+src/tomlstack/_version.py

tomlstack-0.1.2/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog,
+and this project follows Semantic Versioning.
+
+## [0.1.2] - 2026-03-01
+
+- first publish version
+
+## [0.1.1rc3] - 2026-03-01
+
+- try to fix OIDC
+
+## [0.1.1rc2] - 2026-03-01
+
+### Added
+
+- CI Python version matrix (`3.11`, `3.12`, `3.13`, `3.x`).
+- Development tool configuration for `ruff`, `mypy`, and `pytest`.
+- Publishing workflows for TestPyPI and PyPI with GitHub Release automation.
+
+### Changed
+
+- Packaging version now comes from git tags via `hatch-vcs`.
+- CI now produces coverage reports and enforces a coverage threshold.
+
+## [0.1.1rc1] - 2026-02-28
+
+### Added
+
+- First release candidate published to TestPyPI.
+
+## [0.1.0] - 2026-02-28
+
+### Added
+
+- Initial public release of `tomlstack`.
+- Top-level `include` support with deterministic merge behavior.
+- `${path}` interpolation with cycle and undefined reference checks.
+- Node provenance (`origin`, `history`, `explain`) APIs.

tomlstack-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+## Development setup
+
+1. Use Python 3.11+.
+2. Install dev dependencies:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Local quality checks
+
+Run tests:
+
+```bash
+uv run python -m pytest -q
+```
+
+Run lint:
+
+```bash
+uv run ruff check .
+```
+
+Run formatting check (optional):
+
+```bash
+uv run ruff format --check .
+```
+
+Run type check:
+
+```bash
+uv run mypy
+```
+
+## Project layout
+
+- Source code: `src/tomlstack/`
+- Tests: `tests/`
+- CI workflows: `.github/workflows/`
+
+## Commit and PR guidelines
+
+- Keep commits focused and minimal.
+- Add or update tests for behavior changes.
+- Update `CHANGELOG.md` for user-visible changes.
+- Ensure CI is green before merge.
+
+## Release flow
+
+1. Ensure `CHANGELOG.md` is up to date.
+2. For release candidate, create tag like `v0.1.1rc1` and push.
+3. For final release, create tag like `v0.1.1` and push.
+4. CI workflows will run tests/build and publish automatically.
+
+Version is derived from git tags via `hatch-vcs` (do not edit version manually in `pyproject.toml`).
+
+See `RELEASE.md` for full publishing details.

tomlstack-0.1.2/LICENSE

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

tomlstack-0.1.2/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: tomlstack
+Version: 0.1.2
+Summary: TOML configuration loader with include/merge/interpolation
+Project-URL: Homepage, https://github.com/wxzhao7/tomlstack
+Project-URL: Repository, https://github.com/wxzhao7/tomlstack
+Project-URL: Issues, https://github.com/wxzhao7/tomlstack/issues
+Author: wxzhao7
+License: MIT
+License-File: LICENSE
+Keywords: config,configuration,include,interpolation,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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: ruff>=0.8; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.3; extra == 'test'
+Provides-Extra: typing
+Requires-Dist: mypy>=1.11; extra == 'typing'
+Description-Content-Type: text/markdown
+
+# tomlstack
+
+`tomlstack` is a lightweight TOML config loader for Python 3.11+ with:
+
+- top-level `include` loading
+- deterministic merge by include order
+- `${path}` interpolation with cycle/undefined checks
+- node-level provenance (`origin`, `explain`, `history`)
+
+tomlstack does not try to be a configuration framework.
+It address two missing pieces to TOML: file composition and safe interpolation — while keeping files self-contained and explainable.
+
+## Install
+
+```bash
+pip install tomlstack
+```
+
+## Quick Start
+
+`main.toml`:
+
+```toml
+include = [
+    "./base.toml",
+    "./prod.toml",
+]
+
+[db]
+url = "postgres://${db.user}:${db.pass}@${db.host}:${db.port}"
+```
+
+`base.toml`:
+
+```toml
+[db]
+user = "alice"
+pass = "secret"
+host = "localhost"
+port = 5432
+```
+
+Python:
+
+```python
+from tomlstack import load
+
+cfg = load("main.toml")
+print(cfg["db"]["url"].raw)    # raw interpolation string
+cfg.resolve()
+print(cfg["db"]["url"].value)  # resolved value
+print(cfg["db"]["url"].origin)
+print(cfg["db"]["url"].history)
+print(cfg.to_dict())
+```
+
+## Include Semantics
+
+- top-level `include` only; nested `include` is treated as normal data
+- syntax: string or list of strings
+- valid include path forms:
+- `./...` or `../...`
+- `@label/...` (label from `__meta__.include.anchors`)
+- absolute path
+- any other form raises error with hint: `Use ./ or ../ or @label/`
+
+### Meta Include Directives
+
+```toml
+[__meta__]
+version = 1
+
+[__meta__.include]
+root = "../.."
+
+[__meta__.include.anchors]
+proj = "./shared"
+```
+
+- `__meta__.include.root` is sugar for `anchors.root`
+- if both `root` and `anchors.root` exist and resolve differently, error
+- anchor/root path values must be absolute or start with `./` or `../`
+- if any file explicitly sets `__meta__.version`, all files in include chain must share one supported version (`1`)
+
+## Merge Rules
+
+Load order for current file:
+
+1. merge first include
+2. merge second include
+3. ...
+4. merge current file (highest priority)
+
+Conflict behavior:
+
+- dict: recursive merge, later wins on key conflict
+- list: later value replaces whole list
+- scalar: later value replaces earlier
+
+## Interpolation Semantics
+
+- interpolation happens on `cfg.resolve()`
+- path syntax supports dot and list index: `${db.apps[0]}`
+- full-string interpolation (`"${db.port}"`) keeps source type
+- embedded interpolation (`"postgres://${db.host}:${db.port}"`) allows only:
+- `str`, `int`, `float`, `date`, `time`, `datetime`
+- formatting syntax: `${path:spec}`
+- for `date/time/datetime`, formatting uses `strftime`
+- otherwise uses Python `format(value, spec)`
+- undefined reference raises `InterpolationUndefinedError`
+- interpolation cycle raises `InterpolationCycleError`
+
+## Public API
+
+- `cfg = load("f.toml")`
+- `cfg.resolve()`
+- `cfg.to_dict()`
+- `node = cfg["proj"][0]["path"]["foo"]`
+- `node.raw`
+- `node.value`
+- `node.origin`
+- `node.history`
+- `node.preview()`
+- `cfg.to_toml()` -> `NotImplementedError`
+
+## Current Limitations
+
+- interpolation path parser supports unquoted dot keys and numeric list indices
+- no nested interpolation expressions
+- `to_toml()` is not implemented yet
+
+## TODO
+
+- [ ] review the details of interpolation
+- [ ] explain history with interpolation
+
+## Release To PyPI
+
+Build package:
+
+```bash
+uv run --with build python -m build
+```
+
+Upload to TestPyPI first:
+
+```bash
+uv run --with twine python -m twine upload --repository testpypi dist/*
+```
+
+Verify install from TestPyPI:
+
+```bash
+python -m pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple tomlstack
+```
+
+Upload to PyPI:
+
+```bash
+uv run --with twine python -m twine upload dist/*
+```