Adopt PEP 563 annotations and modern union syntax

[Andy-Jost]

Summary

• Use from __future__ import annotations consistently across cuda.core
• Replace Union[X, Y] with X | Y and Optional[X] with X | None in type annotations
• Remove redundant TYPE_CHECKING blocks where the imports are no longer needed
• Retain TYPE_CHECKING blocks only where needed for forward references (circular imports)

Changes

• 15 files updated with modern type annotation syntax
• Net reduction of ~20 lines

Test Coverage

• All existing tests pass
• No new tests needed (type annotation changes only)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[Andy-Jost]

/ok to test efa558e

[Andy-Jost]

/ok to test 3894090

[Andy-Jost]

/ok to test e488097

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-1518/
https://nvidia.github.io/cuda-python/pr-preview/pr-1518/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-1518/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-1518/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[rwgk]

I believe these are still needed:

add_back_needed_TYPE_CHECKING_imports.txt

That diff was generated by Cursor. I did not test.

Some of the added imports exist as cimports. Cursor told me (I asked about Context specifically, to pick out one):

• cimport Context only tells Cython about the extension type; it’s not visible to Python type checkers or doc tools.
• With from __future__ import annotations, runtime doesn’t need the import, so removing it is fine for correctness/builds.
• If you want mypy/pyright/Sphinx to resolve Context in annotations, keep the if TYPE_CHECKING: import.

Does that reasoning hold water?

[Andy-Jost]

@rwgk Thanks — I ran into several of these as well. This change introduces new dangling type references: annotations that don’t affect building, linting, or runtime correctness, but that cannot be resolved.

For example, this would fail when calling get_type_hints:

import typing
typing.get_type_hints(buffer.close)  # -> Exception: cannot resolve Stream

I started addressing these issues but quickly realized it led down a rabbit hole. There appear to be many similar problems beyond just this change.

If we need to support dynamic retrieval of type hints—for example, for documentation purposes—then we’ll likely need a more coordinated effort. In that case, we should probably add tests that apply get_type_hints across the codebase.

For this particular change, I chose to prioritize removing TYPE_CHECKING blocks even if it leaves dangling type references. Fixing those seems outside the scope of this update.

[rwgk]

For this particular change, I chose to prioritize removing TYPE_CHECKING blocks even if it leaves dangling type references. Fixing those seems outside the scope of this update.

Sounds good to me, but I'd definitely check in the sphinx-generated docs before/after this PR, to be sure the removals don't introduce a regression there. Did you do this already?

[Andy-Jost]

Good point. Here are two links to the Buffer documentation: before after

This change made DevicePointerT a dangling type annotation in the buffer module. Looking at Buffer.from_handle as an example, there is no link in either case, so this change did not make it worse.

Taking one from your list, here is Context in the device module: before after. Looking at Device.set_current the type annotation for Context is the same in both cases (no link).

The links are overall in a sorry state. For example:

• In Buffer.copy_to, no links for Steam and GraphBuilder
• In Buffer.fill, links for Steam and GraphBuilder

We have a lot to improve in the documentation, but I don't see any place this change make things worse.