{"author":null,"author_email":"Joren Hammudoglu ","bugtrack_url":null,"classifiers":["Development Status :: 4 - Beta","License :: OSI Approved :: BSD License","Operating System :: OS Independent","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Typing :: Typed"],"description":"

optype

\n\n

\n Building blocks for precise & flexible type hints.\n

\n\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

\n \n \n \n \n \n \n \n \n \n \n \n \n

\n\n---\n\n## Installation\n\n### PyPI\n\nOptype is available as [`optype`][PYPI] on PyPI:\n\n```shell\npip install optype\n```\n\nFor optional [NumPy][NUMPY] support, it is recommended to use the\n`numpy` extra.\nThis ensures that the installed `numpy` version is compatible with\n`optype`, following [NEP 29][NEP29] and [SPEC 0][SPEC0].\n\n```shell\npip install \"optype[numpy]\"\n```\n\nSee the [`optype.numpy` docs](#optypenumpy) for more info.\n\n### Conda\n\nOptype can also be installed as with `conda` from the [`conda-forge`][CONDA] channel:\n\n```shell\nconda install conda-forge::optype\n```\n\n[PYPI]: https://pypi.org/project/optype/\n[CONDA]: https://anaconda.org/conda-forge/optype\n[NUMPY]: https://github.com/numpy/numpy\n\n## Example\n\nLet's say you're writing a `twice(x)` function, that evaluates `2 * x`.\nImplementing it is trivial, but what about the type annotations?\n\nBecause `twice(2) == 4`, `twice(3.14) == 6.28` and `twice('I') = 'II'`, it\nmight seem like a good idea to type it as `twice[T](x: T) -> T: ...`.\nHowever, that wouldn't include cases such as `twice(True) == 2` or\n`twice((42, True)) == (42, True, 42, True)`, where the input- and output types\ndiffer.\nMoreover, `twice` should accept *any* type with a custom `__rmul__` method\nthat accepts `2` as argument.\n\nThis is where `optype` comes in handy, which has single-method protocols for\n*all* the builtin special methods.\nFor `twice`, we can use `optype.CanRMul[T, R]`, which, as the name suggests,\nis a protocol with (only) the `def __rmul__(self, lhs: T) -> R: ...` method.\nWith this, the `twice` function can written as:\n\n\n\n\n\n\n\n\n\n\n

Python 3.10	Python 3.12+
\n\n```python\nfrom typing import Literal\nfrom typing import TypeAlias, TypeVar\nfrom optype import CanRMul\n\nR = TypeVar(\"R\")\nTwo: TypeAlias = Literal[2]\nRMul2: TypeAlias = CanRMul[Two, R]\n\n\ndef twice(x: RMul2[R]) -> R:\n return 2 * x\n```\n\n	\n\n```python\nfrom typing import Literal\nfrom optype import CanRMul\n\ntype Two = Literal[2]\ntype RMul2[R] = CanRMul[Two, R]\n\n\ndef twice[R](x: RMul2[R]) -> R:\n return 2 * x\n```\n\n

\n\nBut what about types that implement `__add__` but not `__radd__`?\nIn this case, we could return `x * 2` as fallback (assuming commutativity).\nBecause the `optype.Can*` protocols are runtime-checkable, the revised\n`twice2` function can be compactly written as:\n\n\n\n\n\n\n\n\n\n\n

Python 3.10	Python 3.12+
\n\n```python\nfrom optype import CanMul\n\nMul2: TypeAlias = CanMul[Two, R]\nCMul2: TypeAlias = Mul2[R] \| RMul2[R]\n\n\ndef twice2(x: CMul2[R]) -> R:\n if isinstance(x, CanRMul):\n return 2 * x\n else:\n return x * 2\n```\n\n	\n\n```python\nfrom optype import CanMul\n\ntype Mul2[R] = CanMul[Two, R]\ntype CMul2[R] = Mul2[R] \| RMul2[R]\n\n\ndef twice2[R](x: CMul2[R]) -> R:\n if isinstance(x, CanRMul):\n return 2 * x\n else:\n return x * 2\n```\n\n

\n\nSee [`examples/twice.py`](examples/twice.py) for the full example.\n\n## Reference\n\nThe API of `optype` is flat; a single `import optype as opt` is all you need\n(except for `optype.numpy`).\n\n\n\n- [`optype`](#optype)\n - [`Just`](#just)\n - [Builtin type conversion](#builtin-type-conversion)\n - [Rich relations](#rich-relations)\n - [Binary operations](#binary-operations)\n - [Reflected operations](#reflected-operations)\n - [Inplace operations](#inplace-operations)\n - [Unary operations](#unary-operations)\n - [Rounding](#rounding)\n - [Callables](#callables)\n - [Iteration](#iteration)\n - [Awaitables](#awaitables)\n - [Async Iteration](#async-iteration)\n - [Containers](#containers)\n - [Attributes](#attributes)\n - [Context managers](#context-managers)\n - [Descriptors](#descriptors)\n - [Buffer types](#buffer-types)\n- [`optype.copy`](#optypecopy)\n- [`optype.dataclasses`](#optypedataclasses)\n- [`optype.inspect`](#optypeinspect)\n- [`optype.io`](#optypeio)\n- [`optype.json`](#optypejson)\n- [`optype.pickle`](#optypepickle)\n- [`optype.string`](#optypestring)\n- [`optype.typing`](#optypetyping)\n - [`Any*` type aliases](#any-type-aliases)\n - [`Empty*` type aliases](#empty-type-aliases)\n - [Literal types](#literal-types)\n- [`optype.dlpack`](#optypedlpack)\n- [`optype.numpy`](#optypenumpy)\n - [Shape-typing](#shape-typing)\n - [Array-likes](#array-likes)\n - [Literals](#literals)\n - [`compat` submodule](#compat-submodule)\n - [`random` submodule](#random-submodule)\n - [`Any*Array` and `Any*DType`](#anyarray-and-anydtype)\n - [Low-level interfaces](#low-level-interfaces)\n\n\n\n### `optype`\n\nThere are five flavors of things that live within `optype`,\n\n-\n The `optype.Just[T]` and its `optype.Just{Int,Float,Complex}` subtypes only accept\n instances of the type itself, while rejecting instances of strict subtypes.\n This can be be used to e.g. work around the `float` and `complex`\n [type promotions][BAD], annotating `object()` sentinels with `Just[object]`,\n rejecting `bool` in functions that accept `int`, etc.\n-\n `optype.Can{}` types describe *what can be done* with it.\n For instance, any `CanAbs[T]` type can be used as argument to the `abs()`\n builtin function with return type `T`. Most `Can{}` implement a single\n special method, whose name directly matched that of the type. `CanAbs`\n implements `__abs__`, `CanAdd` implements `__add__`, etc.\n-\n `optype.Has{}` is the analogue of `Can{}`, but for special *attributes*.\n `HasName` has a `__name__` attribute, `HasDict` has a `__dict__`, etc.\n-\n `optype.Does{}` describe the *type of operators*.\n So `DoesAbs` is the type of the `abs({})` builtin function,\n and `DoesPos` the type of the `+{}` prefix operator.\n-\n `optype.do_{}` are the correctly-typed implementations of `Does{}`. For\n each `do_{}` there is a `Does{}`, and vice-versa.\n So `do_abs: DoesAbs` is the typed alias of `abs({})`,\n and `do_pos: DoesPos` is a typed version of `operator.pos`.\n The `optype.do_` operators are more complete than `operators`,\n have runtime-accessible type annotations, and have names you don't\n need to know by heart.\n\nThe reference docs are structured as follows:\n\nAll [typing protocols][PC] here live in the root `optype` namespace.\nThey are [runtime-checkable][RC] so that you can do e.g.\n`isinstance('snail', optype.CanAdd)`, in case you want to check whether\n`snail` implements `__add__`.\n\nUnlike`collections.abc`, `optype`'s protocols aren't abstract base classes,\ni.e. they don't extend `abc.ABC`, only `typing.Protocol`.\nThis allows the `optype` protocols to be used as building blocks for `.pyi`\ntype stubs.\n\n[BAD]: https://typing.readthedocs.io/en/latest/spec/special-types.html#special-cases-for-float-and-complex\n[PC]: https://typing.readthedocs.io/en/latest/spec/protocol.html\n[RC]: https://typing.readthedocs.io/en/latest/spec/protocol.html#runtime-checkable-decorator-and-narrowing-types-by-isinstance\n\n#### `Just`\n\n`Just` is in invariant type \"wrapper\", where `Just[T]` only accepts instances of `T`,\nand rejects instances of any strict subtypes of `T`.\n\nNote that e.g. `Literal[\"\"]` and `LiteralString` are not a strict `str` subtypes,\nand are therefore assignable to `Just[str]`, but instances of `class S(str): ...`\nare **not** assignable to `Just[str]`.\n\nDisallow passing `bool` as `int`:\n\n```py\nimport optype as op\n\n\ndef assert_int(x: op.Just[int]) -> int:\n assert type(x) is int\n return x\n\n\nassert_int(42) # ok\nassert_int(False) # rejected\n```\n\nAnnotating a sentinel:\n\n```py\nimport optype as op\n\n_DEFAULT = object()\n\n\ndef intmap(\n value: int,\n # same as `dict[int, int] | op.Just[object]`\n mapping: dict[int, int] | op.JustObject = _DEFAULT,\n /,\n) -> int:\n # same as `type(mapping) is object`\n if isinstance(mapping, op.JustObject):\n return value\n\n return mapping[value]\n\n\nintmap(1) # ok\nintmap(1, {1: 42}) # ok\nintmap(1, \"some object\") # rejected\n```\n\n> [!TIP]\n> The `Just{Bytes,Int,Float,Complex,Date,Object}` protocols are runtime-checkable,\n> so that `instance(42, JustInt) is True` and `instance(bool(), JustInt) is False`.\n> It's implemented through meta-classes, and type-checkers have no problem with it.\n\n| `optype` type | accepts instances of |\n| ------------- | -------------------- |\n| `Just[T]` | `T` |\n| `JustInt` | `builtins.int` |\n| `JustFloat` | `builtins.float` |\n| `JustComplex` | `builtins.complex` |\n| `JustBytes` | `builtins.bytes` |\n| `JustObject` | `builtins.object` |\n| `JustDate` | `datetime.date` |\n\n##### :warning: Compatibility: (based)pyright\n\nOn `pyright<1.1.390` and `basedpyright<1.22.1` this `Just[T]` type does not work,\ndue to a bug in the `typeshed` stubs for `object.__class__` (fixed in\n[python/typeshed#13021](https://github.com/python/typeshed/pull/13021)).\n\nHowever, you could use `JustInt`, `JustFloat`, and `JustComplex` types work\naround this: These already work on `pyright<1.390` without problem.\n\n##### :warning: Compatibility: (based)mypy\n\nOn `mypy<1.15` this does not work with promoted types, such as `float` and `bytes`\n(fixed in [python/mypy#18360](https://github.com/python/mypy/pull/18360)).\n\nFor other (\"unpromoted\") types like `Just[int]`, this already works, even\nbefore the `typeshed` fix above (mypy ignores `@property` setter types and\noverwrites it with the getter's return type).\n\n#### Builtin type conversion\n\nThe return type of these special methods is *invariant*. Python will raise an\nerror if some other (sub)type is returned.\nThis is why these `optype` interfaces don't accept generic type arguments.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`complex(_)`	`do_complex`	`DoesComplex`	`__complex__`	`CanComplex`
`float(_)`	`do_float`	`DoesFloat`	`__float__`	`CanFloat`
`int(_)`	`do_int`	`DoesInt`	`__int__`	`CanInt[R: int = int]`
`bool(_)`	`do_bool`	`DoesBool`	`__bool__`	`CanBool[R: bool = bool]`
`bytes(_)`	`do_bytes`	`DoesBytes`	`__bytes__`	`CanBytes[R: bytes = bytes]`
`str(_)`	`do_str`	`DoesStr`	`__str__`	`CanStr[R: str = str]`

\n\n> [!NOTE]\n> The `Can*` interfaces of the types that can used as `typing.Literal`\n> accept an optional type parameter `R`.\n> This can be used to indicate a literal return type,\n> for surgically precise typing, e.g. `None`, `True`, and `42` are\n> instances of `CanBool[Literal[False]]`, `CanInt[Literal[1]]`, and\n> `CanStr[Literal['42']]`, respectively.\n\nThese formatting methods are allowed to return instances that are a subtype\nof the `str` builtin. The same holds for the `__format__` argument.\nSo if you're a 10x developer that wants to hack Python's f-strings, but only\nif your type hints are spot-on; `optype` is you friend.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`repr(_)`	`do_repr`	`DoesRepr`	`__repr__`	`CanRepr[R: str = str]`
`format(_, x)`	`do_format`	`DoesFormat`	`__format__`	`CanFormat[T: str = str, R: str = str]`

\n\nAdditionally, `optype` provides protocols for types with (custom) *hash* or\n*index* methods:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`hash(_)`	`do_hash`	`DoesHash`	`__hash__`	`CanHash`
\n `_.__index__()`\n (docs)\n	`do_index`	`DoesIndex`	`__index__`	`CanIndex[R: int = int]`

\n\n#### Rich relations\n\nThe \"rich\" comparison special methods often return a `bool`.\nHowever, instances of any type can be returned (e.g. a numpy array).\nThis is why the corresponding `optype.Can*` interfaces accept a second type\nargument for the return type, that defaults to `bool` when omitted.\nThe first type parameter matches the passed method argument, i.e. the\nright-hand side operand, denoted here as `x`.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	reflected	function	type	method	type
`_ == x`	`x == _`	`do_eq`	`DoesEq`	`__eq__`	`CanEq[T = object, R = bool]`
`_ != x`	`x != _`	`do_ne`	`DoesNe`	`__ne__`	`CanNe[T = object, R = bool]`
`_ < x`	`x > _`	`do_lt`	`DoesLt`	`__lt__`	`CanLt[T, R = bool]`
`_ <= x`	`x >= _`	`do_le`	`DoesLe`	`__le__`	`CanLe[T, R = bool]`
`_ > x`	`x < _`	`do_gt`	`DoesGt`	`__gt__`	`CanGt[T, R = bool]`
`_ >= x`	`x <= _`	`do_ge`	`DoesGe`	`__ge__`	`CanGe[T, R = bool]`

\n\n#### Binary operations\n\nIn the [Python docs][NT], these are referred to as \"arithmetic operations\".\nBut the operands aren't limited to numeric types, and because the\noperations aren't required to be commutative, might be non-deterministic, and\ncould have side-effects.\nClassifying them \"arithmetic\" is, at the very least, a bit of a stretch.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`_ + x`	`do_add`	`DoesAdd`	`__add__`	`CanAdd[T, R]`
`_ - x`	`do_sub`	`DoesSub`	`__sub__`	`CanSub[T, R]`
`_ * x`	`do_mul`	`DoesMul`	`__mul__`	`CanMul[T, R]`
`_ @ x`	`do_matmul`	`DoesMatmul`	`__matmul__`	`CanMatmul[T, R]`
`_ / x`	`do_truediv`	`DoesTruediv`	`__truediv__`	`CanTruediv[T, R]`
`_ // x`	`do_floordiv`	`DoesFloordiv`	`__floordiv__`	`CanFloordiv[T, R]`
`_ % x`	`do_mod`	`DoesMod`	`__mod__`	`CanMod[T, R]`
`divmod(_, x)`	`do_divmod`	`DoesDivmod`	`__divmod__`	`CanDivmod[T, R]`
\n `_ ** x` \n `pow(_, x)`\n	`do_pow/2`	`DoesPow`	`__pow__`	\n `CanPow2[T, R]` \n `CanPow[T, None, R, Never]`\n
`pow(_, x, m)`	`do_pow/3`	`DoesPow`	`__pow__`	\n `CanPow3[T, M, R]` \n `CanPow[T, M, Never, R]`\n
`_ << x`	`do_lshift`	`DoesLshift`	`__lshift__`	`CanLshift[T, R]`
`_ >> x`	`do_rshift`	`DoesRshift`	`__rshift__`	`CanRshift[T, R]`
`_ & x`	`do_and`	`DoesAnd`	`__and__`	`CanAnd[T, R]`
`_ ^ x`	`do_xor`	`DoesXor`	`__xor__`	`CanXor[T, R]`
`_ \| x`	`do_or`	`DoesOr`	`__or__`	`CanOr[T, R]`

\n\n> [!NOTE]\n> Because `pow()` can take an optional third argument, `optype`\n> provides separate interfaces for `pow()` with two and three arguments.\n> Additionally, there is the overloaded intersection type\n> `CanPow[T, M, R, RM] =: CanPow2[T, R] & CanPow3[T, M, RM]`, as interface\n> for types that can take an optional third argument.\n\n#### Reflected operations\n\nFor the binary infix operators above, `optype` additionally provides\ninterfaces with *reflected* (swapped) operands, e.g. `__radd__` is a reflected\n`__add__`.\nThey are named like the original, but prefixed with `CanR` prefix, i.e.\n`__name__.replace('Can', 'CanR')`.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`x + _`	`do_radd`	`DoesRAdd`	`__radd__`	`CanRAdd[T, R]`
`x - _`	`do_rsub`	`DoesRSub`	`__rsub__`	`CanRSub[T, R]`
`x * _`	`do_rmul`	`DoesRMul`	`__rmul__`	`CanRMul[T, R]`
`x @ _`	`do_rmatmul`	`DoesRMatmul`	`__rmatmul__`	`CanRMatmul[T, R]`
`x / _`	`do_rtruediv`	`DoesRTruediv`	`__rtruediv__`	`CanRTruediv[T, R]`
`x // _`	`do_rfloordiv`	`DoesRFloordiv`	`__rfloordiv__`	`CanRFloordiv[T, R]`
`x % _`	`do_rmod`	`DoesRMod`	`__rmod__`	`CanRMod[T, R]`
`divmod(x, _)`	`do_rdivmod`	`DoesRDivmod`	`__rdivmod__`	`CanRDivmod[T, R]`
\n `x ** _` \n `pow(x, _)`\n	`do_rpow`	`DoesRPow`	`__rpow__`	`CanRPow[T, R]`
`x << _`	`do_rlshift`	`DoesRLshift`	`__rlshift__`	`CanRLshift[T, R]`
`x >> _`	`do_rrshift`	`DoesRRshift`	`__rrshift__`	`CanRRshift[T, R]`
`x & _`	`do_rand`	`DoesRAnd`	`__rand__`	`CanRAnd[T, R]`
`x ^ _`	`do_rxor`	`DoesRXor`	`__rxor__`	`CanRXor[T, R]`
`x \| _`	`do_ror`	`DoesROr`	`__ror__`	`CanROr[T, R]`

\n\n> [!NOTE]\n> `CanRPow` corresponds to `CanPow2`; the 3-parameter \"modulo\" `pow` does not\n> reflect in Python.\n>\n> According to the relevant [python docs][RPOW]:\n> > Note that ternary `pow()` will not try calling `__rpow__()` (the coercion\n> > rules would become too complicated).\n\n[RPOW]: https://docs.python.org/3/reference/datamodel.html#object.__rpow__\n\n#### Inplace operations\n\nSimilar to the reflected ops, the inplace/augmented ops are prefixed with\n`CanI`, namely:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	types
`_ += x`	`do_iadd`	`DoesIAdd`	`__iadd__`	\n `CanIAdd[T, R]` \n `CanIAddSelf[T]`\n
`_ -= x`	`do_isub`	`DoesISub`	`__isub__`	\n `CanISub[T, R]` \n `CanISubSelf[T]`\n
`_ *= x`	`do_imul`	`DoesIMul`	`__imul__`	\n `CanIMul[T, R]` \n `CanIMulSelf[T]`\n
`_ @= x`	`do_imatmul`	`DoesIMatmul`	`__imatmul__`	\n `CanIMatmul[T, R]` \n `CanIMatmulSelf[T]`\n
`_ /= x`	`do_itruediv`	`DoesITruediv`	`__itruediv__`	\n `CanITruediv[T, R]` \n `CanITruedivSelf[T]`\n
`_ //= x`	`do_ifloordiv`	`DoesIFloordiv`	`__ifloordiv__`	\n `CanIFloordiv[T, R]` \n `CanIFloordivSelf[T]`\n
`_ %= x`	`do_imod`	`DoesIMod`	`__imod__`	\n `CanIMod[T, R]` \n `CanIModSelf[T]`\n
`_ **= x`	`do_ipow`	`DoesIPow`	`__ipow__`	\n `CanIPow[T, R]` \n `CanIPowSelf[T]`\n
`_ <<= x`	`do_ilshift`	`DoesILshift`	`__ilshift__`	\n `CanILshift[T, R]` \n `CanILshiftSelf[T]`\n
`_ >>= x`	`do_irshift`	`DoesIRshift`	`__irshift__`	\n `CanIRshift[T, R]` \n `CanIRshiftSelf[T]`\n
`_ &= x`	`do_iand`	`DoesIAnd`	`__iand__`	\n `CanIAnd[T, R]` \n `CanIAndSelf[T]`\n
`_ ^= x`	`do_ixor`	`DoesIXor`	`__ixor__`	\n `CanIXor[T, R]` \n `CanIXorSelf[T]`\n
`_ \|= x`	`do_ior`	`DoesIOr`	`__ior__`	\n `CanIOr[T, R]` \n `CanIOrSelf[T]`\n

\n\nThese inplace operators usually return itself (after some in-place mutation).\nBut unfortunately, it currently isn't possible to use `Self` for this (i.e.\nsomething like `type MyAlias[T] = optype.CanIAdd[T, Self]` isn't allowed).\nSo to help ease this unbearable pain, `optype` comes equipped with ready-made\naliases for you to use. They bear the same name, with an additional `*Self`\nsuffix, e.g. `optype.CanIAddSelf[T]`.\n\n#### Unary operations\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	types
`+_`	`do_pos`	`DoesPos`	`__pos__`	\n `CanPos[R]` \n `CanPosSelf`\n
`-_`	`do_neg`	`DoesNeg`	`__neg__`	\n `CanNeg[R]` \n `CanNegSelf`\n
`~_`	`do_invert`	`DoesInvert`	`__invert__`	\n `CanInvert[R]` \n `CanInvertSelf`\n
`abs(_)`	`do_abs`	`DoesAbs`	`__abs__`	\n `CanAbs[R]` \n `CanAbsSelf`\n

