docs(cuda.core): use PEP 604 unions in docstrings (#2601)

Docstrings across cuda_core still spelled parameter types with the
pre-3.10 typing generics. Replace Union[...] and Optional[...] with the
| form the rest of the package already uses, e.g. `stream : Stream |
None, optional` in _memoryview.pyx.

Docstrings only, so the .pyi changes are the stubgen-pyx output for the
edited .pyx files and no runtime behavior moves. In _module.pyx this also
realigns the max_potential_block_size docstring with its signature, which
already reads int | driver.CUoccupancyB2DSize.

Two code-level spellings stay as they are:

- LinkerHandleT in _linker.pyx is a runtime value, not an annotation.
  _program.pyx builds ProgramHandleT from it with `nvrtc.nvrtcProgram |
  int | LinkerHandleT`, and PEP 604 `|` on the forward-reference strings
  it holds raises TypeError.
- The union_type literal in _process_define_macro is error-message text
  rather than a docstring.

Sequence[...] and Iterable[...] elsewhere in cuda_core are
collections.abc generics and are unaffected.

Signed-off-by: Aryan <aryansputta@gmail.com>
Co-authored-by: Michael Droettboom <mdboom@gmail.com>

Author: aryanputta

cuda_core/cuda/core/_launch_config.pyi

@@ -18,15 +18,15 @@ class LaunchConfig:
 
     Attributes
     ----------
-    grid : Union[tuple, int]
+    grid : tuple | int
         Collection of threads that will execute a kernel function. When cluster
         is not specified, this represents the number of blocks, otherwise
         this represents the number of clusters.
-    cluster : Union[tuple, int]
+    cluster : tuple | int
         Group of blocks (Thread Block Cluster) that will execute on the same
         GPU Processing Cluster (GPC). Blocks within a cluster have access to
         distributed shared memory and can be explicitly synchronized.
-    block : Union[tuple, int]
+    block : tuple | int
         Group of threads (Thread Block) that will execute on the same
         streaming multiprocessor (SM). Threads within a thread blocks have
         access to shared memory and can be explicitly synchronized.
@@ -46,11 +46,11 @@ class LaunchConfig:
 
         Parameters
         ----------
-        grid : Union[tuple, int], optional
+        grid : tuple | int, optional
             Grid dimensions (number of blocks or clusters if cluster is specified)
-        cluster : Union[tuple, int], optional
+        cluster : tuple | int, optional
             Cluster dimensions (Thread Block Cluster)
-        block : Union[tuple, int], optional
+        block : tuple | int, optional
             Block dimensions (threads per block)
         shmem_size : int, optional
             Dynamic shared memory size in bytes (default: 0)

cuda_core/cuda/core/_launch_config.pyx

@@ -38,15 +38,15 @@ cdef class LaunchConfig:
 
     Attributes
     ----------
-    grid : Union[tuple, int]
+    grid : tuple | int
         Collection of threads that will execute a kernel function. When cluster
         is not specified, this represents the number of blocks, otherwise
         this represents the number of clusters.
-    cluster : Union[tuple, int]
+    cluster : tuple | int
         Group of blocks (Thread Block Cluster) that will execute on the same
         GPU Processing Cluster (GPC). Blocks within a cluster have access to
         distributed shared memory and can be explicitly synchronized.
-    block : Union[tuple, int]
+    block : tuple | int
         Group of threads (Thread Block) that will execute on the same
         streaming multiprocessor (SM). Threads within a thread blocks have
         access to shared memory and can be explicitly synchronized.
@@ -77,11 +77,11 @@ cdef class LaunchConfig:
 
         Parameters
         ----------
-        grid : Union[tuple, int], optional
+        grid : tuple | int, optional
             Grid dimensions (number of blocks or clusters if cluster is specified)
-        cluster : Union[tuple, int], optional
+        cluster : tuple | int, optional
             Cluster dimensions (Thread Block Cluster)
-        block : Union[tuple, int], optional
+        block : tuple | int, optional
             Block dimensions (threads per block)
         shmem_size : int, optional
             Dynamic shared memory size in bytes (default: 0)

cuda_core/cuda/core/_module.pyi

@@ -158,7 +158,7 @@ class KernelOccupancy:
 
         Parameters
         ----------
-            dynamic_shared_memory_needed: Union[int, driver.CUoccupancyB2DSize]
+            dynamic_shared_memory_needed: int | driver.CUoccupancyB2DSize
                 The amount of dynamic shared memory in bytes needed by block.
                 Use `0` if block does not need shared memory. Use C-callable
                 represented by :obj:`~driver.CUoccupancyB2DSize` to encode
@@ -343,13 +343,13 @@ class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str, os.PathLike]
+        module : bytes | str | os.PathLike
             Either a bytes object containing the in-memory cubin to load, or
             a file path object (or its string representation) pointing to the
             on-disk cubin to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).
