From b5f6c0ee785060931b4e6cfbca44ab6cec319520 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 19 May 2026 18:43:05 -0400 Subject: [PATCH 1/2] Follow-on to cuda.core AGENTS.md --- cuda_core/AGENTS.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/cuda_core/AGENTS.md b/cuda_core/AGENTS.md index 77edde4da3..121646958a 100644 --- a/cuda_core/AGENTS.md +++ b/cuda_core/AGENTS.md @@ -125,12 +125,19 @@ Python or Cython type annotations should be included for all public APIs. Avoid the use of `Any` unless absolutely necessary. The argument and return types as defined in the docstrings should match the type annotations. +The use of `if typing.TYPE_CHECK:` blocks is often necessary to avoid import +cycles. However, this can occasionally mask symbols used by Sphinx to make +cross-references in the docs. If importing an object doesn't create a cycle, it +should be imported outside of an `if typing.TYPE_CHECK:` block, even if it is +only used in type annotations. + ### Semantics -Designs involving manual resource management should be avoided. Where -appropriate, provide context managers (implemented with `__enter__` and -`__exit__`, not `contextlib.contextmanager`) or RAII using a `__del__` or -`__dealloc__` method. +APIs should exist for both manual resource management (such as `close()`) and +automatic resource management, using context managers or destructors where +appropriate. Context managers should be implemented with `__enter__` and +`__exit__`, not `contextlib.contextmanager`. For destructors use `__dealloc__` +where possible, otherwise `__del__`. ### Documentation From fba9163015a4b8cd8f8018e1d854fdddc4bb2f51 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 19 May 2026 19:38:18 -0400 Subject: [PATCH 2/2] Update cuda_core/AGENTS.md --- cuda_core/AGENTS.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/cuda_core/AGENTS.md b/cuda_core/AGENTS.md index 121646958a..2e7391b2b8 100644 --- a/cuda_core/AGENTS.md +++ b/cuda_core/AGENTS.md @@ -125,11 +125,7 @@ Python or Cython type annotations should be included for all public APIs. Avoid the use of `Any` unless absolutely necessary. The argument and return types as defined in the docstrings should match the type annotations. -The use of `if typing.TYPE_CHECK:` blocks is often necessary to avoid import -cycles. However, this can occasionally mask symbols used by Sphinx to make -cross-references in the docs. If importing an object doesn't create a cycle, it -should be imported outside of an `if typing.TYPE_CHECK:` block, even if it is -only used in type annotations. +Python imports should generally be outside of an if typing.TYPE_CHECK: block, even if the imported object is only used in type annotations. Use if typing.TYPE_CHECK: only to avoid creating import cycles. (This guidance maximizes compatibility with the cross-reference mechanisms in Sphinx.) ### Semantics