🏷️ io.matlab: stub private cython modules (#718)

Author: jorenham

scipy-stubs/io/matlab/_mio5_utils.pyi

@@ -0,0 +1,66 @@
+# defined in scipy/io/matlab/_mio5_utils.pyx
+
+from collections.abc import Iterable
+from typing import Any, ClassVar, Final, Literal, Never, TypeAlias
+from typing_extensions import CapsuleType
+
+import numpy as np
+import optype.numpy as onp
+import optype.numpy.compat as npc
+
+from ._miobase import MatVarReader
+from ._streams import GenericStream, _FileLike
+
+_bint: TypeAlias = Literal[0, 1] | bool  # noqa: PYI042
+
+###
+
+# NOTE: These apprear to be broken, and will always raise `TypeError: no default __reduce__ due to non-trivial __cinit__`
+def __reduce_cython__(self: Never) -> Never: ...  # undocumented
+def __setstate_cython__(self: Never, __pyx_state: Never) -> None: ...  # undocumented  # pyright: ignore[reportGeneralTypeIssues]
+
+swapped_code: Final[Literal[">", "<"]] = ...  # undocumented  # ">" sys.byteorder == "little" else "<"
+
+def byteswap_u4(u4: np.uint32) -> np.uint32: ...  # undocumented
+
+class VarHeader5:  # undocumented
+    # cdef readonly object name
+    name: Final[object]
+    # cdef readonly int mclass
+    mclass: Final[int]
+    # cdef readonly object dims
+    dims: Final[Iterable[int | npc.integer]]
+    # cdef readonly int is_logical
+    is_logical: Final[_bint]
+    # cdef public int is_global
+    is_global: _bint
+    # cdef readonly size_t nzmax
+    nzmax: Final[int]
+
+    def __reduce_cython__(self) -> tuple[Any, ...]: ...
+    def __setstate_cython__(self, /, state: tuple[object, ...]) -> None: ...
+
+    #
+    def set_dims(self, /, dims: object) -> None: ...
+
+class VarReader5:  # undocumented
+    __pyx_vtable__: ClassVar[CapsuleType] = ...
+
+    # cdef public int is_swapped, little_endian
+    is_swapped: _bint
+    little_endian: _bint
+
+    def __init__(self, /, preader: MatVarReader) -> None: ...
+    def set_stream(self, /, fobj: GenericStream | _FileLike) -> None: ...
+    def read_tag(self, /) -> tuple[int, int, str | None]: ...
+    def read_numeric(self, /, copy: _bint = True, nnz: int = -1) -> onp.Array1D[Any]: ...
+    def read_full_tag(self, /) -> tuple[np.uint32, np.uint32]: ...
+    def read_header(self, /, check_stream_limit: _bint) -> VarHeader5: ...
+    def array_from_header(self, /, header: VarHeader5, process: _bint = 1) -> Any: ...  # squeezed ndarray or sparse csc_array
+    def shape_from_header(self, /, header: VarHeader5) -> tuple[int, ...]: ...
+    def read_real_complex(self, /, header: VarHeader5) -> onp.ArrayND[np.float64 | np.complex128]: ...
+    def read_char(self, /, header: VarHeader5) -> onp.ArrayND[np.str_]: ...
+    def read_cells(self, /, header: VarHeader5) -> onp.ArrayND[np.object_]: ...
+    def read_fieldnames(self, /) -> list[str]: ...
+    def read_struct(self, /, header: VarHeader5) -> onp.ArrayND[np.object_]: ...
+    def read_opaque(self, /, hdr: VarHeader5) -> onp.Array1D[np.void]: ...

scipy-stubs/io/matlab/_mio_utils.pyi

@@ -0,0 +1,46 @@
+import datetime as dt
+from typing import Any, Final, Never, TypeVar, overload
+from typing_extensions import CapsuleType
+
+import numpy as np
+import optype.numpy as onp
+import optype.numpy.compat as npc
+
+_ArrayT = TypeVar("_ArrayT", bound=onp.ArrayND[Any, onp.AtLeast1D])
+
+###
+
+__pyx_capi__: Final[dict[str, CapsuleType]] = ...
+
+#
+@overload
+def squeeze_element(arr: onp.ArrayND[Any, tuple[Never]]) -> Any: ...
+@overload
+def squeeze_element(arr: _ArrayT) -> _ArrayT: ...
+
+# TODO: use generic item type of `np.generic` when we require `numpy>=2.2`
+@overload
+def squeeze_element(arr: onp.Array0D[np.bool_]) -> bool: ...
+@overload
+def squeeze_element(arr: onp.Array0D[npc.integer]) -> int: ...
+@overload
+def squeeze_element(arr: onp.Array0D[np.float16 | np.float32 | np.float64]) -> float: ...  # type: ignore[overload-overlap]
+@overload
+def squeeze_element(arr: onp.Array0D[np.longdouble]) -> np.longdouble: ...
+@overload
+def squeeze_element(arr: onp.Array0D[np.complex64 | np.complex128]) -> complex: ...  # type: ignore[overload-overlap]
+@overload
+def squeeze_element(arr: onp.Array0D[np.clongdouble]) -> np.clongdouble: ...
+@overload
+def squeeze_element(arr: onp.Array0D[np.bytes_]) -> bytes: ...
+@overload
+def squeeze_element(arr: onp.Array0D[np.str_]) -> str: ...
+@overload
+def squeeze_element(arr: onp.Array0D[np.datetime64]) -> dt.date | int | None: ...
+@overload
+def squeeze_element(arr: onp.Array0D[np.timedelta64]) -> dt.timedelta | int | None: ...
+@overload
+def squeeze_element(arr: onp.Array0D[np.object_]) -> Any: ...
+
+#
+def chars_to_strings(in_arr: onp.ArrayND[np.str_]) -> onp.ArrayND[np.str_]: ...

scipy-stubs/io/matlab/_miobase.pyi

@@ -1,6 +1,6 @@
 import abc
 from collections.abc import Callable, Mapping
-from typing import IO, Final, Literal, Protocol, TypeVar, type_check_only
+from typing import IO, Any, Final, Literal, Protocol, TypeVar, type_check_only
 
 import numpy as np
 import numpy.typing as npt
@@ -29,13 +29,13 @@ class MatWriteWarning(UserWarning): ...
 class MatVarReader:
     def __init__(self, /, file_reader: MatFileReader) -> None: ...
     @abc.abstractmethod
-    def read_header(self, /) -> dict[str, object]: ...
+    def read_header(self, /) -> dict[str, Any]: ...
     @abc.abstractmethod
     def array_from_header(self, /, header: Mapping[str, object]) -> onp.ArrayND: ...
 
 class MatFileReader:
     mat_stream: Final[IO[bytes]]
-    dtypes: Final[Mapping[str, np.dtype[np.generic]]]
+    dtypes: Final[Mapping[str, np.dtype[Any]]]
     byte_order: Final[ByteOrder]
     struct_as_record: Final[bool]
     verify_compressed_data_integrity: Final[bool]
@@ -62,10 +62,10 @@ class MatFileReader:
     def end_of_stream(self, /) -> bool: ...
 
 def _get_matfile_version(fileobj: IO[bytes]) -> tuple[Literal[1, 2], int]: ...
-def convert_dtypes(dtype_template: Mapping[str, str], order_code: ByteOrder) -> dict[str, np.dtype[np.generic]]: ...
+def convert_dtypes(dtype_template: Mapping[str, str], order_code: ByteOrder) -> dict[str, np.dtype[Any]]: ...
 def read_dtype(mat_stream: IO[bytes], a_dtype: npt.DTypeLike) -> onp.ArrayND: ...
 def matfile_version(file_name: FileName, *, appendmat: bool = True) -> tuple[Literal[0, 1, 2], int]: ...
-def matdims(arr: onp.ArrayND, oned_as: Literal["column", "row"] = "column") -> onp.AtLeast1D: ...
+def matdims(arr: onp.ArrayND, oned_as: Literal["column", "row"] = "column") -> tuple[Any, ...]: ...
 def arr_dtype_number(arr: onp.HasDType[np.dtype[np.character]], num: int | str) -> np.dtype[np.character]: ...
 def arr_to_chars(arr: onp.ArrayND[np.str_]) -> onp.ArrayND[np.str_]: ...
 

scipy-stubs/io/matlab/_streams.pyi

@@ -0,0 +1,34 @@
+from typing import Any, ClassVar, Final, Literal, Protocol, type_check_only
+from typing_extensions import CapsuleType
+
+@type_check_only
+class _FileLike(Protocol):
+    def read(self, size: int, /) -> bytes: ...
+    def tell(self, /) -> int: ...
+    def seek(self, offset: int, whence: int = 0, /) -> int | None: ...
+
+###
+
+BLOCK_SIZE: Final = 131072  # undocumented
+
+__pyx_capi__: Final[dict[str, CapsuleType]] = ...  # undocumented
+
+class GenericStream:  # undocumented
+    __pyx_vtable__: ClassVar[CapsuleType] = ...
+
+    fobs: Final[_FileLike]
+
+    def __init__(self, /, fobj: _FileLike) -> None: ...
+    def seek(self, /, offset: int, whence: int = 0) -> Literal[0, -1]: ...
+    def tell(self, /) -> int: ...
+    def read(self, /, n_bytes: int) -> bytes: ...
+    def all_data_read(self, /) -> Literal[1]: ...
+    def __reduce_cython__(self) -> tuple[Any, ...]: ...
+    def __setstate_cython__(self, /, state: tuple[object, ...]) -> None: ...
+
+class ZlibInputStream(GenericStream):  # undocumented
+    def __init__(self, /, fobj: _FileLike, max_length: int) -> None: ...
+
+def _read_into(st: GenericStream, n: int) -> bytes: ...  # undocumented
+def _read_string(st: GenericStream, n: int) -> bytes: ...  # undocumented
+def make_stream(fobj: GenericStream | _FileLike) -> GenericStream: ...  # undocumented