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.ymland the[tool.mypy]block ofpyproject.tomlcite it by section —typing spec §3.2and 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 §…— notmypy spec, which would read as covering the tool rather than the coverage it is bought to provideScope: where
geovistarunsmypy, what it is allowed not to check yet, and the order in which that allowance is withdrawn; the strictness settings themselves stay as they areLineage: typing spec
Children: none
Published: in the specifications index, since change 1 of docs spec §4 took off the
orphan: trueit 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 |
|
|---|---|---|
|
492 |
186, across 22 of 25 modules |
|
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#
🤝 Agreed (2026-10-06, @bjlittle, #2564) — The authoritative check runs against the locked environment, never a second copy of it.
additional_dependencieson amirrors-mypyhook would mean maintaining a list ofgeovista’s dependencies thatpixineither 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 thatrasterio,h3,pandasandpyvistaqtare imported from. The divergence is silent and no test can detect it. See §3.1.🤝 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.
🤝 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 forlons.shape, so a caller who reads the signature and the docstring and passes a list getsAttributeError. Converting at the boundary makes the published contract true and cannot break an existing caller. See §3.3.🤝 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: ignorecomment 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.4 Gallery Suppressions#
122 of the 150 errors in examples/ are two defects, measured on 2026-10-06 against
pyvista 0.49.0 with the override below lifted. Their causes differ, and this section got
the second one wrong twice before it was measured; §8 records both
corrections:
77 ×
call-arg, Missing positional argument “self” in call to “call” of “_Wrapped”, raised on no-argument calls such asp.view_xy().pyvista’s_Wrappeddecorator loses the descriptor protocol in its annotations. This one is upstream. It ispyvistaissue 6589, open since 2024, and is fixed onmainbypyvistapull request 9162, merged the day after 0.49.0 was released. Checked against a clone of thatmain, the count is 0. Tracked by #2568.45 ×
attr-defined, pv.Plotter.camera? has no attribute “zoom”, 44 of them onzoomand one onroll. This one is ours, and it is one line.GeoPlotterBase.view_poideclaresself.camera: pv.Plotter.camera, naming a property where a type belongs.mypycannot bind it, so the attribute keeps the unbound type it prints aspv.Plotter.camera?, and sinceGeoPlotterBaseprecedespv.PlotteramongGeoPlotter’s bases, that declaration shadowspyvista’s owncameraand every access through it fails.geoplotter.pyis in the ratchet, so the annotation is never reported where it is written, only where it does damage. Change 5 removed the declaration (§3.5). All 45 cleared, and 44no-untyped-calltook their place, becauseCamera.zoomhas no annotations in 0.49.0. That residue is upstream, andpyvistamainalready annotates it. Tracked by #2569.
Both are disabled for the gallery alone, which leaves its genuine errors visible, 35 of them after change 5:
[[tool.mypy.overrides]]
# typing spec §3.4 -- two "pyvista" 0.49 defects, both fixed on its "main":
# "_Wrapped" loses the descriptor protocol, and "Camera.zoom" carries no
# annotations. Confined to the gallery, whose scripts are published as
# example code, so a "type: ignore" comment in one is a directive a reader
# is invited to copy. Withdraw when the "pyvista" floor carries both fixes.
disable_error_code = ["call-arg", "no-untyped-call"]
module = ["geovista.examples.*"]
The comment is quoted as it stands in pyproject.toml, because a specification that
quotes the code has to quote what the code says. Both codes now name upstream defects
fixed on pyvista main, so the override goes when the floor reaches the release that
carries them (#2568). Change 5 also adds seven errors in uber_h3.py, which keeps
the plotter’s actors in fields typed str | PolyData. They appeared once add_mesh
admitted it can return None, and change 7 corrects them with the rest of the gallery.
It did, by letting uber_h3.py’s asset type hold an actor or None. Change 7 also found
that _Wrapped reports arg-type, not call-arg, when a call passes its first argument
positionally, so the two gallery calls that did now pass it by keyword, which the override
already covers. And the union-attr override on geovista.examples.grid.*, which blamed
geopy, was hiding four reads of an optional point of interest, so it went too.
In the library, measured on 2026-10-11 with the whole ratchet lifted, attr-defined is
zero, call-arg is one, in cli.py, and no-untyped-call is four, in raster.py and
themes.py, all in modules change 6 retires, so the suppression stays confined to where
the plotting calls are. Change 6c met those four, and two more that report.py’s pyvista
import revealed, with typed locals (§8 item 8).
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 |
0 |
✅ landed (2026-10-06, #2565) |
2 |
|
29 |
✅ landed (2026-10-08, #2580) |
3 |
|
28 |
✅ landed (2026-10-09, #2599) |
4 |
|
20 |
✅ landed (2026-10-10, #2612) |
5 |
|
38 |
✅ landed (2026-10-11, #2619) |
6a |
The untyped imports, and |
11 |
✅ landed (2026-10-11, #2631) |
6b |
|
38 |
✅ landed (2026-10-21, #2676) |
6c |
|
19 |
✅ landed (2026-10-21, #2680) |
7 |
|
20 |
✅ landed (2026-10-21, #2681) |
8 |
The |
0 |
💡 candidate: the |
9 |
The |
0 |
💡 candidate: |
10 |
The cast in |
0 |
💡 candidate: |
11 |
The override for the distributions that ship no annotations withdrawn |
0 |
💡 candidate: one of them ships |
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…"
Key
---
config:
theme: default
darkMode: false
themeVariables:
fontSize: 12px
flowchart:
useMaxWidth: false
padding: 6
nodeSpacing: 15
rankSpacing: 20
---
flowchart LR
subgraph key_states[" "]
direction TB
key_landed["landed"]
key_progress["in progress"]
key_todo["not started"]
key_candidate["candidate"]
key_ready["ready to start"]
key_landed ~~~ key_progress ~~~ key_todo ~~~ key_candidate ~~~ key_ready
end
subgraph key_relations[" "]
direction LR
key_after_1["1"] -->|"after"| key_after_2["2"]
key_before_1["1"] -->|"before"| key_before_2["2"]
key_with_1["1"] <==>|"with"| key_with_2["2"]
key_or_1["1"] -.->|"with or after"| key_or_2["2"]
end
key_states ~~~ key_relations
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
style key_states fill:none,stroke:none
style key_relations fill:none,stroke:none
class key_landed gv_landed
class key_progress gv_progress
class key_todo gv_todo
class key_candidate gv_candidate
class key_ready gv_ready
class key_after_1,key_after_2,key_before_1,key_before_2,key_with_1,key_with_2,key_or_1,key_or_2 gv_todo
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_dependencieson themirrors-mypyhook. The routetephpytakes, and the one this work began with. Self-contained and runs unchanged onpre-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
ArrayLikeannotations 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 documentedarray_likepromise 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_unreachableand the threeenable_error_codeentries stay as they are. This work makes the existing settings effective; it does not add to them.tests/anddocs/.filesnamessrc/geovistaalone, and widening it is a separate decision with its own error budget.Chasing the
pyvistafix into a release. Thecall-argdefect is already reported and already fixed onmain, as are the missingCamera.zoomannotations, 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-untypedfrom distributions that ship no annotations —lazy_loaderalone accounts for 19, thengeopy,rasterioandshapely2 each, and one each fromclick_default_group,fastparquet,pandasandpooch— plus 3import-not-found. The gallery addscmocean,cartopyandh3on top, which is why the figure here is smaller than a count taken over the whole tree. Two of the three not-found,geovistaconfigandgeovista.siteconfig, are the optional site configuration and are meant to be absent, so they want a targetedignore_missing_importsrather than a fix. The configuration carries none for them yet. Change 2 clearedlazy_loader’s 19 early, with the override of §8 item 5, because the first module to leave the ratchet imports it. Change 3 clearedrasterio’s 2 with typeshed’stypes-rasterio, not an override:rasterioships nopy.typed, but typeshed has carried stubs for it since June 2026, and against themfrom_tiffreported eleven lines of its own. conda-forge also carriestypes-shapely,pandas-stubsandtypes-click-default-group, and nothing forgeopyorpooch. Change 6a took the three stub packages into thedevsfeature, and they revealed two errors ingeometry.py.pooch,geopyandfastparquetship no annotations and have no stubs, so one override covers them until they do (§8 item 9). The two site configurations share a second withpyvistaqt, which shipspy.typedbut is in no locked environment (#2630).
8. Open Items#
Each carries the grammar of items spec §3.2.
🏁 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
pyvistamainsince September 2026. The other is not upstream at all. Each now has its own trigger and its own issue, below.❓ Open (🔎 2026-10-07, #2567 · 🎯 row 8 of §4 · 🎫 #2568) — The
call-argsuppression will outlive its cause.pyvistapull request 9162 fixes it, and the pin inpyproject.tomlis>=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.🏁 Resolved (2026-10-11, #2619 · 🔎 2026-10-07, #2567) — The
attr-definedsuppression hid a bug of ours. It is labelled upstream inpyproject.toml, and the cause is one annotation ingeoplotter.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 blamedlazy.load, on the theory thatmypycould 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.pyimportspyvistaunderTYPE_CHECKINGas well, which is whatmypyreads, and the 77call-argerrors of item 2 are raised on methodsGeoPlotterinherits, 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 quotespyproject.tomlverbatim. Change 5 removed the annotation and swappedattr-definedforno-untyped-callin the override, whose comment now names its real causes.🏁 Resolved (2026-10-07,
lazy-loaderissue 181 · 🔎 2026-10-06, #2564) — Whether to pursuelazy_loaderupstream. 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, whichmypyreads through__init__.pyiinstead. With a typed copy onmypy_pathand the library checked under--strict, a barepy.typedmarker turns those 19 into 42no-untyped-call, one at everylazy.load, the wayCamera.zoombehaves in §3.4. The marker together with annotations onloadandattachand a return type onattach_stubclears 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 usinglazy_loaderuntil Python 3.15 is the floor and then move to thelazy importof 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.❓ Open (🔎 2026-10-07, #2572 · 🎯 row 9 of §4 · 🎫 #2570) — The
lazy_loaderoverride comes out when upstream allows. Theignore_missing_importsoverride forlazy_loaderclears all 19 locally. It was meant for change 6, and change 2 brought it in, becausetransform.pyimportslazy_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 replaceslazy_loader, whichever is first.❓ Open (🔎 2026-10-08, #2580 · 🎯 row 8 of §4 · 🎫 #2851) — The cast in
transform_mesh, and a typed local incore.py, wait on the samepyvistarelease.pyvista0.49 annotatespyvista_ndarray.__setitem__withkey: int | NumpyArray[int], which refuses the tuple index ofmesh.points[:, 0]that it accepts at runtime, so change 2 sets the points through atyping.cast. The annotation refuses a slice key in the same way, so change 6b types the ids that_keep_rolesassigns through one as any array.pyvistapull 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.❓ Open (🔎 2026-10-09, #2599 · 🎯 row 10 of §4 · 🎫 #2601) — The cast in
from_tiffwaits on typeshed.types-rasteriotypes the rows and columns ofrasterio.transform.xyasint | Sequence[int].rasteriotakes arrays, which is whatTransform.from_tiffpasses, so change 3 passes them through atyping.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.❓ Open (🔎 2026-10-11, #2619 · 🎯 row 8 of §4 · 🎫 #2852) — Ten typed locals wait on the same
pyvistarelease.pyvista0.49 leavesGPUInfo.__init__,GPUInfo.get_info,Texture.__init__,Texture.to_image,Theme.__init__andPolyData.append_polydataunannotated, and its_Wrappeddecorator, item 2’s cause, breaksself.reset_camera(render=False). So_warn_opacityandview_poicallGPUInfoandreset_camerathrough locals annotatedCallable. Change 6a added a third, forp.add_axes()in theplotcommand ofcli.py, and change 6c six more: two inReport, two inwrap_textureand one in each theme’s__init__. Change 7 added the last, in the gallery:uber_h3.pybinds whatappend_polydatareturns to a local annotatedPolyData, an ordinary line for an example, not aCallable.pyvistamainfixes every defect, and the locals come out with the floor that carries them, the trigger items 2 and 6 already wait on.maintypesto_imageas returningImageData | None, so the local inwrap_texturealready allowsNone.❓ 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) andh3(4.5.0) carry nopy.typedand have no stubs on conda-forge or in typeshed, so oneignore_missing_importsoverride makes each importAny. Change 6c brought the entries forgeopyandfastparquetto life by takingpantry/data.pyout of the ratchet, and change 7 added the last three, which only the gallery imports.fastparquetcame out when the earthquakes sample moved topyarrow(#2783), whichpantry/data.pyfinds withfind_specand never imports, aspyarrowships no annotations either. Each name comes out when its distribution or a stub package types it.pooch,cartopy,cmoceanandh3have open upstream issues asking for annotations;cmocean’s offers a stub file for its colormaps, which would not lift the override without apy.typedmarker.❓ Open (🔎 2026-10-21, #2676 · 🎯 row 8 of §4 · 🎫 #2853) — Four typed locals wait on the same
pyvistarelease.pyvista0.49 types its arrays with Python’sint,boolandfloatas the dtype.numpy.float64subclassesfloat, so a float array passes intopyvista, butnumpy.intpandnumpy.boolsubclass neitherintnorbool, soextract_cellsrefuses every real mask or index array. For the same reason, numpy’s own methods refuse arrays thatpyvistahands back:+=on a mesh’s faces, andminon a cell’s points. Change 6b types the two masks infilters.remesh, the faces incore.combineand the points incore.slice_cellsas any array.pyvistapull 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.❓ Open (🔎 2026-11-03, #2850 · 🎯 row 12 of §4 · 🎫 #2860) — Row 8 reads only some of the pixi tables.
_pyvista_floorsintests/test_ci_typing.pyreads the floor fromrequirements/pypi-core.txt,[tool.pixi.dependencies], and each feature’sdependenciesandpypi-dependencies, but not from a top-level[tool.pixi.pypi-dependencies]or atargettable. Apyvistafloor raised in one of those would not fire row 8. Neither table exists yet.❓ Open (🔎 2026-11-03, #2850 · 🎯 row 12 of §4 · 🎫 #2861) — A
py.typedbelow a package’s root counts as typed._typedcounts a marker anywhere beneath a module, such as a vendored subpackage’s, butmypyhonours 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.❓ 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
pyvistafloor 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 lockedpyvistareaches 0.50.0 could prompt the floor’s rise.
9. References#
pyvista’stype-checking.ymlworkflow, the precedent for §3.1: pyvista/pyvistamypy’spython_version, pinned to the support floor by #2563, and thetests/test_python_support.pyconvention this specification’s ratchet test followsmypyissue 13916, the reason the hook passes no filenames: python/mypy#13916pyvistaissue 6589 and pull request 9162, the report and the fix for thecall-arghalf of §3.4: pyvista/pyvista#6589 and pyvista/pyvista#9162pyvistapull request 9262, which widens the indexpyvista_ndarray.__setitem__accepts, cited by item 6 of §8: pyvista/pyvista#9262pyvistapull requests 9344 and 9351, which replace the array aliases that item 10 of §8 waits on: pyvista/pyvista#9344 and pyvista/pyvista#9351lazy_loaderissue 165, on its relation to PEP 810, cited by item 4 of §8: scientific-python/lazy-loader#165lazy_loaderissue 181, the request for a marker and annotations that resolves item 4 of §8: scientific-python/lazy-loader#181typeshedpull request 15884, which added therasteriostubs that change 3 checksbridge.pyagainst: python/typeshed#15884typeshedissue 16504, reporting three gaps in those stubs, cited by item 7 of §8: python/typeshed#16504
10. Verification#
Each row follows ledger spec §3.4.
Decision |
Status |
Evidence |
|---|---|---|
✅ verified (2026-11-01, #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). |
||
✅ verified (2026-11-01, #2796) |
||
✅ verified (2026-11-01, #2796) |
✅ 3 · ✍️ 1 · ⏳ 0 · 🗄️ 0: 4 of 4 decisions in force verified