diff --git a/array_api_strict/_flags.py b/array_api_strict/_flags.py index f6cef29..8b46374 100644 --- a/array_api_strict/_flags.py +++ b/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 `. + .. 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 - `. Examples -------- 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/changelog.md b/docs/changelog.md index 04c383d..9c5da3c 100644 --- a/docs/changelog.md +++ b/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') + ` 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 + +- 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 diff --git a/docs/index.md b/docs/index.md index fc385d4..a14fbcb 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 @@ -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') + ` or by setting the + environment variable {envvar}`ARRAY_API_STRICT_API_VERSION=2023.12 + `. (numpy.array_api)= ## Relationship to `numpy.array_api`