Type Coverage Specification#

Estimated reading time: 45 minutes

Living document. This specification is maintained alongside the code, not archived behind it. From change 1 of §4 onward, .pre-commit-config.yaml, .github/workflows/ci-typing.yml and the [tool.mypy] block of pyproject.toml cite it by section — typing spec §3.2 and the like — so these sections carry the reasoning behind what those files do, and where the two ever diverge it is the specification that gets corrected. Read it as current; the roadmap states what has actually landed.

  • Date: 2026-10-06 (originated; maintained since)

  • Status: living design specification

  • Citation prefix: typing spec §… — not mypy spec, which would read as covering the tool rather than the coverage it is bought to provide

  • Scope: where geovista runs mypy, what it is allowed not to check yet, and the order in which that allowance is withdrawn; the strictness settings themselves stay as they are

  • Lineage: typing spec

  • Children: none

  • Published: in the specifications index, since change 1 of docs spec §4 took off the orphan: true it carried while nothing listed it

1. Purpose#

geovista has run mypy in strict mode since the configuration was written, and that check has never seen a third-party type. The pre-commit hook is mirrors-mypy, whose isolated virtual environment installs mypy and nothing else, so every import from pyvista, numpy, pyproj and the rest resolves to Any. A check against Any succeeds against anything.

The size of what it misses was measured on 2026-10-06, by running the same configuration inside the geovista pixi environment where the real types are present:

Errors

Distinct Source Lines

src/geovista excluding examples/

492

186, across 22 of 25 modules

src/geovista/examples/

150

142

total

642

328

The error count overstates the defect count. mypy reports an attribute access on a union once per member, and numpy.typing.ArrayLike is a seven-member union, so one line can raise seven errors. Counting distinct source lines instead, and setting aside the errors suppressed by §3.4, the work is 206 lines.

Three of the twenty-five library modules report nothing, and none of the three is much of a check: mypy reads __init__.pyi in place of __init__.py, _version.py is generated by setuptools-scm, and __main__.py is nineteen lines. The check that was supposed to be guarding the other twenty-two has been reporting success throughout.

