pyiv 0.3.0__tar.gz

pyiv-0.3.0/.cursor/rules/packaging-docs.mdc

@@ -0,0 +1,27 @@
+---
+description: PyPI metadata, install claims, changelog format, and GitHub release copy must match README and the docs site.
+globs: pyproject.toml,RELEASE.md,CHANGELOG.md,LICENSE,.github/workflows/release.yml,.github/workflows/version-bump.yml
+alwaysApply: false
+---
+
+# Packaging copy
+
+`[project]` in `pyproject.toml` is the PyPI sidebar. Keep it real:
+
+- Author and URLs must not be `Your Name` / `yourusername`.
+- `Documentation` = `https://rl337.org/pyiv/`
+- Homepage / Repository / Issues = `https://github.com/rl337/pyiv` (and `/issues`)
+- `Changelog` = `https://rl337.org/pyiv/changelog.html`
+- Description should match the README one-liner (Guice-style DI, not factory-first)
+
+Install commands in `RELEASE.md`, release workflow text, and GitHub Release bodies must match README: `pip install pyiv` (and `pip install pyiv==<version>` on a tagged release). Unreleased `main` may use the git URL. Do not mention Poetry. PyPI is final `X.Y.Z` only.
+
+## Changelog
+
+`CHANGELOG.md` is the source of truth (GitHub, PyPI URL, Sphinx `docs/changelog.rst`). Keep a Changelog layout:
+
+- New user-facing work goes under `## Unreleased`. Do not invent `X.Y.Z` in a PR; versions are auto-bumped on `main`.
+- After that bump is on `main`, move Unreleased bullets to `## X.Y.Z - YYYY-MM-DD`.
+- User-facing only (Added / Changed / Deprecated / Removed / Fixed / Security). No “fix typo in comment,” no squash-commit dumps.
+- One set of bullets GitHub Releases can reuse. Same install command as README.
+- The docs homepage and `project.urls` Changelog must keep pointing at the site page.

pyiv-0.3.0/.cursor/rules/pydoc-doctest.mdc

@@ -0,0 +1,17 @@
+---
+description: Runnable doctests in pyiv module and class docstrings; they are the API docs source of truth.
+globs: pyiv/**/*.py
+alwaysApply: false
+---
+
+# Doctests in pyiv
+
+Public module and class docstrings are compiled into the Sphinx site and executed by `pytest --doctest-modules`.
+
+- Examples must be self-contained: define every name the snippet uses.
+- Do not hit the network, sleep for real time, or write files in the repo cwd. Use in-memory doubles (`MemoryFilesystem`, `SyntheticClock`, `MemoryConsole`) or invalid-input `Traceback` examples.
+- Inject `Set[T]` / `List[T]` through a host class constructor, not `injector.inject(Set[T])`.
+- Unregistered **concrete** classes are instantiated; Optional-none examples need an ABC (or a type the injector cannot build).
+- Expected output containing a newline must use `\\n` in the docstring (otherwise doctest sees a real line break).
+- Do not use `# doctest: +SKIP`. If a method is a variant of another API, put one
+  self-contained example on the primary method and point the other at it in prose.

pyiv-0.3.0/.cursor/rules/website.mdc

