1"""A module with the precisions of generic `~numpy.number` types."""
2from .._utils import set_module
3from typing import final
4
5
6@final # Disallow the creation of arbitrary `NBitBase` subclasses
7@set_module("numpy.typing")
8class NBitBase:
9 """
10 A type representing `numpy.number` precision during static type checking.
11
12 Used exclusively for the purpose static type checking, `NBitBase`
13 represents the base of a hierarchical set of subclasses.
14 Each subsequent subclass is herein used for representing a lower level
15 of precision, *e.g.* ``64Bit > 32Bit > 16Bit``.
16
17 .. versionadded:: 1.20
18
19 Examples
20 --------
21 Below is a typical usage example: `NBitBase` is herein used for annotating
22 a function that takes a float and integer of arbitrary precision
23 as arguments and returns a new float of whichever precision is largest
24 (*e.g.* ``np.float16 + np.int64 -> np.float64``).
25
26 .. code-block:: python
27
28 >>> from __future__ import annotations
29 >>> from typing import TypeVar, TYPE_CHECKING
30 >>> import numpy as np
31 >>> import numpy.typing as npt
32
33 >>> S = TypeVar("S", bound=npt.NBitBase)
34 >>> T = TypeVar("T", bound=npt.NBitBase)
35
36 >>> def add(a: np.floating[S], b: np.integer[T]) -> np.floating[S | T]:
37 ... return a + b
38
39 >>> a = np.float16()
40 >>> b = np.int64()
41 >>> out = add(a, b)
42
43 >>> if TYPE_CHECKING:
44 ... reveal_locals()
45 ... # note: Revealed local types are:
46 ... # note: a: numpy.floating[numpy.typing._16Bit*]
47 ... # note: b: numpy.signedinteger[numpy.typing._64Bit*]
48 ... # note: out: numpy.floating[numpy.typing._64Bit*]
49
50 """
51
52 def __init_subclass__(cls) -> None:
53 allowed_names = {
54 "NBitBase", "_256Bit", "_128Bit", "_96Bit", "_80Bit",
55 "_64Bit", "_32Bit", "_16Bit", "_8Bit",
56 }
57 if cls.__name__ not in allowed_names:
58 raise TypeError('cannot inherit from final class "NBitBase"')
59 super().__init_subclass__()
60
61@final
62@set_module("numpy._typing")
63# Silence errors about subclassing a `@final`-decorated class
64class _256Bit(NBitBase): # type: ignore[misc]
65 pass
66
67@final
68@set_module("numpy._typing")
69class _128Bit(_256Bit): # type: ignore[misc]
70 pass
71
72@final
73@set_module("numpy._typing")
74class _96Bit(_128Bit): # type: ignore[misc]
75 pass
76
77@final
78@set_module("numpy._typing")
79class _80Bit(_96Bit): # type: ignore[misc]
80 pass
81
82@final
83@set_module("numpy._typing")
84class _64Bit(_80Bit): # type: ignore[misc]
85 pass
86
87@final
88@set_module("numpy._typing")
89class _32Bit(_64Bit): # type: ignore[misc]
90 pass
91
92@final
93@set_module("numpy._typing")
94class _16Bit(_32Bit): # type: ignore[misc]
95 pass
96
97@final
98@set_module("numpy._typing")
99class _8Bit(_16Bit): # type: ignore[misc]
100 pass