API Reference

array_api_strict is a strict, minimal implementation of the Python array API (https://data-apis.org/array-api/latest/)

The purpose of array-api-strict is to provide an implementation of the array API for consuming libraries to test against so they can be completely sure their usage of the array API is portable.

It is not intended to be used by end-users. End-users of the array API should just use their favorite array library (NumPy, CuPy, PyTorch, etc.) as usual. It is also not intended to be used as a dependency by consuming libraries. Consuming library code should use the array-api-compat (https://data-apis.org/array-api-compat/) package to support the array API. Rather, it is intended to be used in the test suites of consuming libraries to test their array API usage.

Array API Strict Flags

These functions configure global flags that allow array-api-strict to be used in different “modes”. These modes include

  • Changing to different supported versions of the standard.

  • Enabling or disabling different optional behaviors (such as data-dependent shapes).

  • Enabling or disabling different optional extensions.

None of these functions are part of the standard itself. A typical array API library will only support one particular configuration of these flags.

array_api_strict.get_array_api_strict_flags()

Get the current array-api-strict flags.

Note

This function is not part of the array API standard. It only exists in array-api-strict.

Note

The inspection API provides a portable way to access most of this information. However, it is only present in standard versions starting with 2023.12. The array API version can be accessed portably using xp.__array_api_version__.

Returns:

dict – A dictionary containing the current array-api-strict flags.

Examples

>>> from array_api_strict import get_array_api_strict_flags
>>> flags = get_array_api_strict_flags()
>>> flags
{'api_version': '2022.12',
 'boolean_indexing': True,
 'data_dependent_shapes': True,
 'enabled_extensions': ('linalg', 'fft')
}

See also

set_array_api_strict_flags

Set one or more flags to a given value.

reset_array_api_strict_flags

Reset the flags to their default values.

ArrayAPIStrictFlags

A context manager to temporarily set the flags.

array_api_strict.set_array_api_strict_flags(*, api_version=None, boolean_indexing=None, data_dependent_shapes=None, enabled_extensions=None)

Set the array-api-strict flags to the specified values.

Flags are global variables that enable or disable array-api-strict behaviors.

The flags can also be changed by setting environment variables.

Note

This function is not part of the array API standard. It only exists in array-api-strict.

Parameters:

  • api_version (str, optional) – The version of the standard to use. Supported versions are: ('2021.12', '2022.12', '2023.12'), plus the draft version 2024.12. The default version number is '2023.12'.

    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 (bool, optional) – Whether indexing by a boolean array is supported. This flag is enabled by default. 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 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).

    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 ('linalg', 'fft'). Note that some extensions require a minimum version of the standard.

Examples

>>> from array_api_strict import set_array_api_strict_flags

>>> # Set the standard version to 2021.12
>>> set_array_api_strict_flags(api_version="2021.12")

>>> # Disable data-dependent shapes and boolean indexing
>>> set_array_api_strict_flags(data_dependent_shapes=False, boolean_indexing=False)

>>> # Enable only the linalg extension (disable the fft extension)
>>> set_array_api_strict_flags(enabled_extensions=["linalg"])

See also

get_array_api_strict_flags

Get the current values of flags.

reset_array_api_strict_flags

Reset the flags to their default values.

ArrayAPIStrictFlags

A context manager to temporarily set the flags.

array_api_strict.reset_array_api_strict_flags()

Reset the array-api-strict flags to their default values.

This will also reset any flags that were set by environment variables back to their default values.

Note

This function is not part of the array API standard. It only exists in array-api-strict.

See set_array_api_strict_flags() for a list of flags and their default values.

Examples

>>> from array_api_strict import reset_array_api_strict_flags
>>> reset_array_api_strict_flags()

See also

get_array_api_strict_flags

Get the current values of flags.

set_array_api_strict_flags

Set one or more flags to a given value.

ArrayAPIStrictFlags

A context manager to temporarily set the flags.

class array_api_strict.ArrayAPIStrictFlags(*, api_version=None, boolean_indexing=None, data_dependent_shapes=None, enabled_extensions=None)

A context manager to temporarily set the array-api-strict flags.

Note

This class is not part of the array API standard. It only exists in array-api-strict.

See set_array_api_strict_flags() for a description of the available flags.

Examples

>>> from array_api_strict import ArrayAPIStrictFlags, get_array_api_strict_flags
>>> with ArrayAPIStrictFlags(api_version="2022.12", boolean_indexing=False):
...     flags = get_array_api_strict_flags()
>>> flags
{'api_version': '2022.12',
 'boolean_indexing': False,
 'data_dependent_shapes': True,
 'enabled_extensions': ('linalg', 'fft')
}

See also

get_array_api_strict_flags

Get the current values of flags.

set_array_api_strict_flags

Set one or more flags to a given value.

reset_array_api_strict_flags

Reset the flags to their default values.

Environment Variables

Flags can also be set with environment variables. set_array_api_strict_flags() will override the values set by environment variables. Note that the environment variables will only change the defaults used by array-api-strict initially. They will not change the defaults used by reset_array_api_strict_flags().

ARRAY_API_STRICT_API_VERSION

A string representing the version number.

ARRAY_API_STRICT_BOOLEAN_INDEXING

“True” or “False” to enable or disable boolean indexing.

ARRAY_API_STRICT_DATA_DEPENDENT_SHAPES

“True” or “False” to enable or disable data dependent shapes.

ARRAY_API_STRICT_ENABLED_EXTENSIONS

A comma separated list of extensions to enable.

Array API Functions

All functions and methods in the array API standard are implemented in array-api-strict. See the Array API Standard for full documentation for each function.