\n\n#### Rounding\n\nThe `round()` built-in function takes an optional second argument.\nFrom a typing perspective, `round()` has two overloads, one with 1 parameter,\nand one with two.\nFor both overloads, `optype` provides separate operand interfaces:\n`CanRound1[R]` and `CanRound2[T, RT]`.\nAdditionally, `optype` also provides their (overloaded) intersection type:\n`CanRound[T, R, RT] = CanRound1[R] & CanRound2[T, RT]`.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`round(_)`	`do_round/1`	`DoesRound`	`__round__/1`	`CanRound1[T = int]`
`round(_, n)`	`do_round/2`	`DoesRound`	`__round__/2`	`CanRound2[T = int, RT = float]`
`round(_, n=...)`	`do_round`	`DoesRound`	`__round__`	`CanRound[T = int, R = int, RT = float]`

\n\nFor example, type-checkers will mark the following code as valid (tested with\npyright in strict mode):\n\n```python\nx: float = 3.14\nx1: CanRound1[int] = x\nx2: CanRound2[int, float] = x\nx3: CanRound[int, int, float] = x\n```\n\nFurthermore, there are the alternative rounding functions from the\n[`math`][MATH] standard library:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`math.trunc(_)`	`do_trunc`	`DoesTrunc`	`__trunc__`	`CanTrunc[R = int]`
`math.floor(_)`	`do_floor`	`DoesFloor`	`__floor__`	`CanFloor[R = int]`
`math.ceil(_)`	`do_ceil`	`DoesCeil`	`__ceil__`	`CanCeil[R = int]`