@@ -0,0 +1,19 @@
+---
+description: README vs Sphinx split, install story, homepage features, and RTD sidebar.
+globs: docs/**/*.rst,docs/**/*.md,docs/conf.py,README.md
+alwaysApply: false
+---
+
+# Website and README
+
+README is the GitHub **and** PyPI long description: what pyiv is, honest install, short quick start, link to https://rl337.org/pyiv/. Do not duplicate the API reference.
+
+**docs/** is the product site. Key Features: type-based injection, scopes, keys/binder, reflection, test doubles, zero dependencies. Do not headline Factory.
+
+Install must match README and release notes: `pip install pyiv`. Unreleased `main` may use `pip install git+https://github.com/rl337/pyiv.git`. No Poetry.
+
+API nav: grouped `toctree`s on `docs/index.rst` (User guide, Core DI, Bindings, Discovery, Test doubles, Integrations). User guide pages live in `docs/guide/` with human titles. Keep `collapse_navigation: False` and `titles_only: True`. Omit `binder_impl`. New public modules need `docs/pyiv/pyiv.<name>.rst` and a toctree entry.
+
+Production is https://rl337.org/pyiv/ from `main`. PR previews are `/branch/<branch>/` only.
+
+If a changelog page exists, link it from the site (homepage + Reference toctree) and from `project.urls`. `CHANGELOG.md` is the source of truth; `docs/changelog.rst` includes it.

pyiv-0.3.0/.cursor/skills/maintain-docs/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: maintain-docs
+description: Keep pyiv's PyPI listing, Sphinx site, and release notes in sync. Use when editing README.md, docs/, pyproject.toml metadata or URLs, CHANGELOG, GitHub releases, install instructions, Key Features, public APIs, or doctests; when adding modules to the API nav; or when the user mentions the website, PyPI, documentation, or changelog.
+---
+
+# Maintain pyiv docs
+
+Three public surfaces must agree. Docstrings feed the site; they are not a fourth landing page.
+
+| Pillar | Files | Job |
+| --- | --- | --- |
+| PyPI listing | `README.md`, `[project]` in `pyproject.toml` | README is GitHub **and** Warehouse long_description. Metadata (author, URLs, description) is the sidebar. Not a second API manual. |
+| Website | `docs/`, `pyiv/**/*.py` docstrings | Product manual at https://rl337.org/pyiv/. Features, install, guide, autodoc. Production is `main` only; PRs go to `/branch/<name>/`. |
+| Release notes | `CHANGELOG.md`, GitHub Releases, `RELEASE.md`, `.github/workflows/release.yml` | Why this version shipped. Same install command as README. Not a squash-commit dump. |
+
+## Install story (must match all three)
+
+- Install: `pip install pyiv`
+- Docs + PyPI: https://rl337.org/pyiv/ and https://pypi.org/project/pyiv/
+- Unreleased `main`: `pip install git+https://github.com/rl337/pyiv.git`
+- Do not mention Poetry.
+- PyPI is production `X.Y.Z` only (no RCs or nightlies). First public version is **0.3.0**.
+
+Canonical URLs (also `[project.urls]`): Homepage/Repository `https://github.com/rl337/pyiv`, Documentation `https://rl337.org/pyiv/`, Changelog `https://rl337.org/pyiv/changelog.html`. No `yourusername` placeholders.
+
+## After a public API change
+
+1. Runnable module doctest (self-contained; no network, real sleeps, or cwd writes).
+2. New public module: `docs/pyiv/pyiv.<module>.rst` **and** the matching toctree on `docs/index.rst`. Omit `binder_impl`.
+3. Homepage Key Features stay: type injection, scopes, keys/binder, reflection, test doubles, zero deps. Not Factory-first.
+4. If the change is user-visible, add a bullet under `## Unreleased` in `CHANGELOG.md` (do not invent a version). GitHub Releases reuse those bullets.
+5. `pytest --doctest-modules pyiv` and `sphinx-build -b html docs docs/_build/html`.
+
+## Sidebar UX
+
+RTD only expands nested toctrees from the current page. Grouped `.. toctree::` directives live on `docs/index.rst` (User guide in `docs/guide/`, then API groups). Keep `collapse_navigation: False` and `titles_only: True` in `docs/conf.py`.

pyiv-0.3.0/.dockerignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Git
+.git/
+.gitignore
+
+# Documentation
+*.md
+!README.md
+
+# CI/CD
+.github/
+
+# Other
+.DS_Store
+*.log
+

