feat(cuda.core)!: drop int location shorthand from managed-memory ops (R6, R8)

Per Leo's review on PR #1775 (_managed_buffer.py:165) and Andy's
parallel question (line 144), drop the `int` shorthand for
prefetch/discard_prefetch/advise locations. The previous design
accepted `Device | Host | int` where `int >= 0` meant a device ordinal
and `-1` magically meant host. With first-class `Device` and `Host`,
the int form was redundant and the `-1 → Host` magic was surprising.

Public API change:
  prefetch(buf, Device(0), stream=...)   # was: prefetch(buf, 0, stream=...)
  prefetch(buf, Host(),    stream=...)   # was: prefetch(buf, -1, stream=...)

This also resolves an inconsistency: ManagedBuffer.preferred_location
already accepted only Device | Host | None, but prefetch() and
discard_prefetch() accepted int. Now uniformly Device | Host.

Pre-1.0 breaking change. Anyone using the int shorthand should switch
to the explicit Device(N) / Host() form.

Files touched:
- _managed_location.py: drop the int branch from _coerce_location;
  TypeError now reads "Device, Host, or None"
- _managed_buffer.py: type signatures `Device | Host | int` → `Device | Host`
- _managed_memory_ops.pyx: docstring updates (3 occurrences)
- tests/memory/test_managed_ops.py: replace int call sites with
  Host()/Device(N); collapse three int-branch tests into one
  test_int_rejected
- 1.0.0-notes.rst: drop the "int values are also accepted" sentence

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: rparolin

cuda_core/cuda/core/_memory/_managed_buffer.py

@@ -162,14 +162,14 @@ def accessed_by(self, locations) -> None:
         for loc in target - current:
             advise(self, _SET_ACCESSED_BY, loc)
 
-    def prefetch(self, location: Device | Host | int, *, stream: Stream | GraphBuilder) -> None:
+    def prefetch(self, location: Device | Host, *, stream: Stream | GraphBuilder) -> None:
         """Prefetch this range to ``location`` on ``stream``."""
         prefetch(self, location, stream=stream)
 
     def discard(self, *, stream: Stream | GraphBuilder) -> None:
         """Discard this range's resident pages on ``stream`` (CUDA 13+)."""
         discard(self, stream=stream)
 
-    def discard_prefetch(self, location: Device | Host | int, *, stream: Stream | GraphBuilder) -> None:
+    def discard_prefetch(self, location: Device | Host, *, stream: Stream | GraphBuilder) -> None:
         """Discard this range and prefetch to ``location`` on ``stream`` (CUDA 13+)."""
         discard_prefetch(self, location, stream=stream)

cuda_core/cuda/core/_memory/_managed_location.py

@@ -48,10 +48,4 @@ def _coerce_location(value, *, allow_none: bool = False) -> _LocSpec | None:
         if allow_none:
             return None
         raise ValueError("location is required")
-    if isinstance(value, int):
-        if value == -1:
-            return _LocSpec(kind="host")
-        if value >= 0:
-            return _LocSpec(kind="device", id=value)
-        raise ValueError(f"device ordinal must be >= 0 (or -1 for host), got {value}")
-    raise TypeError(f"location must be a Device, Host, int, or None; got {type(value).__name__}")
+    raise TypeError(f"location must be a Device, Host, or None; got {type(value).__name__}")

cuda_core/cuda/core/_memory/_managed_memory_ops.pyx

@@ -239,7 +239,7 @@ def advise(
         ``"unset_read_mostly"``, ``"set_preferred_location"``,
         ``"unset_preferred_location"``, ``"set_accessed_by"``,
         ``"unset_accessed_by"``) and ``CUmem_advise`` enum values are accepted.
-    location : :class:`~cuda.core.Device` | :class:`~cuda.core.Host` | int | Sequence[...]
+    location : :class:`~cuda.core.Device` | :class:`~cuda.core.Host` | Sequence[...]
         Target location(s). Required for advice values that consult a
         location; ignored (may be ``None``) for ``set_read_mostly``,
         ``unset_read_mostly``, and ``unset_preferred_location``. A sequence
