From c9d2908066bf35c023c22236915448b06f0eb159 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 25 Aug 2020 10:56:33 +0100 Subject: [PATCH 1/2] Add a section on function and method signature conventions This prevents repeating the same information multiple times; we can refer to this instead. --- .../function_and_method_signatures.md | 53 +++++++++++++++++++ spec/API_specification/index.rst | 1 + 2 files changed, 54 insertions(+) create mode 100644 spec/API_specification/function_and_method_signatures.md diff --git a/spec/API_specification/function_and_method_signatures.md b/spec/API_specification/function_and_method_signatures.md new file mode 100644 index 000000000..31af7da5d --- /dev/null +++ b/spec/API_specification/function_and_method_signatures.md @@ -0,0 +1,53 @@ +# Function and method signatures + +Function signatures in this standard adhere to the following: + +1. Positional parameters must be + [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. + Positional-only parameters have no externally-usable name. When a function + accepting positional-only parameters is called, positional arguments are + mapped to these parameters based solely on their order. + + _Rationale: existing libraries have incompatible conventions, and using names + of positional parameters is not normal/recommended practice._ + +2. Optional parameters must be + [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments. + + _Rationale: this leads to more readable code, and it makes it easier to + evolve an API over time by adding keywords without having to worry about + keyword order._ + +3. For functions that have a single positional array parameter, that parameter + is called `x`. For functions that have multiple array parameters, those + parameters are called `xi` with `i = 1, 2, ...` (i.e., `x1`, `x2`). + +4. Type annotations are left out of the signatures themselves for readability; + they are added to the descriptions of individual parameters however. In code + which aims to adhere to the standard, adding type annotations is strongly + recommended. + +A function signature and description will look like: + +``` +funcname(x1, x2, /, *, key1=-1, key2=None) + + Parameters + + x1 : array + description + x2 : array + description + key1 : int + description + key2 : Optional[str] + description + + Returns + + out : array + description +``` + +Method signatures will follow the same conventions and, modulo the addition of +`self`. diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index ae8246799..f20f916fe 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -5,6 +5,7 @@ API specification :caption: API specification :maxdepth: 1 + function_and_method_signatures array_object indexing data_types From 28b1964ba0a7c0168725b64b463c1a87cf63c9a5 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 25 Aug 2020 12:12:45 +0100 Subject: [PATCH 2/2] Add Assumptions section Includes: - hardware and software environments - dependencies (including abstract dependency diagram) - backwards compatibility - production code & interactive use --- .../images/dependency_assumption_diagram.png | Bin 0 -> 37576 bytes spec/assumptions.md | 67 ++++++++++++++++-- 2 files changed, 63 insertions(+), 4 deletions(-) create mode 100644 spec/_static/images/dependency_assumption_diagram.png diff --git a/spec/_static/images/dependency_assumption_diagram.png b/spec/_static/images/dependency_assumption_diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..f77f11f4566198e5f8f9f6059adf30c0da5737ad GIT binary patch literal 37576 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 literal 0 HcmV?d00001 diff --git a/spec/assumptions.md b/spec/assumptions.md index b7157e67d..2e5f6f07d 100644 --- a/spec/assumptions.md +++ b/spec/assumptions.md @@ -1,15 +1,74 @@ # Assumptions -## Hardware environments +## Hardware and software environments +No assumptions on a specific hardware environment are made. It must be possible +to create an array library adhering to this standard that runs (efficiently) on +a variety of different hardware: CPUs with different architectures, GPUs, +distributed systems and TPUs and other emerging accelerators. +The same applies to software environments: it must be possible to create an +array library adhering to this standard that runs efficiently independent of +what compilers, build-time or run-time execution environment, or distribution +and install method is employed. Parallel execution, JIT compilation, and +delayed (lazy) evaluation must all be possible. -## Software environments - +The variety of hardware and software environments puts _constraints_ on choices +made in the API standard. For example, JIT compilers may require output dtypes +of functions to be predictable from input dtypes only rather than input values. ## Dependencies +The only dependency that's assumed in this standard is that on Python itself. +Python >= 3.8 is assumed, motivated by the use of positional-only parameters +(see [function and method signatures](API_specification/function_and_method_signatures.md)). + +Importantly, array libraries are not assumed to be aware of each other, or of +a common array-specific layer. The [use cases](use_cases.md) do not require +such a dependency, and building and evolving an array library is easier without +such a coupling. Facilitation support of multiple array types in downstream +libraries is an important use case however, the assumed dependency structure +for that is: + +![dependency assumptions diagram](_static/images/dependency_assumption_diagram.png) + +Array libraries may know how to interoperate with each other, for example by +constructing their own array type from that of another library or by shared +memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.md)). +This can be done without a dependency though - only adherence to a protocol is +enough. + +Array-consuming libraries will have to depend on one or more array libraries. +That could be a "soft dependency" though, meaning retrieving an array library +namespace from array instances that are passed in, but not explicitly doing +`import arraylib_name`. + + +## Backwards compatibility + +The assumption made during creation of this standard is that libraries are +constrained by backwards compatibility guarantees to their users, and are +likely unwilling to make significant backwards-incompatible changes for the +purpose of conforming to this standard. Therefore it is assumed that the +standard will be made available in a new namespace within each library, or the +library will provide a way to retrieve a module or module-like object that +adheres to this standard. See [How to adopt this API](purpose_and_scope.html#how-to-adopt-this-api) +for more details. + + +## Production code & interactive use +It is assumed that the primary use case is writing production code, for example +in array-consuming libraries. As a consequence, making it easy to ensure that +code is written as intended and has unambiguous semantics is preferred - and +clear exceptions must be raised otherwise. -## Interactive use & production code +It is also assumed that this does not significantly detract from the +interactive user experience. However, in case existing libraries differ in +behavior, the more strict version of that behavior is typically preferred. A +good example is array inputs to functions - while NumPy accepts lists, tuples, +generators, and anything else that could be turned into an array, most other +libraries only accept their own array types. This standard follows the latter choice. +It is likely always possible to put a thin "interactive use convenience layer" +on top of a more strict behavior.