Merge with main

data-apis · asmeurer · Jan 20, 2022 · Dec 14, 2021 · Dec 14, 2021 · Dec 14, 2021
commit 3e88dace9b302f4ac1a14a44766b3b91acd68da5
diff --git a/.gitignore b/.gitignore
@@ -3,4 +3,5 @@ build/
 .vscode/
 node_modules/
 __pycache__/
-*.pyc
+*.pyc
+spec/**/generated
diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md
diff --git a/spec/API_specification/constants.md b/spec/API_specification/constants.md
diff --git a/spec/API_specification/constants.rst b/spec/API_specification/constants.rst
@@ -0,0 +1,24 @@
+Constants
+=========
+
+    Array API specification for constants.
+
+A conforming implementation of the array API standard must provide and support the following constants adhering to the following conventions.
+
+-   Each constant must have a Python floating-point data type (i.e., ``float``) and be provided as a Python scalar value.
+
+Objects in API
+--------------
+
+.. currentmodule:: signatures.constants
+
+..
+  NOTE: please keep the functions in alphabetical order
+
+.. autosummary::
+   :toctree: generated
+
+   e
+   inf
+   nan
+   pi
diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
@@ -528,6 +528,12 @@ For floating-point operands,
 
 Calculates the division for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
 
+```{note}
+If one or both of the input arrays have integer data types, the result is implementation-dependent, as type promotion between data type "kinds" (e.g., integer versus floating-point) is unspecified.
+
+Specification-compliant libraries may choose to raise an error or return an array containing the element-wise results. If an array is returned, the array must have a floating-point data type.
+```
+
 #### Special Cases
 
 For floating-point operands,
@@ -1223,7 +1229,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin
 ```{note}
 If both `x1` and `x2` have integer data types, the result of `pow` when `x2_i` is negative (i.e., less than zero) is unspecified and thus implementation-dependent.
 
-If `x1` has an integer data type and `x2` has a floating-point data type, behavior is implementation-dependent (type promotion between data type "kinds" (integer versus floating-point) is unspecified).
+If `x1` has an integer data type and `x2` has a floating-point data type, behavior is implementation-dependent, as type promotion between data type "kinds" (e.g., integer versus floating-point) is unspecified.
 ```
 
 #### Special Cases

diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst
@@ -7,20 +7,20 @@ API specification
    :caption: API specification
    :maxdepth: 3
 
-   function_and_method_signatures
    array_object
-   indexing
-   data_types
-   data_type_functions
-   type_promotion
    broadcasting
+   constants
    creation_functions
-   manipulation_functions
+   data_type_functions
+   data_types
    elementwise_functions
-   statistical_functions
+   function_and_method_signatures
+   indexing
    linear_algebra_functions
+   manipulation_functions
    searching_functions
-   sorting_functions
    set_functions
+   sorting_functions
+   statistical_functions
+   type_promotion
    utility_functions
-   constants
diff --git a/spec/API_specification/signatures/array_object.py b/spec/API_specification/signatures/array_object.py
@@ -761,7 +761,7 @@ def __pow__(self: array, other: Union[int, float, array], /) -> array:
         Notes
         -----
         - If both ``self`` and ``other`` have integer data types, the result of ``__pow__`` when `other_i` is negative (i.e., less than zero) is unspecified and thus implementation-dependent.
-        - If ``self`` has an integer data type and ``other`` has a floating-point data type, behavior is implementation-dependent (type promotion between data type "kinds" (integer versus floating-point) is unspecified).
+        - If ``self`` has an integer data type and ``other`` has a floating-point data type, behavior is implementation-dependent, as type promotion between data type "kinds" (e.g., integer versus floating-point) is unspecified.
         - Element-wise results must equal the results returned by the equivalent element-wise function :ref:`function-pow`.
 
         **Special cases**
@@ -875,6 +875,8 @@ def __truediv__(self: array, other: Union[int, float, array], /) -> array:
         Notes
         -----
         - Element-wise results must equal the results returned by the equivalent element-wise function :ref:`function-divide`.
