From df96cee6b76634fe3055a93569fe2b1d7a67a684 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Tue, 21 Dec 2021 23:21:18 -0500 Subject: [PATCH 1/6] Transform data_type_functions.md to rst --- spec/API_specification/data_type_functions.md | 181 ------------------ .../API_specification/data_type_functions.rst | 27 +++ .../signatures/data_type_functions.py | 147 ++++++++++++++ 3 files changed, 174 insertions(+), 181 deletions(-) delete mode 100644 spec/API_specification/data_type_functions.md create mode 100644 spec/API_specification/data_type_functions.rst create mode 100644 spec/API_specification/signatures/data_type_functions.py diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md deleted file mode 100644 index 69a595b93..000000000 --- a/spec/API_specification/data_type_functions.md +++ /dev/null @@ -1,181 +0,0 @@ -# Data type functions - -> Array API specification for data type functions. - -A conforming implementation of the array API standard must provide and support the following data type functions. - - - -## Objects in API - -(function-astype)= -### astype(x, dtype, /, *, copy=True) - -Copies an array to a specified data type irrespective of {ref}`type-promotion` rules. - -```{note} -Casting floating-point `NaN` and `infinity` values to integral data types is not specified and is implementation-dependent. -``` - -```{note} -When casting a boolean input array to a numeric data type, a value of `True` must cast to a numeric value equal to `1`, and a value of `False` must cast to a numeric value equal to `0`. - -When casting a numeric input array to `bool`, a value of `0` must cast to `False`, and a non-zero value must cast to `True`. -``` - -#### Parameters - -- **x**: _<array>_ - - - array to cast. - -- **dtype**: _<dtype>_ - - - desired data type. - -- **copy**: _<bool>_ - - - specifies whether to copy an array when the specified `dtype` matches the data type of the input array `x`. If `True`, a newly allocated array must always be returned. If `False` and the specified `dtype` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated must be returned. Default: `True`. - -#### Returns - -- **out**: _<array>_ - - - an array having the specified data type. The returned array must have the same shape as `x`. - -(function-broadcast_arrays)= -### broadcast_arrays(*arrays) - -Broadcasts one or more arrays against one another. - -#### Parameters - -- **arrays**: _<array>_ - - - an arbitrary number of to-be broadcasted arrays. - -#### Returns - -- **out**: _List\[ <array> ]_ - - - a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array. - -(function-broadcast_to)= -### broadcast_to(x, /, shape) - -Broadcasts an array to a specified shape. - -#### Parameters - -- **x**: _<array>_ - - - array to broadcast. - -- **shape**: _Tuple\[int, ...]_ - - - array shape. Must be compatible with `x` (see {ref}`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - an array having a specified shape. Must have the same data type as `x`. - -#### Raises - -- if the array is incompatible with the specified shape (see {ref}`broadcasting`). - -(function-can_cast)= -### can_cast(from_, to, /) - -Determines if one data type can be cast to another data type according {ref}`type-promotion` rules. - -#### Parameters - -- **from_**: _Union\[ <dtype>, <array>]_ - - - input data type or array from which to cast. - -- **to**: _<dtype>_ - - - desired data type. - -#### Returns - -- **out**: _bool_ - - - `True` if the cast can occur according to {ref}`type-promotion` rules; otherwise, `False`. - -(function-finfo)= -### finfo(type, /) - -Machine limits for floating-point data types. - -#### Parameters - -- **type**: _Union\[ <dtype>, <array> ]_ - - - the kind of floating-point data-type about which to get information. - -#### Returns - -- **out**: _<finfo object>_ - - - an object having the following attributes: - - - **bits**: _int_ - - number of bits occupied by the floating-point data type. - - **eps**: _float_ - - difference between 1.0 and the next smallest representable floating-point number larger than 1.0 according to the IEEE-754 standard. - - **max**: _float_ - - largest representable number. - - **min**: _float_ - - smallest representable number. - - **smallest_normal**: _float_ - - smallest positive floating-point number with full precision. - -(function-iinfo)= -### iinfo(type, /) - -Machine limits for integer data types. - -#### Parameters - -- **type**: _Union\[ <dtype>, <array> ]_ - - - the kind of integer data-type about which to get information. - -#### Returns - -- **out**: _<iinfo object>_ - - - a class with that encapsules the following attributes: - - - **bits**: _int_ - - number of bits occupied by the type - - **max**: _int_ - - largest representable number. - - **min**: _int_ - - smallest representable number. - -(function-result_type)= -### result_type(*arrays_and_dtypes) - -Returns the dtype that results from applying the type promotion rules -(see {ref}`type-promotion`) to the arguments. - -```{note} -If provided mixed dtypes (e.g., integer and floating-point), the returned dtype will be implementation-specific. -``` - -#### Parameters - -- **arrays_and_dtypes**: _Union\[ <array>, <dtype> \]_ - - - an arbitrary number of input arrays and/or dtypes. - -#### Returns - -- **out**: _<dtype>_ - - - the dtype resulting from an operation involving the input arrays and dtypes. diff --git a/spec/API_specification/data_type_functions.rst b/spec/API_specification/data_type_functions.rst new file mode 100644 index 000000000..3586ea8ec --- /dev/null +++ b/spec/API_specification/data_type_functions.rst @@ -0,0 +1,27 @@ +Data type functions +=================== + + Array API specification for data type functions. + +A conforming implementation of the array API standard must provide and support the following data type functions. + + +Objects in API +-------------- + +.. currentmodule:: signatures.data_type_functions + +.. + NOTE: please keep the functions in alphabetical order + +.. autosummary:: + :toctree: generated + :template: method.rst + + astype + broadcast_arrays + broadcast_to + can_cast + finfo + iinfo + result_type diff --git a/spec/API_specification/signatures/data_type_functions.py b/spec/API_specification/signatures/data_type_functions.py new file mode 100644 index 000000000..7f0d8f11d --- /dev/null +++ b/spec/API_specification/signatures/data_type_functions.py @@ -0,0 +1,147 @@ +from ._types import List, Tuple, Union, array, dtype, finfo_object, iinfo_object + +def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array: + """ + Copies an array to a specified data type irrespective of :ref:`type-promotion` rules. + + Parameters + ---------- + x: array + array to cast. + dtype: dtype + desired data type. + copy: bool + specifies whether to copy an array when the specified ``dtype`` matches the data type of the input array ``x``. If ``True``, a newly allocated array must always be returned. If ``False`` and the specified ``dtype`` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated must be returned. Default: ``True``. + + Returns + ------- + out: array + an array having the specified data type. The returned array must have the same shape as ``x``. + + Notes + ----- + - Casting floating-point ``NaN`` and ``infinity`` values to integral data types is not specified and is implementation-dependent. + - When casting a boolean input array to a numeric data type, a value of ``True`` must cast to a numeric value equal to ``1``, and a value of ``False`` must cast to a numeric value equal to ``0``. + - When casting a numeric input array to ``bool``, a value of ``0`` must cast to ``False``, and a non-zero value must cast to ``True``. + """ + +def broadcast_arrays(*arrays: array) -> List[array]: + """ + Broadcasts one or more arrays against one another. + + Parameters + ---------- + arrays: array + an arbitrary number of to-be broadcasted arrays. + + Returns + ------- + out: List[array] + a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array. + """ + +def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array: + """ + Broadcasts an array to a specified shape. + + Parameters + ---------- + x: array + array to broadcast. + shape: Tuple[int, ...] + array shape. Must be compatible with ``x`` (see :ref:`broadcasting`). + + Returns + ------- + out: array + an array having a specified shape. Must have the same data type as ``x``. + + + **Raises** + + if the array is incompatible with the specified shape (see :ref:`broadcasting`). + """ + +def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool: + """ + Determines if one data type can be cast to another data type according :ref:`type-promotion` rules. + + Parameters + ---------- + from_: Union[dtype, array] + input data type or array from which to cast. + to: dtype + desired data type. + + Returns + ------- + out: bool + ``True`` if the cast can occur according to :ref:`type-promotion` rules; otherwise, ``False``. + """ + +def finfo(type: Union[dtype, array], /) -> finfo_object: + """ + Machine limits for floating-point data types. + + Parameters + ---------- + type: Union[dtype, array] + the kind of floating-point data-type about which to get information. + + Returns + ------- + out: finfo object + an object having the followng attributes: + bits: int + number of bits occupied by the floating-point data type. + eps: float + difference between 1.0 and the next smallest representable floating-point number larger than 1.0 according to the IEEE-754 standard. + max: float + largest representable number. + min: float + smallest representable number. + smallest_normal: float + smallest positive floating-point number with full precision. + """ + +def iinfo(type: Union[dtype, array], /) -> iinfo_object: + """ + Machine limits for integer data types. + + Parameters + ---------- + type: Union[dtype, array] + the kind of integer data-type about which to get information. + + Returns + ------- + out: iinfo object + a class with that encapsules the following attributes: + bits: int + number of bits occupied by the type. + max: int + largest representable number. + min: int + smallest representable number. + """ + +def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: + """ + Returns the dtype that results from applying the type promotion rules (see :ref:`type-promotion`) to the arguments. + + Parameters + ---------- + arrays_and_dtypes: Union[array, dtype] + an arbitrary number of input arrays and/or dtypes. + + Returns + ------- + out: dtype + the dtype resulting from an operation involving the input arrays and dtypes. + + Notes + ----- + - If provided mixed dtypes (e.g., integer and floating-point), the returned dtype will be implementation-specific. + """ + +__all__ = ['astype', 'broadcast_arrays', 'broadcast_to', 'can_cast', 'finfo', 'iinfo', 'result_type'] From 7615488ef288e592967d38427a9b2ae40d6e7d83 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Mon, 17 Jan 2022 12:39:15 -0500 Subject: [PATCH 2/6] Fix title case --- spec/API_specification/data_type_functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/data_type_functions.rst b/spec/API_specification/data_type_functions.rst index 3586ea8ec..4b35a297a 100644 --- a/spec/API_specification/data_type_functions.rst +++ b/spec/API_specification/data_type_functions.rst @@ -1,4 +1,4 @@ -Data type functions +Data Type Functions =================== Array API specification for data type functions. From a32764f335f2489b6737329d417f82ae04794d9e Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Wed, 26 Jan 2022 21:48:10 -0500 Subject: [PATCH 3/6] Update notes and fix non existent labels --- .../signatures/creation_functions.py | 2 +- .../signatures/data_type_functions.py | 21 ++++++++++--------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/spec/API_specification/signatures/creation_functions.py b/spec/API_specification/signatures/creation_functions.py index aa25a24a2..0cb199850 100644 --- a/spec/API_specification/signatures/creation_functions.py +++ b/spec/API_specification/signatures/creation_functions.py @@ -54,7 +54,7 @@ def asarray(obj: Union[array, bool, int, float, NestedSequence, SupportsBufferPr .. admonition:: Note :class: note - If ``dtype`` is not ``None``, then array conversions should obey :ref:`type-promotion` rules. Conversions not specified according to :ref:`type-promotion` rules may or may not be permitted by a conforming array library. To perform an explicit cast, use :ref:`function-astype`. + If ``dtype`` is not ``None``, then array conversions should obey :ref:`type-promotion` rules. Conversions not specified according to :ref:`type-promotion` rules may or may not be permitted by a conforming array library. To perform an explicit cast, use :func:`signatures.data_type_functions.astype`. device: Optional[device] device on which to place the created array. If ``device`` is ``None`` and ``x`` is an array, the output array device must be inferred from ``x``. Default: ``None``. diff --git a/spec/API_specification/signatures/data_type_functions.py b/spec/API_specification/signatures/data_type_functions.py index 7f0d8f11d..ce3be0b9e 100644 --- a/spec/API_specification/signatures/data_type_functions.py +++ b/spec/API_specification/signatures/data_type_functions.py @@ -4,6 +4,14 @@ def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array: """ Copies an array to a specified data type irrespective of :ref:`type-promotion` rules. + .. note:: + Casting floating-point ``NaN`` and ``infinity`` values to integral data types is not specified and is implementation-dependent. + + .. note:: + When casting a boolean input array to a numeric data type, a value of ``True`` must cast to a numeric value equal to ``1``, and a value of ``False`` must cast to a numeric value equal to ``0``. + + When casting a numeric input array to ``bool``, a value of ``0`` must cast to ``False``, and a non-zero value must cast to ``True``. + Parameters ---------- x: array @@ -17,12 +25,6 @@ def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array: ------- out: array an array having the specified data type. The returned array must have the same shape as ``x``. - - Notes - ----- - - Casting floating-point ``NaN`` and ``infinity`` values to integral data types is not specified and is implementation-dependent. - - When casting a boolean input array to a numeric data type, a value of ``True`` must cast to a numeric value equal to ``1``, and a value of ``False`` must cast to a numeric value equal to ``0``. - - When casting a numeric input array to ``bool``, a value of ``0`` must cast to ``False``, and a non-zero value must cast to ``True``. """ def broadcast_arrays(*arrays: array) -> List[array]: @@ -129,6 +131,9 @@ def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: """ Returns the dtype that results from applying the type promotion rules (see :ref:`type-promotion`) to the arguments. + .. note:: + If provided mixed dtypes (e.g., integer and floating-point), the returned dtype will be implementation-specific. + Parameters ---------- arrays_and_dtypes: Union[array, dtype] @@ -138,10 +143,6 @@ def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: ------- out: dtype the dtype resulting from an operation involving the input arrays and dtypes. - - Notes - ----- - - If provided mixed dtypes (e.g., integer and floating-point), the returned dtype will be implementation-specific. """ __all__ = ['astype', 'broadcast_arrays', 'broadcast_to', 'can_cast', 'finfo', 'iinfo', 'result_type'] From b1ced32bce9f07d8c7e07830abe1a48398d8a8b1 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Mon, 31 Jan 2022 13:45:31 -0500 Subject: [PATCH 4/6] Add bullet points --- .../signatures/data_type_functions.py | 48 ++++++++++++------- 1 file changed, 32 insertions(+), 16 deletions(-) diff --git a/spec/API_specification/signatures/data_type_functions.py b/spec/API_specification/signatures/data_type_functions.py index ce3be0b9e..533af8aa8 100644 --- a/spec/API_specification/signatures/data_type_functions.py +++ b/spec/API_specification/signatures/data_type_functions.py @@ -94,16 +94,26 @@ def finfo(type: Union[dtype, array], /) -> finfo_object: ------- out: finfo object an object having the followng attributes: - bits: int - number of bits occupied by the floating-point data type. - eps: float - difference between 1.0 and the next smallest representable floating-point number larger than 1.0 according to the IEEE-754 standard. - max: float - largest representable number. - min: float - smallest representable number. - smallest_normal: float - smallest positive floating-point number with full precision. + + - **bits**: *int* + + number of bits occupied by the floating-point data type. + + - **eps**: *float* + + difference between 1.0 and the next smallest representable floating-point number larger than 1.0 according to the IEEE-754 standard. + + - **max**: *float* + + largest representable number. + + - **min**: *float* + + smallest representable number. + + - **smallest_normal**: *float* + + smallest positive floating-point number with full precision. """ def iinfo(type: Union[dtype, array], /) -> iinfo_object: @@ -119,12 +129,18 @@ def iinfo(type: Union[dtype, array], /) -> iinfo_object: ------- out: iinfo object a class with that encapsules the following attributes: - bits: int - number of bits occupied by the type. - max: int - largest representable number. - min: int - smallest representable number. + + - **bits**: *int* + + number of bits occupied by the type. + + - **max**: *int* + + largest representable number. + + - **min**: *int* + + smallest representable number. """ def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: From 1e4dd7c097e2a8aee121cb161ad0373832881cbb Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Mon, 7 Feb 2022 12:48:47 -0500 Subject: [PATCH 5/6] Remove raises section --- spec/API_specification/signatures/data_type_functions.py | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/spec/API_specification/signatures/data_type_functions.py b/spec/API_specification/signatures/data_type_functions.py index 533af8aa8..9f04915db 100644 --- a/spec/API_specification/signatures/data_type_functions.py +++ b/spec/API_specification/signatures/data_type_functions.py @@ -56,12 +56,7 @@ def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array: Returns ------- out: array - an array having a specified shape. Must have the same data type as ``x``. - - - **Raises** - - if the array is incompatible with the specified shape (see :ref:`broadcasting`). + an array having a specified shape. Must have the same data type as ``x``. If the array is incompatible with the specified shape (see :ref:`broadcasting`), the function should raise an exception. """ def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool: From 5537c93cbb22c0a86aed455ff37244233e6c2265 Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 7 Feb 2022 11:40:56 -0800 Subject: [PATCH 6/6] Move sentence --- spec/API_specification/signatures/data_type_functions.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/signatures/data_type_functions.py b/spec/API_specification/signatures/data_type_functions.py index 9f04915db..2356a8b2e 100644 --- a/spec/API_specification/signatures/data_type_functions.py +++ b/spec/API_specification/signatures/data_type_functions.py @@ -51,12 +51,12 @@ def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array: x: array array to broadcast. shape: Tuple[int, ...] - array shape. Must be compatible with ``x`` (see :ref:`broadcasting`). + array shape. Must be compatible with ``x`` (see :ref:`broadcasting`). If the array is incompatible with the specified shape, the function should raise an exception. Returns ------- out: array - an array having a specified shape. Must have the same data type as ``x``. If the array is incompatible with the specified shape (see :ref:`broadcasting`), the function should raise an exception. + an array having a specified shape. Must have the same data type as ``x``. """ def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool: