Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: clarify copy kwarg behavior in asarray for libraries disallowing mutation #886

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

docs: clarify copy kwarg behavior in asarray for libraries disallowing mutation #886

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
861b28c
docs: clarify `copy` kwarg behavior in `asarray` for libraries disall…
kgryte Jan 23, 2025
5dc7223
docs: fix stray note
kgryte Jan 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 7 additions & 8 deletions src/array_api_stubs/_draft/creation_functions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,19 +100,15 @@ def asarray(

Default: ``None``.

.. 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 :func:`array_api.astype`.

.. note::
If an input value exceeds the precision of the resolved output array data type, behavior is left unspecified and, thus, implementation-defined.

device: Optional[device]
device on which to place the created array. If ``device`` is ``None`` and ``obj`` is an array, the output array device must be inferred from ``obj``. Default: ``None``.
copy: Optional[bool]
boolean indicating whether or not to copy the input. If ``True``, the function must always copy. If ``False``, the function must never copy for input which supports the buffer protocol and must raise a ``ValueError`` in case a copy would be necessary. If ``None``, the function must reuse existing memory buffer if possible and copy otherwise. Default: ``None``.

.. note::

A common use case for setting ``copy`` equal to ``True`` is to guarantee that, when provided an array ``x``, ``asarray(x, copy=True)`` returns an array which may be mutated without affecting user data. For conforming implementations which disallow mutation, explicitly copying array data belonging to a known array type to a new memory location may not be necessary. Accordingly, such implementations may choose to ignore the ``copy`` keyword argument when ``obj`` is an array belonging to that implementation.

Returns
-------
out: array
Expand All @@ -121,6 +117,9 @@ def asarray(
Notes
-----

- 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:`array_api.astype`.
- If an input value exceeds the precision of the resolved output array data type, behavior is left unspecified and, thus, implementation-defined.

.. versionchanged:: 2022.12
Added complex data type support.
"""
Expand Down
Loading