@@ -313,7 +313,7 @@ def prefetch(
     ----------
     targets : :class:`Buffer` | Sequence[:class:`Buffer`]
         One or more managed allocations to operate on.
-    location : :class:`~cuda.core.Device` | :class:`~cuda.core.Host` | int | Sequence[...]
+    location : :class:`~cuda.core.Device` | :class:`~cuda.core.Host` | Sequence[...]
         Target location(s). A single location applies to all targets; a
         sequence must match ``len(targets)``. ``int`` values are coerced
         to a location (``-1`` maps to host, ``>=0`` to that device ordinal).
@@ -407,7 +407,7 @@ def discard_prefetch(
     ----------
     targets : :class:`Buffer` | Sequence[:class:`Buffer`]
         One or more managed allocations to discard and re-prefetch.
-    location : :class:`~cuda.core.Device` | :class:`~cuda.core.Host` | int | Sequence[...]
+    location : :class:`~cuda.core.Device` | :class:`~cuda.core.Host` | Sequence[...]
         Target location(s). A single location applies to all targets;
         a sequence must match ``len(targets)``.
     options : :class:`DiscardPrefetchOptions`, optional

cuda_core/docs/source/release/1.0.0-notes.rst

@@ -43,8 +43,7 @@ New features
   single managed :class:`Buffer` or a sequence; with cuda.bindings 12.8+
   the N>1 case dispatches to the corresponding ``cuMem*BatchAsync`` driver
   entry point, addressing the managed-memory portion of #1333. Locations
-  are expressed via :class:`Device` or :class:`Host`; ``int`` values are
-  also accepted (``-1`` maps to host, ``>=0`` to that device ordinal).
+  are expressed via :class:`Device` or :class:`Host`.
   Per-call options use frozen dataclasses
   (:class:`~utils.AdviseOptions`, :class:`~utils.PrefetchOptions`,
   :class:`~utils.DiscardOptions`, :class:`~utils.DiscardPrefetchOptions`)

cuda_core/tests/memory/test_managed_ops.py

@@ -68,7 +68,7 @@ def test_managed_memory_prefetch_supports_managed_pool_allocations(init_cuda):
     buffer = mr.allocate(_MANAGED_TEST_ALLOCATION_SIZE)
     stream = device.create_stream()
 
-    utils.prefetch(buffer, _HOST_LOCATION_ID, stream=stream)
+    utils.prefetch(buffer, Host(), stream=stream)
     stream.sync()
     last_location = _get_int_mem_range_attr(
         buffer,
@@ -143,7 +143,7 @@ def test_managed_memory_discard_prefetch_supports_managed_pool_allocations(init_
     buffer = mr.allocate(_MANAGED_TEST_ALLOCATION_SIZE)
     stream = device.create_stream()
 
-    utils.prefetch(buffer, _HOST_LOCATION_ID, stream=stream)
+    utils.prefetch(buffer, Host(), stream=stream)
     stream.sync()
 
     utils.discard_prefetch(buffer, device, stream=stream)
@@ -166,7 +166,7 @@ def test_managed_memory_discard_prefetch_supports_external_managed_allocations(i
     buffer = DummyUnifiedMemoryResource(device).allocate(_MANAGED_TEST_ALLOCATION_SIZE)
     stream = device.create_stream()
 
-    utils.prefetch(buffer, _HOST_LOCATION_ID, stream=stream)
+    utils.prefetch(buffer, Host(), stream=stream)
     stream.sync()
 
     utils.discard_prefetch(buffer, device, stream=stream)
@@ -227,8 +227,8 @@ def test_managed_memory_advise_location_validation(init_cuda):
     # set_read_mostly works without a location (location is ignored)
     utils.advise(buffer, "set_read_mostly")
 
-    # set_preferred_location requires a location; device ordinal works
-    utils.advise(buffer, "set_preferred_location", device.device_id)
+    # set_preferred_location requires a location; Device works
+    utils.advise(buffer, "set_preferred_location", device)
 
     # set_preferred_location with host location
     utils.advise(buffer, "set_preferred_location", Host())
@@ -241,9 +241,9 @@ def test_managed_memory_advise_location_validation(init_cuda):
     with pytest.raises(ValueError, match="does not support location_type='host_numa_current'"):
         utils.advise(buffer, "set_accessed_by", Host.numa_current())
 
-    # Inferred location from int: -1 maps to host, 0 maps to device
-    utils.advise(buffer, "set_preferred_location", -1)
-    utils.advise(buffer, "set_preferred_location", 0)
+    # Both Host and Device locations are accepted
+    utils.advise(buffer, "set_preferred_location", Host())
+    utils.advise(buffer, "set_preferred_location", Device(0))
 
     buffer.close()
 
@@ -356,18 +356,6 @@ def test_host_numa_current_passthrough(self):
         spec = _coerce_location(Host.numa_current())
         assert spec.kind == "host_numa_current"
 
-    def test_int_device(self):
-        from cuda.core._memory._managed_location import _coerce_location
-
-        spec = _coerce_location(0)
-        assert spec.kind == "device"
-        assert spec.id == 0
-
-    def test_int_minus_one_is_host(self):
-        from cuda.core._memory._managed_location import _coerce_location
-
-        assert _coerce_location(-1).kind == "host"
-
     def test_none_when_disallowed(self):
         from cuda.core._memory._managed_location import _coerce_location
 
@@ -379,16 +367,17 @@ def test_none_when_allowed(self):
 
         assert _coerce_location(None, allow_none=True) is None
 
-    def test_bad_int(self):
+    def test_int_rejected(self):
         from cuda.core._memory._managed_location import _coerce_location
 
-        with pytest.raises(ValueError, match="device ordinal"):
-            _coerce_location(-2)
+        # int shorthand was removed in favor of explicit Device/Host
+        with pytest.raises(TypeError, match="Device, Host, or None"):
+            _coerce_location(0)
 
     def test_bad_type(self):
         from cuda.core._memory._managed_location import _coerce_location
 
-        with pytest.raises(TypeError, match="Device, Host, int, or None"):
+        with pytest.raises(TypeError, match="Device, Host, or None"):
             _coerce_location("device")