2. Decisions#

  1. 🤝 Agreed (2026-10-06, @bjlittle, #2564) — The authoritative check runs against the locked environment, never a second copy of it. additional_dependencies on a mirrors-mypy hook would mean maintaining a list of geovista’s dependencies that pixi neither reads nor updates. That list demonstrably diverges: a probe carrying the eight typed core distributions saw 602 errors where the pixi environment saw 642, because the hook’s virtual environment has none of the optional dependencies that rasterio, h3, pandas and pyvistaqt are imported from. The divergence is silent and no test can detect it. See §3.1.

  2. 🤝 Agreed (2026-10-06, @bjlittle, #2564) — The hook goes live before the errors are fixed, not after. Twenty-two modules cannot be corrected in one reviewable change, and a check that stays blind until the last of them lands guards nothing in the meantime. A per-module ratchet makes the debt explicit and lets each module be retired on its own. See §3.2.

  3. 🤝 Agreed (2026-10-06, @bjlittle, #2564) — An annotation that over-promises is corrected by honouring it, not by narrowing it. to_cartesian(lons: ArrayLike, ...) reaches straight for lons.shape, so a caller who reads the signature and the docstring and passes a list gets AttributeError. Converting at the boundary makes the published contract true and cannot break an existing caller. See §3.3.

  4. 🤝 Agreed (2026-10-07, @bjlittle, #2567) — A defect a gallery script cannot fix is suppressed in the configuration, never worked around in the script. The gallery is rendered into the documentation and readers are invited to copy it, so a type: ignore comment in one is a directive published as example code. The suppression then has to name its real cause, or nobody will know when it can go. See §3.4.

3. Architecture#

3.1 Where the Check Runs#

The mirrors-mypy hook is replaced by a local hook that invokes the pixi environment’s own mypy:

ci:
  skip: [mypy]

- repo: local
  hooks:
    - id: mypy
      name: mypy
      entry: pixi run --frozen -e geovista mypy
      language: system
      pass_filenames: false
      types: [python]

--frozen resolves strictly from pixi.lock, so the hook checks against exactly the environment CI installs. Measured on 2026-10-06, this runs in 17 seconds against the 93 seconds the mirrors-mypy virtual environment took to build, and reports all 642 errors rather than 602.

pre-commit.ci has no pixi, so the hook is listed under ci.skip. The coverage it would have provided moves to .github/workflows/ci-typing.yml, which runs the identical command. This follows pyvista, which runs mypy as a dedicated workflow and carries no mypy hook at all; geovista keeps the hook as well, because this repository gates commits with hooks rather than deferring to CI.

All three existing [[tool.mypy.overrides]] blocks are kept, and one of the three is narrowed. Measured on 2026-10-06, removing all three raises the total from 642 to 648. disallow_untyped_decorators stays on geovista.cli unchanged: click ships py.typed, but main.command is an untyped decorator and three commands depend on it. The union-attr suppression on geovista.examples.grid.* is unchanged too; it predates this spec. disallow_subclassing_any is the one that narrows. It stays on geovista.qt, where pyvistaqt is absent from the locked environment altogether, so its three base classes are Any, but it is redundant for geovista.geoplotter and geovista.report, which report an identical 36 and 5 errors either way, so those two names come off its module list.

3.2 The Ratchet#

The twenty-two modules carrying errors are listed once with ignore_errors, alongside the gallery. With the library ignored and the §3.4 suppression applied, examples/ still reports 28 errors — 8 import-untyped and the 20 lines change 7 corrects — so geovista.examples.* joins the ratchet as a twenty-third entry and leaves with change 7.

[[tool.mypy.overrides]]
# typing spec §3.2 -- the ratchet. This list only ever shrinks, and
# "tests/test_typing_ratchet.py" holds it to that. Delete the whole
# block, and that test, when the last entry goes.
ignore_errors = true
module = [
  "geovista.bridge",
  "geovista.common",
  # the remaining twenty
  "geovista.examples.*",
]

From that point the check is live for every module added afterwards, the three that report nothing today having little in them to check. Each subsequent change deletes one entry and fixes what it exposes. Change 7 retired the last entry, the gallery, and with it the block and its test. The test’s guards on ci-typing.yml, the mypy hook and the top of [tool.mypy] moved to tests/test_ci_typing.py, beside one that refuses any override carrying ignore_errors, so the end state is held as firmly as the descent was.

A ratchet with nothing holding it becomes a dumping ground, so the list was mirrored in a test that permitted removals and refused additions:

RATCHET_BASELINE = frozenset({"geovista.bridge", "geovista.common", ...})


def test_ratchet_only_shrinks():
    added, retired = _drift(_ignored(), RATCHET_BASELINE)
    assert not added, f"added to the typing ratchet: {sorted(added)}"
    assert not retired, f"no longer ignored: {sorted(retired)} -- update the baseline"

The second assertion is what keeps the first one honest. A baseline that names are only ever checked against is a high-water mark, and it keeps the name a retirement took out: a later change can then put that module back under ignore_errors and the test still passes, handing back the coverage the retiring change won with nothing in the diff to catch it. Holding the two level costs a line per retirement, and makes re-entry an addition to a list documented as only ever shrinking, in front of a reviewer watching it grow.

The same reasoning governs how the test reads ci-typing.yml. The workflow matters only because pre-commit.ci skips mypy on the understanding that it runs there instead, so the test requires the hook’s entry to be the last command of a step carrying neither if nor continue-on-error. Searching the script for the command as a substring would accept echo-ing it, commenting it out, or appending || true. Requiring it last covers the job’s bash -l {0}, which drops the -e that GitHub’s default shell carries, so a command with anything after it can fail while the step succeeds.

This follows tests/test_python_support.py, which encodes a convention as a test rather than trusting it to review, and reads pyproject.toml as text so that it needs neither a built artefact nor a network.

3.3 The ArrayLike Contract#

295 of the 492 library errors, spread over 61 lines, are one idiom. A parameter is annotated ArrayLike, which is correct for a public boundary, and the body then treats it as an ndarray:

def to_cartesian(
    lons: ArrayLike,
    lats: ArrayLike,
    *,
    radius: float | None = None,
    # further keyword-only arguments elided
) -> np.ndarray:
    # 143 lines further on, with no conversion anywhere in between
    if lons.shape != lats.shape:
        msg = "'lons' and 'lats' do not have same shape."
        raise ValueError(msg)

ArrayLike admits str, bytes, complex and nested sequences, none of which carry .shape. The annotation and the docstring both say array_like; the implementation requires rather more, and a caller who believes them raises AttributeError at runtime today. The signature is not wrong about what the function should accept — the body is wrong about what it does accept.

The correction converts at the boundary:

lons, lats = np.asanyarray(lons), np.asanyarray(lats)

Docstrings are unchanged, because they already promise array_like. Behaviour widens only, so no existing caller can break, and np.asanyarray returns its argument unchanged when handed an array, so the hot paths are unaffected.

Those 61 lines sit in eight modules, and two of them hold most of it — transform.py has 20 and bridge.py 19, which is roughly two-thirds of each module’s errors. geodesic.py has 7, common.py 6, geoplotter.py 4, and pantry/meshes.py, search.py and pantry/data.py the remaining 5 between them. The roadmap of §4 is ordered to follow that concentration, so the idiom is established in the first two changes and applied by rote afterwards. Change 2 found, though, that only one of transform.py’s 20 lines needed the conversion.

The conversion narrows only where mypy can see numpy. A module that loads it lazily, with np = lazy.load("numpy"), hands mypy an Any, and assigning an Any never narrows an ArrayLike parameter, so the module must also import numpy under TYPE_CHECKING, as common.py does. Change 2 measured this on transform.py, which already converted with np.atleast_1d and still reported the idiom: importing numpy and pyproj that way cleared 15 of its 20 lines on its own. Four of the other five came from the return annotations of transform_points and combine, which promised ArrayLike for an ndarray, and the fifth was zlevel. core.py, crs.py, filters.py, geoplotter.py, gridlines.py, raster.py, pantry/data.py and pantry/meshes.py still load numpy without one.

The rule governs published signatures. Once change 2 had landed, the ArrayLike idiom was left on 13 of bridge.py’s lines. One conversion, at the top of Transform.from_points, cleared two of them along with a genuine AttributeError. The other eleven sat in private helpers that only ever receive what a boundary has converted, _verify_2d and the _contiguous nested in _as_contiguous_1d, so change 3 annotates them with the ndarray they receive. The API reference publishes no private members.

Change 4 found the idiom on eight of common.py’s lines, not the six counted above, all in two public functions and both real bugs. vectors_to_cartesian read .shape from points and vector components it never converted, so lists raised AttributeError, and nan_mask handed a list back unchanged where it promises an array. Both now convert at the boundary. nan_mask converts a list with np.ma.asanyarray, because np.asanyarray drops the mask of any masked array the list holds, and any function that handles masked data needs the same care.

Change 4 also met a pattern this rule does not cover: a runtime type check on an annotated parameter. mypy reports the check’s body unreachable, because the annotation says the check can never fail. The parameter is annotated instead with the type the function accepts before it validates, pv.DataSet for cast_UnstructuredGrid_to_PolyData, which keeps the check reachable without a type: ignore. That check was broken as well, and raised AttributeError where it meant TypeError.

The review of change 4 also found an annotation narrower than its docstring. wrap documents any NumPy data-type for dtype but was annotated np.dtype | None, so mypy refused np.float32 and "f4", and change 4 had altered the function’s default to fit that annotation. #2616 widened the annotation to DTypeLike instead, for the reason §5 gives against tightening a published contract to match an implementation. #2614 tracked it.

Change 5 found the idiom where mypy could not see it. geoplotter.py loaded numpy and pyproj with lazy.load and imported neither under TYPE_CHECKING, so both were Any and the module reported 15 lines where it had 16. _add_graticule_labels indexed GraticuleGrid.lonlat as an array, so a list raised TypeError, and multiplied its mask by REMESH_SEAM, which is −1, so a list mask became empty and raised ValueError; both now convert where they are used. npoints_by_idx converts its points too. BBox called it 259 times with lists that grow to tens of thousands of points, though, and converting them on every call made BBox ten times slower. BBox now indexes its own lists and calls npoints directly: a private caller on a hot path can step past a converting boundary instead of paying for it.

Change 6b met change 4’s runtime check twice more, in core.py. combine and slice_cells check for the pv.PolyData they were annotated to receive, so both now take a pv.DataSet. combine handed a single mesh back before its check, so combine(pv.ImageData(...)) returned an ImageData from a function annotated to return PolyData. It now raises TypeError, as it does for any other mesh it can’t combine. find_nearest_cell documents z as optional and zero by default, and accepted None, which VTK refused with TypeError on a projected mesh. None now means zero.

Change 6c applied the rule a third time: set_plot_theme checks for a Theme or a str at runtime, so it takes an object. It also met an annotation narrower than its behaviour, outside geovista: scooby.Report wraps a single package in a list at runtime, but is annotated for a list only, so geovista.Report, which promises either, wraps it itself.

3.5 Where geovista Departs From pyvista#

GeoPlotterBase is a mixin. GeoPlotter combines it with pyvista’s Plotter, and geovista.qt with pyvistaqt’s QtInteractor and BackgroundPlotter, both plotters too. It was also combined with pyvistaqt’s MultiPlotter, which is not, until GeoMultiPlotter was removed (#2622). mypy had no way to know any of that. So the mixin declared what it borrowed: Callable[..., None] for add_text, add_point_labels and reset_camera, Theme for theme, and for camera an annotation that isn’t a type (§3.4). Each one clashed with pyvista’s own definition. Change 5 gives the mixin pv.BasePlotter as its base under TYPE_CHECKING, and object at runtime. The declarations go, and so do the three type: ignore comments they needed.

What remains is deliberate. add_mesh and add_points take the mesh or the points positionally and everything else by keyword, where pyvista accepts a long run of positional arguments, and add_mesh adds nothing for an empty mesh and returns None. Matching pyvista would change geovista’s public API, so both def lines carry # type: ignore[override], citing this section. add_mesh, add_points, add_base_layer and add_coastlines, which return what add_mesh returns, are annotated pv.Actor | None. Change 5 removes three type: ignore comments from the library and adds these two, leaving nine.

Change 6c does the same for ThemeMixin, which the two geovista themes combine with pyvista’s Theme and DocumentTheme. It sets theme properties on self, so mypy declared them on the mixin, where they clashed with the theme’s, and couldn’t see self.font at all. With Theme as its base under TYPE_CHECKING, each theme has to list the mixin first, or its bases have no consistent order. That changes their MRO, which nothing reads but the slot gathering below, since the mixin adds only mixin_state. Five type: ignore comments go, leaving four in the library. The mixin also lacked __slots__, and pyvista gathers the slots of every class in a theme’s MRO to compare, convert or save it, so ==, to_dict and save raised AttributeError on both themes. It now declares that it has none, so the themes, like pyvista’s, refuse an attribute they don’t have, where a misspelt one was accepted silently.

4. Roadmap#

#

Scope

Lines

Status

1

The local hook, ci-typing.yml, the ratchet and its test

0

✅ landed (2026-10-06, #2565)

2

transform.py

29

✅ landed (2026-10-08, #2580)

3

bridge.py

28

✅ landed (2026-10-09, #2599)

4

common.py

20

✅ landed (2026-10-10, #2612)

5

geoplotter.py, geodesic.py

38

✅ landed (2026-10-11, #2619)

6a

The untyped imports, and cache, cli, config, geometry, qt

11

✅ landed (2026-10-11, #2631)

6b

core, search, filters, gridlines, crs

38

✅ landed (2026-10-21, #2676)

6c

pantry and its three modules, raster, report, themes

19

✅ landed (2026-10-21, #2680)

7

examples/, its ratchet entry, and the ratchet retired

20

✅ landed (2026-10-21, #2681)

8

The pyvista release carrying the fixes of §3.4 as the floor, and the override of §3.4 and the casts and typed locals waiting on it withdrawn

0

💡 candidate: the pyvista floor reaches 0.50.0

9

The lazy_loader override withdrawn

0

💡 candidate: lazy_loader ships py.typed, or the Python floor reaches 3.15

10

The cast in Transform.from_tiff withdrawn

0

💡 candidate: types-rasterio takes an array for the rows of rasterio.transform.xy

11

The override for the distributions that ship no annotations withdrawn

0

💡 candidate: one of them ships py.typed, or gains a stub package

12

The trigger tests of rows 8 to 11 hardened

0

📋 not started

        ---
config:
  theme: default
  darkMode: false
  themeVariables:
    fontSize: 12px
  flowchart:
    useMaxWidth: false
    padding: 6
    nodeSpacing: 25
    rankSpacing: 35
---
flowchart LR
  subgraph typing_spec["typing spec"]
    typing_spec_4_row_1["1"]
    typing_spec_4_row_2["2"]
    typing_spec_4_row_3["3"]
    typing_spec_4_row_4["4"]
    typing_spec_4_row_5["5"]
    typing_spec_4_row_6a["6a"]
    typing_spec_4_row_6b["6b"]
    typing_spec_4_row_6c["6c"]
    typing_spec_4_row_7["7"]
    typing_spec_4_row_8["8"]
    typing_spec_4_row_9["9"]
    typing_spec_4_row_10["10"]
    typing_spec_4_row_11["11"]
    typing_spec_4_row_12["12"]
  end
  classDef gv_landed fill:#eeeeee,stroke:#bbbbbb,color:#666666
  classDef gv_progress fill:#ffe8a3,stroke:#c99a00,color:#000000
  classDef gv_todo fill:#ffffff,stroke:#555555,color:#000000
  classDef gv_candidate fill:#ffffff,stroke:#999999,stroke-dasharray:4 3,color:#555555
  classDef gv_ready fill:#d9f2d9,stroke:#2e8b2e,stroke-width:3px,color:#000000
  classDef gv_landed_small fill:#eeeeee,stroke:#bbbbbb,color:#666666,font-size:11px
  classDef gv_progress_small fill:#ffe8a3,stroke:#c99a00,color:#000000,font-size:11px
  classDef gv_todo_small fill:#ffffff,stroke:#555555,color:#000000,font-size:11px
  classDef gv_candidate_small fill:#ffffff,stroke:#999999,stroke-dasharray:4 3,color:#555555,font-size:11px
  classDef gv_ready_small fill:#d9f2d9,stroke:#2e8b2e,stroke-width:3px,color:#000000,font-size:11px
  class typing_spec_4_row_1 gv_landed
  class typing_spec_4_row_2 gv_landed
  class typing_spec_4_row_3 gv_landed
  class typing_spec_4_row_4 gv_landed
  class typing_spec_4_row_5 gv_landed
  class typing_spec_4_row_6a gv_landed
  class typing_spec_4_row_6b gv_landed
  class typing_spec_4_row_6c gv_landed
  class typing_spec_4_row_7 gv_landed
  class typing_spec_4_row_8 gv_candidate
  class typing_spec_4_row_9 gv_candidate
  class typing_spec_4_row_10 gv_candidate
  class typing_spec_4_row_11 gv_candidate
  class typing_spec_4_row_12 gv_ready
  click typing_spec_4_row_1 href "#typing-spec-4-row-1" "1: The local hook, ci-typing.yml, the ratch…"
  click typing_spec_4_row_2 href "#typing-spec-4-row-2" "2: transform.py"
  click typing_spec_4_row_3 href "#typing-spec-4-row-3" "3: bridge.py"
  click typing_spec_4_row_4 href "#typing-spec-4-row-4" "4: common.py"
  click typing_spec_4_row_5 href "#typing-spec-4-row-5" "5: geoplotter.py, geodesic.py"
  click typing_spec_4_row_6a href "#typing-spec-4-row-6a" "6a: The untyped imports, and cache, cli, con…"
  click typing_spec_4_row_6b href "#typing-spec-4-row-6b" "6b: core, search, filters, gridlines, crs"
  click typing_spec_4_row_6c href "#typing-spec-4-row-6c" "6c: pantry and its three modules, raster, re…"
  click typing_spec_4_row_7 href "#typing-spec-4-row-7" "7: examples/, its ratchet entry, and the ra…"
  click typing_spec_4_row_8 href "#typing-spec-4-row-8" "8: The pyvista release carrying the fixes o…"
  click typing_spec_4_row_9 href "#typing-spec-4-row-9" "9: The lazy_loader override withdrawn"
  click typing_spec_4_row_10 href "#typing-spec-4-row-10" "10: The cast in Transform.from_tiff withdraw…"
  click typing_spec_4_row_11 href "#typing-spec-4-row-11" "11: The override for the distributions that…"
  click typing_spec_4_row_12 href "#typing-spec-4-row-12" "12: The trigger tests of rows 8 to 11 harden…"

    

Row 6, the seventeen library modules left in the ratchet, was split into three pull requests (@bjlittle, 2026-10-11). Its count of 51 does not reproduce. Lifted at the census commit, the seventeen report 71 lines, and on main before 6a, 53. Ten of them load numpy or pyvista lazily without importing it under TYPE_CHECKING (§3.3), and with those imports the 53 becomes 68. Each row counts the lines its change clears from that 68, so 6a’s 11 includes three untyped imports in pantry/data.py.

Rows 8 to 11 wait on releases upstream, so each is a candidate (items spec §2 decision 8), and the items of §8 they owe name them. tests/test_ci_typing.py asserts every trigger, failing with the row to land. Row 8 fires when the pyvista floor reaches 0.50.0, in requirements/pypi-core.txt or the pixi manifest. That is the next release from pyvista’s main, where pull requests 9162, 9262, 9344 and 9351 merged. 0.49.1 and 0.49.2 came from its 0.49 release branch, and carry none of them. The row withdraws the whole override of §3.4, including its no-untyped-call half, which waits on the annotations of Camera.zoom and has no item of its own. Row 9 reads the locked lazy_loader and requires-python, and row 10 the installed stubs. Item 5 waits on the floor, but the override only changes what mypy reports, and mypy runs against the lock, so a typed release in the lock is enough. Row 11 reads each distribution its override names. They gain annotations one at a time, so each name comes out in a pull request of its own, and the row lands with the last. Row 12 hardens those trigger tests themselves, and the items of §8 it owes name it.

Statuses follow docs spec §3.6: a landed row names the date and the pull request that landed it. This is a living document, so a change that measures something the design assumed edits the design in place, and the sentence that was there before survives nowhere else. Change 1 rewrote the entry count of §3.2 and the override claim of §3.1; the row is what makes #2565 reachable from the sections it corrected, so a reader who wants the measurement rather than the conclusion has somewhere to go.

Each change carries a towncrier fragment and the agentic label. Changes 2 to 4 alter published signatures and each adds tests exercising the widened input.

5. Alternatives Considered#

  • additional_dependencies on the mirrors-mypy hook. The route tephpy takes, and the one this work began with. Self-contained and runs unchanged on pre-commit.ci. It is rejected on the measurement in §2: the second dependency list is unlocked, hand-maintained, and already 40 errors adrift.

  • A CI job alone, with no hook. pyvista’s arrangement exactly. Rejected because this repository’s practice is that hooks gate commits, and a type error found only after pushing is found a cycle too late.

  • Narrowing the ArrayLike annotations instead of converting. A smaller change with no runtime effect. Rejected because it tightens a published contract to match an implementation shortfall, and leaves the documented array_like promise to be reworded across every affected docstring.

  • One change for all 206 lines. Atomic, with no interim configuration. Rejected as a 25-file review spanning public signatures, internals and gallery scripts, where a problem in any one module blocks the rest.

6. Testing#

tests/test_typing_ratchet.py held the ratchet to §3.2, failing when a module was added to the ignore list and passing when one was removed. Change 7 deleted it with the last entry, and tests/test_ci_typing.py now fails if any override ignores a module’s errors, and keeps that test’s guards on ci-typing.yml and the mypy hook. It also fails on a # mypy: comment anywhere in the package, and on any per-module relaxation of strict mode beyond the three this specification gives reasons for: geovista.cli’s and geovista.qt’s in §3.1, and the gallery’s in §3.4. Adding, changing or withdrawing one is then a change to the test (#2687). The same module asserts the triggers of rows 8 to 11 of §4, reading the floors in the manifests and the distributions installed, and fails when one fires.

Changes 2 to 4 of the roadmap each add tests passing lists where arrays were passed before, so that the widened contract of §3.3 is exercised rather than merely annotated.

The check itself is verified by ci-typing.yml, which fails the pull request on any error.

7. Scope#

Out of scope:

  • The strictness settings. strict, warn_unreachable and the three enable_error_code entries stay as they are. This work makes the existing settings effective; it does not add to them.

  • tests/ and docs/. files names src/geovista alone, and widening it is a separate decision with its own error budget.

  • Chasing the pyvista fix into a release. The call-arg defect is already reported and already fixed on main, as are the missing Camera.zoom annotations, so what remains is a version floor, tracked by #2568. It does not gate any of the roadmap.

  • The untyped imports. 32 errors are imports rather than code: 29 import-untyped from distributions that ship no annotations — lazy_loader alone accounts for 19, then geopy, rasterio and shapely 2 each, and one each from click_default_group, fastparquet, pandas and pooch — plus 3 import-not-found. The gallery adds cmocean, cartopy and h3 on top, which is why the figure here is smaller than a count taken over the whole tree. Two of the three not-found, geovistaconfig and geovista.siteconfig, are the optional site configuration and are meant to be absent, so they want a targeted ignore_missing_imports rather than a fix. The configuration carries none for them yet. Change 2 cleared lazy_loader’s 19 early, with the override of §8 item 5, because the first module to leave the ratchet imports it. Change 3 cleared rasterio’s 2 with typeshed’s types-rasterio, not an override: rasterio ships no py.typed, but typeshed has carried stubs for it since June 2026, and against them from_tiff reported eleven lines of its own. conda-forge also carries types-shapely, pandas-stubs and types-click-default-group, and nothing for geopy or pooch. Change 6a took the three stub packages into the devs feature, and they revealed two errors in geometry.py. pooch, geopy and fastparquet ship no annotations and have no stubs, so one override covers them until they do (§8 item 9). The two site configurations share a second with pyvistaqt, which ships py.typed but is in no locked environment (#2630).

8. Open Items#

Each carries the grammar of items spec §3.2.

  1. 🏁 Resolved (2026-10-06, #2568 and #2569 · 🔎 2026-10-06, #2564) — Are the §3.4 defects reported upstream? This item asserted that neither was, and raising the issues to track them showed both halves of that wrong. One defect was reported in 2024 and has been fixed on pyvista main since September 2026. The other is not upstream at all. Each now has its own trigger and its own issue, below.

  2. ❓ Open (🔎 2026-10-07, #2567 · 🎯 row 8 of §4 · 🎫 #2568) — The call-arg suppression will outlive its cause. pyvista pull request 9162 fixes it, and the pin in pyproject.toml is >=0.48.0,<0.50.0, so what matters is the floor rather than the ceiling. Withdraw that half of the override when the floor reaches the release carrying the fix.

  3. 🏁 Resolved (2026-10-11, #2619 · 🔎 2026-10-07, #2567) — The attr-defined suppression hid a bug of ours. It is labelled upstream in pyproject.toml, and the cause is one annotation in geoplotter.py, described in §3.4. Until it is corrected, 45 errors in the gallery sit under a comment that sends the next reader to the wrong repository. This item and §3.4 first blamed lazy.load, on the theory that mypy could not see a base class loaded at runtime, and so did #2569 as first written. Checking that premise on 2026-10-07, before taking item 4 upstream, disproved it. geoplotter.py imports pyvista under TYPE_CHECKING as well, which is what mypy reads, and the 77 call-arg errors of item 2 are raised on methods GeoPlotter inherits, which could not happen if its base were unresolved. The unbound type in the message, pv.Plotter.camera?, is the annotation’s own text. The same check found that §3.4 had been showing a one-line paraphrase of the override’s comment while saying it quoted it; it now quotes pyproject.toml verbatim. Change 5 removed the annotation and swapped attr-defined for no-untyped-call in the override, whose comment now names its real causes.

  4. 🏁 Resolved (2026-10-07, lazy-loader issue 181 · 🔎 2026-10-06, #2564) — Whether to pursue lazy_loader upstream. Yes, after measuring. It is 19 of the 29 untyped imports, one for each of the 20 library modules that import it except __init__.py, which mypy reads through __init__.pyi instead. With a typed copy on mypy_path and the library checked under --strict, a bare py.typed marker turns those 19 into 42 no-untyped-call, one at every lazy.load, the way Camera.zoom behaves in §3.4. The marker together with annotations on load and attach and a return type on attach_stub clears all 19 and leaves every other error unchanged, line for line, so the request asks for both and offers a follow-up pull request. A maintainer’s advice there, in its issue 165, is to keep using lazy_loader until Python 3.15 is the floor and then move to the lazy import of PEP 810. This item argued until 2026-10-07 that it was also the root of item 3; it is not, which left the import count as the whole case.

  5. ❓ Open (🔎 2026-10-07, #2572 · 🎯 row 9 of §4 · 🎫 #2570) — The lazy_loader override comes out when upstream allows. The ignore_missing_imports override for lazy_loader clears all 19 locally. It was meant for change 6, and change 2 brought it in, because transform.py imports lazy_loader, as most library modules do, and could not leave the ratchet without it. It comes out when the floor reaches a release carrying the marker, or when PEP 810 replaces lazy_loader, whichever is first.

  6. ❓ Open (🔎 2026-10-08, #2580 · 🎯 row 8 of §4 · 🎫 #2851) — The cast in transform_mesh, and a typed local in core.py, wait on the same pyvista release. pyvista 0.49 annotates pyvista_ndarray.__setitem__ with key: int | NumpyArray[int], which refuses the tuple index of mesh.points[:, 0] that it accepts at runtime, so change 2 sets the points through a typing.cast. The annotation refuses a slice key in the same way, so change 6b types the ids that _keep_roles assigns through one as any array. pyvista pull request 9262 widens the key, merged on 2026-09-23 after 0.49.0, so the cast and the local come out with the floor that carries it, the trigger item 2 already waits on.

  7. ❓ Open (🔎 2026-10-09, #2599 · 🎯 row 10 of §4 · 🎫 #2601) — The cast in from_tiff waits on typeshed. types-rasterio types the rows and columns of rasterio.transform.xy as int | Sequence[int]. rasterio takes arrays, which is what Transform.from_tiff passes, so change 3 passes them through a typing.cast. It comes out when the stubs accept arrays. The report to typeshed covers two other gaps as well, which the code handles without a cast.

  8. ❓ Open (🔎 2026-10-11, #2619 · 🎯 row 8 of §4 · 🎫 #2852) — Ten typed locals wait on the same pyvista release. pyvista 0.49 leaves GPUInfo.__init__, GPUInfo.get_info, Texture.__init__, Texture.to_image, Theme.__init__ and PolyData.append_polydata unannotated, and its _Wrapped decorator, item 2’s cause, breaks self.reset_camera(render=False). So _warn_opacity and view_poi call GPUInfo and reset_camera through locals annotated Callable. Change 6a added a third, for p.add_axes() in the plot command of cli.py, and change 6c six more: two in Report, two in wrap_texture and one in each theme’s __init__. Change 7 added the last, in the gallery: uber_h3.py binds what append_polydata returns to a local annotated PolyData, an ordinary line for an example, not a Callable. pyvista main fixes every defect, and the locals come out with the floor that carries them, the trigger items 2 and 6 already wait on. main types to_image as returning ImageData | None, so the local in wrap_texture already allows None.

  9. ❓ Open (🔎 2026-10-11, #2631 · 🎯 row 11 of §4 · 🎫 #2629) — Five dependencies ship no annotations. The latest releases of pooch (1.9.0), geopy (2.5.0), cartopy (0.26.0), cmocean (4.0.3) and h3 (4.5.0) carry no py.typed and have no stubs on conda-forge or in typeshed, so one ignore_missing_imports override makes each import Any. Change 6c brought the entries for geopy and fastparquet to life by taking pantry/data.py out of the ratchet, and change 7 added the last three, which only the gallery imports. fastparquet came out when the earthquakes sample moved to pyarrow (#2783), which pantry/data.py finds with find_spec and never imports, as pyarrow ships no annotations either. Each name comes out when its distribution or a stub package types it. pooch, cartopy, cmocean and h3 have open upstream issues asking for annotations; cmocean’s offers a stub file for its colormaps, which would not lift the override without a py.typed marker.

  10. ❓ Open (🔎 2026-10-21, #2676 · 🎯 row 8 of §4 · 🎫 #2853) — Four typed locals wait on the same pyvista release. pyvista 0.49 types its arrays with Python’s int, bool and float as the dtype. numpy.float64 subclasses float, so a float array passes into pyvista, but numpy.intp and numpy.bool subclass neither int nor bool, so extract_cells refuses every real mask or index array. For the same reason, numpy’s own methods refuse arrays that pyvista hands back: += on a mesh’s faces, and min on a cell’s points. Change 6b types the two masks in filters.remesh, the faces in core.combine and the points in core.slice_cells as any array. pyvista pull requests 9344 and 9351 replace the annotations. Both merged on 2026-09-29, after the 0.49 release branch was cut on 2026-09-07, so 0.49.1 doesn’t carry them, and the locals come out with the floor that does, the trigger items 2, 6 and 8 wait on.

  11. ❓ Open (🔎 2026-11-03, #2850 · 🎯 row 12 of §4 · 🎫 #2860) — Row 8 reads only some of the pixi tables. _pyvista_floors in tests/test_ci_typing.py reads the floor from requirements/pypi-core.txt, [tool.pixi.dependencies], and each feature’s dependencies and pypi-dependencies, but not from a top-level [tool.pixi.pypi-dependencies] or a target table. A pyvista floor raised in one of those would not fire row 8. Neither table exists yet.

  12. ❓ Open (🔎 2026-11-03, #2850 · 🎯 row 12 of §4 · 🎫 #2861) — A py.typed below a package’s root counts as typed. _typed counts a marker anywhere beneath a module, such as a vendored subpackage’s, but mypy honours only the one at the package root. Rows 9 and 11 would fire early rather than miss a release, so the cost is a false alarm.

  13. ❓ Open (🔎 2026-11-03, #2850 · 🎯 row 12 of §4 · 🎫 #2862) — Nothing prompts row 8 when the release it waits on arrives. Row 8 fires when the pyvista floor reaches 0.50.0, and the floor rises only when someone raises it, so nothing says when 0.50.0 ships and the lock picks it up. Items 2, 6, 8 and 10 wait on the floor by design, but a check that reports, without failing, when the locked pyvista reaches 0.50.0 could prompt the floor’s rise.

9. References#

10. Verification#

Each row follows ledger spec §3.4.

Decision

Status

Evidence

§2 decision 1

✅ verified (2026-11-01, #2796)

tests/test_ci_typing.py

§2 decision 2

✍️ signed off (2026-11-01, @bjlittle, #2796)

Checked in review that the hook and its ratchet went live in row 1 of §4 (#2565), before any module was corrected, and that row 7 retired the ratchet (#2681).

§2 decision 3

✅ verified (2026-11-01, #2796)

tests/bridge/test_lists.py

§2 decision 4

✅ verified (2026-11-01, #2796)

tests/test_ci_typing.py

✅ 3 · ✍️ 1 · ⏳ 0 · 🗄️ 0: 4 of 4 decisions in force verified