Merge remote-tracking branch 'origin/main' into cv_remove_py3.9

Author: clintval

.github/workflows/publish_fgpyo.yml

@@ -94,7 +94,7 @@ jobs:
           ref: ${{ github.ref_name }}
 
       - name: Generate a Changelog
-        uses: orhun/git-cliff-action@v3
+        uses: orhun/git-cliff-action@v4
         id: git-cliff
         with:
           config: pyproject.toml

.github/workflows/tests.yml

@@ -1,4 +1,4 @@
-name: test
+name: Static Analysis, Unit Tests, and Documentation
 
 on:
   push:
@@ -8,6 +8,9 @@ on:
       - "!**"
   workflow_call:
 
+env:
+  UV_VERSION: 0.8.22
+
 
 permissions:
   pull-requests: write
@@ -19,58 +22,31 @@ jobs:
       matrix:
         PYTHON_VERSION: ["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: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8  # v5.0.0
 
-      - name: Get full Python version
-        id: full-python-version
-        run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")
-      
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
-
-      - name: Set up cache
-        uses: actions/cache@v4
-        id: cache
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba  # v6.3.1
         with:
-          path: .venv
-          key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/uv.lock') }}
-
-      - name: Ensure cache is healthy
-        if: steps.cache.outputs.cache-hit == 'true'
-        run: uv run pip --version >/dev/null 2>&1 || rm -rf .venv
-
-      - name: Check that the lock file is up to date
-        run: uv lock --check
+          version: "${{ env.UV_VERSION }}"
+          python-version: "${{ matrix.PYTHON_VERSION }}"
+          enable-cache: 'true'
+          cache-suffix: "${{ matrix.PYTHON_VERSION }}"
 
       - name: Install dependencies
-        run: uv sync  --no-install-project
-
-      - name: Install project
-        run: uv pip install --group dev --group docs
-
-      - name: Style checking
-        run: uv run ruff format --check fgpyo tests
-
-      - name: Run lint
-        run: uv run ruff check fgpyo tests
-
-      - name: Run mypy
-        run: uv run mypy fgpyo tests --config=pyproject.toml
+        run: |
+          uv sync --locked
 
-      - name: Run pytest
-        run: uv run pytest --cov=fgpyo --cov-report=xml --cov-branch 
+      - name: Test the library
+        run: |
+          uv run poe check-all
 
       - name: Run docs
         run: |
           set -euo pipefail
-          uv run mkdocs build --strict
+          uv run poe build-docs
 
       - name: Upload code coverage
-        uses: codecov/codecov-action@v4.5.0
+        uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7  # v5.5.1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/wheels.yml

@@ -1,35 +1,40 @@
-name: build wheels
+name: Build Wheels
 
 on:
   pull_request:
   workflow_call:
   workflow_dispatch:
 
+env:
+  UV_VERSION: 0.8.22
+
 jobs:
   build-wheels:
-    name: Build wheels for ${{ matrix.python }}
+    name: Build wheels for ${{ matrix.PYTHON_VERSION }}
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ["3.10", "3.11", "3.12", "3.13"]
+        PYTHON_VERSION: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8  # v5.0.0
 
-      - name: Set up Python ${{ matrix.python }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python }}
-      
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba  # v6.3.1
+        with:
+          version: "${{ env.UV_VERSION }}"
+          python-version: "${{ matrix.PYTHON_VERSION }}"
+          enable-cache: 'true'
+          cache-suffix: "${{ matrix.PYTHON_VERSION }}"
 
       - name: Build wheels
-        run: uv build --wheel -o wheelhouse
+        run: |
+          uv build --wheel -o wheelhouse
 
       - name: Upload wheels
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
         with:
-          name: fgpyo-wheels-${{ matrix.python }}
+          name: fgpyo-wheels-${{ matrix.PYTHON_VERSION }}
           path: ./wheelhouse/fgpyo*.whl
           if-no-files-found: error

ci/check.sh

@@ -1,58 +1,13 @@
 #!/usr/bin/env bash
 
-function banner() {
-    echo
-    echo "================================================================================"
-    echo -e "$*"
-    echo "================================================================================"
-    echo
-}
-
-#####################################################################
-# Takes two parameters, a "name" and a "command".
-# Runs the command and prints out whether it succeeded or failed, and
-# also tracks a list of failed steps in $failures.
-#####################################################################
-function run() {
-    local name=$1
-    local cmd=$2
-
-    banner "Running $name [$cmd]"
-    set +e
-    $cmd
-    exit_code=$?
-    set -e
-
-    if [[ $exit_code == 0 ]]; then
-        echo Passed "$name": "[$cmd]"
-    else
-        echo Failed "$name": "[$cmd]"
-        if [ -z "$failures" ]; then
-            failures="$failures $name"
-        else
-            failures="$failures, $name"
-        fi
-    fi
-}
-
 # Require uv
 if [ ! -x "$(command -v uv)" ]; then
     echo >&2 "Error: 'uv' not found."
     echo >&2 "Install via https://docs.astral.sh/uv/getting-started/installation/"
     exit 1
 fi
 
-run "Checking lockfile"    "uv lock --check"
-run "Updating environment" "uv sync --locked"
-run "Style Checking"       "uv run ruff format fgpyo tests"
-run "Linting"              "uv run ruff check --fix fgpyo tests"
-run "Type Checking"        "uv run mypy fgpyo tests --config pyproject.toml"
-run "Unit Tests"           "uv run pytest -vv -r sx tests"
-run "Make docs"            "uv run mkdocs build --strict"
+set -euo pipefail
 
