numpy 2.3.5__cp313-cp313-macosx_14_0_arm64.whl

numpy/_core/_dtype.py

@@ -0,0 +1,366 @@
+"""
+A place for code to be called from the implementation of np.dtype
+
+String handling is much easier to do correctly in python.
+"""
+import numpy as np
+
+_kind_to_stem = {
+    'u': 'uint',
+    'i': 'int',
+    'c': 'complex',
+    'f': 'float',
+    'b': 'bool',
+    'V': 'void',
+    'O': 'object',
+    'M': 'datetime',
+    'm': 'timedelta',
+    'S': 'bytes',
+    'U': 'str',
+}
+
+
+def _kind_name(dtype):
+    try:
+        return _kind_to_stem[dtype.kind]
+    except KeyError as e:
+        raise RuntimeError(
+            f"internal dtype error, unknown kind {dtype.kind!r}"
+        ) from None
+
+
+def __str__(dtype):
+    if dtype.fields is not None:
+        return _struct_str(dtype, include_align=True)
+    elif dtype.subdtype:
+        return _subarray_str(dtype)
+    elif issubclass(dtype.type, np.flexible) or not dtype.isnative:
+        return dtype.str
+    else:
+        return dtype.name
+
+
+def __repr__(dtype):
+    arg_str = _construction_repr(dtype, include_align=False)
+    if dtype.isalignedstruct:
+        arg_str = arg_str + ", align=True"
+    return f"dtype({arg_str})"
+
+
+def _unpack_field(dtype, offset, title=None):
+    """
+    Helper function to normalize the items in dtype.fields.
+
+    Call as:
+
+    dtype, offset, title = _unpack_field(*dtype.fields[name])
+    """
+    return dtype, offset, title
+
+
+def _isunsized(dtype):
+    # PyDataType_ISUNSIZED
+    return dtype.itemsize == 0
+
+
+def _construction_repr(dtype, include_align=False, short=False):
+    """
+    Creates a string repr of the dtype, excluding the 'dtype()' part
+    surrounding the object. This object may be a string, a list, or
+    a dict depending on the nature of the dtype. This
+    is the object passed as the first parameter to the dtype
+    constructor, and if no additional constructor parameters are
+    given, will reproduce the exact memory layout.
+
+    Parameters
+    ----------
+    short : bool
+        If true, this creates a shorter repr using 'kind' and 'itemsize',
+        instead of the longer type name.
+
+    include_align : bool
+        If true, this includes the 'align=True' parameter
+        inside the struct dtype construction dict when needed. Use this flag
+        if you want a proper repr string without the 'dtype()' part around it.
+
+        If false, this does not preserve the
+        'align=True' parameter or sticky NPY_ALIGNED_STRUCT flag for
+        struct arrays like the regular repr does, because the 'align'
+        flag is not part of first dtype constructor parameter. This
+        mode is intended for a full 'repr', where the 'align=True' is
+        provided as the second parameter.
+    """
+    if dtype.fields is not None:
+        return _struct_str(dtype, include_align=include_align)
+    elif dtype.subdtype:
+        return _subarray_str(dtype)
+    else:
+        return _scalar_str(dtype, short=short)
+
+
+def _scalar_str(dtype, short):
+    byteorder = _byte_order_str(dtype)
+
+    if dtype.type == np.bool:
+        if short:
+            return "'?'"
+        else:
+            return "'bool'"
+
+    elif dtype.type == np.object_:
+        # The object reference may be different sizes on different
+        # platforms, so it should never include the itemsize here.
+        return "'O'"
+
+    elif dtype.type == np.bytes_:
+        if _isunsized(dtype):
+            return "'S'"
+        else:
+            return "'S%d'" % dtype.itemsize
+
+    elif dtype.type == np.str_:
+        if _isunsized(dtype):
+            return f"'{byteorder}U'"
+        else:
+            return "'%sU%d'" % (byteorder, dtype.itemsize / 4)
+
+    elif dtype.type == str:
+        return "'T'"
+
+    elif not type(dtype)._legacy:
+        return f"'{byteorder}{type(dtype).__name__}{dtype.itemsize * 8}'"
+
+    # unlike the other types, subclasses of void are preserved - but
+    # historically the repr does not actually reveal the subclass
+    elif issubclass(dtype.type, np.void):
+        if _isunsized(dtype):
+            return "'V'"
+        else:
+            return "'V%d'" % dtype.itemsize
+
+    elif dtype.type == np.datetime64:
+        return f"'{byteorder}M8{_datetime_metadata_str(dtype)}'"
+
+    elif dtype.type == np.timedelta64:
+        return f"'{byteorder}m8{_datetime_metadata_str(dtype)}'"
+
+    elif dtype.isbuiltin == 2:
+        return dtype.type.__name__
+
+    elif np.issubdtype(dtype, np.number):
+        # Short repr with endianness, like '<f8'
+        if short or dtype.byteorder not in ('=', '|'):
+            return "'%s%c%d'" % (byteorder, dtype.kind, dtype.itemsize)
+
+        # Longer repr, like 'float64'
+        else:
+            return "'%s%d'" % (_kind_name(dtype), 8 * dtype.itemsize)
+
+    else:
+        raise RuntimeError(
+            "Internal error: NumPy dtype unrecognized type number")
+
+
+def _byte_order_str(dtype):
+    """ Normalize byteorder to '<' or '>' """
+    # hack to obtain the native and swapped byte order characters
+    swapped = np.dtype(int).newbyteorder('S')
+    native = swapped.newbyteorder('S')
+
+    byteorder = dtype.byteorder
+    if byteorder == '=':
+        return native.byteorder
+    if byteorder == 'S':
+        # TODO: this path can never be reached
+        return swapped.byteorder
+    elif byteorder == '|':
+        return ''
+    else:
+        return byteorder
+
+
+def _datetime_metadata_str(dtype):
+    # TODO: this duplicates the C metastr_to_unicode functionality
+    unit, count = np.datetime_data(dtype)
+    if unit == 'generic':
+        return ''
+    elif count == 1:
+        return f'[{unit}]'
+    else:
+        return f'[{count}{unit}]'
+
+
+def _struct_dict_str(dtype, includealignedflag):
+    # unpack the fields dictionary into ls
+    names = dtype.names
+    fld_dtypes = []
+    offsets = []
+    titles = []
+    for name in names:
+        fld_dtype, offset, title = _unpack_field(*dtype.fields[name])
+        fld_dtypes.append(fld_dtype)
+        offsets.append(offset)
+        titles.append(title)
+
+    # Build up a string to make the dictionary
+
+    if np._core.arrayprint._get_legacy_print_mode() <= 121:
+        colon = ":"
+        fieldsep = ","
+    else:
+        colon = ": "
+        fieldsep = ", "
+
+    # First, the names
+    ret = "{'names'%s[" % colon
+    ret += fieldsep.join(repr(name) for name in names)
+
+    # Second, the formats
+    ret += f"], 'formats'{colon}["
+    ret += fieldsep.join(
+        _construction_repr(fld_dtype, short=True) for fld_dtype in fld_dtypes)
+
+    # Third, the offsets
+    ret += f"], 'offsets'{colon}["
+    ret += fieldsep.join("%d" % offset for offset in offsets)
+
+    # Fourth, the titles
+    if any(title is not None for title in titles):
+        ret += f"], 'titles'{colon}["
+        ret += fieldsep.join(repr(title) for title in titles)
+
+    # Fifth, the itemsize
+    ret += "], 'itemsize'%s%d" % (colon, dtype.itemsize)
+
+    if (includealignedflag and dtype.isalignedstruct):
+        # Finally, the aligned flag
+        ret += ", 'aligned'%sTrue}" % colon
+    else:
+        ret += "}"
+
+    return ret
+
+
+def _aligned_offset(offset, alignment):
+    # round up offset:
+    return - (-offset // alignment) * alignment
+
+
+def _is_packed(dtype):
+    """
+    Checks whether the structured data type in 'dtype'
+    has a simple layout, where all the fields are in order,
+    and follow each other with no alignment padding.
+
+    When this returns true, the dtype can be reconstructed
+    from a list of the field names and dtypes with no additional
+    dtype parameters.
+
+    Duplicates the C `is_dtype_struct_simple_unaligned_layout` function.
+    """
+    align = dtype.isalignedstruct
+    max_alignment = 1
+    total_offset = 0
+    for name in dtype.names:
+        fld_dtype, fld_offset, title = _unpack_field(*dtype.fields[name])
+
+        if align:
+            total_offset = _aligned_offset(total_offset, fld_dtype.alignment)
+            max_alignment = max(max_alignment, fld_dtype.alignment)
+
+        if fld_offset != total_offset:
+            return False
+        total_offset += fld_dtype.itemsize
+
+    if align:
+        total_offset = _aligned_offset(total_offset, max_alignment)
+
+    return total_offset == dtype.itemsize
+
+
+def _struct_list_str(dtype):
+    items = []
+    for name in dtype.names:
+        fld_dtype, fld_offset, title = _unpack_field(*dtype.fields[name])
+
+        item = "("
+        if title is not None:
+            item += f"({title!r}, {name!r}), "
+        else:
+            item += f"{name!r}, "
+        # Special case subarray handling here
+        if fld_dtype.subdtype is not None:
+            base, shape = fld_dtype.subdtype
+            item += f"{_construction_repr(base, short=True)}, {shape}"
+        else:
+            item += _construction_repr(fld_dtype, short=True)
+
+        item += ")"
+        items.append(item)
+
+    return "[" + ", ".join(items) + "]"
+
+
+def _struct_str(dtype, include_align):
+    # The list str representation can't include the 'align=' flag,
+    # so if it is requested and the struct has the aligned flag set,
+    # we must use the dict str instead.
+    if not (include_align and dtype.isalignedstruct) and _is_packed(dtype):
+        sub = _struct_list_str(dtype)
+
+    else:
+        sub = _struct_dict_str(dtype, include_align)
+
+    # If the data type isn't the default, void, show it
+    if dtype.type != np.void:
+        return f"({dtype.type.__module__}.{dtype.type.__name__}, {sub})"
+    else:
+        return sub
+
+
+def _subarray_str(dtype):
+    base, shape = dtype.subdtype
+    return f"({_construction_repr(base, short=True)}, {shape})"
+
+
+def _name_includes_bit_suffix(dtype):
+    if dtype.type == np.object_:
+        # pointer size varies by system, best to omit it
+        return False
+    elif dtype.type == np.bool:
+        # implied
+        return False
+    elif dtype.type is None:
+        return True
+    elif np.issubdtype(dtype, np.flexible) and _isunsized(dtype):
+        # unspecified
+        return False
+    else:
+        return True
+
+
+def _name_get(dtype):
+    # provides dtype.name.__get__, documented as returning a "bit name"
+
+    if dtype.isbuiltin == 2:
+        # user dtypes don't promise to do anything special
+        return dtype.type.__name__
+
+    if not type(dtype)._legacy:
+        name = type(dtype).__name__
+
+    elif issubclass(dtype.type, np.void):
+        # historically, void subclasses preserve their name, eg `record64`
+        name = dtype.type.__name__
+    else:
+        name = _kind_name(dtype)
+
+    # append bit counts
+    if _name_includes_bit_suffix(dtype):
+        name += f"{dtype.itemsize * 8}"
+
+    # append metadata to datetimes
+    if dtype.type in (np.datetime64, np.timedelta64):
+        name += _datetime_metadata_str(dtype)
+
+    return name

numpy/_core/_dtype.pyi

@@ -0,0 +1,58 @@
+from typing import Final, TypeAlias, TypedDict, overload, type_check_only
+from typing import Literal as L
+
+from typing_extensions import ReadOnly, TypeVar
+
+import numpy as np
+
+###
+
+_T = TypeVar("_T")
+
+_Name: TypeAlias = L["uint", "int", "complex", "float", "bool", "void", "object", "datetime", "timedelta", "bytes", "str"]
+
+@type_check_only
+class _KindToStemType(TypedDict):
+    u: ReadOnly[L["uint"]]
+    i: ReadOnly[L["int"]]
+    c: ReadOnly[L["complex"]]
+    f: ReadOnly[L["float"]]
+    b: ReadOnly[L["bool"]]
+    V: ReadOnly[L["void"]]
+    O: ReadOnly[L["object"]]
+    M: ReadOnly[L["datetime"]]
+    m: ReadOnly[L["timedelta"]]
+    S: ReadOnly[L["bytes"]]
+    U: ReadOnly[L["str"]]
+
+###
+
+_kind_to_stem: Final[_KindToStemType] = ...
+
+#
+def _kind_name(dtype: np.dtype) -> _Name: ...
+def __str__(dtype: np.dtype) -> str: ...
+def __repr__(dtype: np.dtype) -> str: ...
+
+#
+def _isunsized(dtype: np.dtype) -> bool: ...
+def _is_packed(dtype: np.dtype) -> bool: ...
+def _name_includes_bit_suffix(dtype: np.dtype) -> bool: ...
+
+#
+def _construction_repr(dtype: np.dtype, include_align: bool = False, short: bool = False) -> str: ...
+def _scalar_str(dtype: np.dtype, short: bool) -> str: ...
+def _byte_order_str(dtype: np.dtype) -> str: ...
+def _datetime_metadata_str(dtype: np.dtype) -> str: ...
+def _struct_dict_str(dtype: np.dtype, includealignedflag: bool) -> str: ...
+def _struct_list_str(dtype: np.dtype) -> str: ...
+def _struct_str(dtype: np.dtype, include_align: bool) -> str: ...
+def _subarray_str(dtype: np.dtype) -> str: ...
+def _name_get(dtype: np.dtype) -> str: ...
+
+#
+@overload
+def _unpack_field(dtype: np.dtype, offset: int, title: _T) -> tuple[np.dtype, int, _T]: ...
+@overload
+def _unpack_field(dtype: np.dtype, offset: int, title: None = None) -> tuple[np.dtype, int, None]: ...
+def _aligned_offset(offset: int, alignment: int) -> int: ...

numpy/_core/_dtype_ctypes.py

@@ -0,0 +1,120 @@
+"""
+Conversion from ctypes to dtype.
+
+In an ideal world, we could achieve this through the PEP3118 buffer protocol,
+something like::
+
+    def dtype_from_ctypes_type(t):
+        # needed to ensure that the shape of `t` is within memoryview.format
+        class DummyStruct(ctypes.Structure):
+            _fields_ = [('a', t)]
+
+        # empty to avoid memory allocation
+        ctype_0 = (DummyStruct * 0)()
+        mv = memoryview(ctype_0)
+
+        # convert the struct, and slice back out the field
+        return _dtype_from_pep3118(mv.format)['a']
+
+Unfortunately, this fails because:
+
+* ctypes cannot handle length-0 arrays with PEP3118 (bpo-32782)
+* PEP3118 cannot represent unions, but both numpy and ctypes can
+* ctypes cannot handle big-endian structs with PEP3118 (bpo-32780)
+"""
+
+# We delay-import ctypes for distributions that do not include it.
+# While this module is not used unless the user passes in ctypes
+# members, it is eagerly imported from numpy/_core/__init__.py.
+import numpy as np
+
+
+def _from_ctypes_array(t):
+    return np.dtype((dtype_from_ctypes_type(t._type_), (t._length_,)))
+
+
+def _from_ctypes_structure(t):
+    for item in t._fields_:
+        if len(item) > 2:
+            raise TypeError(
+                "ctypes bitfields have no dtype equivalent")
+
+    if hasattr(t, "_pack_"):
+        import ctypes
+        formats = []
+        offsets = []
+        names = []
+        current_offset = 0
+        for fname, ftyp in t._fields_:
+            names.append(fname)
+            formats.append(dtype_from_ctypes_type(ftyp))
+            # Each type has a default offset, this is platform dependent
+            # for some types.
+            effective_pack = min(t._pack_, ctypes.alignment(ftyp))
+            current_offset = (
+                (current_offset + effective_pack - 1) // effective_pack
+            ) * effective_pack
+            offsets.append(current_offset)
+            current_offset += ctypes.sizeof(ftyp)
+
+        return np.dtype({
+            "formats": formats,
+            "offsets": offsets,
+            "names": names,
+            "itemsize": ctypes.sizeof(t)})
+    else:
+        fields = []
+        for fname, ftyp in t._fields_:
+            fields.append((fname, dtype_from_ctypes_type(ftyp)))
+
+        # by default, ctypes structs are aligned
+        return np.dtype(fields, align=True)
+
+
+def _from_ctypes_scalar(t):
+    """
+    Return the dtype type with endianness included if it's the case
+    """
+    if getattr(t, '__ctype_be__', None) is t:
+        return np.dtype('>' + t._type_)
+    elif getattr(t, '__ctype_le__', None) is t:
+        return np.dtype('<' + t._type_)
+    else:
+        return np.dtype(t._type_)
+
+
+def _from_ctypes_union(t):
+    import ctypes
+    formats = []
+    offsets = []
+    names = []
+    for fname, ftyp in t._fields_:
+        names.append(fname)
+        formats.append(dtype_from_ctypes_type(ftyp))
+        offsets.append(0)  # Union fields are offset to 0
+
+    return np.dtype({
+        "formats": formats,
+        "offsets": offsets,
+        "names": names,
+        "itemsize": ctypes.sizeof(t)})
+
+
+def dtype_from_ctypes_type(t):
+    """
+    Construct a dtype object from a ctypes type
+    """
+    import _ctypes
+    if issubclass(t, _ctypes.Array):
+        return _from_ctypes_array(t)
+    elif issubclass(t, _ctypes._Pointer):
+        raise TypeError("ctypes pointers have no dtype equivalent")
+    elif issubclass(t, _ctypes.Structure):
+        return _from_ctypes_structure(t)
+    elif issubclass(t, _ctypes.Union):
+        return _from_ctypes_union(t)
+    elif isinstance(getattr(t, '_type_', None), str):
+        return _from_ctypes_scalar(t)
+    else:
+        raise NotImplementedError(
+            f"Unknown ctypes type {t.__name__}")

numpy/_core/_dtype_ctypes.pyi

@@ -0,0 +1,83 @@
+import _ctypes
+import ctypes as ct
+from typing import Any, overload
+
+import numpy as np
+
+#
+@overload
+def dtype_from_ctypes_type(t: type[_ctypes.Array[Any] | _ctypes.Structure]) -> np.dtype[np.void]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_bool]) -> np.dtype[np.bool]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_int8 | ct.c_byte]) -> np.dtype[np.int8]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_uint8 | ct.c_ubyte]) -> np.dtype[np.uint8]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_int16 | ct.c_short]) -> np.dtype[np.int16]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_uint16 | ct.c_ushort]) -> np.dtype[np.uint16]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_int32 | ct.c_int]) -> np.dtype[np.int32]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_uint32 | ct.c_uint]) -> np.dtype[np.uint32]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_ssize_t | ct.c_long]) -> np.dtype[np.int32 | np.int64]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_size_t | ct.c_ulong]) -> np.dtype[np.uint32 | np.uint64]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_int64 | ct.c_longlong]) -> np.dtype[np.int64]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_uint64 | ct.c_ulonglong]) -> np.dtype[np.uint64]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_float]) -> np.dtype[np.float32]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_double]) -> np.dtype[np.float64]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_longdouble]) -> np.dtype[np.longdouble]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.c_char]) -> np.dtype[np.bytes_]: ...
+@overload
+def dtype_from_ctypes_type(t: type[ct.py_object[Any]]) -> np.dtype[np.object_]: ...
+
+# NOTE: the complex ctypes on python>=3.14 are not yet supported at runtim, see
+# https://github.com/numpy/numpy/issues/28360
+
+#
+def _from_ctypes_array(t: type[_ctypes.Array[Any]]) -> np.dtype[np.void]: ...
+def _from_ctypes_structure(t: type[_ctypes.Structure]) -> np.dtype[np.void]: ...
+def _from_ctypes_union(t: type[_ctypes.Union]) -> np.dtype[np.void]: ...
+
+# keep in sync with `dtype_from_ctypes_type` (minus the first overload)
+@overload
+def _from_ctypes_scalar(t: type[ct.c_bool]) -> np.dtype[np.bool]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_int8 | ct.c_byte]) -> np.dtype[np.int8]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_uint8 | ct.c_ubyte]) -> np.dtype[np.uint8]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_int16 | ct.c_short]) -> np.dtype[np.int16]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_uint16 | ct.c_ushort]) -> np.dtype[np.uint16]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_int32 | ct.c_int]) -> np.dtype[np.int32]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_uint32 | ct.c_uint]) -> np.dtype[np.uint32]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_ssize_t | ct.c_long]) -> np.dtype[np.int32 | np.int64]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_size_t | ct.c_ulong]) -> np.dtype[np.uint32 | np.uint64]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_int64 | ct.c_longlong]) -> np.dtype[np.int64]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_uint64 | ct.c_ulonglong]) -> np.dtype[np.uint64]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_float]) -> np.dtype[np.float32]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_double]) -> np.dtype[np.float64]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_longdouble]) -> np.dtype[np.longdouble]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.c_char]) -> np.dtype[np.bytes_]: ...
+@overload
+def _from_ctypes_scalar(t: type[ct.py_object[Any]]) -> np.dtype[np.object_]: ...