diff --git a/spec/API_specification/array_object.rst b/spec/API_specification/array_object.rst index b45e41987..b15bbdc43 100644 --- a/spec/API_specification/array_object.rst +++ b/spec/API_specification/array_object.rst @@ -5,14 +5,7 @@ Array object Array API specification for array object attributes and methods. -A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods adhering to the following conventions. - -* Positional parameters must be `positional-only `_ parameters. Positional-only parameters have no externally-usable name. When a method accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. -* Optional parameters must be `keyword-only `_ arguments. -* Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. -* Unless stated otherwise, methods must support the data types defined in :ref:`data-types`. -* Unless stated otherwise, methods must adhere to the type promotion rules defined in :ref:`type-promotion`. -* Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. +A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods. Furthermore, a conforming implementation of the array API standard must support array objects of arbitrary rank ``N`` (i.e., number of dimensions), where ``N`` is greater than or equal to zero. diff --git a/spec/API_specification/creation_functions.rst b/spec/API_specification/creation_functions.rst index 9984ff04c..ff5c06368 100644 --- a/spec/API_specification/creation_functions.rst +++ b/spec/API_specification/creation_functions.rst @@ -3,10 +3,8 @@ Creation Functions Array API specification for creating arrays. -A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. +A conforming implementation of the array API standard must provide and support the following functions. -- 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. -- Optional parameters must be `keyword-only `_ arguments. Objects in API -------------- diff --git a/spec/API_specification/elementwise_functions.rst b/spec/API_specification/elementwise_functions.rst index 1f6e818a6..bc21e14b9 100644 --- a/spec/API_specification/elementwise_functions.rst +++ b/spec/API_specification/elementwise_functions.rst @@ -5,17 +5,6 @@ Element-wise Functions Array API specification for element-wise functions. -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. -- Optional parameters must be `keyword-only `_ arguments. -- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. -- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. -- Functions may only be required for a subset of input data type. Libraries may choose to implement functions for additional data types, but that behavior is not required by the specification. See :ref:`data-type-categories`. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. -- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. -- Unless stated otherwise, element-wise mathematical functions must satisfy the minimum accuracy requirements defined in :ref:`accuracy`. - Objects in API -------------- diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index bbb96c8a9..603131ab9 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -3,6 +3,18 @@ API specification ================= +A conforming implementation of the array API standard must provide and support the APIs and behavior detailed in this specification while adhering to the following conventions. + +- When a function signature includes a `/`, positional parameters must be `positional-only `_ parameters. See :ref:`function-and-method-signatures`. +- When a function signature includes a `*`, optional parameters must be `keyword-only `_ arguments. See :ref:`function-and-method-signatures`. +- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. +- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. +- Functions may only be required for a subset of input data types. Libraries may choose to implement functions for additional data types, but that behavior is not required by the specification. See :ref:`data-type-categories`. +- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. +- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. +- Unless stated otherwise, element-wise mathematical functions must satisfy the minimum accuracy requirements defined in :ref:`accuracy`. + + .. toctree:: :caption: API specification :maxdepth: 3 diff --git a/spec/API_specification/indexing_functions.rst b/spec/API_specification/indexing_functions.rst index 264b787ae..aef298566 100644 --- a/spec/API_specification/indexing_functions.rst +++ b/spec/API_specification/indexing_functions.rst @@ -5,13 +5,8 @@ Indexing Functions Array API specification for functions for indexing arrays. -A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. +A conforming implementation of the array API standard must provide and support the following functions. -- 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. -- Optional parameters must be `keyword-only `_ arguments. -- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. -- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. Objects in API -------------- diff --git a/spec/API_specification/linear_algebra_functions.rst b/spec/API_specification/linear_algebra_functions.rst index 9bae18e77..04d36f50a 100644 --- a/spec/API_specification/linear_algebra_functions.rst +++ b/spec/API_specification/linear_algebra_functions.rst @@ -3,14 +3,8 @@ Linear Algebra Functions Array API specification for linear algebra functions. -A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. +A conforming implementation of the array API standard must provide and support the following functions. -* 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. -* Optional parameters must be `keyword-only `_ arguments. -* Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. -* Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. -* Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. -* Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. .. currentmodule:: array_api diff --git a/spec/API_specification/manipulation_functions.rst b/spec/API_specification/manipulation_functions.rst index 86f708a86..4f43f0835 100644 --- a/spec/API_specification/manipulation_functions.rst +++ b/spec/API_specification/manipulation_functions.rst @@ -3,11 +3,8 @@ Manipulation Functions Array API specification for manipulating arrays. -A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. +A conforming implementation of the array API standard must provide and support the following functions. -- 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. -- Optional parameters must be `keyword-only `_ arguments. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. Objects in API -------------- diff --git a/spec/API_specification/searching_functions.rst b/spec/API_specification/searching_functions.rst index bf09e4c8a..01ab4e82a 100644 --- a/spec/API_specification/searching_functions.rst +++ b/spec/API_specification/searching_functions.rst @@ -5,13 +5,8 @@ Searching Functions Array API specification for functions for searching arrays. -A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. +A conforming implementation of the array API standard must provide and support the following functions. -- 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. -- Optional parameters must be `keyword-only `_ arguments. -- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. -- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. Objects in API -------------- diff --git a/spec/API_specification/set_functions.rst b/spec/API_specification/set_functions.rst index b7072d100..addf31e1f 100644 --- a/spec/API_specification/set_functions.rst +++ b/spec/API_specification/set_functions.rst @@ -3,11 +3,8 @@ Set Functions Array API specification for creating and operating on sets. -A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. +A conforming implementation of the array API standard must provide and support the following functions. -- 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. -- Optional parameters must be `keyword-only `_ arguments. -- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. Objects in API -------------- diff --git a/spec/API_specification/sorting_functions.rst b/spec/API_specification/sorting_functions.rst index 19d7fb439..ad3af8857 100644 --- a/spec/API_specification/sorting_functions.rst +++ b/spec/API_specification/sorting_functions.rst @@ -3,11 +3,8 @@ Sorting Functions Array API specification for sorting functions. -A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. +A conforming implementation of the array API standard must provide and support the following functions. -* 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. -* Optional parameters must be `keyword-only `_ arguments. -* Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. .. note:: diff --git a/spec/API_specification/statistical_functions.rst b/spec/API_specification/statistical_functions.rst index 6734506ed..23cd2cb1d 100644 --- a/spec/API_specification/statistical_functions.rst +++ b/spec/API_specification/statistical_functions.rst @@ -3,14 +3,8 @@ Statistical Functions Array API specification for statistical functions. -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. -- Optional parameters must be `keyword-only `_ arguments. -- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. -- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. -- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. +A conforming implementation of the array API standard must provide and support the following functions. + Objects in API -------------- diff --git a/spec/API_specification/utility_functions.rst b/spec/API_specification/utility_functions.rst index f869b4321..5105fa3df 100644 --- a/spec/API_specification/utility_functions.rst +++ b/spec/API_specification/utility_functions.rst @@ -3,14 +3,8 @@ Utility Functions Array API specification for utility functions. -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. -- Optional parameters must be `keyword-only `_ arguments. -- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. -- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. -- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. +A conforming implementation of the array API standard must provide and support the following functions. + Objects in API -------------- diff --git a/spec/extensions/fourier_transform_functions.rst b/spec/extensions/fourier_transform_functions.rst index e048dbfad..170ae390b 100644 --- a/spec/extensions/fourier_transform_functions.rst +++ b/spec/extensions/fourier_transform_functions.rst @@ -3,18 +3,23 @@ Fourier transform Functions Array API specification for Fourier transform functions. -A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. +Extension name and usage +------------------------ + +The name of the namespace providing the extension must be: ``fft``. + +If implemented, this ``fft`` extension must be retrievable via:: + + >>> xp = x.__array_namespace__() + >>> if hasattr(xp, 'fft'): + >>> # Use `xp.fft` -- 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. -- Optional parameters must be `keyword-only `_ arguments. -- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. -- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. -- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. Objects in API -------------- +A conforming implementation of this ``fft`` extension must provide and support the following functions. + .. currentmodule:: array_api.fft .. diff --git a/spec/extensions/index.rst b/spec/extensions/index.rst index 706820f3b..30d9cfa90 100644 --- a/spec/extensions/index.rst +++ b/spec/extensions/index.rst @@ -21,6 +21,9 @@ 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__``. +The functions in an extension must adhere to the same conventions as those in +the array API standard. See :ref:`api-specification`. + Extensions ---------- diff --git a/spec/extensions/linear_algebra_functions.rst b/spec/extensions/linear_algebra_functions.rst index c91ce021d..6759b2260 100644 --- a/spec/extensions/linear_algebra_functions.rst +++ b/spec/extensions/linear_algebra_functions.rst @@ -17,20 +17,6 @@ If implemented, this ``linalg`` extension must be retrievable via:: >>> # 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. -- Optional parameters must be `keyword-only `_ arguments. -- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. -- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. -- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. - Design Principles ----------------- @@ -95,6 +81,9 @@ Accordingly, the standardization process affords the opportunity to reduce inter Objects in API -------------- + +A conforming implementation of this ``linalg`` extension must provide and support the following functions. + .. NOTE: please keep the functions in alphabetical order