+        - If one or both of ``self`` and ``other`` have integer data types, the result is implementation-dependent, as type promotion between data type "kinds" (e.g., integer versus floating-point) is unspecified.
+        - Specification-compliant libraries may choose to raise an error or return an array containing the element-wise results. If an array is returned, the array must have a floating-point data type.
 
         **Special cases**
 

diff --git a/spec/API_specification/signatures/constants.py b/spec/API_specification/signatures/constants.py
@@ -0,0 +1,25 @@
+e = 2.718281828459045
+"""
+IEEE 754 floating-point representation of Euler's constant.
+
+``e = 2.71828182845904523536028747135266249775724709369995...``
+"""
+
+inf = float('inf')
+"""
+IEEE 754 floating-point representation of (positive) infinity.
+"""
+
+nan = float('nan')
+"""
+IEEE 754 floating-point representation of Not a Number (``NaN``).
+"""
+
+pi = 3.141592653589793
+"""
+IEEE 754 floating-point representation of the mathematical constant ``π``.
+
+``pi = 3.1415926535897932384626433...``
+"""
+
+__all__ = ['e', 'inf', 'nan', 'pi']
diff --git a/spec/API_specification/statistical_functions.md b/spec/API_specification/statistical_functions.md
@@ -21,7 +21,7 @@ A conforming implementation of the array API standard must provide and support t
 Calculates the maximum value of the input array `x`.
 
 ```{note}
-When the number of elements over which to compute the maximum value is zero, the maximum value is implementation-defined. Specification-compliant libraries may choose to error, return a sentinel value (e.g., if `x` is a floating-point input array, return `NaN`), or return the minimum possible value for the input array `x` data type (e.g., if `x` is a floating-point array, return `-infinity`).
+When the number of elements over which to compute the maximum value is zero, the maximum value is implementation-defined. Specification-compliant libraries may choose to raise an error, return a sentinel value (e.g., if `x` is a floating-point input array, return `NaN`), or return the minimum possible value for the input array `x` data type (e.g., if `x` is a floating-point array, return `-infinity`).
 ```
 
 #### Special Cases
@@ -92,7 +92,7 @@ Let `N` equal the number of elements over which to compute the arithmetic mean.
 Calculates the minimum value of the input array `x`.
 
 ```{note}
-When the number of elements over which to compute the minimum value is zero, the minimum value is implementation-defined. Specification-compliant libraries may choose to error, return a sentinel value (e.g., if `x` is a floating-point input array, return `NaN`), or return the maximum possible value for the input array `x` data type (e.g., if `x` is a floating-point array, return `+infinity`).
+When the number of elements over which to compute the minimum value is zero, the minimum value is implementation-defined. Specification-compliant libraries may choose to raise an error, return a sentinel value (e.g., if `x` is a floating-point input array, return `NaN`), or return the maximum possible value for the input array `x` data type (e.g., if `x` is a floating-point array, return `+infinity`).
 ```
 
 #### Special Cases

diff --git a/spec/Makefile b/spec/Makefile
@@ -12,9 +12,13 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile clean
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	-rm -rf $(BUILDDIR)
+	-rm -rf "$(SOURCEDIR)/API_specification/generated"
diff --git a/spec/conf.py b/spec/conf.py
@@ -47,6 +47,16 @@
 add_module_names = False
 napoleon_custom_sections = [('Returns', 'params_style')]
 
+# Make autosummary show the signatures of functions in the tables using actual
+# Python syntax. There's currently no supported way to do this, so we have to
+# just patch out the function that processes the signatures. See
+# https://github.com/sphinx-doc/sphinx/issues/10053.
+import sphinx.ext.autosummary as autosummary_mod
+if hasattr(autosummary_mod, '_module'):
+        # It's a sphinx deprecated module wrapper object
+    autosummary_mod = autosummary_mod._module
+autosummary_mod.mangle_signature = lambda sig, max_chars=30: sig
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -162,4 +172,4 @@ def process_signature(app, what, name, obj, options, signature, return_annotatio
     return signature, return_annotation
 
 def setup(app):
-    app.connect("autodoc-process-signature", process_signature)
+    app.connect("autodoc-process-signature", process_signature)