[rasterio] Add stubs for rasterio 1.5#15884
Open
thomas-maschler wants to merge 7 commits into
Open
Conversation
Covers the public rasterio 1.5.x API plus the private Cython modules that are transitively required by public re-exports. `partial-stub = true` (a handful of internal Cython helpers are `Incomplete`). `affine.Affine` is referenced through a single stubs-only indirection module (`rasterio._affine_types`) that aliases `Affine` to `Any` until affine ships its own `py.typed` (planned for v3), per discussion in issue python#15870. When affine v3 lands, replacing the body of `_affine_types.pyi` with `from affine import Affine as Affine` will restore precision package-wide in a single edit. PEP 702 `@deprecated` markers cover every documented `RasterioDeprecationWarning` site, including the overload-based parameter deprecations (warp.transform_geom antimeridian_*, windows.from_bounds height/width/precision, 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, rasterio.path.{parse_path,vsi_path}). Closes python#15870 (in part; see issue for the affine-stubs decision).
This comment has been minimized.
This comment has been minimized.
rasterio ships self-contained binary wheels for every platform/Python combination typeshed CI targets (manylinux x86_64/aarch64, macOS x86_64/arm64, Windows), so no system GDAL is needed for stubtest. Removing libgdal-dev also unblocks the aggregate apt-install step: libgdal-dev on Ubuntu noble hard-depends on default-libmysqlclient-dev, whose libmysqlclient-dev provider is currently broken in the noble archive. Also strips justifying / explanatory comments throughout the stubs.
* check_open.py: rename `_opaque_mode` -> `check_opaque_mode` so the helper is no longer flagged as `reportUnusedFunction`. * check_transform_geom.py: mark the two intentional deprecated-overload calls with `# pyright: ignore[reportDeprecated]` (they exist to exercise the `@deprecated` overload routing).
This comment has been minimized.
This comment has been minimized.
`pyrightconfig.stricter.json` (which checks rasterio because the package isn't on the exclude list) flagged `_base._parse_path(path: str): ...` for an unknown return type (`reportUnknownParameterType`) on every Darwin/Windows matrix combo. The runtime forwards to `rasterio._path._parse_path`; mirror its return annotation here. Also apply ruff format to drop the blank lines between adjacent class members (typeshed style; was getting re-applied by pre-commit-ci).
Contributor
|
According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
affinereferences through a stubs-only indirection instead of bundlingtypes-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
_-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.tomlwithversion = "1.5.*",requires-python = ">=3.12"(rasterio 1.5 itself requires 3.12+),dependencies = ["numpy>=2", "click>=8"], and a[tool.stubtest]section pinned torasterio==1.5.*pluslibgdal-dev/gdalapt/brew packages.partial-stub = true— the entire public surface is covered, but a handful of internal Cython helpers are deliberatelyIncomplete.@tests/stubtest_allowlist.txtfor the remaining@disjoint_basemarkers / Cython-introspected parameter-name drift in a small set of private modules.@tests/test_cases/check_{crs,dataset,open,transform_geom,windows}.pyregression tests.affine.AffinestrategyPer the discussion on #15870, rasterio's stubs reference
affine.Affinethrough a single stubs-only indirection module (rasterio._affine_types) that aliasesAffinetoAny:Affine v3 is currently in the 3.0rc3 pre-release and already ships complete inline type hints plus a
py.typedmarker (affine.pywas moved toaffine/__init__.pyin rc3 specifically to enable that distribution). When v3 is final, the swap is one line in one file:This avoids any need to ship
types-affinein typeshed.PEP 702
@deprecatedmarkersCover every documented
RasterioDeprecationWarningsite, 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_optionsswallows the deprecated kwarg in the modern overload (transform.rowcol(precision=)andtransform.TransformMethodsMixin.index(precision=)); these carry inline notes in the stub.Local validation
Run against
rasterio==1.5.0in a fresh venv:check_typeshed_structuremypy_test(3.10‑3.15)regr_test rasteriostubtest_third_party rasteriopyright(basic settings)ruff check+ruff format --checkflake8 --select=YNotes
WktVersion.WKT2_2019 = "WKT2_2018"— the stub mirrors this upstream quirk (likely a typo, but stubtest would flag any "correction").plot.contrast_strechis misspelled upstream; the stub matches with an inline comment.rasterio.rio.*(the CLI) is deliberately not stubbed.