Merge pull request #45 from asmeurer/release

array-api-strict 2.0 release

Author: asmeurer

array_api_strict/_flags.py

@@ -59,54 +59,59 @@ def set_array_api_strict_flags(
     Flags are global variables that enable or disable array-api-strict
     behaviors.
 
+    The flags can also be changed by setting :ref:`environment variables <environment-variables>`.
+
     .. note::
 
        This function is **not** part of the array API standard. It only exists
        in array-api-strict.
 
-    - `api_version`: The version of the standard to use. Supported
-      versions are: ``{supported_versions}``. The default version number is
-      ``{default_version!r}``.
-
-      Note that 2021.12 is supported, but currently gives the same thing as
-      2022.12 (except that the fft extension will be disabled).
+    Parameters
+    ----------
+    api_version : str, optional
+        The version of the standard to use. Supported versions are:
+        ``{supported_versions}``. The default version number is
+        ``{default_version!r}``.
 
-      2023.12 support is experimental. Some features in 2023.12 may still be
-      missing, and it hasn't been fully tested.
+        Note that 2021.12 is supported, but currently gives the same thing as
+        2022.12 (except that the fft extension will be disabled).
 
-    - `boolean_indexing`: Whether indexing by a boolean array is supported.
-      Note that although boolean array indexing does result in data-dependent
-      shapes, this flag is independent of the `data_dependent_shapes` flag
-      (see below).
+        2023.12 support is experimental. Some features in 2023.12 may still be
+        missing, and it hasn't been fully tested. A future version of
+        array-api-strict will change the default version to 2023.12.
 
-    - `data_dependent_shapes`: Whether data-dependent shapes are enabled in
-      array-api-strict.
+    boolean_indexing : bool, optional
+        Whether indexing by a boolean array is supported.
+        Note that although boolean array indexing does result in
+        data-dependent shapes, this flag is independent of the
+        `data_dependent_shapes` flag (see below).
 
-      This flag is enabled by default. Array libraries that use computation
-      graphs may not be able to support functions whose output shapes depend
-      on the input data.
+    data_dependent_shapes : bool, optional
+        Whether data-dependent shapes are enabled in array-api-strict.
+        This flag is enabled by default. Array libraries that use computation
+        graphs may not be able to support functions whose output shapes depend
+        on the input data.
 
-      The functions that make use of data-dependent shapes, and are therefore
-      disabled by setting this flag to False are
+        The functions that make use of data-dependent shapes, and are therefore
+        disabled by setting this flag to False are
 
-      - `unique_all()`, `unique_counts()`, `unique_inverse()`, and `unique_values()`.
-      - `nonzero()`
-      - `repeat()` when the `repeats` argument is an array (requires 2023.12
-        version of the standard)
+        - `unique_all()`, `unique_counts()`, `unique_inverse()`, and `unique_values()`.
+        - `nonzero()`
+        - `repeat()` when the `repeats` argument is an array (requires the
+          2023.12 version of the standard)
 
-      Note that while boolean indexing is also data-dependent, it is
-      controlled by a separate `boolean_indexing` flag (see above).
+        Note that while boolean indexing is also data-dependent, it is
+        controlled by a separate `boolean_indexing` flag (see above).
 
-      See
-      https://data-apis.org/array-api/latest/design_topics/data_dependent_output_shapes.html
-      for more details.
+        See
+        https://data-apis.org/array-api/latest/design_topics/data_dependent_output_shapes.html
+        for more details.
 
-    - `enabled_extensions`: A list of extensions that are enabled in
-      array-api-strict. The default is ``{default_extensions}``. Note that
-      some extensions require a minimum version of the standard.
+    enabled_extensions : list of str, optional
+        A list of extensions that are enabled in array-api-strict. The default
+        is ``{default_extensions}``. Note that some extensions require a
+        minimum version of the standard.
 
-    The flags can also be changed by setting :ref:`environment variables
-    <environment-variables>`.
 
     Examples
     --------

docs/api.rst

@@ -3,6 +3,8 @@ API Reference
 
 .. automodule:: array_api_strict
 
+.. _array-api-strict-flags:
+
 Array API Strict Flags
 ----------------------
 
@@ -12,7 +14,6 @@ Array API Strict Flags
 
 .. autofunction:: get_array_api_strict_flags
 
-.. _set_array_api_strict_flags:
 .. autofunction:: set_array_api_strict_flags
 .. autofunction:: reset_array_api_strict_flags
 .. autoclass:: ArrayAPIStrictFlags

docs/changelog.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 2.0 (2024-06-27)
+
+### Major Changes
+
+- array-api-strict has a new set of [flags](array-api-strict-flags) that can
+  be used to dynamically enable or disable features in array-api-strict. These
+  flags allow you to change the supported array API version, enable or disable
+  [extensions](https://data-apis.org/array-api/latest/extensions/index.html),
+  enable or disable features that rely on data-dependent shapes, and enable or
+  disable boolean indexing. Future versions may add additional flags to allow
+  changing other optional or varying behaviors in the standard.
+
+- Added experimental support for the
+  [2023.12](https://data-apis.org/array-api/2023.12/changelog.html#v2023-12)
+  version of the array API standard. The default version is still 2022.12, but
+  the version can be changed to 2023.12 using the aforementioned flags, either
+  by calling
+  {func}`array_api_strict.set_array_api_strict_flags(api_version='2023.12')
+  <array_api_strict.set_array_api_strict_flags>` or setting the environment
+  variable {envvar}`ARRAY_API_STRICT_API_VERSION=2023.12
+  <ARRAY_API_STRICT_API_VERSION>`. A future version of array-api-strict will
+  change the default version to 2023.12.
+
+### Minor Changes
+
+- Calling `iter()` on an array now correctly raises `TypeError`.
+
+- Add some missing names to `__all__`.
+
 ## 1.1.1 (2024-04-29)
 
 - Fix the `api_version` argument to `__array_namespace__` to accept

docs/index.md

@@ -20,7 +20,7 @@ array-api-strict currently supports the
 version of the standard. Experimental
 [2023.12](https://data-apis.org/array-api/latest/changelog.html#v2023-12)
 support is implemented, [but must be enabled with a
-flag](set_array_api_strict_flags).
+flag](array-api-strict-flags).
 
 ## Install
 
@@ -37,7 +37,7 @@ and [Conda-forge](https://anaconda.org/conda-forge/array-api-strict)
 conda install --channel conda-forge array-api-strict
 ```
 
-array-api-strict supports NumPy 1.26 and (the upcoming) NumPy 2.0.
+array-api-strict supports NumPy 1.26 and NumPy 2.0.
 
 ## Rationale
 
@@ -109,7 +109,7 @@ strict/minimal:
   like `sin` will accept integer array inputs, but the [standard only requires
   them to accept floating-point
   inputs](https://data-apis.org/array-api/latest/API_specification/generated/array_api.sin.html#array_api.sin),
-  so in array-api-strict, `sin(integer_array)` will raise an exception.
+  so in array-api-strict, `sin(asarray(0))` will raise an exception.
 
 - The
   [indexing](https://data-apis.org/array-api/latest/API_specification/indexing.html)
@@ -131,6 +131,12 @@ strict/minimal:
   functions](https://data-apis.org/array-api/latest/API_specification/creation_functions.html)
   such as `asarray`.
 
+- Optional behavior such as [optional
+  extensions](https://data-apis.org/array-api/latest/extensions/index.html),
+  functions that use data-dependent shapes, and boolean indexing are enabled
+  by default but can disabled with the [array-api-strict
+  flags](array-api-strict-flags).
+
 ## Caveats
 
 array-api-strict is a thin pure Python wrapper around NumPy. NumPy 2.0 fully
@@ -170,23 +176,13 @@ issue, but this hasn't necessarily been tested thoroughly.
    this deviation may be tested with type checking. This [behavior may improve
    in the future](https://github.com/data-apis/array-api-strict/issues/6).
 
-5. There are some behaviors in the standard that are not required to be
-   implemented by libraries that cannot support [data dependent
-   shapes](https://data-apis.org/array-api/latest/design_topics/data_dependent_output_shapes.html).
-   This includes [the `unique_*`
-   functions](https://data-apis.org/array-api/latest/API_specification/set_functions.html),
-   [boolean array
-   indexing](https://data-apis.org/array-api/latest/API_specification/indexing.html#boolean-array-indexing),
-   and the
-   [`nonzero`](https://data-apis.org/array-api/latest/API_specification/generated/array_api.nonzero.html)
-   function. array-api-strict currently implements all of these. In the
-   future, [there may be a way to disable them](https://github.com/data-apis/array-api-strict/issues/7).
-
-6. array-api-strict currently uses the 2022.12 version of the array API
-   standard. Support for 2023.12 is implemented but is still experimental and
-   not fully tested. It can be enabled with
-   [`array_api_strict.set_array_api_strict_flags(api_version='2023.12')`](set_array_api_strict_flags).
-
+5. array-api-strict currently uses the 2022.12 version of the array API
+   standard by default. Support for 2023.12 is implemented but is still
+   experimental and not fully tested. It can be enabled with
+   {func}`array_api_strict.set_array_api_strict_flags(api_version='2023.12')
+   <array_api_strict.set_array_api_strict_flags>` or by setting the
+   environment variable {envvar}`ARRAY_API_STRICT_API_VERSION=2023.12
+   <ARRAY_API_STRICT_API_VERSION>`.
 
 (numpy.array_api)=
 ## Relationship to `numpy.array_api`