[DOC]: cuda.core docs/type hints understate option params since dict is accepted at runtime but not documented #2248

Is this a duplicate?

• I confirmed there appear to be no duplicate issues for this bug and that I agree to the Code of Conduct

Is this for new documentation, or an update to existing docs?

Update

Describe the incorrect/future/missing documentation

Several cuda.core public APIs document their options/config parameter as accepting only a dataclass (or None), but at runtime these parameters also accept a plain dict since the argument is normalized by check_or_create_options, converting a dict into the dataclass via cls(**options).
As a result, the documented signatures and the shipped .pyi type stubs are narrower than the actual accepted types.

Affected APIs:

• Device.create_context — ContextOptions | None (also accepts dict)
• Device.create_event — EventOptions | None (also accepts dict)
• Stream.record — EventOptions | None (also accepts dict)
• launch — LaunchConfig (also accepts dict)
• Program.__init__ — ProgramOptions | None (also accepts dict)
• Linker.__init__ — LinkerOptions | None (also accepts dict)
• SMResource.split — SMResourceOptions (also accepts dict)
• WorkqueueResource.configure — WorkqueueResourceOptions (also accepts dict)
• VirtualMemoryResource.__init__ — VirtualMemoryResourceOptions | None (also accepts dict)

This also seems inconsistent with PinnedMemoryResource.__init__, which already annotates its parameter as PinnedMemoryResourceOptions | dict[str, object] | None, so the convention for accepting a dict already seems to exist in the codebase.

If this is a correction, please provide a link to the incorrect documentation. If this is a new documentation request, please link to where you have looked.

for example, https://nvidia.github.io/cuda-python/cuda-core/latest/generated/cuda.core.Program.html#cuda-core-program.

i have started a fix for this in my fork: fnrizzi@80dc3ec
but not yet opened MR to give precedence to the issue first as per contributing guidelines.