@@ -63,3 +63,82 @@ This file describes `cuda_core`, the high-level Pythonic CUDA subpackage in the
6363 call-site consistency.
6464- Prefer explicit error propagation over silent fallback paths.
6565- If you change public behavior, update tests and docs under ` docs/source/ ` .
66+
67+ ## API design guidelines
68+
69+ These are some API design guidelines we try to follow when adding new APIs to
70+ ` cuda.core ` . These rules only apply to public APIs. Private implementation
71+ details can violate these rules at any time.
72+
73+ Public APIs are defined as symbols defined in ` __all__ ` within modules or
74+ subpackages that are not prefixed with ` _ ` .
75+
76+ In code reviews, any violations of this section should be considered
77+ suggestions, not hard rules. Consistency with existing API design in this code
78+ base is also important.
79+
80+ ### Unintentional exposure of symbols
81+
82+ The following things should not be exposed as part of the public API:
83+
84+ - Private symbols (prefixed with ` _ ` )
85+ - Symbols from a third-party module or the standard library
86+ - Helper classes that can not be instantiated from Python
87+
88+ ### Naming
89+
90+ As a blanket rule, we follow the naming guidelines for capitalization in PEP 8.
91+
92+ Naming should be consistent. We should use the same English words for the same
93+ concepts throughout the public API. When abbreviations are used, they should be
94+ commonly understood, and they should also be used consistently across the public
95+ API.
96+
97+ For all attributes of a class:
98+
99+ - Properties and member variables should be nouns
100+ - Methods should be verbs
101+ - Methods that take no arguments, are idempotent and cheap (O(1) or trivial),
102+ and do not mutate observable state should be properties
103+
104+ Make sure conceptual pairs match, e.g. add/remove, get/set, create/delete,
105+ alloc/free.
106+
107+ Free functions should be verbs.
108+
109+ ### Enumerations
110+
111+ Enumerations from the underlying ` cuda_bindings ` should not be re-exposed.
112+ Instead, a new ` StrEnum ` subclass should be used to define the values. Anywhere
113+ a ` StrEnum ` is accepted as an argument, a ` str ` should also be acceptable. An
114+ invalid value should raise an exception. When a function returns a ` str ` drawn
115+ from a small number of values, return a ` StrEnum ` subclass instead.
116+
117+ ### Exception handling
118+
119+ Raising exceptions is preferred over a C-style return code that must be checked
120+ by the user.
121+
122+ ### Type annotations
123+
124+ Python or Cython type annotations should be included for all public APIs. Avoid
125+ the use of ` Any ` unless absolutely necessary. The argument and return types as
126+ defined in the docstrings should match the type annotations.
127+
128+ ### Semantics
129+
130+ Designs involving manual resource management should be avoided. Where
131+ appropriate, provide context managers (implemented with ` __enter__ ` and
132+ ` __exit__ ` , not ` contextlib.contextmanager ` ) or RAII using a ` __del__ ` or
133+ ` __dealloc__ ` method.
134+
135+ ### Documentation
136+
137+ The entirety of the public API should be documented in ` api.rst ` or one of the
138+ subpages linked from it. Classes that are not directly instantiable but which
139+ may be returned through the public API should be documented in ` api_private.rst `
140+ so that they are documented but don't appear in the main index.
141+
142+ ### API stability
143+
144+ Reviews should point out where existing public APIs are broken.
0 commit comments