[rasterio] Add stubs for rasterio 1.5#15884

thomas-maschler

Summary

Adds type stubs for rasterio tracking the current rasterio==1.5.* release.

Follow-up to #15870 — please refer to that issue for the discussion that shaped the PR's scope (in particular the decision to ship affine references through a stubs-only indirection instead of bundling types-affine).

Also addresses rasterio/rasterio#2322 (the upstream type-hinting tracker): rasterio's maintainers opted not to add inline annotations, so external stubs are the practical alternative — this PR provides them.

What's included

43 stub files covering the rasterio 1.5 public API surface, plus the Cython _-prefixed modules transitively required by public re-exports (_base, _io, _warp, _env, _err, _features, _filepath, _path, _show_versions, _transform, _typing, _version, _vsiopener, _affine_types).
METADATA.toml with version = "1.5.*", requires-python = ">=3.12" (rasterio 1.5 itself requires 3.12+), dependencies = ["numpy>=2", "click>=8"], and a [tool.stubtest] section pinned to rasterio==1.5.* plus libgdal-dev / gdal apt/brew packages.
partial-stub = true — the entire public surface is covered, but a handful of internal Cython helpers are deliberately Incomplete.
@tests/stubtest_allowlist.txt for the remaining @disjoint_base markers / Cython-introspected parameter-name drift in a small set of private modules.
@tests/test_cases/check_{crs,dataset,open,transform_geom,windows}.py regression tests.

affine.Affine strategy

Per the discussion on #15870, rasterio's stubs reference affine.Affine through a single stubs-only indirection module (rasterio._affine_types) that aliases Affine to Any:

# rasterio/_affine_types.pyi
from typing import Any, TypeAlias

Affine: TypeAlias = Any

Affine v3 is currently in the 3.0rc3 pre-release and already ships complete inline type hints plus a py.typed marker (affine.py was moved to affine/__init__.py in rc3 specifically to enable that distribution). When v3 is final, the swap is one line in one file:

# rasterio/_affine_types.pyi
from affine import Affine as Affine

This avoids any need to ship types-affine in typeshed.

PEP 702 @deprecated markers

Cover every documented RasterioDeprecationWarning site, including the overload-based parameter deprecations:

warp.transform_geom(antimeridian_cutting=, antimeridian_offset=)
windows.from_bounds(height=, width=, precision=)
merge.merge(precision=)
features.geometry_window(north_up=, rotated=, pixel_precision=)
transform.TransformerBase.rowcol(precision=)
windows.WindowMethodsMixin.window(precision=)

…and whole-symbol cases: CRS.is_valid, Window.round_shape, DatasetReaderBase.statistics, DatasetBase.is_tiled, env.hascreds, env.ensure_env_credentialled, io.FilePath, path.parse_path, path.vsi_path.

Two deprecations cannot be expressed via overload because **rpc_options swallows the deprecated kwarg in the modern overload (transform.rowcol(precision=) and transform.TransformMethodsMixin.index(precision=)); these carry inline notes in the stub.

Local validation

Run against rasterio==1.5.0 in a fresh venv:

Check Result

check_typeshed_structure	pass
mypy_test (3.10‑3.15)	pass
regr_test rasterio	pass
stubtest_third_party rasterio	pass
pyright (basic settings)	pass
ruff check + ruff format --check	pass
flake8 --select=Y	pass

Notes

WktVersion.WKT2_2019 = "WKT2_2018" — the stub mirrors this upstream quirk (likely a typo, but stubtest would flag any "correction").
plot.contrast_strech is misspelled upstream; the stub matches with an inline comment.
rasterio.rio.* (the CLI) is deliberately not stubbed.

srittau

A few general notes:

For various reasons, we use tests only sparingly in typeshed for complicated situations. For example, assert_type(reader.bounds, BoundingBox) basically only repeats the type hint and tests that the type checkers works correctly.

Without looking at the tests in detail, we should probably just remove them wholesale for now.
Using Any needs an explanation, which types are allowed or why Any is necessary, unless it's obvious for someone not familar with the library. dict[str, Any] is probably the most common case that's considered obvious, specializations like NDArray[Any] is another case. Example where it's not obvious:

def __init__(self, *args: Any, **kwargs: Any) -> None: ...

What happens with args and kwargs here? Why can't it be typed? Are they just forwarded? In that case we could type them with the arguments of the function they are forwarded to. Or are they forwarded to a function where the arguments are unknown? Then that should be a comment. Just leaving it unannotated for now is also an option.

Another example:

def clone_file_obj(fobj: Any) -> Any: ...

What's the meaning of Any here?

There should be comments explaining why these entries are on the allowlist.

I added comments

Are these two options really necessary? Are really modules (that are not listed in the allowlist) missing?

i removed those flags added missing stubs

thomas-maschler

Thanks for the review. This is ready for another look. I addressed your comments in separate commits.

thomas-maschler

@srittau please let me know if there are any other changes I should do. Thanks

github-actions

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

thomas-maschler and others added 2 commits June 8, 2026 12:31

[pre-commit.ci] auto fixes from pre-commit.com hooks

e703f5d