cuda.core: accept dict for XyzOptions that are extension types

[juenglin]

Restores undocumented dict acceptance for options in several cuda.core constructors/methods, which was inadvertently removed by #2619. Covers the three memory-resource constructors and the stream-creation path (Stream._init, Context.create_stream).

Why this is necessary

check_or_create_options (cuda_core/cuda/core/_utils/cuda_utils.pyx) normalizes a plain dict into the options dataclass via cls(**options), so passing a dict for options has always worked at runtime. The options classes (DeviceMemoryResourceOptions, StreamOptions, etc.) are @dataclass cdef class — Cython extension types.

Cython enforces PEP-484 parameter annotations at the call boundary of def methods on cdef classes: when a parameter is annotated with an extension type, Cython emits a runtime isinstance check that rejects other types (including dict) with TypeError before the method body runs. See the "Extension types and None" section of the Extension Types guide.

#2619 removed | dict[str, object] from these annotations so the public stubs would show only the typed dataclass. That was correct in spirit, but it turned the call-boundary check into a regression: dicts that previously flowed through to check_or_create_options now get rejected at the boundary, silently breaking any code relying on the dict shorthand.

What this PR does

Applies Cython's @cython.annotation_typing(False) compiler directive to each affected def method. The directive tells Cython to ignore the PEP-484 annotations for its own type analysis, so the parameter is treated as a generic object at the call boundary and dicts pass through to check_or_create_options. The annotations remain in the source and are still picked up by stubgen-pyx, so the generated .pyi stubs naturally show the clean XxxOptions | None signature — no stub postprocessor needed. See the "Disabling annotations" section of the Pure Python Mode guide.

Changes

• cuda_core/cuda/core/_memory/_device_memory_resource.pyx, _managed_memory_resource.pyx, _pinned_memory_resource.pyx: @cython.annotation_typing(False) on each __init__; options annotation restored to XxxOptions | None = None.
• cuda_core/cuda/core/_stream.pyx: @cython.annotation_typing(False) on Stream._init.
• cuda_core/cuda/core/_context.pyx: @cython.annotation_typing(False) on Context.create_stream.
• tests/memory/test_backward_compatibility.py: tests asserting each memory-resource constructor accepts a plain dict for options.
• tests/test_stream.py: test asserting Device.create_stream accepts a plain dict for options.

Generated .pyi stubs are unchanged by re-running stubgen-pyx (idempotent): the directive is invisible to the stub generator and the source annotations are preserved verbatim.

closes #2248

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[juenglin]

/ok to test 3c027ea

[github-actions]

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

[mdboom]

I think the stubgen-pyx workaround is ultimately unnecessary. Cython doesn't care about the annotation, so we can just set them directly to what we want them to be in the .pyi.

We can declare or not declare whether we accept a dict in the type annotation (that's sort of a larger question we are trying to answer offline -- whether we want to /commit/ to that).

But the tests on their own if useful if we decide we want to accept dicts going forward.

I should add Cython is a weird tool and Python type annotations being informational-only are pretty unique among languages. When you put them together (Cython pre-dates Python type annotations by at least a decade), it's a very confusing mishmash.

[juenglin]

Cython doesn't care about the annotation, so we can just set them directly to what we want them to be in the .pyi.

That's not what I found. If you run the tests added by this PR against a main build, you will find that they are failing.

I dislike this change also and would be happy to close this PR. But that requires that we accept the behavior change introduced by PR #2619.

[mdboom]

Cython doesn't care about the annotation, so we can just set them directly to what we want them to be in the .pyi.

That's not what I found. If you run the tests added by this PR against a main build, you will find that they are failing.

Ah, you are right. I was thinking of cdef functions/methods, not def ones.

I dislike this change also and would be happy to close this PR. But that requires that we accept the behavior change introduced by PR #2619.

Yeah, this is kind of a mess with the way Cython uses type annotations for runtime semantic behavior (which is not how Python works at all). We should probably discuss the best way forward at the next meeting.

[juenglin]

/ok to test 4a030f2

[mdboom]

This is 100% a more manageable solution than the previous one, and I'd be fine merging this on a technical/maintenance level.

Not approving just yet because:

1. I think we should have one more quick round of discussion to make sure this is directionally where we want to go

2. If this is, let's add some AGENTS.md comments recommending this annotation on cdef class methods that accept option classes (or whatever the exact "rule" we need to apply is).