-if [ -z "$failures" ]; then
-    banner "Checks Passed"
-else
-    banner "Checks Failed with failures in: $failures"
-    exit 1
-fi
+uv run poe fix-and-check-all
+uv run poe build-docs

docs/scripts/strip_doctest_flags.py

@@ -0,0 +1,25 @@
+"""MkDocs hook to strip doctest flags from rendered documentation.
+
+Doctest flags like `# doctest: +SKIP` are useful for controlling doctest execution,
+but they clutter the documentation. This hook removes them from the rendered HTML.
+"""
+
+import re
+from typing import Any
+
+# Pattern to match doctest flags like: # doctest: +SKIP, # doctest: +ELLIPSIS, etc.
+# Also handles multiple flags like: # doctest: +SKIP, +ELLIPSIS
+DOCTEST_FLAG_PATTERN = re.compile(r"\s*#\s*doctest:\s*[+\w,\s]+")
+
+
+def on_page_content(html: str, **kwargs: Any) -> str:
+    """Remove doctest flags from page content.
+
+    Args:
+        html: The rendered HTML content of the page.
+        **kwargs: Additional keyword arguments passed by MkDocs.
+
+    Returns:
+        The HTML content with doctest flags removed.
+    """
+    return DOCTEST_FLAG_PATTERN.sub("", html)

fgpyo/collections/__init__.py

@@ -17,6 +17,7 @@
 True
 >>> is_sorted([1, 2, 4, 3])
 False
+
 ```
 
 ## Examples of a "Peekable" Iterator
@@ -34,7 +35,10 @@
 >>> from fgpyo.collections import PeekableIterator
 >>> piter = PeekableIterator(iter([]))
 >>> piter.peek()
+Traceback (most recent call last):
+    ...
 StopIteration
+
 ```
 
 A peekable iterator will return the next item before consuming it.
@@ -47,6 +51,7 @@
 1
 >>> [j for j in piter]
 [2, 3]
+
 ```
 
 The [`can_peek()`][fgpyo.collections.PeekableIterator.can_peek] function can be used to determine if
@@ -63,7 +68,10 @@
 >>> piter.peek() if piter.can_peek() else -1
 -1
 >>> next(piter)
+Traceback (most recent call last):
+    ...
 StopIteration
+
 ```
 
 [`PeekableIterator`][fgpyo.collections.PeekableIterator]'s constructor supports creation from

fgpyo/fasta/builder.py

@@ -9,31 +9,39 @@
 Writing a FASTA with two contigs each with 100 bases:
 
 ```python
-    >>> from fgpyo.fasta.builder import FastaBuilder
-    >>> builder = FastaBuilder()
-    >>> builder.add("chr10").add("AAAAAAAAAA", 10)
-    >>> builder.add("chr11").add("GGGGGGGGGG", 10)
-    >>> builder.to_file(path = pathlib.Path("test.fasta"))
+>>> from pathlib import Path
+>>> from fgpyo.fasta.builder import FastaBuilder
+>>> builder = FastaBuilder()
+>>> builder.add("chr10").add("AAAAAAAAAA", 10)  # doctest: +ELLIPSIS
+<fgpyo.fasta.builder.ContigBuilder object at ...>
+>>> builder = builder.add("chr11").add("GGGGGGGGGG", 10)
+>>> fasta_path = Path(getfixture("tmp_path")) / "test.fasta"
+>>> builder.to_file(path=fasta_path)  # doctest: +SKIP
+
 ```
 
 Writing a FASTA with one contig with 100 A's and 50 T's:
 
 ```python
-    >>> from fgpyo.fasta.builder import FastaBuilder
-    >>> builder = FastaBuilder()
-    >>> builder.add("chr10").add("AAAAAAAAAA", 10).add("TTTTTTTTTT", 5)
-    >>> builder.to_file(path = pathlib.Path("test.fasta"))
+>>> from fgpyo.fasta.builder import FastaBuilder
+>>> builder = FastaBuilder()
+>>> builder.add("chr10").add("AAAAAAAAAA", 10).add("TTTTTTTTTT", 5)  # doctest: +ELLIPSIS
+<fgpyo.fasta.builder.ContigBuilder object at ...>
+>>> builder.to_file(path=fasta_path)  # doctest: +SKIP
+
 ```
 
 Add bases to existing contig:
 
 ```python
-    >>> from fgpyo.fasta.builder import FastaBuilder
-    >>> builder = FastaBuilder()
-    >>> contig_one = builder.add("chr10").add("AAAAAAAAAA", 1)
-    >>> contig_one.add("NNN", 1)
-    >>> contig_one.bases
-    'AAAAAAAAAANNN'
+>>> from fgpyo.fasta.builder import FastaBuilder
+>>> builder = FastaBuilder()
+>>> contig_one = builder.add("chr10").add("AAAAAAAAAA", 1)
+>>> contig_one.add("NNN", 1)  # doctest: +ELLIPSIS
+<fgpyo.fasta.builder.ContigBuilder object at ...>
+>>> contig_one.bases
+'AAAAAAAAAANNN'
+
 ```
 
 """