@@ -361,13 +361,13 @@ class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str, os.PathLike]
+        module : bytes | str | os.PathLike
             Either a bytes object containing the in-memory ptx code to load, or
             a file path object (or its string representation) pointing to the
             on-disk ptx file to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).
@@ -379,13 +379,13 @@ class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str, os.PathLike]
+        module : bytes | str | os.PathLike
             Either a bytes object containing the in-memory ltoir code to load,
             or a file path object (or its string representation) pointing to the
             on-disk ltoir file to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).
@@ -397,13 +397,13 @@ class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str, os.PathLike]
+        module : bytes | str | os.PathLike
             Either a bytes object containing the in-memory fatbin to load, or
             or a file path object (or its string representation) pointing to the
             on-disk fatbin to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).
@@ -415,12 +415,12 @@ class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str]
+        module : bytes | str
             Either a bytes object containing the in-memory object code to load, or
             a file path string pointing to the on-disk object code to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).
@@ -432,12 +432,12 @@ class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str]
+        module : bytes | str
             Either a bytes object containing the in-memory library to load, or
             a file path string pointing to the on-disk library to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).

cuda_core/cuda/core/_module.pyx

@@ -300,7 +300,7 @@ cdef class KernelOccupancy:
 
         Parameters
         ----------
-            dynamic_shared_memory_needed: Union[int, driver.CUoccupancyB2DSize]
+            dynamic_shared_memory_needed: int | driver.CUoccupancyB2DSize
                 The amount of dynamic shared memory in bytes needed by block.
                 Use `0` if block does not need shared memory. Use C-callable
                 represented by :obj:`~driver.CUoccupancyB2DSize` to encode
@@ -669,13 +669,13 @@ cdef class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str, os.PathLike]
+        module : bytes | str | os.PathLike
             Either a bytes object containing the in-memory cubin to load, or
             a file path object (or its string representation) pointing to the
             on-disk cubin to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).
@@ -688,13 +688,13 @@ cdef class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str, os.PathLike]
+        module : bytes | str | os.PathLike
             Either a bytes object containing the in-memory ptx code to load, or
             a file path object (or its string representation) pointing to the
             on-disk ptx file to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).
@@ -707,13 +707,13 @@ cdef class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str, os.PathLike]
+        module : bytes | str | os.PathLike
             Either a bytes object containing the in-memory ltoir code to load,
             or a file path object (or its string representation) pointing to the
             on-disk ltoir file to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).
@@ -726,13 +726,13 @@ cdef class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str, os.PathLike]
+        module : bytes | str | os.PathLike
             Either a bytes object containing the in-memory fatbin to load, or
             or a file path object (or its string representation) pointing to the
             on-disk fatbin to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).
@@ -745,12 +745,12 @@ cdef class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str]
+        module : bytes | str
             Either a bytes object containing the in-memory object code to load, or
             a file path string pointing to the on-disk object code to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).
@@ -763,12 +763,12 @@ cdef class ObjectCode:
 
         Parameters
         ----------
-        module : Union[bytes, str]
+        module : bytes | str
             Either a bytes object containing the in-memory library to load, or
             a file path string pointing to the on-disk library to load.
-        name : Optional[str]
+        name : str | None
             A human-readable identifier representing this code object.
-        symbol_mapping : Optional[dict]
+        symbol_mapping : dict | None
             A dictionary specifying how the unmangled symbol names (as keys)
             should be mapped to the mangled names before trying to retrieve
             them (default to no mappings).

cuda_core/cuda/core/_program.pyi

@@ -166,7 +166,7 @@ class ProgramOptions:
         Enable device code optimization. When specified along with '-G', enables limited debug information generation
         for optimized device code.
         Default: None
