improcv 0.1.0a1__tar.gz

improcv-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,265 @@
+name: release
+
+# Triggered only by pushing a tag matching v* (e.g. v0.1.0a1). test.yml also
+# reacts to the same tag push independently -- this workflow does not rely on
+# that parallel run to gate publishing; it re-runs the full test matrix itself
+# (via a reusable workflow call to test.yml) and adds its own release-specific
+# checks (tag/version/HEAD verification, exact-artifact build+install+smoke
+# test) before anything is uploaded or published.
+
+on:
+  push:
+    tags: ["v*"]
+
+# Deny-by-default at the workflow level; each job below grants only the
+# scope it actually needs. In particular, only the two publish jobs get
+# `id-token: write` (required for PyPI Trusted Publishing) -- the job that
+# builds and verifies the artifact never receives OIDC credentials.
+permissions: {}
+
+# Two tags pushed close together must not publish concurrently, and an
+# in-progress release must never be cancelled by a later trigger (which could
+# leave TestPyPI and PyPI in different states, or abort mid-publish).
+#
+# `queue: max` (GitHub Actions concurrency, shipped 2026-05-07) lets up to 100
+# runs wait in this group instead of the `queue: single` default, which only
+# holds one pending run and cancels/replaces it if another arrives -- so a
+# third tag pushed while a second is still queued behind a running first
+# would otherwise never run at all. Verified directly against GitHub's own
+# "Using concurrency" docs (fetched 2026-07-23): `queue` accepts `single`
+# (default) or `max` (up to 100 pending). NOTE: `actionlint` v1.7.12 (current
+# latest release as of this writing) does not yet recognize the `queue` key
+# and will report `unexpected key "queue" for "concurrency" section` --
+# this is a known, tracked actionlint gap (rhysd/actionlint#654, #657, #661,
+# all open), not evidence that the key is invalid. Confirmed via GitHub's
+# current documentation, which is authoritative here over a linter that
+# hasn't caught up yet.
+concurrency:
+  group: release
+  queue: max
+  cancel-in-progress: false
+
+jobs:
+  check-tag:
+    name: Verify tag matches origin/main HEAD and pyproject.toml version
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout full history
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Verify the tag points at origin/main's current HEAD
+        # Comparing the tag's version to pyproject.toml alone is not enough:
+        # 0.1.0a1 has been the version string for many commits, so an old
+        # commit would also pass a version-only check. Requiring an exact
+        # match against origin/main's current HEAD (not "is an ancestor of
+        # main") ensures the release is always cut from the actual latest
+        # reviewed state of the default branch.
+        run: |
+          git fetch origin main --quiet
+          tag_commit="$(git rev-parse "${GITHUB_SHA}^{commit}")"
+          main_commit="$(git rev-parse origin/main)"
+          if [ "$tag_commit" != "$main_commit" ]; then
+            echo "::error::Tag commit ($tag_commit) does not match origin/main HEAD ($main_commit). Refusing to release from a commit that is not main's current HEAD."
+            exit 1
+          fi
+          echo "Tag commit matches origin/main HEAD: $main_commit"
+
+      - name: Verify the tag matches pyproject.toml's version exactly (PEP 440)
+        run: python3 scripts/verify_release_version.py
+
+  test-matrix:
+    name: Full Python/OpenCV test matrix (reused from test.yml)
+    needs: check-tag
+    permissions:
+      contents: read
+    uses: ./.github/workflows/test.yml
+
+  build-and-verify:
+    name: Build and verify the exact artifacts to be published
+    needs: test-matrix
+    runs-on: ubuntu-latest
+    # No id-token permission here on purpose: this job builds and smoke-tests
+    # the artifact but never publishes, so it never needs OIDC credentials.
+    permissions:
+      contents: read
+    env:
+      MPLBACKEND: "Agg"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.31"
+          python-version: "3.11"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Verify dist/ contains exactly one wheel and one sdist
+        run: |
+          shopt -s nullglob
+          wheels=(dist/*.whl)
+          sdists=(dist/*.tar.gz)
+          echo "wheels: ${#wheels[@]}, sdists: ${#sdists[@]}"
+          ls -la dist/
+          if [ "${#wheels[@]}" -ne 1 ] || [ "${#sdists[@]}" -ne 1 ]; then
+            echo "::error::Expected exactly one wheel and one sdist in dist/, found ${#wheels[@]} wheel(s) and ${#sdists[@]} sdist(s)."
+            exit 1
+          fi
+
+      - name: Check package metadata and description rendering (pinned Twine)
+        run: uvx "twine==6.2.0" check dist/*
+
+      - name: Install the wheel into a clean environment (no extras) and smoke-test
+        # uv venv/uv pip --python pin the interpreter explicitly: setup-uv's
+        # own python-version input sets UV_PYTHON for uv's *own* commands,
+        # but does not guarantee a plain `python`/`python3` on PATH resolves
+        # to that same interpreter.
+        run: |
+          uv venv --python 3.11 /tmp/smoke-wheel
+          uv pip install --python /tmp/smoke-wheel/bin/python dist/*.whl "opencv-python-headless>=4.9,<6"
+          /tmp/smoke-wheel/bin/python -c "
+          import os
+          import sys
+
+          import numpy as np
+          import improcv as im
+
+          expected_version = os.environ['GITHUB_REF_NAME']
+          if expected_version.startswith('v'):
+              expected_version = expected_version[1:]
+          assert im.__version__ == expected_version, (im.__version__, expected_version)
+
+          image = np.zeros((20, 20, 3), dtype=np.uint8)
+          result = im.resize(image, width=10)
+          assert result.shape == (10, 10, 3), result.shape
+          assert 'matplotlib' not in sys.modules, 'import improcv must never import matplotlib'
+          print('smoke test OK (wheel, no extras):', im.__version__, result.shape)
+          "
+
+      - name: Verify improcv.visualization fails clearly without the viz extra (wheel)
+        run: |
+          /tmp/smoke-wheel/bin/python -c "
+          try:
+              import improcv.visualization
+              raise SystemExit('expected ImportError, none was raised')
+          except ImportError as exc:
+              assert 'improcv[viz]' in str(exc), str(exc)
+              print('smoke test OK: clear ImportError without the viz extra (wheel)')
+          "
+
+      - name: Install the wheel with the viz extra into a separate clean environment and smoke-test
+        run: |
+          uv venv --python 3.11 /tmp/smoke-wheel-viz
+          uv pip install --python /tmp/smoke-wheel-viz/bin/python "$(echo dist/*.whl)[viz]" "opencv-python-headless>=4.9,<6"
+          /tmp/smoke-wheel-viz/bin/python -c "
+          import os
+
+          import numpy as np
+          import improcv as im
+          import improcv.visualization as viz
+
+          expected_version = os.environ['GITHUB_REF_NAME']
+          if expected_version.startswith('v'):
+              expected_version = expected_version[1:]
+          assert im.__version__ == expected_version, (im.__version__, expected_version)
+
+          image = np.zeros((20, 20, 3), dtype=np.uint8)
+          viz.show_image(image)
+          viz.plot_histogram(image)
+          print('smoke test OK: show_image and plot_histogram both ran under Agg (wheel+viz)', im.__version__)
+          "
+
+      - name: Install the sdist into a separate clean environment and smoke-test
+        run: |
+          uv venv --python 3.11 /tmp/smoke-sdist
+          uv pip install --python /tmp/smoke-sdist/bin/python dist/*.tar.gz "opencv-python-headless>=4.9,<6"
+          /tmp/smoke-sdist/bin/python -c "
+          import os
+
+          import numpy as np
+          import improcv as im
+
+          expected_version = os.environ['GITHUB_REF_NAME']
+          if expected_version.startswith('v'):
+              expected_version = expected_version[1:]
+          assert im.__version__ == expected_version, (im.__version__, expected_version)
+
+          image = np.zeros((20, 20, 3), dtype=np.uint8)
+          result = im.resize(image, width=10)
+          assert result.shape == (10, 10, 3), result.shape
+          print('smoke test OK (sdist):', im.__version__, result.shape)
+          "
+
+      - name: Upload the verified dist/ as the release artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-dist
+          path: dist/
+          # Short, but long enough to survive the manual TestPyPI
+          # verification + `pypi` environment approval step in between
+          # publish-testpypi and publish-pypi -- 1 day was too tight if that
+          # approval doesn't happen immediately.
+          retention-days: 7
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build-and-verify
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download the verified release artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist/
+          # TestPyPI-only: lets a re-run after a partial upload or a
+          # transient TestPyPI outage succeed safely instead of erroring on
+          # a version that's already (partially) there. Deliberately not
+          # set on publish-pypi below -- a duplicate there should still
+          # fail loudly.
+          skip-existing: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    # Order is TestPyPI -> PyPI: the real-PyPI job only starts after the
+    # TestPyPI publish (the dry run of the mechanism itself) has succeeded.
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    # Production PyPI stays behind the `pypi` GitHub Environment, which
+    # should be configured with a required reviewer (see the design doc's
+    # manual-steps section) -- this job pauses for manual approval before
+    # running.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download the verified release artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        with:
+          packages-dir: dist/

improcv-0.1.0a1/.github/workflows/test.yml

@@ -0,0 +1,240 @@
+name: test
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*"]
+  pull_request:
+    branches: ["main"]
+  # Lets release.yml invoke this workflow's own `test`/`lowest-deps` matrix as
+  # part of the release pipeline, so a release can't be published without the
+  # full test matrix passing inside that same run -- rather than only relying
+  # on this workflow's own independent, parallel run against the same tag
+  # push, whose failure would not block publishing.
+  workflow_call:
+
+# Deny-by-default beyond read access to repo contents: standalone runs of
+# this workflow (push/pull_request) only ever need to check out the code,
+# and the reusable-workflow-call path from release.yml explicitly caps this
+# further via its own `permissions: contents: read` on the calling job.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        opencv: ["4", "5"]
+        include:
+          - opencv: "4"
+            opencv-spec: "opencv-python-headless>=4.9,<5"
+          - opencv: "5"
+            opencv-spec: "opencv-python-headless>=5,<6"
+    env:
+      OMP_NUM_THREADS: "1"
+      OPENBLAS_NUM_THREADS: "1"
+      MKL_NUM_THREADS: "1"
+      MPLBACKEND: "Agg"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.31"
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Install pinned OpenCV major version (${{ matrix.opencv }}.x)
+        run: uv pip install "${{ matrix.opencv-spec }}"
+
+      # --no-sync everywhere below: plain `uv run` re-syncs the environment
+      # against pyproject/uv.lock first, which would silently reinstall the
+      # locked (latest, 5.x) opencv-python-headless and undo the pinned
+      # override above — verified this actually happens before adding
+      # --no-sync, it's not a hypothetical concern.
+      - name: Lint
+        run: uv run --no-sync ruff check .
+
+      - name: Check formatting
+        run: uv run --no-sync ruff format --check .
+
+      - name: Type check
+        run: uv run --no-sync pyright
+
+      - name: Test
+        run: uv run --no-sync pytest
+
+  # Representative, non-Linux platform coverage (brief §8 requires "at least
+  # representative Windows and macOS configurations") -- deliberately just
+  # one job per platform, not the full Python x OpenCV matrix duplicated
+  # twice more: the goal is catching platform-specific problems (path
+  # handling, OpenCV wheel behavior, thread-library differences), not
+  # tripling CI runtime. Each of the two platforms takes one end of the
+  # supported Python range and the opposite OpenCV major line from the
+  # other, so between them all four "extremes" (oldest/newest Python,
+  # both OpenCV lines) get at least one non-Linux run. Verified directly
+  # (PyPI file listing for the latest opencv-python-headless release on
+  # both the 4.x and 5.x lines) that both ship `cp37-abi3` wheels for
+  # `win_amd64` and both `macosx_*_arm64`/`macosx_*_x86_64` -- so wheel
+  # availability isn't a constraint on either platform or Python choice.
+  # No lint/type-check here: both are platform-independent by nature and
+  # already covered above -- only `pytest` runs, which is the check that
+  # can actually differ by platform.
+  test-windows:
+    name: Representative test (windows-latest, Python 3.11, OpenCV 4.x)
+    runs-on: windows-latest
+    env:
+      MPLBACKEND: "Agg"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.31"
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Install pinned OpenCV major version (4.x)
+        run: uv pip install "opencv-python-headless>=4.9,<5"
+
+      - name: Test
+        run: uv run --no-sync pytest
+
+  test-macos:
+    name: Representative test (macos-latest, Python 3.14, OpenCV 5.x)
+    runs-on: macos-latest
+    env:
+      MPLBACKEND: "Agg"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.31"
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Install pinned OpenCV major version (5.x)
+        run: uv pip install "opencv-python-headless>=5,<6"
+
+      - name: Test
+        run: uv run --no-sync pytest
+
+  lowest-deps:
+    # Everything above always resolves via uv.lock, which picks the
+    # newest version satisfying each constraint — so numpy>=1.24,
+    # opencv-python>=4.9, and matplotlib>=3.8 in pyproject.toml were never
+    # actually tested at those floors. This job pins the exact declared
+    # minimums (on the oldest supported Python, since numpy 1.24 has no
+    # wheels for 3.12+) to catch a floor that's declared but doesn't
+    # actually work.
+    runs-on: ubuntu-latest
+    env:
+      MPLBACKEND: "Agg"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.31"
+          python-version: "3.11"
+
+      - name: Create a venv and install the declared minimum versions
+        # Exact floors, not `.*` wildcards: `numpy==1.24.*`/`matplotlib==3.8.*`
+        # resolve to the newest patch on that branch, not the actual declared
+        # minimum -- verified this job was never really testing 1.24.0/3.8.0.
+        # pytest is pinned to the version currently locked in uv.lock so this
+        # release-critical job doesn't depend on an arbitrary future pytest.
+        run: |
+          uv venv --python 3.11
+          uv pip install "numpy==1.24.0" "opencv-python-headless==4.9.0.80" "matplotlib==3.8.0" "pytest==9.1.1"
+          uv pip install -e . --no-deps
+
+      - name: Test against the lowest declared dependency versions
+        run: uv run --no-sync pytest
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.31"
+          python-version: "3.11"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check package metadata and description rendering
+        run: uvx "twine==6.2.0" check dist/*
+
+      - name: Install the built wheel into a clean environment (no viz extra)
+        # uv venv/uv pip --python pin the interpreter explicitly: setup-uv's
+        # own python-version input sets UV_PYTHON for uv's *own* commands,
+        # but does not guarantee a plain `python`/`python3` on PATH resolves
+        # to that same interpreter.
+        run: |
+          uv venv --python 3.11 /tmp/smoke-env
+          uv pip install --python /tmp/smoke-env/bin/python dist/*.whl "opencv-python-headless>=4.9,<6"
+
+      - name: Smoke-test the installed wheel (not the source tree)
+        run: |
+          cd /tmp
+          /tmp/smoke-env/bin/python -c "
+          import sys
+
+          import numpy as np
+          import improcv as im
+
+          image = np.zeros((20, 20, 3), dtype=np.uint8)
+          result = im.resize(image, width=10)
+          assert result.shape == (10, 10, 3), result.shape
+          assert 'matplotlib' not in sys.modules, 'import improcv must never import matplotlib'
+          print('smoke test OK:', im.__name__, result.shape)
+          "
+
+      - name: Smoke-test that improcv.visualization fails clearly without the viz extra
+        run: |
+          cd /tmp
+          /tmp/smoke-env/bin/python -c "
+          try:
+              import improcv.visualization
+              raise SystemExit('expected ImportError, none was raised')
+          except ImportError as exc:
+              assert 'improcv[viz]' in str(exc), str(exc)
+              print('smoke test OK: clear ImportError without the viz extra')
+          "
+
+      - name: Install the built wheel with the viz extra into a separate clean environment
+        run: |
+          uv venv --python 3.11 /tmp/smoke-env-viz
+          uv pip install --python /tmp/smoke-env-viz/bin/python "$(echo dist/*.whl)[viz]" "opencv-python-headless>=4.9,<6"
+
+      - name: Smoke-test improcv.visualization with the viz extra installed
+        env:
+          MPLBACKEND: "Agg"
+        run: |
+          cd /tmp
+          /tmp/smoke-env-viz/bin/python -c "
+          import numpy as np
+          import improcv.visualization as viz
+
+          image = np.zeros((20, 20, 3), dtype=np.uint8)
+          ax = viz.show_image(image)
+          ax2 = viz.plot_histogram(image)
+          print('smoke test OK: show_image and plot_histogram both ran under Agg')
+          "

improcv-0.1.0a1/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# Private planning/working docs — internal agreements and process notes,
+# not meant to be visible in the public repo. Public docs (once we have
+# them) live elsewhere under docs/, so only this subfolder is ignored.
+CLAUDE.md
+IMPROCV_PROJECT_BRIEF.md
+.claude/
+docs/superpowers/