cuda_core __init__.py files expose implementation details and external symbols

[mdboom]

From Claude Code:

Summary

Several __init__.py files in cuda_core expose implementation details or symbols defined outside the cuda_core package. This should be cleaned up before 1.0 to ensure a well-defined public API surface.

Findings

1. cuda/core/__init__.py (most significant)

• No __all__ — every imported name becomes public by default.
• External package leak — imports cuda.bindings (line 8) and injects its versioned symbols into the module namespace via globals().update(versioned_mod.__dict__) (line 20). This makes cuda.bindings internals accessible as if they were cuda.core API. [EDIT: This is a false statement]
• Underscore symbol exposed — _StridedLayout is imported from private module cuda.core._layout (line 39) and available as an unguarded public name.
• Remove _StridedLayout from cuda.core public API #1932
• Make namespace hygiene easier in cuda.core.__init__.py #1934

2. cuda/core/experimental/__init__.py

• Re-exports _StridedLayout from cuda.core._layout (line 48) — an underscore-prefixed internal class offered as public API.
• Uses a __import__("sys").modules injection to register a utils submodule (line 41), which is non-standard and obscures the API surface.

[EDIT: "experimental" is a weird vestige -- no reason to touch it]

3. cuda/core/_memory/_legacy.py

• __all__ includes _SynchronousMemoryResource — an underscore-prefixed class explicitly listed as a public export, then wildcard-imported up through cuda/core/_memory/__init__.py.
• Remove _SynchronousMemoryResource from cuda.core._memory public API #1933

4. cuda/core/system/__init__.py (minor)

• Uses wildcard imports (from ._device import *, etc.). Mitigated by defining and extending __all__, but any additions to submodule __all__ lists auto-propagate without review.

[EDIT: This is by-design, since exposure is defined near where things are defined rather in a separate file. It may make sense to make the other submodules work this way.]

Suggested improvements

• Add __all__ to cuda/core/__init__.py to explicitly define the public API. [EDIT: We could but that wouldn't actually solve much]
• Avoid globals().update() of external package dicts; import only the specific symbols needed. [EDIT: We need to do this]
• Either rename _StridedLayout to drop the underscore (if it is intentionally public) or stop exporting it.
• Remove _SynchronousMemoryResource from _legacy.py's __all__ if it is truly internal.
• Replace wildcard imports with explicit import lists where feasible.