\n\nAlmost all implementations use `int` for `R`.\nIn fact, if no type for `R` is specified, it will default in `int`.\nBut technially speaking, these methods can be made to return anything.\n\n[MATH]: https://docs.python.org/3/library/math.html\n[NT]: https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types\n\n#### Callables\n\nUnlike `operator`, `optype` provides the operator for callable objects:\n`optype.do_call(f, *args. **kwargs)`.\n\n`CanCall` is similar to `collections.abc.Callable`, but is runtime-checkable,\nand doesn't use esoteric hacks.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`_(args, *kwargs)`	`do_call`	`DoesCall`	`__call__`	`CanCall[**Pss, R]`

\n\n> [!NOTE]\n> Pyright (and probably other typecheckers) tend to accept\n> `collections.abc.Callable` in more places than `optype.CanCall`.\n> This could be related to the lack of co/contra-variance specification for\n> `typing.ParamSpec` (they should almost always be contravariant, but\n> currently they can only be invariant).\n>\n> In case you encounter such a situation, please open an issue about it, so we\n> can investigate further.\n\n#### Iteration\n\nThe operand `x` of `iter(_)` is within Python known as an *iterable*, which is\nwhat `collections.abc.Iterable[V]` is often used for (e.g. as base class, or\nfor instance checking).\n\nThe `optype` analogue is `CanIter[R]`, which as the name suggests,\nalso implements `__iter__`. But unlike `Iterable[V]`, its type parameter `R`\nbinds to the return type of `iter(_) -> R`. This makes it possible to annotate\nthe specific type of the *iterable* that `iter(_)` returns. `Iterable[V]` is\nonly able to annotate the type of the iterated value. To see why that isn't\npossible, see [python/typing#548](https://github.com/python/typing/issues/548).\n\nThe `collections.abc.Iterator[V]` is even more awkward; it is a subtype of\n`Iterable[V]`. For those familiar with `collections.abc` this might come as a\nsurprise, but an iterator only needs to implement `__next__`, `__iter__` isn't\nneeded. This means that the `Iterator[V]` is unnecessarily restrictive.\nApart from that being theoretically \"ugly\", it has significant performance\nimplications, because the time-complexity of `isinstance` on a\n`typing.Protocol` is $O(n)$, with the $n$ referring to the amount of members.\nSo even if the overhead of the inheritance and the `abc.ABC` usage is ignored,\n`collections.abc.Iterator` is twice as slow as it needs to be.\n\nThat's one of the (many) reasons that `optype.CanNext[V]` and\n`optype.CanNext[V]` are the better alternatives to `Iterable` and `Iterator`\nfrom the abracadabra collections. This is how they are defined:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`next(_)`	`do_next`	`DoesNext`	`__next__`	`CanNext[V]`
`iter(_)`	`do_iter`	`DoesIter`	`__iter__`	`CanIter[R: CanNext[object]]`

\n\nFor the sake of compatibility with `collections.abc`, there is\n`optype.CanIterSelf[V]`, which is a protocol whose `__iter__` returns\n`typing.Self`, as well as a `__next__` method that returns `T`.\nI.e. it is equivalent to `collections.abc.Iterator[V]`, but without the `abc`\nnonsense.\n\n#### Awaitables\n\nThe `optype` is almost the same as `collections.abc.Awaitable[R]`, except\nthat `optype.CanAwait[R]` is a pure interface, whereas `Awaitable` is\nalso an abstract base class (making it absolutely useless when writing stubs).\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	method	type
`await _`	`__await__`	`CanAwait[R]`

\n\n#### Async Iteration\n\nYes, you guessed it right; the abracadabra collections made the exact same\nmistakes for the async iterablors (or was it \"iteramblers\"...?).\n\nBut fret not; the `optype` alternatives are right here:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`anext(_)`	`do_anext`	`DoesANext`	`__anext__`	`CanANext[V]`
`aiter(_)`	`do_aiter`	`DoesAIter`	`__aiter__`	`CanAIter[R: CanAnext[object]]`