-    ptxas_options : Union[str, list[str]], optional
+    ptxas_options : str | list[str], optional
         Specify one or more options directly to ptxas, the PTX optimizing assembler. Options should be strings.
         For example ["-v", "-O2"].
         Default: None
@@ -200,17 +200,17 @@ class ProgramOptions:
     gen_opt_lto : bool, optional
         Run the optimizer passes before generating the LTO IR.
         Default: False
-    define_macro : Union[str, tuple[str, str], list[Union[str, tuple[str, str]]]], optional
+    define_macro : str | tuple[str, str] | list[str | tuple[str, str]], optional
         Predefine a macro. Can be either a string, in which case that macro will be set to 1, a 2 element tuple of
         strings, in which case the first element is defined as the second, or a list of strings or tuples.
         Default: None
-    undefine_macro : Union[str, list[str]], optional
+    undefine_macro : str | list[str], optional
         Cancel any previous definition of a macro, or list of macros.
         Default: None
-    include_path : Union[str, list[str]], optional
+    include_path : str | list[str], optional
         Add the directory or directories to the list of directories to be searched for headers.
         Default: None
-    pre_include : Union[str, list[str]], optional
+    pre_include : str | list[str], optional
         Preinclude one or more headers during preprocessing. Can be either a string or a list of strings.
         Default: None
     no_source_include : bool, optional
@@ -243,13 +243,13 @@ class ProgramOptions:
     no_display_error_number : bool, optional
         Disable the display of a diagnostic number for warning messages.
         Default: False
-    diag_error : Union[int, list[int]], optional
+    diag_error : int | list[int], optional
         Emit error for a specified diagnostic message number or comma-separated list of numbers.
         Default: None
-    diag_suppress : Union[int, list[int]], optional
+    diag_suppress : int | list[int], optional
         Suppress a specified diagnostic message number or comma-separated list of numbers.
         Default: None
-    diag_warn : Union[int, list[int]], optional
+    diag_warn : int | list[int], optional
         Emit warning for a specified diagnostic message number or comma-separated list of numbers.
         Default: None
     brief_diagnostics : bool, optional

cuda_core/cuda/core/_program.pyx

@@ -319,7 +319,7 @@ class ProgramOptions:
         Enable device code optimization. When specified along with '-G', enables limited debug information generation
         for optimized device code.
         Default: None
-    ptxas_options : Union[str, list[str]], optional
+    ptxas_options : str | list[str], optional
         Specify one or more options directly to ptxas, the PTX optimizing assembler. Options should be strings.
         For example ["-v", "-O2"].
         Default: None
@@ -353,17 +353,17 @@ class ProgramOptions:
     gen_opt_lto : bool, optional
         Run the optimizer passes before generating the LTO IR.
         Default: False
-    define_macro : Union[str, tuple[str, str], list[Union[str, tuple[str, str]]]], optional
+    define_macro : str | tuple[str, str] | list[str | tuple[str, str]], optional
         Predefine a macro. Can be either a string, in which case that macro will be set to 1, a 2 element tuple of
         strings, in which case the first element is defined as the second, or a list of strings or tuples.
         Default: None
-    undefine_macro : Union[str, list[str]], optional
+    undefine_macro : str | list[str], optional
         Cancel any previous definition of a macro, or list of macros.
         Default: None
-    include_path : Union[str, list[str]], optional
+    include_path : str | list[str], optional
         Add the directory or directories to the list of directories to be searched for headers.
         Default: None
-    pre_include : Union[str, list[str]], optional
+    pre_include : str | list[str], optional
         Preinclude one or more headers during preprocessing. Can be either a string or a list of strings.
         Default: None
     no_source_include : bool, optional
@@ -396,13 +396,13 @@ class ProgramOptions:
     no_display_error_number : bool, optional
         Disable the display of a diagnostic number for warning messages.
         Default: False
-    diag_error : Union[int, list[int]], optional
+    diag_error : int | list[int], optional
         Emit error for a specified diagnostic message number or comma-separated list of numbers.
         Default: None
-    diag_suppress : Union[int, list[int]], optional
+    diag_suppress : int | list[int], optional
         Suppress a specified diagnostic message number or comma-separated list of numbers.
         Default: None
-    diag_warn : Union[int, list[int]], optional
+    diag_warn : int | list[int], optional
         Emit warning for a specified diagnostic message number or comma-separated list of numbers.
         Default: None
     brief_diagnostics : bool, optional