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.