From 5d24ef34299d5adc27520ba5f42b0e60bf8cc6f8 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Wed, 22 Dec 2021 15:59:09 -0500 Subject: [PATCH 1/3] Transform data_types.md to rst --- spec/API_specification/data_types.md | 165 ------------------ spec/API_specification/data_types.rst | 163 +++++++++++++++++ .../signatures/data_types.py | 20 +++ 3 files changed, 183 insertions(+), 165 deletions(-) delete mode 100644 spec/API_specification/data_types.md create mode 100644 spec/API_specification/data_types.rst create mode 100644 spec/API_specification/signatures/data_types.py diff --git a/spec/API_specification/data_types.md b/spec/API_specification/data_types.md deleted file mode 100644 index de4798b41..000000000 --- a/spec/API_specification/data_types.md +++ /dev/null @@ -1,165 +0,0 @@ -(data-types)= - -# Data Types - -> Array API specification for supported data types. - -A conforming implementation of the array API standard must provide and support the following data types. - -## bool - -Boolean (`True` or `False`). - -## int8 - -An 8-bit signed integer whose values exist on the interval `[-128, +127]`. - -## int16 - -A 16-bit signed integer whose values exist on the interval `[−32,767, +32,767]`. - -## int32 - -A 32-bit signed integer whose values exist on the interval `[−2,147,483,647, +2,147,483,647]`. - -## int64 - -A 64-bit signed integer whose values exist on the interval `[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]`. - -## uint8 - -An 8-bit unsigned integer whose values exist on the interval `[0, +255]`. - -## uint16 - -A 16-bit unsigned integer whose values exist on the interval `[0, +65,535]`. - -## uint32 - -A 32-bit unsigned integer whose values exist on the interval `[0, +4,294,967,295]`. - -## uint64 - -A 64-bit unsigned integer whose values exist on the interval `[0, +18,446,744,073,709,551,615]`. - -## float32 - -IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). - -## float64 - -IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). - -```{note} -IEEE 754-2019 requires support for subnormal (a.k.a., denormal) numbers, which are useful for supporting gradual underflow. However, hardware support for subnormal numbers is not universal, and many platforms (e.g., accelerators) and compilers support toggling denormals-are-zero (DAZ) and/or flush-to-zero (FTZ) behavior to increase performance and to guard against timing attacks. - -Accordingly, subnormal behavior is left unspecified and, thus, implementation-defined. Conforming implementations may vary in their support for subnormal numbers. -``` - -:::{admonition} Future extension -:class: hint -`complex64` and `complex128` data types are expected to be included in the next -version of this standard and to have the following casting rules (will be added -to {ref}`type-promotion`): - -![Type promotion diagram for complex data types in next version](/_static/images/dtype_promotion_complex.png) - -See [array-api/issues/102](https://github.com/data-apis/array-api/issues/102) -for more details. -::: - -```{note} -A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification. -``` - -(data-type-objects)= -## Data Type Objects - -Data types ("dtypes") are objects which are used as `dtype` specifiers in functions and methods (e.g., `zeros((2, 3), dtype=float32)`). - -```{note} -A conforming implementation may add additional methods or attributes to data type objects beyond those described in this specification. -``` - -```{note} -Implementations may provide other ways to specify data types (e.g., `zeros((2, 3), dtype='f4')`) which are not described in this specification; however, in order to ensure portability, array library consumers are recommended to use data type objects as provided by specification conforming array libraries. -``` - -A conforming implementation of the array API standard must provide and support data type objects having the following attributes and methods. - -### Methods - - - -(data-type-method-__eq__)= -### \_\_eq\_\_(self, other, /) - -Computes the truth value of `self == other` in order to test for data type object equality. - -#### Parameters - -- **self**: _<dtype>_ - - - data type instance. May be any supported data type. - -- **other**: _<dtype>_ - - - other data type instance. May be any supported data type. - -#### Returns - -- **out**: _<bool>_ - - - a boolean indicating whether the data type objects are equal. - -(data-type-defaults)= -## Default Data Types - -A conforming implementation of the array API standard must define the following default data types. - -- a default floating-point data type (either `float32` or `float64`). -- a default integer data type (either `int32` or `int64`). -- a default array index data type (either `int32` or `int64`). - -The default floating-point data type must be the same across platforms. - -The default integer data type should be the same across platforms, but the default may vary depending on whether Python is 32-bit or 64-bit. - -The default array index data type may be `int32` on 32-bit platforms, but the default should be `int64` otherwise. - -```{note} -The default data types should be clearly defined in a conforming library's documentation. -``` - -(data-type-categories)= -## Data Type Categories - -For the purpose of organizing functions within this specification, the following data type categories are defined. - -```{note} -Conforming libraries are not required to organize data types according to these categories. These -categories are only intended for use within this specification. -``` - -```{note} -Future versions of the specification will include additional categories for -complex data types. -``` - -### Numeric Data Types - -`int8`, `int16`, `int32`, `int64`, `uint8`, `uint16`, `uint32`, -`uint64`, `float32`, and `float64` (i.e., all data types except for `bool`). - -### Integer Data Types - -`int8`, `int16`, `int32`, `int64`, `uint8`, `uint16`, `uint32`, and -`uint64`. - -### Floating-point Data Types - -`float32` and `float64`. - -### Boolean Data Types - -`bool`. diff --git a/spec/API_specification/data_types.rst b/spec/API_specification/data_types.rst new file mode 100644 index 000000000..d645f9c58 --- /dev/null +++ b/spec/API_specification/data_types.rst @@ -0,0 +1,163 @@ +.. _data-types: + +Data Types +========== + + Array API specification for supported data types. + +A conforming implementation of the array API standard must provide and support the following data types. + +bool +---- + +Boolean (``True`` or ``False``). + +int8 +---- + +An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. + +int16 +----- + +A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. + +int32 +----- + +A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. + +int64 +----- + +A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. + +uint8 +----- + +An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. + +uint16 +------ + +A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. + +uint32 +------ + +A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. + +uint64 +------ + +A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. + +float32 +------- + +IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). + +float64 +------- + +IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). + +.. note:: + IEEE 754-2019 requires support for subnormal (a.k.a., denormal) numbers, which are useful for supporting gradual underflow. However, hardware support for subnormal numbers is not universal, and many platforms (e.g., accelerators) and compilers support toggling denormals-are-zero (DAZ) and/or flush-to-zero (FTZ) behavior to increase performance and to guard against timing attacks. + + Accordingly, subnormal behavior is left unspecified and, thus, implementation-defined. Conforming implementations may vary in their support for subnormal numbers. + +.. admonition:: Future extension + + ``complex64`` and ``complex128`` data types are expected to be included in the next version of this standard and to have the following casting rules (will be added to :ref:`type-promotion`): + + .. image:: /_static/images/dtype_promotion_complex.png + + See `array-api/issues/102 `_ for more details + +.. note:: + A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification. + +.. _data-type-objects: + +Data Type Objects +----------------- + +Data types ("dtypes") are objects which are used as ``dtype`` specifiers in functions and methods (e.g., ``zeros((2, 3), dtype=float32)``). + +.. note:: + A conforming implementation may add additional methods or attributes to data type objects beyond those described in this specification. + +.. note:: + Implementations may provide other ways to specify data types (e.g., ``zeros((2, 3), dtype='f4')``) which are not described in this specification; however, in order to ensure portability, array library consumers are recommended to use data type objects as provided by specification conforming array libraries. + +A conforming implementation of the array API standard must provide and support data type objects having the following attributes and methods. + +Methods +~~~~~~~ + +.. + NOTE: please keep the functions in alphabetical order + +.. currentmodule:: signatures.data_types + +.. autosummary:: + :toctree: generated + :template: method.rst + + __eq__ + + +.. _data-type-defaults: + +Default Data Types +------------------ + +A conforming implementation of the array API standard must define the following default data types. + +- a default floating-point data type (either ``float32`` or ``float64``). +- a default integer data type (either ``int32`` or ``int64``). +- a default array index data type (either ``int32`` or ``int64``). + +The default floating-point data type must be the same across platforms. + +The default integer data type should be the same across platforms, but the default may vary depending on whether Python is 32-bit or 64-bit. + +The default array index data type may be ``int32`` on 32-bit platforms, but the default should be ``int64`` otherwise. + +.. note:: + The default data types should be clearly defined in a conforming library's documentation. + +.. _data-type-categories: + +Data Type Categories +-------------------- + +For the purpose of organizing functions within this specification, the following data type categories are defined. + +.. note:: + Conforming libraries are not required to organize data types according to these categories. These categories are only intended for use within this specification. + +.. note:: + Future versions of the specification will include additional categories for complex data types. + + +Numeric Data Types +~~~~~~~~~~~~~~~~~~ + +``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, ``uint64``, ``float32``, and ``float64`` (i.e., all data types except for ``bool``). + +Integer Data Types +~~~~~~~~~~~~~~~~~~ + +``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, and ``uint64``. + +Floating-point Data Types +~~~~~~~~~~~~~~~~~~~~~~~~~ + +``float32`` and ``float64``. + +Boolean Data Types +~~~~~~~~~~~~~~~~~~ + +``bool``. diff --git a/spec/API_specification/signatures/data_types.py b/spec/API_specification/signatures/data_types.py new file mode 100644 index 000000000..b8a718613 --- /dev/null +++ b/spec/API_specification/signatures/data_types.py @@ -0,0 +1,20 @@ +from ._types import List, Tuple, Union, array, dtype + +def __eq__(self: dtype, other: dtype, /) -> bool: + """ + Computes the truth value of ``self == other`` in order to test for data type object equality. + + Parameters + ---------- + self: dtype + data type instance. May be any supported data type. + other: dtype + other data type instance. May be any supported data type. + + Returns + ------- + out: bool + a boolean indicating whether the data type objects are equal. + """ + +all = [__eq__] \ No newline at end of file From 5b2075421f4707b9ffa2c03b4f57d8017a258aec Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Mon, 10 Jan 2022 14:39:48 -0500 Subject: [PATCH 2/3] Remove unused imports --- spec/API_specification/signatures/data_types.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/signatures/data_types.py b/spec/API_specification/signatures/data_types.py index b8a718613..fd00521f1 100644 --- a/spec/API_specification/signatures/data_types.py +++ b/spec/API_specification/signatures/data_types.py @@ -1,4 +1,4 @@ -from ._types import List, Tuple, Union, array, dtype +from ._types import dtype def __eq__(self: dtype, other: dtype, /) -> bool: """ @@ -17,4 +17,4 @@ def __eq__(self: dtype, other: dtype, /) -> bool: a boolean indicating whether the data type objects are equal. """ -all = [__eq__] \ No newline at end of file +all = [__eq__] From d374b4cbc2038628dfd30b7ae8b249c2ddf8c67c Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Mon, 17 Jan 2022 13:06:00 -0500 Subject: [PATCH 3/3] Add review changes --- spec/API_specification/data_types.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/data_types.rst b/spec/API_specification/data_types.rst index d645f9c58..f40006c4e 100644 --- a/spec/API_specification/data_types.rst +++ b/spec/API_specification/data_types.rst @@ -68,10 +68,11 @@ IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-20 Accordingly, subnormal behavior is left unspecified and, thus, implementation-defined. Conforming implementations may vary in their support for subnormal numbers. .. admonition:: Future extension + :class: admonition tip ``complex64`` and ``complex128`` data types are expected to be included in the next version of this standard and to have the following casting rules (will be added to :ref:`type-promotion`): - .. image:: /_static/images/dtype_promotion_complex.png + .. image:: /_static/images/dtype_promotion_complex.png See `array-api/issues/102 `_ for more details