pyiv-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+    branches: [main, master, develop]
+  workflow_dispatch:
+
+jobs:
+  validation:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-${{ matrix.python-version }}-
+            ${{ runner.os }}-pip-
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build hatchling
+
+      - name: Install project dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,docs]" || pip install -e .
+          # Pin versions for consistency across Python versions
+          # black 25.x requires Python 3.9+, use 24.8.0 for Python 3.8 compatibility
+          # isort 7.0.0 may not be available, use 5.13.2 for compatibility
+          # mypy 1.8+ requires Python 3.9+, use 1.7.1 for Python 3.8 compatibility
+          if python -c "import sys; exit(0 if sys.version_info >= (3, 9) else 1)"; then
+            pip install pytest pytest-cov black==25.11.0 isort==5.13.2 mypy bandit
+          else
+            pip install pytest pytest-cov black==24.8.0 isort==5.13.2 "mypy<1.8" bandit
+          fi
+
+      - name: Run validation checks
+        run: |
+          if [ -f "run_checks.sh" ]; then
+            chmod +x run_checks.sh
+            ./run_checks.sh
+          else
+            echo "No run_checks.sh found, running basic checks..."
+            pytest --cov=pyiv --cov-report=xml --cov-report=html --cov-report=term-missing
+            black --check pyiv/ tests/ || true
+            isort --check-only pyiv/ tests/ || true
+            mypy pyiv/ || true
+            bandit -r pyiv/ -f json -o bandit-report.json || true
+          fi
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./build/coverage.xml
+          flags: pyiv
+          name: codecov-pyiv-${{ matrix.python-version }}
+          fail_ci_if_error: false
+
+      - name: Upload bandit security report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bandit-security-report-${{ matrix.python-version }}
+          path: build/bandit-report.json
+          if-no-files-found: ignore
+
+      - name: Upload coverage HTML report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html-report-${{ matrix.python-version }}
+          path: build/htmlcov/
+          if-no-files-found: ignore
+
+      - name: Build distribution packages
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build --sdist --wheel
+          twine check dist/*
+          echo "✓ Distribution packages built successfully"
+

pyiv-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,227 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - "pyiv/**"
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    branches: [main, master]
+    paths:
+      - "pyiv/**"
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# One site tree (production root + /branch/<name>/ previews). Serialize deploys
+# so a PR cannot clobber main and two previews cannot race on gh-pages.
+concurrency:
+  group: documentation-site
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+  pull-requests: write
+
+env:
+  PREVIEW_DIR: branch
+  SITE_URL: https://rl337.org/pyiv
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Fork PRs cannot push gh-pages or deploy Pages.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        if: github.event.action != 'closed'
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Cache pip packages
+        if: github.event.action != 'closed'
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-3.12-docs-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-3.12-docs-
+            ${{ runner.os }}-pip-3.12-
+
+      - name: Install documentation dependencies
+        if: github.event.action != 'closed'
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Build documentation with Sphinx
+        if: github.event.action != 'closed'
+        run: sphinx-build -b html docs docs/_build/html
+
+      - name: Upload Sphinx artifact
+        if: github.event.action != 'closed'
+        uses: actions/upload-artifact@v4
+        with:
+          name: pyiv-documentation
+          path: docs/_build/html
+          if-no-files-found: error
+
+      - name: Checkout published site tree
+        continue-on-error: true
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: published
+
+      - name: Assemble production root and branch previews
+        id: preview
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          EVENT_ACTION: ${{ github.event.action }}
+          GIT_REF: ${{ github.ref }}
+          HEAD_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          set -euo pipefail
+          mkdir -p published
+          rm -rf published/.git
+
+          python3 <<'PY'
+          import os, re, shutil
+          from pathlib import Path
+
+          published = Path("published")
+          published.mkdir(exist_ok=True)
+          preview_root = published / os.environ["PREVIEW_DIR"]
+          sphinx = Path("docs/_build/html")
+          event = os.environ["EVENT_NAME"]
+          action = os.environ.get("EVENT_ACTION") or ""
+          git_ref = os.environ["GIT_REF"]
+          head_ref = os.environ["HEAD_REF"]
+          parts = [
+              re.sub(r"[^A-Za-z0-9._-]", "-", p)
+              for p in head_ref.split("/")
+              if p not in ("", ".", "..")
+          ]
+          safe = "/".join(parts) or "unnamed"
+          is_prod = git_ref in ("refs/heads/main", "refs/heads/master") and event != "pull_request"
+          preview_url = f"{os.environ['SITE_URL']}/{os.environ['PREVIEW_DIR']}/{safe}/"
+
+          def copy_tree(src: Path, dest: Path) -> None:
+              dest.mkdir(parents=True, exist_ok=True)
+              for item in src.iterdir():
+                  target = dest / item.name
+                  if item.is_dir():
+                      shutil.copytree(item, target, dirs_exist_ok=True)
+                  else:
+                      shutil.copy2(item, target)
+
+          if event == "pull_request" and action == "closed":
+              shutil.rmtree(preview_root / safe, ignore_errors=True)
+          elif is_prod:
+              saved = Path("/tmp/pyiv-preview-branch")
+              if preview_root.exists():
+                  if saved.exists():
+                      shutil.rmtree(saved)
+                  shutil.copytree(preview_root, saved)
+              for child in list(published.iterdir()):
+                  if child.name == os.environ["PREVIEW_DIR"]:
+                      continue
+                  if child.is_dir():
+                      shutil.rmtree(child)
+                  else:
+                      child.unlink()
+              copy_tree(sphinx, published)
+              if saved.exists():
+                  if preview_root.exists():
+                      shutil.rmtree(preview_root)
+                  shutil.copytree(saved, preview_root)
+          else:
+              dest = preview_root / safe
+              if dest.exists():
+                  shutil.rmtree(dest)
+              copy_tree(sphinx, dest)
+
+          (published / ".nojekyll").write_text("")
+          github_output = Path(os.environ["GITHUB_OUTPUT"])
+          with github_output.open("a") as fh:
+              fh.write(f"safe={safe}\n")
+              fh.write(f"url={preview_url}\n")
+              fh.write(f"is_prod={'true' if is_prod else 'false'}\n")
+              fh.write(f"has_root={'true' if (published / 'index.html').is_file() else 'false'}\n")
+          PY
+
+      - name: Publish site tree to gh-pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: published
+          branch: gh-pages
+          clean: true
+
+      - name: Setup Pages
+        if: steps.preview.outputs.has_root == 'true'
+        uses: actions/configure-pages@v4
+
+      - name: Upload Pages artifact
+        if: steps.preview.outputs.has_root == 'true'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: published
+
+      - name: Deploy to GitHub Pages
+        if: steps.preview.outputs.has_root == 'true'
+        id: deployment
+        uses: actions/deploy-pages@v4
+        with:
+          artifact_name: github-pages
+
+      - name: Comment preview URL on the pull request
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        env:
+          PREVIEW_URL: ${{ steps.preview.outputs.url }}
+          HAS_ROOT: ${{ steps.preview.outputs.has_root }}
+          CLOSED: ${{ github.event.action == 'closed' }}
+        with:
+          script: |
+            const marker = '<!-- pyiv-docs-preview -->';
+            const closed = process.env.CLOSED === 'true';
+            const live = process.env.HAS_ROOT === 'true';
+            const url = process.env.PREVIEW_URL;
+            let body;
+            if (closed) {
+              body = `${marker}\nPreview removed from the docs site. Production is unchanged at ${process.env.SITE_URL}/.`;
+            } else if (live) {
+              body = `${marker}\nDocs preview: ${url}\n\nProduction stays at ${process.env.SITE_URL}/ (main only). This preview updates on each push.`;
+            } else {
+              body = `${marker}\nDocs preview will be at ${url} after the next **main** deploy (the production tree is not on \`gh-pages\` yet, so this PR will not publish over the live homepage).`;
+            }
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find(c => c.body && c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }

pyiv-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,143 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types:
+      - completed
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+    inputs:
+      publish_target:
+        description: "Upload destination. none = GitHub Release only (if untagged)."
+        required: true
+        default: none
+        type: choice
+        options:
+          - none
+          - testpypi
+          - pypi
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'workflow_run' &&
+       github.event.workflow_run.conclusion == 'success' &&
+       (github.event.workflow_run.head_branch == 'main' ||
+        github.event.workflow_run.head_branch == 'master'))
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build hatchling twine
+
+      - name: Read version from pyproject.toml
+        id: version
+        run: |
+          VERSION=$(grep -E '^version = ' pyproject.toml | sed -E "s/^version = [\"'](.*)[\"']/\1/")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Version: $VERSION"
+
+      - name: Build and check
+        run: |
+          python -m build --sdist --wheel
+          twine check dist/*
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Tag if missing
+        id: tag
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git fetch origin --tags
+          if git rev-parse "v${VERSION}" >/dev/null 2>&1; then
+            echo "created=false" >> "$GITHUB_OUTPUT"
+            echo "Tag v${VERSION} already exists"
+          else
+            git tag -a "v${VERSION}" -m "Release v${VERSION}"
+            git push origin "v${VERSION}"
+            echo "created=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: GitHub Release
+        if: steps.tag.outputs.created == 'true'
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: v${{ steps.version.outputs.version }}
+          name: Release v${{ steps.version.outputs.version }}
+          body: |
+            ## Installation
+            ```bash
+            pip install pyiv==${{ steps.version.outputs.version }}
+            ```
+            Changelog: https://rl337.org/pyiv/changelog.html
+          files: dist/*
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: package
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.publish_target != 'none'
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to TestPyPI
+        if: github.event.inputs.publish_target == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+          attestations: false
+
+      - name: Smoke-install from TestPyPI
+        if: github.event.inputs.publish_target == 'testpypi'
+        run: |
+          python -m pip install --upgrade pip
+          pip install -i https://test.pypi.org/simple/ --no-deps "pyiv==${{ needs.package.outputs.version }}"
+          python -c "import pyiv; assert pyiv.__version__ == '${{ needs.package.outputs.version }}'"
+
+      - name: Publish to PyPI
+        if: github.event.inputs.publish_target == 'pypi'
+        uses: pypa/gh-action-pypi-publish@release/v1