From a3f6ef690986eecbcb3a6fbfb5d2a5a17fa6a3f3 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 27 Jun 2024 16:04:22 -0600 Subject: [PATCH 01/10] Fix docs build issues --- docs/api.rst | 3 ++- docs/index.md | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index ed702dc..760d11f 100644 --- a/docs/api.rst +++ b/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 diff --git a/docs/index.md b/docs/index.md index fc385d4..3a2edd5 100644 --- a/docs/index.md +++ b/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 @@ -185,7 +185,7 @@ issue, but this hasn't necessarily been tested thoroughly. 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). + {func}`array_api_strict.set_array_api_strict_flags(api_version='2023.12') `. (numpy.array_api)= From 4a02c5a4120a77c1c31c88afe536911c529709f2 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 27 Jun 2024 16:12:47 -0600 Subject: [PATCH 02/10] Use numpydoc-style parameters for set_array_api_strict_flags --- array_api_strict/_flags.py | 84 ++++++++++++++++++++------------------ 1 file changed, 44 insertions(+), 40 deletions(-) diff --git a/array_api_strict/_flags.py b/array_api_strict/_flags.py index f6cef29..1694650 100644 --- a/array_api_strict/_flags.py +++ b/array_api_strict/_flags.py @@ -64,46 +64,50 @@ def set_array_api_strict_flags( 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). - - 2023.12 support is experimental. Some features in 2023.12 may still be - missing, and it hasn't been fully tested. - - - `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). - - - `data_dependent_shapes`: 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 - - - `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) - - 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. - - - `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. + 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}``. + + Note that 2021.12 is supported, but currently gives the same thing as + 2022.12 (except that the fft extension will be disabled). + + 2023.12 support is experimental. Some features in 2023.12 may still be + missing, and it hasn't been fully tested. + + 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). + + 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 + + - `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) + + 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. + + 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 `. From 64e7236ddeef458124f44a1c978d0e98ce1b8223 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 27 Jun 2024 16:13:29 -0600 Subject: [PATCH 03/10] Note about the default version changing in the future --- array_api_strict/_flags.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/array_api_strict/_flags.py b/array_api_strict/_flags.py index 1694650..c61ea1b 100644 --- a/array_api_strict/_flags.py +++ b/array_api_strict/_flags.py @@ -75,7 +75,8 @@ def set_array_api_strict_flags( 2022.12 (except that the fft extension will be disabled). 2023.12 support is experimental. Some features in 2023.12 may still be - missing, and it hasn't been fully tested. + missing, and it hasn't been fully tested. A future version of + array-api-strict will change the default version to 2023.12. boolean_indexing : bool, optional Whether indexing by a boolean array is supported. From 0b47a05c61b1eb34b7385954943fd8ff617a86bd Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 27 Jun 2024 16:23:08 -0600 Subject: [PATCH 04/10] Fix issues with set_array_api_strict_flags docstring --- array_api_strict/_flags.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/array_api_strict/_flags.py b/array_api_strict/_flags.py index c61ea1b..8b46374 100644 --- a/array_api_strict/_flags.py +++ b/array_api_strict/_flags.py @@ -59,6 +59,8 @@ 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 `. + .. note:: This function is **not** part of the array API standard. It only exists @@ -95,8 +97,8 @@ def set_array_api_strict_flags( - `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) + - `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). @@ -110,8 +112,6 @@ def set_array_api_strict_flags( 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 - `. Examples -------- From 8716970263f1be6ad294aec25a95341204eef00d Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 27 Jun 2024 16:26:03 -0600 Subject: [PATCH 05/10] Add changelog entries for 2.0 release --- docs/changelog.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/changelog.md b/docs/changelog.md index 04c383d..3d5bf32 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,5 +1,33 @@ # 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 behavior 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') + ` or setting the environment + variable {envvar}`ARRAY_API_STRICT_API_VERSION=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 From a2cbb4e356a6948deea82797fc85e1d9628c4e5d Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 27 Jun 2024 16:31:06 -0600 Subject: [PATCH 06/10] Small changes to the CHANGELOG --- docs/changelog.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/changelog.md b/docs/changelog.md index 3d5bf32..9c5da3c 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -10,7 +10,7 @@ [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 behavior in the standard. + 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) @@ -20,7 +20,8 @@ {func}`array_api_strict.set_array_api_strict_flags(api_version='2023.12') ` or setting the environment variable {envvar}`ARRAY_API_STRICT_API_VERSION=2023.12 - `. + `. A future version of array-api-strict will + change the default version to 2023.12. ### Minor Changes From b2a395e9b509e15664f212241803fa4c0af94d74 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 27 Jun 2024 16:36:57 -0600 Subject: [PATCH 07/10] NumPy 2.0 is no longer upcoming --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 3a2edd5..a9578a1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 From c68650e29bd31f4335b4d872f46293968d107c04 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 27 Jun 2024 16:37:07 -0600 Subject: [PATCH 08/10] Update some text in the docs index page --- docs/index.md | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/index.md b/docs/index.md index a9578a1..f37479c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -170,23 +170,17 @@ 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). +5. By default, all extensions in the standard are enabled, as well as optional + behaviors such as data-dependent shapes and boolean indexing. These can be + disabled with the [array-api-strict flags](array-api-strict-flags). 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 - {func}`array_api_strict.set_array_api_strict_flags(api_version='2023.12') `. - + 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') + ` or by setting the + environment variable {envvar}`ARRAY_API_STRICT_API_VERSION=2023.12 + `. (numpy.array_api)= ## Relationship to `numpy.array_api` From 50a16699eeea8466fac3a6a5f5083e81482501af Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 27 Jun 2024 16:39:41 -0600 Subject: [PATCH 09/10] Move some text around in the index page --- docs/index.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index f37479c..0465a8d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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,11 +176,7 @@ 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. By default, all extensions in the standard are enabled, as well as optional - behaviors such as data-dependent shapes and boolean indexing. These can be - disabled with the [array-api-strict flags](array-api-strict-flags). - -6. array-api-strict currently uses the 2022.12 version of the array API +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') From eb8dd464eea5873a59f73c109d8e3347918319d7 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 27 Jun 2024 16:40:56 -0600 Subject: [PATCH 10/10] Clarify some text --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 0465a8d..a14fbcb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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)