from _typeshed import Incomplete, StrPath, SupportsReadline
from collections.abc import Buffer, Sequence
from typing import IO, Any, Generic, Self, SupportsIndex, overload, override
from typing_extensions import TypeVar
import numpy as np
from numpy import _ByteOrder, _ToIndices
from numpy._typing import (
ArrayLike,
DTypeLike,
_AnyShape,
_ArrayLikeBool_co,
_DTypeLike,
_HasDType,
_ScalarLike_co,
_Shape,
_ShapeLike,
_VoidDTypeLike,
)
from .core import MaskedArray
__all__ = ["MaskedRecords", "mrecarray", "fromarrays", "fromrecords", "fromtextfile", "addfield"]
###
_ShapeT_co = TypeVar("_ShapeT_co", bound=_Shape, default=_AnyShape, covariant=True)
_DTypeT_co = TypeVar("_DTypeT_co", bound=np.dtype, default=np.dtype, covariant=True)
type _Ignored = object
type _Names = str | Sequence[str]
###
# mypy: disable-error-code=no-untyped-def
class MaskedRecords(MaskedArray[_ShapeT_co, _DTypeT_co], Generic[_ShapeT_co, _DTypeT_co]):
_mask: Any
_fill_value: Any
def __new__(
cls,
shape: _ShapeLike,
dtype: DTypeLike | None = None,
buf: Buffer | None = None,
offset: SupportsIndex = 0,
strides: _ShapeLike | None = None,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
byteorder: _ByteOrder | None = None,
aligned: bool = False,
mask: _ArrayLikeBool_co = ...,
hard_mask: bool = False,
fill_value: _ScalarLike_co | None = None,
keep_mask: bool = True,
copy: bool = False,
**options: _Ignored,
) -> Self: ...
#
@property
@override
def _data(self, /) -> np.recarray[_ShapeT_co, _DTypeT_co]: ...
@property
def _fieldmask(self, /) -> np.ndarray[_ShapeT_co, np.dtype[np.bool]] | np.bool: ...
#
@override
def __array_finalize__(self, obj: np.ndarray) -> None: ... # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
@override
def __getattribute__(self, attr: str, /) -> Any: ...
@override
def __setattr__(self, attr: str, val: Any, /) -> None: ...
@override
def __getitem__(self, indx: str | _ToIndices, /) -> Incomplete: ... # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
@override
def __setitem__(self, indx: str | _ToIndices, value: Incomplete, /) -> None: ... # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
# unlike `MaskedArray`, these two methods don't return `Self`
@override
def harden_mask(self) -> None: ... # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
@override
def soften_mask(self) -> None: ... # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
# keep in sync with `MaskedArray.view`, but without the `fill_value`
@override # type: ignore[override]
@overload # ()
def view(self, /, dtype: None = None, type: None = None) -> Self: ... # pyrefly: ignore[bad-override]
@overload # (dtype: DTypeT)
def view[DTypeT: np.dtype](
self, /, dtype: DTypeT | _HasDType[DTypeT], type: None = None
) -> MaskedRecords[_ShapeT_co, DTypeT]: ...
@overload # (dtype: dtype[ScalarT])
def view[ScalarT: np.generic](
self, /, dtype: _DTypeLike[ScalarT], type: None = None
) -> MaskedRecords[_ShapeT_co, np.dtype[ScalarT]]: ...
@overload # ([dtype: _, ]*, type: ArrayT)
def view[ArrayT: np.ndarray](self, /, dtype: DTypeLike | None = None, *, type: type[ArrayT]) -> ArrayT: ...
@overload # (dtype: _, type: ArrayT)
def view[ArrayT: np.ndarray](self, /, dtype: DTypeLike | None, type: type[ArrayT]) -> ArrayT: ...
@overload # (dtype: ArrayT, /)
def view[ArrayT: np.ndarray](self, /, dtype: type[ArrayT], type: None = None) -> ArrayT: ...
@overload # (dtype: <like `DTypeLike` but without `_DTypeLike[Any]`>)
def view(self, /, dtype: _VoidDTypeLike | str | None, type: None = None) -> MaskedRecords[_ShapeT_co, np.dtype]: ... # pyright: ignore[reportIncompatibleMethodOverride]
# unlike `MaskedArray` and `ndarray`, this `copy` method has no `order` parameter
@override
def copy(self, /) -> Self: ... # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
mrecarray = MaskedRecords
@overload # known dtype, known shape
def fromarrays[DTypeT: np.dtype, ShapeT: _Shape](
arraylist: Sequence[ArrayLike],
dtype: DTypeT | _HasDType[DTypeT],
shape: ShapeT,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
) -> MaskedRecords[ShapeT, DTypeT]: ...
@overload # known dtype, unknown shape
def fromarrays[DTypeT: np.dtype](
arraylist: Sequence[ArrayLike],
dtype: DTypeT | _HasDType[DTypeT],
shape: _ShapeLike | None = None,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
) -> MaskedRecords[_AnyShape, DTypeT]: ...
@overload # known scalar-type, known shape
def fromarrays[ScalarT: np.generic, ShapeT: _Shape](
arraylist: Sequence[ArrayLike],
dtype: _DTypeLike[ScalarT],
shape: ShapeT,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
) -> MaskedRecords[ShapeT, np.dtype[ScalarT]]: ...
@overload # known scalar-type, unknown shape
def fromarrays[ScalarT: np.generic](
arraylist: Sequence[ArrayLike],
dtype: _DTypeLike[ScalarT],
shape: _ShapeLike | None = None,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
) -> MaskedRecords[_AnyShape, np.dtype[ScalarT]]: ...
@overload # unknown dtype, known shape (positional)
def fromarrays[ShapeT: _Shape](
arraylist: Sequence[ArrayLike],
dtype: DTypeLike | None,
shape: ShapeT,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
) -> MaskedRecords[ShapeT]: ...
@overload # unknown dtype, known shape (keyword)
def fromarrays[ShapeT: _Shape](
arraylist: Sequence[ArrayLike],
dtype: DTypeLike | None = None,
*,
shape: ShapeT,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
) -> MaskedRecords[ShapeT]: ...
@overload # unknown dtype, unknown shape
def fromarrays(
arraylist: Sequence[ArrayLike],
dtype: DTypeLike | None = None,
shape: _ShapeLike | None = None,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
) -> MaskedRecords: ...
#
@overload # known dtype, known shape
def fromrecords[DTypeT: np.dtype, ShapeT: _Shape](
reclist: ArrayLike,
dtype: DTypeT,
shape: ShapeT,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
mask: _ArrayLikeBool_co = ...,
) -> MaskedRecords[ShapeT, DTypeT]: ...
@overload # known dtype, unknown shape
def fromrecords[DTypeT: np.dtype](
reclist: ArrayLike,
dtype: DTypeT,
shape: _ShapeLike | None = None,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
mask: _ArrayLikeBool_co = ...,
) -> MaskedRecords[_AnyShape, DTypeT]: ...
@overload # known scalar-type, known shape
def fromrecords[ScalarT: np.generic, ShapeT: _Shape](
reclist: ArrayLike,
dtype: _DTypeLike[ScalarT],
shape: ShapeT,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
mask: _ArrayLikeBool_co = ...,
) -> MaskedRecords[ShapeT, np.dtype[ScalarT]]: ...
@overload # known scalar-type, unknown shape
def fromrecords[ScalarT: np.generic](
reclist: ArrayLike,
dtype: _DTypeLike[ScalarT],
shape: _ShapeLike | None = None,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
mask: _ArrayLikeBool_co = ...,
) -> MaskedRecords[_AnyShape, np.dtype[ScalarT]]: ...
@overload # unknown dtype, known shape (positional)
def fromrecords[ShapeT: _Shape](
reclist: ArrayLike,
dtype: DTypeLike | None,
shape: ShapeT,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
mask: _ArrayLikeBool_co = ...,
) -> MaskedRecords[ShapeT, np.dtype[Incomplete]]: ...
@overload # unknown dtype, known shape (keyword)
def fromrecords[ShapeT: _Shape](
reclist: ArrayLike,
dtype: DTypeLike | None = None,
*,
shape: ShapeT,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
mask: _ArrayLikeBool_co = ...,
) -> MaskedRecords[ShapeT, np.dtype[Incomplete]]: ...
@overload # unknown dtype, unknown shape
def fromrecords(
reclist: ArrayLike,
dtype: DTypeLike | None = None,
shape: _ShapeLike | None = None,
formats: DTypeLike | None = None,
names: _Names | None = None,
titles: _Names | None = None,
aligned: bool = False,
byteorder: _ByteOrder | None = None,
fill_value: _ScalarLike_co | None = None,
mask: _ArrayLikeBool_co = ...,
) -> MaskedRecords[_AnyShape, np.dtype[Incomplete]]: ...
# undocumented
@overload
def openfile(fname: StrPath) -> IO[str]: ...
@overload
def openfile[FileT: SupportsReadline[str]](fname: FileT) -> FileT: ...
#
def fromtextfile(
fname: StrPath | SupportsReadline[str],
delimiter: str | None = None,
commentchar: str = "#",
missingchar: str = "",
varnames: Sequence[str] | None = None,
vartypes: Sequence[DTypeLike] | None = None,
) -> MaskedRecords[tuple[int], np.dtype[np.void]]: ...
#
def addfield[ShapeT: _Shape](
mrecord: MaskedRecords[ShapeT],
newfield: ArrayLike,
newfieldname: str | None = None,
) -> np.recarray[ShapeT, np.dtype[np.void]]: ...