herogold 0.1.1__tar.gz

herogold-0.1.1/.github/FUNDING.yml

@@ -0,0 +1,16 @@
+# These are supported funding model platforms
+
+github: HEROgold # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+# patreon: # Replace with a single Patreon username
+# open_collective: # Replace with a single Open Collective username
+# ko_fi: # Replace with a single Ko-fi username
+# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+# liberapay: # Replace with a single Liberapay username
+# issuehunt: # Replace with a single IssueHunt username
+# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+# polar: # Replace with a single Polar username
+# buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+# thanks_dev: # Replace with a single thanks.dev username
+# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
+#

herogold-0.1.1/.github/copilot-instructions.md

@@ -0,0 +1,79 @@
+Copilot instructions for this repository
+=====================================
+
+Primary goal
+------------
+Keep a single namespace package `herogold` which contains optional subpackages
+(`herogold.sentinel`, `herogold.color`, `herogold.log`, etc.). Subpackages
+are small utilities and boilerplate helpers — each lives under a per-package
+`src/herogold/<pkg>` layout so that after installation the import path is
+`from herogold.<pkg> import ...`.
+
+Python version and features
+---------------------------
+- Prefer the Python interpreter indicated by a `.python-version` file in the
+  subpackage root. If that file is missing, use the latest available version, and us the tool `uv` to set it. (uv python pin <version>)
+- Use modern, stable language features appropriate for the target Python version:
+  - builtin generics (e.g. `list[int]`, `dict[str, str]`) for typing
+  - `def[T](arg1: T) -> T:` style generics
+  - `match` / `case` (structural pattern matching) where it improves clarity or adds functionality
+  - concise `f`-strings and clear, explicit `__repr__` for debugging
+  - `dataclasses`, `typing.Protocol`, `TypedDict`, `Annotated` where helpful
+  - prefer `pathlib.Path`, `importlib`, and high-level stdlib APIs
+
+Packaging and layout rules
+-------------------------
+- Source layout: package code must live under `src/herogold/<pkg>/` (not
+  `src/<pkg>`). This ensures installed imports are `herogold.<pkg>`.
+- Each subpackage should include a minimal `__init__.py` and public API
+  surface (use `__all__` when helpful). Also add small README.md files in
+  subpackage folders describing purpose and a tiny usage example.
+- Do NOT create compatibility shims at the top-level (no `import sentinel ->
+  herogold.sentinel` shims). We prefer the canonical `herogold.<pkg>` import.
+- Keep per-package `pyproject.toml` metadata accurate. If you change
+  package layout, update workspace mappings (`[tool.uv.sources]` and
+  `pyproject` extras) accordingly.
+
+Coding style and quality
+------------------------
+- Follow the repository's formatter/linter settings (Black, ruff) if present
+  in `pyproject.toml` or `ruff.toml`. Use type annotations liberally and keep functions small
+  and testable.
+- Add or update unit tests (pytest) for any new behavior. Put tests under
+  `tests/` or inside each package's `tests/` folder. Use small, fast tests.
+- Always use typehinting. use `ruff check` and `ty check` to confirm these cases.
+  `ty check` is alpha, so just to be sure, also use `mypy`
+
+When generating code
+--------------------
+- Produce complete, runnable artifacts: module files, a minimal README, and
+  a couple of tests. If adding CLI entry points, wire them in `pyproject.toml`.
+- use tools and cli commands (like `ruff`, `uv`, etc) to create these where possible
+- Avoid adding external dependencies unless explicitly requested. If a
+  dependency is required, update the appropriate package `pyproject.toml`
+- add new packages to the workspace configuration in the root `pyproject.toml`
+
+Safety and network
+------------------
+- Do not include secrets or make remote network calls in generated code.
+
+Workflows and CI/CD
+----------------------
+- use existing workflows and CI/CD patterns in `.github/workflows/` and `.github/example-workflows/`
+- `.github/example-workflows/` contains reusable examples and should be referenced first when creating new workflows
+- use #fetch https://docs.astral.sh/uv/guides/integration/github over python actions
+- make sure workflows runs parallel jobs where possible to speed up feedback loops
+- call and reuse existing workflows where possible
+- cache and use results of other workflows to avoid redundant work if it provides value
+
+Examples
+--------
+- Import sentinel sentinel value:
+  from herogold.sentinel import MISSING
+- Import rainbow
+  from herogold.rainbow import RAINBOW
+- Import logging helpers:
+  from herogold.log import LoggerMixin
+
+If anything is ambiguous, prefer small, conservative changes and ask for
+clarification before large refactors.

herogold-0.1.1/.github/example-workflows/coverage.yml

@@ -0,0 +1,40 @@
+name: Coverage
+
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  coveralls-upload:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests with coverage
+        run: uv run coverage run --source=. -m pytest tests/
+
+      - name: Upload coverage data to coveralls.io
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
+          COVERALLS_SERVICE_NAME: github-actions
+          COVERALLS_PARALLEL: true
+        run: uvx coveralls --service=github
+
+      - name: Coveralls Finished
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
+        run: uvx coveralls --finish
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}

