Update the docstring of numpy/_array_api/__init__.py

Author: asmeurer

numpy/_array_api/__init__.py

@@ -1,32 +1,35 @@
 """
 A NumPy sub-namespace that conforms to the Python array API standard.
 
+This submodule accompanies NEP 47, which proposes its inclusion in NumPy.
+
 This is a proof-of-concept namespace that wraps the corresponding NumPy
 functions to give a conforming implementation of the Python array API standard
 (https://data-apis.github.io/array-api/latest/). The standard is currently in
 an RFC phase and comments on it are both welcome and encouraged. Comments
 should be made either at https://github.com/data-apis/array-api or at
 https://github.com/data-apis/consortium-feedback/discussions.
 
-This submodule will be accompanied with a NEP (not yet written) proposing its
-inclusion in NumPy.
-
 NumPy already follows the proposed spec for the most part, so this module
 serves mostly as a thin wrapper around it. However, NumPy also implements a
 lot of behavior that is not included in the spec, so this serves as a
 restricted subset of the API. Only those functions that are part of the spec
 are included in this namespace, and all functions are given with the exact
 signature given in the spec, including the use of position-only arguments, and
 omitting any extra keyword arguments implemented by NumPy but not part of the
-spec. Note that the array object itself is unchanged, as implementing a
-restricted subclass of ndarray seems unnecessarily complex for the purposes of
-this namespace, so the API of array methods and other behaviors of the array
-object will include things that are not part of the spec.
-
-The spec is designed as a "minimal API subset" and explicitly allows libraries
-to include behaviors not specified by it. But users of this module that intend
-to write portable code should be aware that only those behaviors that are
-listed in the spec are guaranteed to be implemented across libraries.
+spec. The behavior of some functions is also modified from the NumPy behavior
+to conform to the standard. Note that the underlying array object itself is
+wrapped in a wrapper Array() class, but is otherwise unchanged. This submodule
+is implemented in pure Python with no C extensions.
+
+The array API spec is designed as a "minimal API subset" and explicitly allows
+libraries to include behaviors not specified by it. But users of this module
+that intend to write portable code should be aware that only those behaviors
+that are listed in the spec are guaranteed to be implemented across libraries.
+Consequently, the NumPy implementation was chosen to be both conforming and
+minimal, so that users can use this implementation of the array API namespace
+and be sure that behaviors that it defines will be available in conforming
+namespaces from other libraries.
 
 A few notes about the current state of this submodule:
 
@@ -45,16 +48,10 @@
     not included here, as it requires a full implementation in NumPy proper
     first.
 
-  - np.argmin and np.argmax do not implement the keepdims keyword argument.
-
   - The linear algebra extension in the spec will be added in a future pull
 request.
 
-  - Some tests in the test suite are still not fully correct in that they test
-    all datatypes whereas certain functions are only defined for a subset of
-    datatypes.
-
-  The test suite is yet complete, and even the tests that exist are not
+  The test suite is not yet complete, and even the tests that exist are not
   guaranteed to give a comprehensive coverage of the spec. Therefore, those
   reviewing this submodule should refer to the standard documents themselves.
 
@@ -68,37 +65,45 @@
   dtypes and only those methods that are required by the spec, as well as to
   limit/change certain behavior that differs in the spec. In particular:
 
+  - The array API namespace does not have scalar objects, only 0-d arrays.
+    Operations in on Array that would create a scalar in NumPy create a 0-d
+    array.
+
   - Indexing: Only a subset of indices supported by NumPy are required by the
     spec. The Array object restricts indexing to only allow those types of
     indices that are required by the spec. See the docstring of the
     numpy._array_api.Array._validate_indices helper function for more
     information.
 
   - Type promotion: Some type promotion rules are different in the spec. In
-    particular, the spec does not have any value-based casting. Note that the
-    code to correct the type promotion rules on numpy._array_api.Array is
-    not yet implemented.
+    particular, the spec does not have any value-based casting. The
+    Array._promote_scalar method promotes Python scalars to arrays,
+    disallowing cross-type promotions like int -> float64 that are not allowed
+    in the spec. Array._normalize_two_args works around some type promotion
+    quirks in NumPy, particularly, value-based casting that occurs when one
+    argument of an operation is a 0-d array.
 
 - All functions include type annotations, corresponding to those given in the
-  spec (see _types.py for definitions of the types 'array', 'device', and
-  'dtype'). These do not currently fully pass mypy due to some limitations in
-  mypy.
+  spec (see _types.py for definitions of some custom types). These do not
+  currently fully pass mypy due to some limitations in mypy.
+
+- Dtype objects are just the NumPy dtype objects, e.g., float64 =
+  np.dtype('float64'). The spec does not require any behavior on these dtype
+  objects other than that they be accessible by name and be comparable by
+  equality, but it was considered too much extra complexity to create custom
+  objects to represent dtypes.
 
 - The wrapper functions in this module do not do any type checking for things
-  that would be impossible without leaving the _array_api namespace.
+  that would be impossible without leaving the _array_api namespace. For
+  example, since the array API dtype objects are just the NumPy dtype objects,
+  one could pass in a non-spec NumPy dtype into a function.
 
 - All places where the implementations in this submodule are known to deviate
   from their corresponding functions in NumPy are marked with "# Note"
   comments. Reviewers should make note of these comments.
 
 Still TODO in this module are:
 
-- Implement the spec type promotion rules on the Array object.
-
-- Disable NumPy warnings in the API functions.
-
-- Implement keepdims on argmin and argmax.
-
 - Device support and DLPack support are not yet implemented. These require
   support in NumPy itself first.