René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"cuda.core: Replace string literals with enums in public API","articleBody":"> This is just a result of a sweep for using strings where enums could be used. This is just to aid the discussion about whether they should be addressed.\n\nSeveral places in the `cuda.core` public API accept or return string values chosen from a small, fixed vocabulary. These are candidates for replacement with proper Python `enum` types, which would improve discoverability, IDE autocompletion, `isinstance` checking, and catch typos at the call site rather than at runtime.\n\n---\n\n## Findings\n\n### Compilation / Linking pipeline\n\n| Location | Kind | Values |\n|---|---|---|\n| `Program.__init__(code_type)` | arg | `\"c++\"`, `\"ptx\"`, `\"nvvm\"` |\n| `Program.compile(target_type)` | arg | `\"ptx\"`, `\"cubin\"`, `\"ltoir\"` |\n| `Program.backend` | return | `\"NVRTC\"`, `\"NVVM\"`, `\"nvJitLink\"`, `\"driver\"` |\n| `Program.pch_status` | return | `\"created\"`, `\"not_attempted\"`, `\"failed\"` |\n| `Linker.link(target_type)` | arg | `\"cubin\"`, `\"ptx\"` |\n| `Linker.backend` | return | `\"nvJitLink\"`, `\"driver\"` |\n| `ObjectCode.code_type` | return | `\"cubin\"`, `\"ptx\"`, `\"ltoir\"`, `\"fatbin\"`, `\"object\"`, `\"library\"` |\n\n### Memory\n\n| Location | Kind | Values |\n|---|---|---|\n| `ManagedMemoryResourceOptions.preferred_location_type` | arg | `\"device\"`, `\"host\"`, `\"host_numa\"` |\n| `ManagedMemoryResource.preferred_location` | return (tuple[0]) | `\"device\"`, `\"host\"`, `\"host_numa\"` |\n| `VirtualMemoryResourceOptions.allocation_type` | arg | `\"pinned\"`, `\"managed\"` |\n| `VirtualMemoryResourceOptions.location_type` | arg | `\"device\"`, `\"host\"`, `\"host_numa\"`, `\"host_numa_current\"` |\n| `VirtualMemoryResourceOptions.handle_type` | arg | `\"posix_fd\"`, `\"generic\"`, `\"win32_kmt\"`, `\"fabric\"` |\n| `VirtualMemoryResourceOptions.granularity` | arg | `\"recommended\"`, `\"minimum\"` |\n| `VirtualMemoryResourceOptions.self_access` / `peer_access` | arg | `\"rw\"`, `\"r\"` |\n\nNote: the `VirtualMemoryResourceOptions` fields already use `Literal[...]` type hints, which partially addresses the issue, but proper enums would still improve iteration, `isinstance` checks, and user discoverability.\n\n### Graph API\n\n| Location | Kind | Values |\n|---|---|---|\n| `GraphAllocOptions.memory_type` | arg | `\"device\"`, `\"host\"`, `\"managed\"` |\n| `AllocNode.memory_type` | return | `\"device\"`, `\"host\"`, `\"managed\"` |\n| `ConditionalNode.cond_type` | return | `\"if\"`, `\"while\"`, `\"switch\"` |\n\n---\n\n## Proposed enum groupings\n\n| Enum name | Values | Consumers |\n|---|---|---|\n| `CodeType` | `cubin`, `ptx`, `ltoir`, `fatbin`, `object`, `library` | `ObjectCode.code_type`, `Linker.link`, `Program.compile` |\n| `SourceType` | `c++`, `ptx`, `nvvm` | `Program.__init__` |\n| `CompilerBackend` | `NVRTC`, `NVVM`, `nvJitLink`, `driver` | `Program.backend`, `Linker.backend` |\n| `PchStatus` | `created`, `not_attempted`, `failed` | `Program.pch_status` |\n| `MemoryType` | `device`, `host`, `managed` | `GraphAllocOptions`, `AllocNode`, `ManagedMemoryResource` |\n| `LocationType` | `device`, `host`, `host_numa`, `host_numa_current` | `VirtualMemoryResourceOptions`, `ManagedMemoryResourceOptions` |\n| `ConditionalType` | `if_`, `while_`, `switch_` | `ConditionalNode.cond_type` |\n| `HandleType` | `posix_fd`, `generic`, `win32_kmt`, `fabric` | `VirtualMemoryResourceOptions` |\n| `Granularity` | `recommended`, `minimum` | `VirtualMemoryResourceOptions` |\n| `AccessMode` | `rw`, `r` | `VirtualMemoryResourceOptions` |\n\n---\n\n## Discussion points\n\n- The compilation/linking pipeline (`Program`, `Linker`, `ObjectCode`) is the highest-impact area since string values flow across multiple API boundaries.\n- Switching from `str` to `enum` would be a breaking change for existing callers. One migration path is to accept both `str` and the enum type during a deprecation window.\n- Some values (`\"c++\"`, `\"if\"`, `\"while\"`) are not valid Python identifiers and would need renaming (e.g. `SourceType.CPP`, `ConditionalType.IF`).","author":{"url":"https://github.com/mdboom","@type":"Person","name":"mdboom"},"datePublished":"2026-04-30T14:09:56Z","url":"https://github.com/NVIDIA/cuda-python/issues/1995"}