herogold-0.1.1/.github/example-workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Docs
+
+on:
+  push:
+    branches: [ master ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - uses: astral-sh/setup-uv@v3
+
+      - name: Generate docs (pdoc + mkdocs)
+        run: |
+          uv sync --group docs
+          uv run pdoc confkit -o docs/api
+          uv run mkdocs build -d site
+
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/master'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site
+          force_orphan: true

herogold-0.1.1/.github/example-workflows/pypi.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  repository_dispatch:
+    types: [new-release-created]
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        uv
+    - name: Build a binary wheel and a source tarball
+      run: uv build --sdist --wheel --out-dir dist
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: Publish Python 🐍 distribution 📦 to PyPI
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/confkit
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

herogold-0.1.1/.github/example-workflows/release.yml

@@ -0,0 +1,70 @@
+name: Auto-release
+
+on:
+  push:
+    branches: [ master ]
+  workflow_dispatch:
+
+jobs:
+  rel-test:
+    uses: ./.github/workflows/test.yml
+
+  new-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    needs: rel-test
+    outputs:
+      version_changed: ${{ steps.version-check.outputs.version_changed }}
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Needed to get all tags for version comparison
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.*"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Check if version changed
+      id: version-check
+      run: |
+        # Get current version from pyproject.toml
+        CURRENT_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+        echo "current_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+
+        # Check if this version already has a tag
+        if git tag --list | grep -q "^v$CURRENT_VERSION$"; then
+          echo "version_changed=false" >> $GITHUB_OUTPUT
+          echo "Version v$CURRENT_VERSION already exists as a tag"
+        else
+          echo "version_changed=true" >> $GITHUB_OUTPUT
+          echo "New version v$CURRENT_VERSION detected - will create release"
+        fi
+
+    - name: Create GitHub Release
+      if: steps.version-check.outputs.version_changed == 'true'
+      uses: softprops/action-gh-release@v2
+      with:
+        tag_name: v${{ steps.version-check.outputs.current_version }}
+        name: Release v${{ steps.version-check.outputs.current_version }}
+        draft: false
+        prerelease: false
+        generate_release_notes: true
+
+    # Trigger PyPI workflow when after we create a release.
+    # Pypi workflow won't with the usual on-release trigger
+    # because another workflow (this one) created the release. (avoiding inf recursion)
+    - name: Trigger PyPI workflow
+      if: steps.version-check.outputs.version_changed == 'true'
+      uses: peter-evans/repository-dispatch@v2
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        event-type: new-release-created
+        client-payload: '{"version": "${{ steps.version-check.outputs.current_version }}"}'

herogold-0.1.1/.github/example-workflows/test.yml

@@ -0,0 +1,40 @@
+name: Test
+
+on:
+  pull_request:
+    branches: [ master ]
+  workflow_dispatch:
+  workflow_call:
+
+concurrency: test-${{ github.sha }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: uv sync --group dev
+
+    - name: Run tests
+      run: uv run pytest .
+
+    - name: Run ruff check
+      run: uv run ruff check .
+
+    - name: Run type checking
+      run: uvx ty check . --ignore no-matching-overload

herogold-0.1.1/.github/workflows/pypi.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  repository_dispatch:
+    types: [new-release-created]
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        uv
+    - name: Build a binary wheel and a source tarball
+      run: uv build --sdist --wheel --out-dir dist
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  # publish-to-pypi:
+  #   name: Publish Python 🐍 distribution 📦 to PyPI
+  #   needs:
+  #   - build
+  #   runs-on: ubuntu-latest
+  #   environment:
+  #     name: pypi
+  #     url: https://pypi.org/p/HeroPy
+  #   permissions:
+  #     id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+  #   steps:
+  #   - name: Download all the dists
+  #     uses: actions/download-artifact@v4
+  #     with:
+  #       name: python-package-distributions
+  #       path: dist/
+  #   - name: Publish distribution 📦 to PyPI
+  #     uses: pypa/gh-action-pypi-publish@release/v1

herogold-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Auto-release
+
+on:
+  push:
+    branches: [ master ]
+  workflow_dispatch:
+
+jobs:
+  rel-test:
+    uses: ./.github/workflows/test.yml
+
+  new-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    needs: rel-test
+    outputs:
+      version_changed: ${{ steps.version-check.outputs.version_changed }}
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Needed to get all tags for version comparison
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.*"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Check if version changed
+      id: version-check
+      run: |
+        # Get current version from pyproject.toml
+        CURRENT_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+        echo "current_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+
+        # Check if this version already has a tag
+        if git tag --list | grep -q "^v$CURRENT_VERSION$"; then
+          echo "version_changed=false" >> $GITHUB_OUTPUT
+          echo "Version v$CURRENT_VERSION already exists as a tag"
+        else
+          echo "version_changed=true" >> $GITHUB_OUTPUT
+          echo "New version v$CURRENT_VERSION detected - will create release"
+        fi
+
+    - name: Create GitHub Release
+      if: steps.version-check.outputs.version_changed == 'true'
+      uses: softprops/action-gh-release@v2
+      with:
+        tag_name: v${{ steps.version-check.outputs.current_version }}
+        name: Release v${{ steps.version-check.outputs.current_version }}
+        draft: false
+        prerelease: false
+        generate_release_notes: true
+
+    # Trigger PyPI workflow when after we create a release.
+    # Pypi workflow won't with the usual on-release trigger
+    # because another workflow (this one) created the release. (avoiding inf recursion)
+    - name: Trigger PyPI workflow
+      if: steps.version-check.outputs.version_changed == 'true'
+      uses: peter-evans/repository-dispatch@v2
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        event-type: new-release-created
+        client-payload: '{"version": "${{ steps.version-check.outputs.current_version }}"}'

herogold-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test
+
+on:
+  pull_request:
+    branches: [ master ]
+  workflow_dispatch:
+  workflow_call:
+
+concurrency: test-${{ github.sha }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+    - name: Install dependencies
+      run: uv sync --all-extras
+
+    - name: Run ruff check
+      run: uvx ruff check .
+
+    # - name: Run type checking
+    #   run: uvx ty check . --ignore no-matching-overload
+
+    # - name: Run tests
+    #   run: uv run pytest .