🏷️ SPEC-7 compliant scipy._typing.ToRNG type alias (previously `See…

…d`) (#333)

scipy-stubs/_typing.pyi

@@ -1,4 +1,4 @@
-# NOTE(scipy-stubs): This ia a module only exists `if typing.TYPE_CHECKING: ...`
+# NOTE: This private(!) module only exists in `if typing.TYPE_CHECKING: ...` and in `.pyi` stubs
 
 from os import PathLike
 from collections.abc import Callable, Sequence
@@ -27,7 +27,7 @@ __all__ = [
     "NanPolicy",
     "OrderCF",
     "OrderKACF",
-    "Seed",
+    "ToRNG",
     "Untyped",
     "UntypedArray",
     "UntypedCallable",
@@ -48,6 +48,21 @@ class EnterNoneMixin:
     def __enter__(self, /) -> None: ...
     def __exit__(self, /, type: type[BaseException] | None, value: BaseException | None, tb: TracebackType | None) -> None: ...
 
+# used in `scipy.linalg.blas` and `scipy.linalg.lapack`
+@type_check_only
+class _FortranFunction(Protocol):
+    @property
+    def dtype(self, /) -> np.dtype[np.number[Any]]: ...
+    @property
+    def int_dtype(self, /) -> np.dtype[np.integer[Any]]: ...
+    @property
+    def module_name(self, /) -> LiteralString: ...
+    @property
+    def prefix(self, /) -> LiteralString: ...
+    @property
+    def typecode(self, /) -> LiteralString: ...
+    def __call__(self, /, *args: object, **kwargs: object) -> object: ...
+
 # placeholders for missing annotations
 Untyped: TypeAlias = Any
 UntypedTuple: TypeAlias = tuple[Untyped, ...]
@@ -69,32 +84,27 @@ AnyBool: TypeAlias = bool | np.bool_ | Literal[0, 1]
 # equivalent to `numpy._typing._shape._ShapeLike`
 AnyShape: TypeAlias = op.CanIndex | Sequence[op.CanIndex]
 
-# numpy types
-RNG: TypeAlias = np.random.BitGenerator | np.random.Generator | np.random.RandomState
-Seed: TypeAlias = RNG | np.random.SeedSequence | onp.ToJustInt | onp.ToJustIntND
+RNG: TypeAlias = np.random.Generator | np.random.RandomState
+# NOTE: This is less incorrect and more accurate than the current `np.random.default_rng` `seed` param annotation.
+ToRNG: TypeAlias = (
+    np.integer[Any]
+    | np.timedelta64
+    | onp.ArrayND[np.integer[Any] | np.timedelta64 | np.flexible | np.object_]
+    | np.random.SeedSequence
+    | np.random.BitGenerator
+    | RNG
+    | None
+)
+
+# numpy literals
 ByteOrder: TypeAlias = Literal["S", "<", "little", ">", "big", "=", "native", "|", "I"]
 OrderCF: TypeAlias = Literal["C", "F"]
-OrderKACF: TypeAlias = Literal["K", "A", "C", "F"]
+OrderKACF: TypeAlias = Literal["K", "A", OrderCF]
 Casting: TypeAlias = Literal["no", "equiv", "safe", "same_kind", "unsafe"]
 CorrelateMode: TypeAlias = Literal["valid", "same", "full"]
 
 # scipy literals
 NanPolicy: TypeAlias = Literal["raise", "propagate", "omit"]
 Alternative: TypeAlias = Literal["two-sided", "less", "greater"]
-DCTType: TypeAlias = Literal[1, 2, 3, 4]
 NormalizationMode: TypeAlias = Literal["backward", "ortho", "forward"]
-
-# used in `scipy.linalg.blas` and `scipy.linalg.lapack`
-@type_check_only
-class _FortranFunction(Protocol):
-    @property
-    def dtype(self, /) -> np.dtype[np.number[Any]]: ...
-    @property
-    def int_dtype(self, /) -> np.dtype[np.integer[Any]]: ...
-    @property
-    def module_name(self, /) -> LiteralString: ...
-    @property
-    def prefix(self, /) -> LiteralString: ...
-    @property
-    def typecode(self, /) -> LiteralString: ...
-    def __call__(self, /, *args: object, **kwargs: object) -> object: ...
+DCTType: TypeAlias = Literal[1, 2, 3, 4]

scipy-stubs/cluster/vq.pyi

@@ -3,7 +3,7 @@ from typing_extensions import TypeVar
 
 import numpy as np
 import optype.numpy as onp
-from scipy._typing import Seed
+from scipy._typing import ToRNG as Seed  # TODO(jorenham)
 
 __all__ = ["kmeans", "kmeans2", "vq", "whiten"]
 

scipy-stubs/interpolate/_polyint.pyi

@@ -3,7 +3,7 @@ from typing import ClassVar, TypeAlias, overload
 
 import numpy as np
 import optype.numpy as onp
-from scipy._typing import Seed
+from scipy._typing import ToRNG
 
 __all__ = [
     "BarycentricInterpolator",
@@ -62,7 +62,7 @@ class BarycentricInterpolator(_Interpolator1DWithDerivatives):
         axis: int = 0,
         *,
         wi: onp.ToFloatND | None = None,
-        random_state: Seed | None = None,
+        random_state: ToRNG = None,
     ) -> None: ...
     def set_yi(self, /, yi: onp.ToComplexND, axis: int | None = None) -> None: ...
     def add_xi(self, /, xi: onp.ToFloat1D, yi: onp.ToComplexND | None = None) -> None: ...

scipy-stubs/linalg/_sketches.pyi

@@ -15,24 +15,24 @@ _ToJust2D: TypeAlias = onp.CanArrayND[_ST] | Sequence[onp.CanArrayND[_ST]] | Seq
 
 ###
 
-def cwt_matrix(n_rows: onp.ToInt, n_columns: onp.ToInt, seed: spt.Seed | None = None) -> csc_matrix: ...
+def cwt_matrix(n_rows: onp.ToInt, n_columns: onp.ToInt, seed: spt.ToRNG = None) -> csc_matrix: ...
 
 #
 @overload
 def clarkson_woodruff_transform(
     input_matrix: onp.ToInt2D,
     sketch_size: onp.ToInt,
-    seed: spt.Seed | None = None,
+    seed: spt.ToRNG = None,
 ) -> onp.Array2D[np.int_]: ...
 @overload
 def clarkson_woodruff_transform(
     input_matrix: _ToJust2D[np.floating[Any], float],
     sketch_size: onp.ToInt,
-    seed: spt.Seed | None = None,
+    seed: spt.ToRNG = None,
 ) -> onp.Array2D[np.float64 | np.longdouble]: ...
 @overload
 def clarkson_woodruff_transform(
     input_matrix: _ToJust2D[np.complexfloating[Any, Any], complex],
     sketch_size: onp.ToInt,
-    seed: spt.Seed | None = None,
+    seed: spt.ToRNG = None,
 ) -> onp.Array2D[np.complex64 | np.clongdouble]: ...

scipy-stubs/optimize/_basinhopping.pyi

@@ -3,7 +3,7 @@ from typing import Concatenate, Literal, Protocol, TypeAlias, TypeVar, type_chec
 
 import numpy as np
 import optype.numpy as onp
-from scipy._typing import Seed
+from scipy._typing import ToRNG
 from ._minimize import OptimizeResult as _MinimizeResult
 from ._optimize import OptimizeResult as _OptimizeResult
 from ._typing import MinimizerKwargs
@@ -61,7 +61,7 @@ def basinhopping(
     interval: onp.ToJustInt = 50,
     disp: onp.ToBool = False,
     niter_success: onp.ToJustInt | None = None,
-    seed: Seed | None = None,
+    seed: ToRNG = None,
     *,
     target_accept_rate: onp.ToFloat = 0.5,
     stepwise_factor: onp.ToFloat = 0.9,

scipy-stubs/optimize/_differentialevolution.pyi

@@ -3,7 +3,7 @@ from typing import Concatenate, Literal, TypeAlias, TypeVar
 
 import numpy as np
 import optype.numpy as onp
-from scipy._typing import Seed
+from scipy._typing import ToRNG
 from scipy.optimize import OptimizeResult as _OptimizeResult
 from ._constraints import Bounds, LinearConstraint, NonlinearConstraint
 
@@ -54,7 +54,7 @@ def differential_evolution(
     tol: onp.ToFloat = 0.01,
     mutation: onp.ToFloat | tuple[onp.ToFloat, onp.ToFloat] = (0.5, 1),
     recombination: onp.ToFloat = 0.7,
-    seed: Seed | None = None,
+    seed: ToRNG = None,
     callback: Callable[[OptimizeResult], None] | Callable[[_Float1D, onp.ToFloat], None] | None = None,
     disp: onp.ToBool = False,
     polish: onp.ToBool = True,

scipy-stubs/optimize/_dual_annealing.pyi

@@ -3,7 +3,7 @@ from typing import Concatenate, Literal, TypeAlias
 
 import numpy as np
 import optype.numpy as onp
-from scipy._typing import Seed
+from scipy._typing import ToRNG
 from scipy.optimize import OptimizeResult as _OptimizeResult
 from ._constraints import Bounds
 from ._typing import MinimizerKwargs
@@ -36,7 +36,7 @@ def dual_annealing(
     visit: onp.ToFloat = 2.62,
     accept: onp.ToFloat = -5.0,
     maxfun: onp.ToFloat = 10_000_000.0,
-    seed: Seed | None = None,
+    seed: ToRNG = None,
     no_local_search: onp.ToBool = False,
     callback: Callable[[_Float1D, float, Literal[0, 1, 2]], bool | None] | None = None,
     x0: onp.ToFloat1D | None = None,

scipy-stubs/optimize/_optimize.pyi

@@ -5,7 +5,7 @@ from typing_extensions import TypeVar
 import numpy as np
 import optype.numpy as onp
 from scipy._lib._util import _RichResult
-from scipy._typing import AnyBool, Seed
+from scipy._typing import AnyBool, ToRNG
 from ._linesearch import line_search_wolfe2 as line_search
 from ._typing import Brack, MethodAll, Solver
 
@@ -662,5 +662,5 @@ def check_grad(
     *args: object,
     epsilon: onp.ToFloat = ...,
     direction: Literal["all", "random"] = "all",
-    seed: Seed | None = None,
+    seed: ToRNG = None,
 ) -> _Float: ...

scipy-stubs/sparse/_construct.pyi

@@ -5,7 +5,7 @@ import numpy as np
 import numpy.typing as npt
 import optype.numpy as onp
 import optype.typing as opt
-from scipy._typing import Seed
+from scipy._typing import ToRNG
 from ._base import _spbase, sparray
 from ._bsr import bsr_array, bsr_matrix
 from ._coo import coo_array, coo_matrix
@@ -897,7 +897,7 @@ def random_array(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: ToDTypeFloat | None = None,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_sampler: _DataSampler | None = None,
 ) -> _SpArray1D[np.float64]: ...
 @overload  # shape: 1d, dtype: <known>
@@ -907,7 +907,7 @@ def random_array(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: ToDType[_SCT],
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_sampler: _DataSampler | None = None,
 ) -> _SpArray1D[_SCT]: ...
 @overload  # shape: 1d, dtype: complex
@@ -917,7 +917,7 @@ def random_array(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: ToDTypeComplex,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_sampler: _DataSampler | None = None,
 ) -> _SpArray1D[np.complex128]: ...
 @overload  # shape: 1d, dtype: <unknown>
@@ -927,7 +927,7 @@ def random_array(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: npt.DTypeLike,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_sampler: _DataSampler | None = None,
 ) -> _SpArray1D: ...
 @overload  # shape: 2d, dtype: <default>
@@ -937,7 +937,7 @@ def random_array(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: ToDTypeFloat | None = None,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_sampler: _DataSampler | None = None,
 ) -> _SpArray2D[np.float64]: ...
 @overload  # shape: 2d, dtype: <known>
@@ -947,7 +947,7 @@ def random_array(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: ToDType[_SCT],
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_sampler: _DataSampler | None = None,
 ) -> _SpArray2D[_SCT]: ...
 @overload  # shape: 2d, dtype: complex
@@ -957,7 +957,7 @@ def random_array(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: ToDTypeComplex,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_sampler: _DataSampler | None = None,
 ) -> _SpArray2D[np.complex128]: ...
 @overload  # shape: 2d, dtype: <unknown>
@@ -967,7 +967,7 @@ def random_array(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: npt.DTypeLike,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_sampler: _DataSampler | None = None,
 ) -> _SpArray2D: ...
 
@@ -979,7 +979,7 @@ def random(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: ToDTypeFloat | None = None,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_rvs: _DataRVS | None = None,
 ) -> _SpMatrix[np.float64]: ...
 @overload  # dtype: <known> (positional)
@@ -989,7 +989,7 @@ def random(
     density: float | Float,
     format: SPFormat,
     dtype: ToDType[_SCT],
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_rvs: _DataRVS | None = None,
 ) -> _SpMatrix[_SCT]: ...
 @overload  # dtype: <known> (keyword)
@@ -1000,7 +1000,7 @@ def random(
     format: SPFormat = "coo",
     *,
     dtype: ToDType[_SCT],
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_rvs: _DataRVS | None = None,
 ) -> _SpMatrix[_SCT]: ...
 @overload  # dtype: complex (positional)
@@ -1010,7 +1010,7 @@ def random(
     density: float | Float,
     format: SPFormat,
     dtype: ToDTypeComplex,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_rvs: _DataRVS | None = None,
 ) -> _SpMatrix[np.complex128]: ...
 @overload  # dtype: complex (keyword)
@@ -1021,7 +1021,7 @@ def random(
     format: SPFormat = "coo",
     *,
     dtype: ToDTypeComplex,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_rvs: _DataRVS | None = None,
 ) -> _SpMatrix[np.complex128]: ...
 @overload  # dtype: <unknown>
@@ -1031,7 +1031,7 @@ def random(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: npt.DTypeLike | None = None,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
     data_rvs: _DataRVS | None = None,
 ) -> _SpMatrix: ...
 
@@ -1043,7 +1043,7 @@ def rand(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: ToDTypeFloat | None = None,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
 ) -> _SpMatrix[np.float64]: ...
 @overload  # dtype: <known> (positional)
 def rand(
@@ -1052,7 +1052,7 @@ def rand(
     density: float | Float,
     format: SPFormat,
     dtype: ToDType[_SCT],
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
 ) -> _SpMatrix[_SCT]: ...
 @overload  # dtype: <known> (keyword)
 def rand(
@@ -1062,7 +1062,7 @@ def rand(
     format: SPFormat = "coo",
     *,
     dtype: ToDType[_SCT],
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
 ) -> _SpMatrix[_SCT]: ...
 @overload  # dtype: complex (positional)
 def rand(
@@ -1071,7 +1071,7 @@ def rand(
     density: float | Float,
     format: SPFormat,
     dtype: ToDTypeComplex,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
 ) -> _SpMatrix[np.complex128]: ...
 @overload  # dtype: complex (keyword)
 def rand(
@@ -1081,7 +1081,7 @@ def rand(
     format: SPFormat = "coo",
     *,
     dtype: ToDTypeComplex,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
 ) -> _SpMatrix[np.complex128]: ...
 @overload  # dtype: <unknown>
 def rand(
@@ -1090,5 +1090,5 @@ def rand(
     density: float | Float = 0.01,
     format: SPFormat = "coo",
     dtype: npt.DTypeLike | None = None,
-    random_state: Seed | None = None,
+    random_state: ToRNG = None,
 ) -> _SpMatrix: ...