"""

This module is home to specific dtypes related functionality and their classes.

For more general information about dtypes, also see `numpy.dtype` and

:ref:`arrays.dtypes`.

Similar to the builtin ``types`` module, this submodule defines types (classes)

that are not widely used directly.

.. versionadded:: NumPy 1.25

The dtypes module is new in NumPy 1.25. Previously DType classes were

only accessible indirectly.

DType classes

-------------

The following are the classes of the corresponding NumPy dtype instances and

NumPy scalar types. The classes can be used in ``isinstance`` checks and can

also be instantiated or used directly. Direct use of these classes is not

typical, since their scalar counterparts (e.g. ``np.float64``) or strings

like ``"float64"`` can be used.

"""

# See doc/source/reference/routines.dtypes.rst for module-level docs

__all__ = ["register_dlpack_dtype"]

def register_dlpack_dtype(dlpack_key, dtype, /):

"""

Register a NumPy dtype for a DLPack ``(code, bits)`` pair so that

`numpy.from_dlpack` can import it and ``ndarray.__dlpack__`` can export

it. Built-in dtype mappings take priority on import.

If you think a conflict is possible but unproblematic you may wrap this

into a try/except block as NumPy will raise an error if another DType

is already registered for the same (code, bits) pair.

While an error is raised, the export is registered even on error.

Registering an identical (not equal) dtype multiple times is allowed but

normally registration should happen at import time.

.. warning::

It is the responsibility of the registering user to ensure that the

mapping is valid.

.. note::

This function was added primarily for ``ml_dtypes`` and may be

replaced with a different mechanism in the future. It is intended

to be used by authors of user-defined dtypes and not end-users.

Parameters

----------

dlpack_key : tuple of int

``(dl_dtype_code, dl_bits)`` matching the DLPack ``DLDataType``,

lanes is assumed to be always 1, currently.

dtype : dtype

A NumPy dtype instance.

Raises

------

ValueError : If a conflicting registration was already done.

See Also

--------

numpy.from_dlpack

"""

# Deferred to avoid circular import.

from numpy._core._multiarray_umath import _register_dlpack_dtype

return _register_dlpack_dtype(dlpack_key, dtype)

def _add_dtype_helper(DType, alias):

# Function to add DTypes a bit more conveniently without channeling them

# through `numpy._core._multiarray_umath` namespace or similar.

from numpy import dtypes

setattr(dtypes, DType.__name__, DType)

__all__.append(DType.__name__)

if alias:

alias = alias.removeprefix("numpy.dtypes.")

setattr(dtypes, alias, DType)

__all__.append(alias)