From 75364b3ec871f127749a4f271b352e32f3d0017c Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Thu, 4 Aug 2022 13:50:08 +0200 Subject: [PATCH] Describe what extensions are and how to use themo Note that an alternative idea discussed earlier was a separate function `get_extension()`, but IIRC that was not considered a good idea. Now that we have module-level `__getattr__`'s, it should not be a problem for any library to use a specified name like `linalg` or `fft`. Whether the functions in the `linalg` extensions should all be required to exist or not was discussed in gh-403 (no clear conclusion there). One option discussed there to deal with hard to implement or more niche APIs is to create a separate status/label or some other way to track desired signatures (details to be worked out if we want to go that way). --- spec/extensions/index.rst | 25 ++++++++++++++++++-- spec/extensions/linear_algebra_functions.rst | 17 +++++++++++++ 2 files changed, 40 insertions(+), 2 deletions(-) diff --git a/spec/extensions/index.rst b/spec/extensions/index.rst index 1b3b7470f..b8e11eb6f 100644 --- a/spec/extensions/index.rst +++ b/spec/extensions/index.rst @@ -3,8 +3,29 @@ Extensions ========== +Extensions are coherent sets of functionality that are commonly implemented +across array libraries. Each array library supporting this standard may, but is +not required to, implement an extension. If an extension is supported, it +must be accessible inside the main array API supporting namespace as a separate +namespace. + +Extension module implementors must aim to provide all functions and other +public objects in an extension. The rationale for this is that downstream usage +can then check whether or not the extension is present (using ``hasattr(xp, +'extension_name')`` should be enough), and can then assume that functions are +implemented. This in turn makes it also easy for array-consuming libraries to +document which array libraries they support - e.g., "all libraries implementing +the array API standard and its linear algebra extension". + +The mechanism through which the extension namespace is made available is up to +the implementer, e.g. via a regular submodule that is imported under the +``linalg`` name, or via a module-level ``__getattr__``. + + +Extensions +---------- + .. toctree:: - :caption: Extensions - :maxdepth: 3 + :maxdepth: 1 linear_algebra_functions diff --git a/spec/extensions/linear_algebra_functions.rst b/spec/extensions/linear_algebra_functions.rst index dbe643bed..c91ce021d 100644 --- a/spec/extensions/linear_algebra_functions.rst +++ b/spec/extensions/linear_algebra_functions.rst @@ -5,6 +5,23 @@ Linear Algebra Extension Array API specification for linear algebra functions. +Extension name and usage +------------------------ + +The name of the namespace providing the extension must be: ``linalg``. + +If implemented, this ``linalg`` extension must be retrievable via:: + + >>> xp = x.__array_namespace__() + >>> if hasattr(xp, 'linalg'): + >>> # Use `xp.linalg` + + +General syntax and semantics rules +---------------------------------- + +.. TODO: get rid of this here, it's duplicated over and over + A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. - Positional parameters must be `positional-only `_ 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.