\n\nBut wait, shouldn't `V` be a `CanAwait`? Well, only if you don't want to get\nfired...\nTechnically speaking, `__anext__` can return any type, and `anext` will pass\nit along without nagging (instance checks are slow, now stop bothering that\nliberal). For details, see the discussion at [python/typeshed#7491][AN].\nJust because something is legal, doesn't mean it's a good idea (don't eat the\nyellow snow).\n\nAdditionally, there is `optype.CanAIterSelf[R]`, with both the\n`__aiter__() -> Self` and the `__anext__() -> V` methods.\n\n[AN]: https://github.com/python/typeshed/pull/7491\n\n#### Containers\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
`len(_)`	`do_len`	`DoesLen`	`__len__`	`CanLen[R: int = int]`
\n `_.__length_hint__()`\n (docs)\n	`do_length_hint`	`DoesLengthHint`	`__length_hint__`	`CanLengthHint[R: int = int]`
`_[k]`	`do_getitem`	`DoesGetitem`	`__getitem__`	`CanGetitem[K, V]`
\n `_.__missing__()`\n (docs)\n	`do_missing`	`DoesMissing`	`__missing__`	`CanMissing[K, D]`
`_[k] = v`	`do_setitem`	`DoesSetitem`	`__setitem__`	`CanSetitem[K, V]`
`del _[k]`	`do_delitem`	`DoesDelitem`	`__delitem__`	`CanDelitem[K]`
`k in _`	`do_contains`	`DoesContains`	`__contains__`	`CanContains[K = object]`
`reversed(_)`	`do_reversed`	`DoesReversed`	`__reversed__`	\n `CanReversed[R]`, or \n `CanSequence[I, V, N = int]`\n

\n\nBecause `CanMissing[K, D]` generally doesn't show itself without\n`CanGetitem[K, V]` there to hold its hand, `optype` conveniently stitched them\ntogether as `optype.CanGetMissing[K, V, D=V]`.\n\nSimilarly, there is `optype.CanSequence[K: CanIndex | slice, V]`, which is the\ncombination of both `CanLen` and `CanItem[I, V]`, and serves as a more\nspecific and flexible `collections.abc.Sequence[V]`.\n\n#### Attributes\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	function	type	method	type
\n `v = _.k` or \n `v = getattr(_, k)`\n	`do_getattr`	`DoesGetattr`	`__getattr__`	`CanGetattr[K: str = str, V = object]`
\n `_.k = v` or \n `setattr(_, k, v)`\n	`do_setattr`	`DoesSetattr`	`__setattr__`	`CanSetattr[K: str = str, V = object]`
\n `del _.k` or \n `delattr(_, k)`\n	`do_delattr`	`DoesDelattr`	`__delattr__`	`CanDelattr[K: str = str]`
`dir(_)`	`do_dir`	`DoesDir`	`__dir__`	`CanDir[R: CanIter[CanIterSelf[str]]]`

\n\n#### Context managers\n\nSupport for the `with` statement.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	method(s)	type(s)
	`__enter__`	\n `CanEnter[C]`, or\n `CanEnterSelf`\n
	`__exit__`	\n `CanExit[R = None]`\n
`with _ as c:`	\n `__enter__`, and \n `__exit__`\n	\n `CanWith[C, R=None]`, or \n `CanWithSelf[R=None]`\n

\n\n`CanEnterSelf` and `CanWithSelf` are (runtime-checkable) aliases for\n`CanEnter[Self]` and `CanWith[Self, R]`, respectively.\n\nFor the `async with` statement the interfaces look very similar:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	method(s)	type(s)
	`__aenter__`	\n `CanAEnter[C]`, or \n `CanAEnterSelf`\n
	`__aexit__`	`CanAExit[R=None]`
`async with _ as c:`	\n `__aenter__`, and \n `__aexit__`\n	\n `CanAsyncWith[C, R=None]`, or \n `CanAsyncWithSelf[R=None]`\n

\n\n#### Descriptors\n\nInterfaces for [descriptors](https://docs.python.org/3/howto/descriptor.html).\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	method	type
\n `v: V = T().d` \n `vt: VT = T.d`\n	`__get__`	`CanGet[T: object, V, VT = V]`
`T().k = v`	`__set__`	`CanSet[T: object, V]`
`del T().k`	`__delete__`	`CanDelete[T: object]`
`class T: d = _`	`__set_name__`	`CanSetName[T: object, N: str = str]`

\n\n#### Buffer types\n\nInterfaces for emulating buffer types using the [buffer protocol][BP].\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

operator	operand
expression	method	type
`v = memoryview(_)`	`__buffer__`	`CanBuffer[T: int = int]`
`del v`	`__release_buffer__`	`CanReleaseBuffer`

\n\n[BP]: https://docs.python.org/3/reference/datamodel.html#python-buffer-protocol\n\n### `optype.copy`\n\nFor the [`copy`][CP] standard library, `optype.copy` provides the following\nruntime-checkable interfaces:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

`copy` standard library	`optype.copy`
function	type	method
`copy.copy(_) -> R`	`__copy__() -> R`	`CanCopy[R]`
`copy.deepcopy(_, memo={}) -> R`	`__deepcopy__(memo, /) -> R`	`CanDeepcopy[R]`
\n `copy.replace(_, /, **changes: V) -> R`\n ^[1]\n	`__replace__(**changes: V) -> R`	`CanReplace[V, R]`

\n\n^[1] *`copy.replace` requires `python>=3.13`\n(but `optype.copy.CanReplace` doesn't)*\n\nIn practice, it makes sense that a copy of an instance is the same type as the\noriginal.\nBut because `typing.Self` cannot be used as a type argument, this difficult\nto properly type.\nInstead, you can use the `optype.copy.Can{}Self` types, which are the\nruntime-checkable equivalents of the following (recursive) type aliases:\n\n```python\ntype CanCopySelf = CanCopy[CanCopySelf]\ntype CanDeepcopySelf = CanDeepcopy[CanDeepcopySelf]\ntype CanReplaceSelf[V] = CanReplace[V, CanReplaceSelf[V]]\n```\n\n[CP]: https://docs.python.org/3/library/copy.html\n\n### `optype.dataclasses`\n\nFor the [`dataclasses`][DC] standard library, `optype.dataclasses` provides the\n`HasDataclassFields[V: Mapping[str, Field]]` interface.\nIt can conveniently be used to check whether a type or instance is a\ndataclass, i.e. `isinstance(obj, HasDataclassFields)`.\n\n[DC]: https://docs.python.org/3/library/dataclasses.html\n\n### `optype.inspect`\n\nA collection of functions for runtime inspection of types, modules, and other\nobjects.\n\n\n \n \n \n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n

Function	Description
`get_args(_)`	\n\nA better alternative to [`typing.get_args()`][GET_ARGS], that\n\n- unpacks `typing.Annotated` and Python 3.12 `type _` alias types\n (i.e. `typing.TypeAliasType`),\n- recursively flattens unions and nested `typing.Literal` types, and\n- raises `TypeError` if not a type expression.\n\nReturn a `tuple[type \| object, ...]` of type arguments or parameters.\n\nTo illustrate one of the (many) issues with `typing.get_args`:\n\n```pycon\n>>> from typing import Literal, TypeAlias, get_args\n>>> Falsy: TypeAlias = Literal[None] \| Literal[False, 0] \| Literal[\"\", b\"\"]\n>>> get_args(Falsy)\n(typing.Literal[None], typing.Literal[False, 0], typing.Literal['', b''])\n```\n\nBut this is in direct contradiction with the\n[official typing documentation][LITERAL-DOCS]:\n\n> When a Literal is parameterized with more than one value, it’s treated as\n> exactly equivalent to the union of those types.\n> That is, `Literal[v1, v2, v3]` is equivalent to\n> `Literal[v1] \| Literal[v2] \| Literal[v3]`.\n\nSo this is why `optype.inspect.get_args` should be used\n\n```pycon\n>>> import optype as opt\n>>> opt.inspect.get_args(Falsy)\n(None, False, 0, '', b'')\n```\n\nAnother issue of `typing.get_args` is with Python 3.12 `type _ = ...` aliases,\nwhich are meant as a replacement for `_: typing.TypeAlias = ...`, and should\ntherefore be treated equally:\n\n```pycon\n>>> import typing\n>>> import optype as opt\n>>> type StringLike = str \| bytes\n>>> typing.get_args(StringLike)\n()\n>>> opt.inspect.get_args(StringLike)\n(, )\n```\n\nClearly, `typing.get_args` fails misarably here; it would have been better\nif it would have raised an error, but it instead returns an empty tuple,\nhiding the fact that it doesn't support the new `type _ = ...` aliases.\nBut luckily, `optype.inspect.get_args` doesn't have this problem, and treats\nit just like it treats `typing.Alias` (and so do the other `optype.inspect`\nfunctions).\n\n
`get_protocol_members(_)`	\n\nA better alternative to [`typing.get_protocol_members()`][PROTO_MEM], that\n\n- doesn't require Python 3.13 or above,\n- supports [PEP 695][PEP695] `type _` alias types on Python 3.12 and above,\n- unpacks unions of `typing.Literal` ...\n- ... and flattens them if nested within another `typing.Literal`,\n- treats `typing.Annotated[T]` as `T`, and\n- raises a `TypeError` if the passed value isn't a type expression.\n\nReturns a `frozenset[str]` with member names.\n\n
`get_protocols(_)`	\n\nReturns a `frozenset[type]` of the public protocols within the passed module.\nPass `private=True` to also return the private protocols.\n\n
`is_iterable(_)`	\n\nCheck whether the object can be iterated over, i.e. if it can be used in a\n`for` loop, without attempting to do so.\nIf `True` is returned, then the object is a `optype.typing.AnyIterable`\ninstance.\n\n
`is_final(_)`	\n\nCheck if the type, method / classmethod / staticmethod / property, is\ndecorated with [`@typing.final`][@FINAL].\n\nNote that a `@property` won't be recognized unless the `@final` decorator is\nplaced below the `@property` decorator.\nSee the function docstring for more information.\n\n
`is_protocol(_)`	\n\nA backport of [`typing.is_protocol`][IS_PROTO] that was added in Python 3.13,\na re-export of [`typing_extensions.is_protocol`][IS_PROTO_EXT].\n\n
`is_runtime_protocol(_)`	\n\nCheck if the type expression is a runtime-protocol, i.e. a\n`typing.Protocol` type, decorated with `@typing.runtime_checkable` (also\nsupports `typing_extensions`).\n\n
`is_union_type(_)`	\n\nCheck if the type is a [`typing.Union`][UNION] type, e.g. `str \| int`.\n\nUnlike `isinstance(_, types.Union)`, this function also returns `True` for\nunions of user-defined `Generic` or `Protocol` types (because those are\ndifferent union types for some reason).\n\n
`is_generic_alias(_)`	\n\nCheck if the type is a subscripted type, e.g. `list[str]` or\n`optype.CanNext[int]`, but not `list`, `CanNext`.\n\nUnlike `isinstance(_, typing.GenericAlias)`, this function also returns `True`\nfor user-defined `Generic` or `Protocol` types (because those are\nuse a different generic alias for some reason).\n\nEven though technically `T1 \| T2` is represented as `typing.Union[T1, T2]`\n(which is a (special) generic alias), `is_generic_alias` will returns `False`\nfor such union types, because calling `T1 \| T2` a subscripted type just\ndoesn't make much sense.\n\n

\n\n> [!NOTE]\n> All functions in `optype.inspect` also work for Python 3.12 `type _` aliases\n> (i.e. `types.TypeAliasType`) and with `typing.Annotated`.\n\n[UNION]: https://docs.python.org/3/library/typing.html#typing.Union\n[LITERAL-DOCS]: https://typing.readthedocs.io/en/latest/spec/literal.html#shortening-unions-of-literals\n[@FINAL]: https://docs.python.org/3/library/typing.html#typing.Literal\n[GET_ARGS]: https://docs.python.org/3/library/typing.html#typing.get_args\n[IS_PROTO]: https://docs.python.org/3.13/library/typing.html#typing.is_protocol\n[IS_PROTO_EXT]: https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.is_protocol\n[PROTO_MEM]: https://docs.python.org/3.13/library/typing.html#typing.get_protocol_members\n\n### `optype.io`\n\nA collection of protocols and type-aliases that, unlike their analogues in `_typeshed`,\nare accessible at runtime, and use a consistent naming scheme.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

`optype.io` protocol	implements	replaces
`CanFSPath[+T: str \| bytes = ...]`	`__fspath__: () -> T`	`os.PathLike[AnyStr]`
`CanRead[+T]`	`read: () -> T`
`CanReadN[+T]`	`read: (int) -> T`	`_typeshed.SupportsRead[T]`
`CanReadline[+T]`	`readline: () -> T`	`_typeshed.SupportsNoArgReadline[+T]`
`CanReadlineN[+T]`	`readline: (int) -> T`	`_typeshed.SupportsReadline[+T]`
`CanWrite[-T, +RT = object]`	`write: (T) -> RT`	`_typeshed.SupportsWrite[-T]`
`CanFlush[+RT = object]`	`write: (T) -> RT`	`_typeshed.SupportsWrite`
`CanFileno`	`fileno: () -> int`	`_typeshed.HasFileno`

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

`optype.io` type alias	expression	replaces
`ToPath[+T: str \| bytes = ...]`	`T \| CanFSPath[T]`	\n `_typeshed.StrPath` \n `_typeshed.BytesPath` \n `_typeshed.StrOrBytesPath` \n `_typeshed.GenericPath[AnyStr]` \n
`ToFileno`	`int \| CanFileno`	`_typeshed.FileDescriptorLike`

\n\n### `optype.json`\n\nType aliases for the `json` standard library:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

`json.load(s)` return type	`json.dumps(s)` input type
`Value`	`AnyValue`
`Array[V: Value = Value]`	`AnyArray[V: AnyValue = AnyValue]`
`Object[V: Value = Value]`	`AnyObject[V: AnyValue = AnyValue]`

\n\nThe `(Any)Value` can be any json input, i.e. `Value | Array | Object` is\nequivalent to `Value`.\nIt's also worth noting that `Value` is a subtype of `AnyValue`, which means\nthat `AnyValue | Value` is equivalent to `AnyValue`.\n\n### `optype.pickle`\n\nFor the [`pickle`][PK] standard library, `optype.pickle` provides the following\ninterfaces:\n\n[PK]: https://docs.python.org/3/library/pickle.html\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

method(s)	signature (bound)	type
`__reduce__`	`() -> R`	`CanReduce[R: str \| tuple = ...]`
`__reduce_ex__`	`(CanIndex) -> R`	`CanReduceEx[R: str \| tuple = ...]`
`__getstate__`	`() -> S`	`CanGetstate[S]`
`__setstate__`	`(S) -> None`	`CanSetstate[S]`
\n `__getnewargs__` \n `__new__`\n	\n `() -> tuple[V, ...]` \n `(V) -> Self` \n	`CanGetnewargs[V]`
\n `__getnewargs_ex__` \n `__new__`\n	\n `() -> tuple[tuple[V, ...], dict[str, KV]]` \n `(tuple[V, ...], *dict[str, KV]) -> Self` \n	`CanGetnewargsEx[V, KV]`

\n\n\n\n### `optype.string`\n\nThe [`string`](https://docs.python.org/3/library/string.html) standard\nlibrary contains practical constants, but it has two issues:\n\n- The constants contain a collection of characters, but are represented as\n a single string. This makes it practically impossible to type-hint the\n individual characters, so typeshed currently types these constants as a\n `LiteralString`.\n- The names of the constants are inconsistent, and doesn't follow\n [PEP 8](https://peps.python.org/pep-0008/#constants).\n\nSo instead, `optype.string` provides an alternative interface, that is\ncompatible with `string`, but with slight differences:\n\n- For each constant, there is a corresponding `Literal` type alias for\n the *individual* characters. Its name matches the name of the constant,\n but is singular instead of plural.\n- Instead of a single string, `optype.string` uses a `tuple` of characters,\n so that each character has its own `typing.Literal` annotation.\n Note that this is only tested with (based)pyright / pylance, so it might\n not work with mypy (it has more bugs than it has lines of codes).\n- The names of the constant are consistent with PEP 8, and use a postfix\n notation for variants, e.g. `DIGITS_HEX` instead of `hexdigits`.\n- Unlike `string`, `optype.string` has a constant (and type alias) for\n binary digits `'0'` and `'1'`; `DIGITS_BIN` (and `DigitBin`). Because\n besides `oct` and `hex` functions in `builtins`, there's also the\n `builtins.bin` function.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

`string._`	`optype.string._`
constant	char type	constant	char type
missing	`DIGITS_BIN`	`DigitBin`
`octdigits`	`LiteralString`	`DIGITS_OCT`	`DigitOct`
`digits`	`DIGITS`	`Digit`
`hexdigits`	`DIGITS_HEX`	`DigitHex`
`ascii_letters`	`LETTERS`	`Letter`
`ascii_lowercase`	`LETTERS_LOWER`	`LetterLower`
`ascii_uppercase`	`LETTERS_UPPER`	`LetterUpper`
`punctuation`	`PUNCTUATION`	`Punctuation`
`whitespace`	`WHITESPACE`	`Whitespace`
`printable`	`PRINTABLE`	`Printable`

\n\nEach of the `optype.string` constants is exactly the same as the corresponding\n`string` constant (after concatenation / splitting), e.g.\n\n```pycon\n>>> import string\n>>> import optype as opt\n>>> \"\".join(opt.string.PRINTABLE) == string.printable\nTrue\n>>> tuple(string.printable) == opt.string.PRINTABLE\nTrue\n```\n\nSimilarly, the values within a constant's `Literal` type exactly match the\nvalues of its constant:\n\n```pycon\n>>> import optype as opt\n>>> from optype.inspect import get_args\n>>> get_args(opt.string.Printable) == opt.string.PRINTABLE\nTrue\n```\n\nThe `optype.inspect.get_args` is a non-broken variant of `typing.get_args`\nthat correctly flattens nested literals, type-unions, and PEP 695 type aliases,\nso that it matches the official typing specs.\n*In other words; `typing.get_args` is yet another fundamentally broken\npython-typing feature that's useless in the situations where you need it\nmost.*\n\n### `optype.typing`\n\n#### `Any*` type aliases\n\nType aliases for anything that can *always* be passed to\n`int`, `float`, `complex`, `iter`, or `typing.Literal`\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Python constructor	`optype.typing` alias
`int(_)`	`AnyInt`
`float(_)`	`AnyFloat`
`complex(_)`	`AnyComplex`
`iter(_)`	`AnyIterable`
`typing.Literal[_]`	`AnyLiteral`

\n\n> [!NOTE]\n> Even though *some* `str` and `bytes` can be converted to `int`, `float`,\n> `complex`, most of them can't, and are therefore not included in these\n> type aliases.\n\n#### `Empty*` type aliases\n\nThese are builtin types or collections that are empty, i.e. have length 0 or\nyield no elements.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

instance	`optype.typing` type
`''`	`EmptyString`
`b''`	`EmptyBytes`
`()`	`EmptyTuple`
`[]`	`EmptyList`
`{}`	`EmptyDict`
`set()`	`EmptySet`
`(i for i in range(0))`	`EmptyIterable`

\n\n#### Literal types\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Literal values	`optype.typing` type	Notes
`{False, True}`	`LiteralFalse`	\n Similar to `typing.LiteralString`, but for\n `bool`.\n
`{0, 1, ..., 255}`	`LiteralByte`	\n Integers in the range 0-255, that make up a `bytes`\n or `bytearray` objects.\n

\n\n### `optype.dlpack`\n\nA collection of low-level types for working [DLPack](DOC-DLPACK).\n\n#### Protocols\n\n\n \n \n \n \n \n\n\n \n \n \n\n\n \n

type signature	bound method
\n\n```plain\nCanDLPack[\n +T = int,\n +D: int = int,\n]\n```\n\n	\n\n```python\ndef __dlpack__(\n *,\n stream: int \| None = ...,\n max_version: tuple[int, int] \| None = ...,\n dl_device: tuple[T, D] \| None = ...,\n copy: bool \| None = ...,\n) -> types.CapsuleType: ...\n```\n\n
\n\n```plain\nCanDLPackDevice[\n +T = int,\n +D: int = int,\n]\n```\n\n	\n\n```python\ndef __dlpack_device__() -> tuple[T, D]: ...\n```\n\n

\n\nThe `+` prefix indicates that the type parameter is *co*variant.\n\n#### Enums\n\nThere are also two convenient\n[`IntEnum`](https://docs.python.org/3/library/enum.html#enum.IntEnum)s\nin `optype.dlpack`: `DLDeviceType` for the device types, and `DLDataTypeCode` for the\ninternal type-codes of the `DLPack` data types.\n\n\n\n### `optype.numpy`\n\nOptype supports both NumPy 1 and 2.\nThe current minimum supported version is `1.24`,\nfollowing [NEP 29][NEP29] and [SPEC 0][SPEC0].\n\nWhen using `optype.numpy`, it is recommended to install `optype` with the\n`numpy` extra, ensuring version compatibility:\n\n```shell\npip install \"optype[numpy]\"\n```\n\n> [!NOTE]\n> For the remainder of the `optype.numpy` docs, assume that the following\n> import aliases are available.\n>\n> ```python\n> from typing import Any, Literal\n> import numpy as np\n> import numpy.typing as npt\n> import optype.numpy as onp\n> ```\n>\n> For the sake of brevity and readability, the [PEP 695][PEP695] and\n> [PEP 696][PEP696] type parameter syntax will be used, which is supported\n> since Python 3.13.\n\n#### Shape-typing\n\n##### Array aliases\n\nOptype provides the generic `onp.Array` type alias for `np.ndarray`.\nIt is similar to `npt.NDArray`, but includes two (optional) type parameters:\none that matches the *shape type* (`ND: tuple[int, ...]`),\nand one that matches the *scalar type* (`ST: np.generic`).\n\nWhen we put the definitions of `npt.NDArray` and `onp.Array` side-by-side,\ntheir differences become clear:\n\n

\n\n\n\n\n\n\n\n\n\n\n

\n\n`numpy.typing.NDArray`[^1]\n\n	\n\n`optype.numpy.Array`\n\n	\n\n`optype.numpy.ArrayND`\n\n
\n\n```python\ntype NDArray[\n # no shape type\n SCT: generic, # no default\n] = ndarray[Any, dtype[SCT]]\n```\n\n	\n\n```python\ntype Array[\n NDT: (int, ...) = (int, ...),\n SCT: generic = generic,\n] = ndarray[NDT, dtype[SCT]]\n```\n\n	\n\n```python\ntype ArrayND[\n SCT: generic = generic,\n NDT: (int, ...) = (int, ...),\n] = ndarray[NDT, dtype[SCT]]\n```\n\n

\n\nAdditionally, there are the four `Array{0,1,2,3}D` aliases, which are\nequivalent to `Array` with `tuple[()]`, `tuple[int]`, `tuple[int, int]` and\n`tuple[int, int, int]` as shape-type, respectively.\n\n[^1]: Since `numpy>=2.2` the `NDArray` alias uses `tuple[int, ...]` as shape-type\n instead of `Any`.\n\n> [!TIP]\n> Before NumPy 2.1, the shape type parameter of `ndarray` (i.e. the type of\n> `ndarray.shape`) was invariant. It is therefore recommended to not use `Literal`\n> within shape types on `numpy<2.1`. So with `numpy>=2.1` you can use\n> `tuple[Literal[3], Literal[3]]` without problem, but with `numpy<2.1` you should use\n> `tuple[int, int]` instead.\n>\n> See [numpy/numpy#25729](https://github.com/numpy/numpy/issues/25729) and\n> [numpy/numpy#26081](https://github.com/numpy/numpy/pull/26081) for details.\n\nIn the same way as `ArrayND` for `ndarray` (shown for reference), its subtypes\n`np.ma.MaskedArray` and `np.matrix` are also aliased:\n\n\n\n\n\n\n\n\n\n\n\n\n\n

\n\n`ArrayND` (`np.ndarray`)\n\n	\n\n`MArray` (`np.ma.MaskedArray`)\n\n	\n\n`Matrix` (`np.matrix`)\n\n
\n\n```python\ntype ArrayND[\n SCT: generic = generic,\n NDT: (int, ...) = (int, ...),\n] = ndarray[NDT, dtype[SCT]]\n```\n\n	\n\n```python\ntype MArray[\n SCT: generic = generic,\n NDT: (int, ...) = (int, ...),\n] = ma.MaskedArray[NDT, dtype[SCT]]\n```\n\n	\n\n```python\ntype Matrix[\n SCT: generic = generic,\n M: int = int,\n N: int = M,\n] = matrix[(M, N), dtype[SCT]]\n```\n\n

\n\nFor masked arrays with specific `ndim`, you could also use one of the four\n`MArray{0,1,2,3}D` aliases.\n\n##### Array typeguards\n\nTo check whether a given object is an instance of `Array{0,1,2,3,N}D`, in a way that\nstatic type-checkers also understand it, the following [PEP 742][PEP742] typeguards can\nbe used:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

typeguard	narrows to	shape type
`optype.numpy._`	`builtins._`
`is_array_nd`	`ArrayND[ST]`	`tuple[int, ...]`
`is_array_0d`	`Array0D[ST]`	`tuple[()]`
`is_array_1d`	`Array1D[ST]`	`tuple[int]`
`is_array_2d`	`Array2D[ST]`	`tuple[int, int]`
`is_array_3d`	`Array3D[ST]`	`tuple[int, int, int]`

\n\nThese functions additionally accept an optional `dtype` argument, that can either be\na `np.dtype[ST]` instance, a `type[ST]`, or something that has a `dtype: np.dtype[ST]`\nattribute.\nThe signatures are almost identical to each other, and in the `0d` case it roughly\nlooks like this:\n\n```py\nST = TypeVar(\"ST\", bound=np.generic, default=np.generic)\n_ToDType: TypeAlias = type[ST] | np.dtype[ST] | HasDType[np.dtype[ST]]\n\n\ndef is_array_0d(a, /, dtype: _ToDType[ST] | None = None) -> TypeIs[Array0D[ST]]: ...\n```\n\n##### Shape aliases\n\nA *shape* is nothing more than a tuple of (non-negative) integers, i.e.\nan instance of `tuple[int, ...]` such as `(42,)`, `(480, 720, 3)` or `()`.\nThe length of a shape is often referred to as the *number of dimensions*\nor the *dimensionality* of the array or scalar.\nFor arrays this is accessible through the `np.ndarray.ndim`, which is\nan alias for `len(np.ndarray.shape)`.\n\n> [!NOTE]\n> Before NumPy 2, the maximum number of dimensions was `32`, but has since\n> been increased to `ndim <= 64`.\n\nTo make typing the shape of an array easier, optype provides two families of\nshape type aliases: `AtLeast{N}D` and `AtMost{N}D`.\nThe `{N}` should be replaced by the number of dimensions, which currently\nis limited to `0`, `1`, `2`, and `3`.\n\nBoth of these families are generic, and their (optional) type parameters must\nbe either `int` (default), or a literal (non-negative) integer, i.e. like\n`typing.Literal[N: int]`.\n\nThe names `AtLeast{N}D` and `AtMost{N}D` are pretty much as self-explanatory:\n\n- `AtLeast{N}D` is a `tuple[int, ...]` with `ndim >= N`\n- `AtMost{N}D` is a `tuple[int, ...]` with `ndim <= N`\n\nThe shape aliases are roughly defined as:\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

`AtLeast{N}D`	`AtMost{N}D`
type signature	alias type	type signature	type alias

\n\n```python\ntype AtLeast0D[\n Ds: int = int,\n] = _\n```\n\n	\n\n```python\ntuple[Ds, ...]\n```\n\n	\n\n```python\ntype AtMost0D = _\n```\n\n	\n\n```python\ntuple[()]\n```\n\n

\n\n```python\ntype AtLeast1D[\n D0: int = int,\n Ds: int = int,\n] = _\n```\n\n	\n\n```python\ntuple[\n D0,\n *tuple[Ds, ...],\n]\n```\n\n	\n\n```python\ntype AtMost1D[\n D0: int = int,\n] = _\n```\n\n	\n\n```python\ntuple[D0] \| AtMost0D\n```\n\n

\n\n```python\ntype AtLeast2D[\n D0: int = int,\n D1: int = int,\n Ds: int = int,\n] = _\n```\n\n	\n\n```python\ntuple[\n D0,\n D1,\n *tuple[Ds, ...],\n]\n```\n\n	\n\n```python\ntype AtMost2D[\n D0: int = int,\n D1: int = int,\n] = _\n```\n\n	\n\n\n```python\n(\n tuple[D0, D1]\n \| AtMost1D[D0]\n)\n```\n\n\n

\n\n```python\ntype AtLeast3D[\n D0: int = int,\n D1: int = int,\n D2: int = int,\n Ds: int = int,\n] = _\n```\n\n	\n\n```python\ntuple[\n D0,\n D1,\n D2,\n *tuple[Ds, ...],\n]\n```\n\n	\n\n```python\ntype AtMost3D[\n D0: int = int,\n D1: int = int,\n D2: int = int,\n] = _\n```\n\n	\n\n\n```python\n(\n tuple[D0, D1, D2]\n \| AtMost2D[D0, D1]\n)\n```\n\n\n

\n\n#### Array-likes\n\nSimilar to the `numpy._typing._ArrayLike{}_co` *coercible array-like* types,\n`optype.numpy` provides the `optype.numpy.To{}ND`. Unlike the ones in `numpy`, these\ndon't accept \"bare\" scalar types (the `__len__` method is required).\nAdditionally, there are the `To{}1D`, `To{}2D`, and `To{}3D` for vector-likes,\nmatrix-likes, and cuboid-likes, and the `To{}` aliases for \"bare\" scalar types.\n\n\n\n \n \n \n\n\n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n\n \n \n \n \n \n\n

`builtins`	`numpy`	`optype.numpy`
exact scalar types	scalar-like	`{1,2,3,N}`-d array-like	strict `{1,2,3}`-d array-like
`False`	`False_`	`ToJustFalse`
\n `False` \n `\| 0`\n	`False_`	`ToFalse`
`True`	`True_`	`ToJustTrue`
\n `True` \n `\| 1`\n	`True_`	`ToTrue`
`bool`	`bool_`	`ToJustBool`	`ToJustBool{}D`	`ToJustBoolStrict{}D`
\n `bool` \n `\| 0` \n `\| 1`\n	`bool_`	`ToBool`	`ToBool{}D`	`ToBoolStrict{}D`
`~int`	`integer`	`ToJustInt`	`ToJustInt{}D`	`ToJustIntStrict{}D`
\n `int` \n `\| bool`\n	\n `integer` \n `\| bool_`\n	`ToInt`	`ToInt{}D`	`ToIntStrict{}D`
`~float`	`float64`	`ToJustFloat64`	`ToJustFloat64_{}D`	`ToJustFloat64Strict{}D`
\n `float` \n `\| int` \n `\| bool`\n	\n `float64` \n `\| float32` \n `\| float16` \n `\| integer` \n `\| bool_`\n	`ToFloat64`	`ToFloat64_{}D`	`ToFloat64Strict{}D`
`~float`	`floating`	`ToJustFloat`	`ToJustFloat{}D`	`ToJustFloatStrict{}D`
\n `float` \n `\| int` \n `\| bool`\n	\n `floating` \n `\| integer` \n `\| bool_`\n	`ToFloat`	`ToFloat{}D`	`ToFloatStrict{}D`
`~complex`	`complex128`	`ToJustComplex128`	`ToJustComplex128_{}D`	`ToJustComplex128Strict{}D`
\n `complex` \n `\| float` \n `\| int` \n `\| bool`\n	\n `complex128` \n `\| complex64` \n `\| float64` \n `\| float64` \n `\| float32` \n `\| float16` \n `\| integer` \n `\| bool_`\n	`ToComplex128`	`ToComplex128_{}D`	`ToComplex128Strict{}D`
`~complex`	`complexfloating`	`ToJustComplex`	`ToJustComplex{}D`	`ToJustComplexStrict{}D`
\n `complex` \n `\| float` \n `\| int` \n `\| bool`\n	\n `number` \n `\| bool_`\n	`ToComplex`	`ToComplex{}D`	`ToComplexStrict{}D`
\n `bytes` \n `\| str` \n `\| complex` \n `\| float` \n `\| int` \n `\| bool`\n	`generic`	`ToScalar`	`ToArray{}D`	`ToArrayStrict{}D`

\n\n> [!NOTE]\n> The `To*Strict{1,2,3}D` aliases were added in `optype 0.7.3`.\n>\n> These array-likes with *strict shape-type* require the shape-typed input to be\n> shape-typed.\n> This means that e.g. `ToFloat1D` and `ToFloat2D` are disjoint (non-overlapping),\n> and makes them suitable to overload array-likes of a particular dtype for different\n> numbers of dimensions.\n\n\n\n> [!NOTE]\n> The `ToJust{Bool,Float,Complex}*` type aliases were added in `optype 0.8.0`.\n>\n> See [`optype.Just`](#just) for more information.\n\n\n\n> [!NOTE]\n> The `To[Just]{False,True}` type aliases were added in `optype 0.9.1`.\n>\n> These only include the `np.bool` types on `numpy>=2.2`. Before that, `np.bool`\n> wasn't generic, making it impossible to distinguish between `np.False_` and `np.True_`\n> using static typing.\n\nSource code: [`optype/numpy/_to.py`][CODE-NP-TO]\n\n> [!NOTE]\n> The `ToArrayStrict{1,2,3}D` types are generic since `optype 0.9.1`, analogous to\n> their non-strict dual type, `ToArray{1,2,3}D`.\n\nSource code: [`optype/numpy/_to.py`][CODE-NP-TO]\n\n#### Literals\n\n| Type Alias | String values |\n| --------------- | ------------------------------------------------------------------ |\n| `ByteOrder` | `ByteOrderChar \\| ByteOrderName \\| {L, B, N, I, S}` |\n| `ByteOrderChar` | `{<, >, =, \\|}` |\n| `ByteOrderName` | `{little, big, native, ignore, swap}` |\n| `Casting` | `CastingUnsafe \\| CastingSafe` |\n| `CastingUnsafe` | `{unsafe}` |\n| `CastingSafe` | `{no, equiv, safe, same_kind}` |\n| `ConvolveMode` | `{full, same, valid}` |\n| `Device` | `{cpu}` |\n| `IndexMode` | `{raise, wrap, clip}` |\n| `OrderCF` | `{C, F}` |\n| `OrderACF` | `{A, C, F}` |\n| `OrderKACF` | `{K, A, C, F}` |\n| `PartitionKind` | `{introselect}` |\n| `SortKind` | `{Q, quick[sort], M, merge[sort], H, heap[sort], S, stable[sort]}` |\n| `SortSide` | `{left, right}` |\n\n#### `compat` submodule\n\nCompatibility module for supporting a wide (currently `1.23` - `2.2`) range of numpy\nversions. It contains two kinds of things:\n\n- All [`numpy.exceptions`][NP-EXC], which didn't exist before `<1.25`, making it very\ndifficult to use if you need to support those versions, especially within stubs.\n- The abstract numeric scalar types, with `numpy>=2.2` type-parameter defaults, which\nI explained in the [`release notes`][NP-REL22].\n\n[NP-EXC]: https://numpy.org/doc/stable/reference/routines.exceptions.html\n[NP-REL22]: https://numpy.org/doc/stable/release/2.2.0-notes.html#new-features\n\n#### `random` submodule\n\n[SPEC 7](https://scientific-python.org/specs/spec-0007/) -compatible type aliases.\nThe `optype.numpy.random` module provides three type aliases: `RNG`, `ToRNG`, and\n`ToSeed`.\n\nIn general, the most useful one is `ToRNG`, which describes what can be\npassed to `numpy.random.default_rng`. It is defined as the union of `RNG`, `ToSeed`,\nand `numpy.random.BitGenerator`.\n\nThe `RNG` is the union type of `numpy.random.Generator` and its legacy dual type,\n`numpy.random.RandomState`.\n\n`ToSeed` accepts integer-like scalars, sequences, and arrays, as well as instances of\n`numpy.random.SeedSequence`.\n\n#### `DType`\n\nIn NumPy, a *dtype* (data type) object, is an instance of the\n`numpy.dtype[ST: np.generic]` type.\nIt's commonly used to convey metadata of a scalar type, e.g. within arrays.\n\nBecause the type parameter of `np.dtype` isn't optional, it could be more\nconvenient to use the alias `optype.numpy.DType`, which is defined as:\n\n```python\ntype DType[ST: np.generic = np.generic] = np.dtype[ST]\n```\n\nApart from the \"CamelCase\" name, the only difference with `np.dtype` is that\nthe type parameter can be omitted, in which case it's equivalent to\n`np.dtype[np.generic]`, but shorter.\n\n#### `Scalar`\n\nThe `optype.numpy.Scalar` interface is a generic runtime-checkable protocol,\nthat can be seen as a \"more specific\" `np.generic`, both in name, and from\na typing perspective.\n\nIts type signature looks roughly like this:\n\n```python\ntype Scalar[\n # The \"Python type\", so that `Scalar.item() -> PT`.\n PT: object,\n # The \"N-bits\" type (without having to deal with `npt.NBitBase`).\n # It matches the `itemsize: NB` property.\n NB: int = int,\n] = ...\n```\n\nIt can be used as e.g.\n\n```python\nare_birds_real: Scalar[bool, Literal[1]] = np.bool_(True)\nthe_answer: Scalar[int, Literal[2]] = np.uint16(42)\nalpha: Scalar[float, Literal[8]] = np.float64(1 / 137)\n```\n\n> [!NOTE]\n> The second type argument for `itemsize` can be omitted, which is equivalent\n> to setting it to `int`, so `Scalar[PT]` and `Scalar[PT, int]` are equivalent.\n\n#### `UFunc`\n\nA large portion of numpy's public API consists of *universal functions*, often\ndenoted as [ufuncs][DOC-UFUNC], which are (callable) instances of\n[`np.ufunc`][REF_UFUNC].\n\n> [!TIP]\n> Custom ufuncs can be created using [`np.frompyfunc`][REF_FROMPY], but also\n> through a user-defined class that implements the required attributes and\n> methods (i.e., duck typing).\n>\nBut `np.ufunc` has a big issue; it accepts no type parameters.\nThis makes it very difficult to properly annotate its callable signature and\nits literal attributes (e.g. `.nin` and `.identity`).\n\nThis is where `optype.numpy.UFunc` comes into play:\nIt's a runtime-checkable generic typing protocol, that has been thoroughly\ntype- and unit-tested to ensure compatibility with all of numpy's ufunc\ndefinitions.\nIts generic type signature looks roughly like:\n\n```python\ntype UFunc[\n # The type of the (bound) `__call__` method.\n Fn: CanCall = CanCall,\n # The types of the `nin` and `nout` (readonly) attributes.\n # Within numpy these match either `Literal[1]` or `Literal[2]`.\n Nin: int = int,\n Nout: int = int,\n # The type of the `signature` (readonly) attribute;\n # Must be `None` unless this is a generalized ufunc (gufunc), e.g.\n # `np.matmul`.\n Sig: str | None = str | None,\n # The type of the `identity` (readonly) attribute (used in `.reduce`).\n # Unless `Nin: Literal[2]`, `Nout: Literal[1]`, and `Sig: None`,\n # this should always be `None`.\n # Note that `complex` also includes `bool | int | float`.\n Id: complex | bytes | str | None = float | None,\n] = ...\n```\n\n> [!NOTE]\n> Unfortunately, the extra callable methods of `np.ufunc` (`at`, `reduce`,\n> `reduceat`, `accumulate`, and `outer`), are incorrectly annotated (as `None`\n> *attributes*, even though at runtime they're methods that raise a\n> `ValueError` when called).\n> This currently makes it impossible to properly type these in\n> `optype.numpy.UFunc`; doing so would make it incompatible with numpy's\n> ufuncs.\n\n#### `Any*Array` and `Any*DType`\n\nThe `Any{Scalar}Array` type aliases describe array-likes that are coercible to an\n`numpy.ndarray` with specific [dtype][REF-DTYPES].\n\nUnlike `numpy.typing.ArrayLike`, these `optype.numpy` aliases **don't**\naccept \"bare\" scalar types such as `float` and `np.float64`. However, arrays of\n\"zero dimensions\" like `onp.Array[tuple[()], np.float64]` will be accepted.\nThis is in line with the behavior of [`numpy.isscalar`][REF-ISSCALAR] on `numpy >= 2`.\n\n```py\nimport numpy.typing as npt\nimport optype.numpy as onp\n\nv_np: npt.ArrayLike = 3.14 # accepted\nv_op: onp.AnyArray = 3.14 # rejected\n\nsigma1_np: npt.ArrayLike = [[0, 1], [1, 0]] # accepted\nsigma1_op: onp.AnyArray = [[0, 1], [1, 0]] # accepted\n```\n\n> [!NOTE]\n> The [`numpy.dtypes` docs][REF-DTYPES] exists since NumPy 1.25, but its\n> type annotations were incorrect before NumPy 2.1 (see\n> [numpy/numpy#27008](https://github.com/numpy/numpy/pull/27008))\n\nSee the [docs][REF-SCT] for more info on the NumPy scalar type hierarchy.\n\n[REF-SCT]: https://numpy.org/doc/stable/reference/arrays.scalars.html\n[REF-DTYPES]: https://numpy.org/doc/stable/reference/arrays.dtypes.html\n[REF-ISSCALAR]: https://numpy.org/doc/stable/reference/generated/numpy.isscalar.html\n\n##### Abstract types\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

`numpy._`	`optype.numpy._`
scalar	scalar base	array-like	dtype-like
`generic`		`AnyArray`	`AnyDType`
`number`	`generic`	`AnyNumberArray`	`AnyNumberDType`
`integer`	`number`	`AnyIntegerArray`	`AnyIntegerDType`
`inexact`	`AnyInexactArray`	`AnyInexactDType`
`unsignedinteger`	`integer`	`AnyUnsignedIntegerArray`	`AnyUnsignedIntegerDType`
`signedinteger`	`AnySignedIntegerArray`	`AnySignedIntegerDType`
`floating`	`inexact`	`AnyFloatingArray`	`AnyFloatingDType`
`complexfloating`	`AnyComplexFloatingArray`	`AnyComplexFloatingDType`

\n\n##### Unsigned integers\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n

`numpy._`	`numpy.dtypes._`	`optype.numpy._`
scalar	scalar base	dtype	array-like	dtype-like
\n\n`uint_` [^5]\n\n	`unsignedinteger`		`AnyUIntArray`	`AnyUIntDType`
`uintp`	`AnyUIntPArray`	`AnyUIntPDType`
`uint8`, `ubyte`	`UInt8DType`	`AnyUInt8Array`	`AnyUInt8DType`
`uint16`, `ushort`	`UInt16DType`	`AnyUInt16Array`	`AnyUInt16DType`
\n\n`uint32`[^6]\n\n	`UInt32DType`	`AnyUInt32Array`	`AnyUInt32DType`
`uint64`	`UInt64DType`	`AnyUInt64Array`	`AnyUInt64DType`
\n\n`uintc`[^6]\n\n	`UIntDType`	`AnyUIntCArray`	`AnyUIntCDType`
\n\n`ulong`[^7]\n\n	`ULongDType`	`AnyULongArray`	`AnyULongDType`
`ulonglong`	`ULongLongDType`	`AnyULongLongArray`	`AnyULongLongDType`

\n\n##### Signed integers\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n

`numpy._`	`numpy.dtypes._`	`optype.numpy._`
scalar	scalar base	dtype	array-like	dtype-like
\n\n`int_` [^5]\n\n	`signedinteger`		`AnyIntArray`	`AnyIntDType`
`intp`	`AnyIntPArray`	`AnyIntPDType`
`int8`, `byte`	`Int8DType`	`AnyInt8Array`	`AnyInt8DType`
`int16`, `short`	`Int16DType`	`AnyInt16Array`	`AnyInt16DType`
\n\n`int32`[^6]\n\n	`Int32DType`	`AnyInt32Array`	`AnyInt32DType`
`int64`	`Int64DType`	`AnyInt64Array`	`AnyInt64DType`
\n\n`intc`[^6]\n\n	`IntDType`	`AnyIntCArray`	`AnyIntCDType`
\n\n`long`[^7]\n\n	`LongDType`	`AnyLongArray`	`AnyLongDType`
`longlong`	`LongLongDType`	`AnyLongLongArray`	`AnyLongLongDType`

\n\n[^5]: Since NumPy 2, `np.uint` and `np.int_` are aliases for `np.uintp` and `np.intp`, respectively.\n[^6]: On unix-based platforms `np.[u]intc` are aliases for `np.[u]int32`.\n[^7]: On NumPy 1 `np.uint` and `np.int_` are what in NumPy 2 are now the `np.ulong` and `np.long` types, respectively.\n\n##### Real floats\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n

`numpy._`	`numpy.dtypes._`	`optype.numpy._`
scalar	scalar base	dtype	array-like	dtype-like
\n `float16`, \n `half`\n	`np.floating`	`Float16DType`	`AnyFloat16Array`	`AnyFloat16DType`
\n `float32`, \n `single`\n	`Float32DType`	`AnyFloat32Array`	`AnyFloat32DType`
\n `float64`, \n `double`\n	\n `np.floating &` \n `builtins.float`\n	`Float64DType`	`AnyFloat64Array`	`AnyFloat64DType`
\n\n`longdouble`[^13]\n\n	`np.floating`	`LongDoubleDType`	`AnyLongDoubleArray`	`AnyLongDoubleDType`

\n\n[^13]: Depending on the platform, `np.longdouble` is (almost always) an alias for **either** `float128`,\n `float96`, or (sometimes) `float64`.\n\n##### Complex floats\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n

`numpy._`	`numpy.dtypes._`	`optype.numpy._`
scalar	scalar base	dtype	array-like	dtype-like
\n `complex64`, \n `csingle`\n	`complexfloating`	`Complex64DType`	`AnyComplex64Array`	`AnyComplex64DType`
\n `complex128`, \n `cdouble`\n	\n `complexfloating &` \n `builtins.complex`\n	`Complex128DType`	`AnyComplex128Array`	`AnyComplex128DType`
\n\n`clongdouble`[^16]\n\n	`complexfloating`	`CLongDoubleDType`	`AnyCLongDoubleArray`	`AnyCLongDoubleDType`

\n\n[^16]: Depending on the platform, `np.clongdouble` is (almost always) an alias for **either** `complex256`,\n `complex192`, or (sometimes) `complex128`.\n\n##### \"Flexible\"\n\nScalar types with \"flexible\" length, whose values have a (constant) length\nthat depends on the specific `np.dtype` instantiation.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

`numpy._`	`numpy.dtypes._`	`optype.numpy._`
scalar	scalar base	dtype	array-like	dtype-like
`str_`	`character`	`StrDType`	`AnyStrArray`	`AnyStrDType`
`bytes_`	`BytesDType`	`AnyBytesArray`	`AnyBytesDType`
`dtype(\"c\")`	`AnyBytes8DType`
`void`	`flexible`	`VoidDType`	`AnyVoidArray`	`AnyVoidDType`

\n\n##### Other types\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n\n \n \n \n \n

`numpy._`	`numpy.dtypes._`	`optype.numpy._`
scalar	scalar base	dtype	array-like	dtype-like
\n\n`bool_`[^0]\n\n	`generic`	`BoolDType`	`AnyBoolArray`	`AnyBoolDType`
`object_`	`ObjectDType`	`AnyObjectArray`	`AnyObjectDType`
`datetime64`	`DateTime64DType`	`AnyDateTime64Array`	`AnyDateTime64DType`
`timedelta64`	\n\n`generic`[^22]\n\n	`TimeDelta64DType`	`AnyTimeDelta64Array`	`AnyTimeDelta64DType`
\n\n[^2056]\n\n		`StringDType`	`AnyStringArray`	`AnyStringDType`

\n\n[^0]: Since NumPy 2, `np.bool` is preferred over `np.bool_`, which only exists for backwards compatibility.\n\n[^22]: At runtime `np.timedelta64` is a subclass of `np.signedinteger`, but this is currently not\n reflected in the type annotations.\n\n[^2056]: The `np.dypes.StringDType` has no associated numpy scalar type, and its `.type` attribute returns the\n `builtins.str` type instead. But from a typing perspective, such a `np.dtype[builtins.str]` isn't a valid type.\n\n#### Low-level interfaces\n\nWithin `optype.numpy` there are several `Can*` (single-method) and `Has*`\n(single-attribute) protocols, related to the `__array_*__` dunders of the\nNumPy Python API.\nThese typing protocols are, just like the `optype.Can*` and `optype.Has*` ones,\nruntime-checkable and extensible (i.e. not `@final`).\n\n> [!TIP]\n> All type parameters of these protocols can be omitted, which is equivalent\n> to passing its upper type bound.\n\n\n \n \n \n \n \n \n\n\n\n \n \n \n\n\n\n \n \n \n\n\n\n \n \n \n\n\n\n \n \n \n\n\n\n \n \n \n\n\n\n \n \n \n\n\n\n \n \n \n\n\n\n \n

Protocol type signature	Implements	NumPy docs
\n\n```python\nclass CanArray[\n ND: tuple[int, ...] = ...,\n ST: np.generic = ...,\n]: ...\n```\n\n	\n\n\n```python\ndef __array__[RT = ST](\n _,\n dtype: DType[RT] \| None = ...,\n) -> Array[ND, RT]\n```\n\n\n	\n\n[User Guide: Interoperability with NumPy][DOC-ARRAY]\n\n

\n\n```python\nclass CanArrayUFunc[\n U: UFunc = ...,\n R: object = ...,\n]: ...\n```\n\n	\n\n```python\ndef __array_ufunc__(\n _,\n ufunc: U,\n method: LiteralString,\n args: object,\n *kwargs: object,\n) -> R: ...\n```\n\n	\n\n[NEP 13][NEP13]\n\n

\n\n```python\nclass CanArrayFunction[\n F: CanCall[..., object] = ...,\n R = object,\n]: ...\n```\n\n	\n\n```python\ndef __array_function__(\n _,\n func: F,\n types: CanIterSelf[type[CanArrayFunction]],\n args: tuple[object, ...],\n kwargs: Mapping[str, object],\n) -> R: ...\n```\n\n	\n\n[NEP 18][NEP18]\n\n

\n\n```python\nclass CanArrayFinalize[\n T: object = ...,\n]: ...\n```\n\n	\n\n```python\ndef __array_finalize__(_, obj: T): ...\n```\n\n	\n\n[User Guide: Subclassing ndarray][DOC-AFIN]\n\n

\n\n```python\nclass CanArrayWrap: ...\n```\n\n	\n\n\n```python\ndef __array_wrap__[ND, ST](\n _,\n array: Array[ND, ST],\n context: (...) \| None = ...,\n return_scalar: bool = ...,\n) -> Self \| Array[ND, ST]\n```\n\n\n	\n\n[API: Standard array subclasses][REF_ARRAY-WRAP]\n\n

\n\n```python\nclass HasArrayInterface[\n V: Mapping[str, object] = ...,\n]: ...\n```\n\n	\n\n```python\n__array_interface__: V\n```\n\n	\n\n[API: The array interface protocol][REF_ARRAY-INTER]\n\n

\n\n```python\nclass HasArrayPriority: ...\n```\n\n	\n\n```python\n__array_priority__: float\n```\n\n	\n\n[API: Standard array subclasses][REF_ARRAY-PRIO]\n\n

\n\n```python\nclass HasDType[\n DT: DType = ...,\n]: ...\n```\n\n	\n\n```python\ndtype: DT\n```\n\n	\n\n[API: Specifying and constructing data types][REF_DTYPE]\n\n

\n\n\n\n[DOC-UFUNC]: https://numpy.org/doc/stable/reference/ufuncs.html\n[DOC-ARRAY]: https://numpy.org/doc/stable/user/basics.interoperability.html#the-array-method\n[DOC-AFIN]: https://numpy.org/doc/stable/user/basics.subclassing.html#the-role-of-array-finalize\n\n[REF_UFUNC]: https://numpy.org/doc/stable/reference/generated/numpy.ufunc.html\n[REF_FROMPY]: https://numpy.org/doc/stable/reference/generated/numpy.frompyfunc.html\n[REF_ARRAY-WRAP]: https://numpy.org/doc/stable/reference/arrays.classes.html#numpy.class.__array_wrap__\n[REF_ARRAY-INTER]: https://numpy.org/doc/stable/reference/arrays.interface.html#python-side\n[REF_ARRAY-PRIO]: https://numpy.org/doc/stable/reference/arrays.classes.html#numpy.class.__array_priority__\n[REF_DTYPE]: https://numpy.org/doc/stable/reference/arrays.dtypes.html#specifying-and-constructing-data-types\n\n[CODE-NP-TO]: https://github.com/jorenham/optype/blob/master/optype/numpy/_to.py\n\n[NEP13]: https://numpy.org/neps/nep-0013-ufunc-overrides.html\n[NEP18]: https://numpy.org/neps/nep-0018-array-function-protocol.html\n[NEP29]: https://numpy.org/neps/nep-0029-deprecation_policy.html\n\n[SPEC0]: https://scientific-python.org/specs/spec-0000/\n\n[PEP695]: https://peps.python.org/pep-0695/\n[PEP696]: https://peps.python.org/pep-0696/\n[PEP742]: https://peps.python.org/pep-0742/\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":"numpy, type hints, typing","license":null,"license_expression":"BSD-3-Clause","license_files":["LICENSE"],"maintainer":null,"maintainer_email":null,"name":"optype","package_url":"https://pypi.org/project/optype/","platform":null,"project_url":"https://pypi.org/project/optype/","project_urls":{"Changelog":"https://github.com/jorenham/optype/releases","Documentation":"https://github.com/jorenham/optype/blob/master/README.md","Funding":"https://github.com/sponsors/jorenham","Issues":"https://github.com/jorenham/optype/issues","Repository":"https://github.com/jorenham/optype/"},"provides_extra":["numpy"],"release_url":"https://pypi.org/project/optype/0.9.3/","requires_dist":["typing-extensions>=4.10; python_version < \"3.13\"","numpy>=1.23.5; extra == \"numpy\""],"requires_python":">=3.10","summary":"Building blocks for precise & flexible type hints","version":"0.9.3","yanked":false,"yanked_reason":null}

Dependencies of optype (2).
Dependency	Optional
typing-extensions	false
numpy	true

Package search

optype

project_urls

Dependencies

All package metadata

Releases