codekingpro/portable-devtools

1import ast
2import sys
3import types
4import unittest
5import warnings
6from _typeshed import ConvertibleToFloat, GenericPath, StrOrBytesPath, StrPath
7from collections.abc import Callable, Iterable, Sequence
8from contextlib import _GeneratorContextManager
9from pathlib import Path
10from re import Pattern
11from typing import (
12    Any,
13    AnyStr,
14    ClassVar,
15    Final,
16    Generic,
17    Literal as L,
18    NoReturn,
19    ParamSpec,
20    Self,
21    SupportsIndex,
22    TypeAlias,
23    TypeVarTuple,
24    overload,
25    type_check_only,
26)
27from typing_extensions import TypeVar, deprecated
28from unittest.case import SkipTest
29
30import numpy as np
31from numpy._typing import (
32    ArrayLike,
33    DTypeLike,
34    NDArray,
35    _ArrayLikeDT64_co,
36    _ArrayLikeNumber_co,
37    _ArrayLikeObject_co,
38    _ArrayLikeTD64_co,
39)
40
41__all__ = [  # noqa: RUF022
42    "IS_EDITABLE",
43    "IS_MUSL",
44    "IS_PYPY",
45    "IS_PYSTON",
46    "IS_WASM",
47    "IS_INSTALLED",
48    "IS_64BIT",
49    "HAS_LAPACK64",
50    "HAS_REFCOUNT",
51    "BLAS_SUPPORTS_FPE",
52    "NOGIL_BUILD",
53    "NUMPY_ROOT",
54    "assert_",
55    "assert_array_almost_equal_nulp",
56    "assert_raises_regex",
57    "assert_array_max_ulp",
58    "assert_warns",
59    "assert_no_warnings",
60    "assert_allclose",
61    "assert_equal",
62    "assert_almost_equal",
63    "assert_approx_equal",
64    "assert_array_equal",
65    "assert_array_less",
66    "assert_string_equal",
67    "assert_array_almost_equal",
68    "assert_raises",
69    "build_err_msg",
70    "decorate_methods",
71    "jiffies",
72    "memusage",
73    "print_assert_equal",
74    "rundocs",
75    "runstring",
76    "verbose",
77    "measure",
78    "IgnoreException",
79    "clear_and_catch_warnings",
80    "SkipTest",
81    "KnownFailureException",
82    "temppath",
83    "tempdir",
84    "suppress_warnings",
85    "assert_array_compare",
86    "assert_no_gc_cycles",
87    "break_cycles",
88    "check_support_sve",
89    "run_threaded",
90]
91
92###
93
94_T = TypeVar("_T")
95_Ts = TypeVarTuple("_Ts")
96_Tss = ParamSpec("_Tss")
97_ET = TypeVar("_ET", bound=BaseException, default=BaseException)
98_FT = TypeVar("_FT", bound=Callable[..., Any])
99_W_co = TypeVar("_W_co", bound=_WarnLog | None, default=_WarnLog | None, covariant=True)
100
101_StrLike: TypeAlias = str | bytes
102_RegexLike: TypeAlias = _StrLike | Pattern[Any]
103_NumericArrayLike: TypeAlias = _ArrayLikeNumber_co | _ArrayLikeObject_co
104
105_ExceptionSpec: TypeAlias = type[_ET] | tuple[type[_ET], ...]
106_WarningSpec: TypeAlias = type[Warning]
107_WarnLog: TypeAlias = list[warnings.WarningMessage]
108_ToModules: TypeAlias = Iterable[types.ModuleType]
109
110# Must return a bool or an ndarray/generic type that is supported by `np.logical_and.reduce`
111_ComparisonFunc: TypeAlias = Callable[
112    [NDArray[Any], NDArray[Any]],
113    bool | np.bool | np.number | NDArray[np.bool | np.number | np.object_],
114]
115
116# Type-check only `clear_and_catch_warnings` subclasses for both values of the
117# `record` parameter. Copied from the stdlib `warnings` stubs.
118@type_check_only
119class _clear_and_catch_warnings_with_records(clear_and_catch_warnings):
120    def __enter__(self) -> list[warnings.WarningMessage]: ...
121
122@type_check_only
123class _clear_and_catch_warnings_without_records(clear_and_catch_warnings):
124    def __enter__(self) -> None: ...
125
126###
127
128verbose: int = 0
129NUMPY_ROOT: Final[Path] = ...
130IS_INSTALLED: Final[bool] = ...
131IS_EDITABLE: Final[bool] = ...
132IS_MUSL: Final[bool] = ...
133IS_PYPY: Final[bool] = ...
134IS_PYSTON: Final[bool] = ...
135IS_WASM: Final[bool] = ...
136IS_64BIT: Final[bool] = ...
137HAS_REFCOUNT: Final[bool] = ...
138HAS_LAPACK64: Final[bool] = ...
139BLAS_SUPPORTS_FPE: Final[bool] = ...
140NOGIL_BUILD: Final[bool] = ...
141
142class KnownFailureException(Exception): ...
143class IgnoreException(Exception): ...
144
145class clear_and_catch_warnings(warnings.catch_warnings[_W_co], Generic[_W_co]):
146    class_modules: ClassVar[tuple[types.ModuleType, ...]] = ()
147    modules: Final[set[types.ModuleType]]
148    @overload  # record: True
149    def __init__(self: clear_and_catch_warnings[_WarnLog], /, record: L[True], modules: _ToModules = ()) -> None: ...
150    @overload  # record: False (default)
151    def __init__(self: clear_and_catch_warnings[None], /, record: L[False] = False, modules: _ToModules = ()) -> None: ...
152    @overload  # record; bool
153    def __init__(self, /, record: bool, modules: _ToModules = ()) -> None: ...
154
155@deprecated("Please use warnings.filterwarnings or pytest.mark.filterwarnings instead")
156class suppress_warnings:
157    log: Final[_WarnLog]
158    def __init__(self, /, forwarding_rule: L["always", "module", "once", "location"] = "always") -> None: ...
159    def __enter__(self) -> Self: ...
160    def __exit__(self, cls: type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None, /) -> None: ...
161    def __call__(self, /, func: _FT) -> _FT: ...
162
163    #
164    def filter(self, /, category: type[Warning] = ..., message: str = "", module: types.ModuleType | None = None) -> None: ...
165    def record(self, /, category: type[Warning] = ..., message: str = "", module: types.ModuleType | None = None) -> _WarnLog: ...
166
167# Contrary to runtime we can't do `os.name` checks while type checking,
168# only `sys.platform` checks
169if sys.platform == "win32" or sys.platform == "cygwin":
170    def memusage(processName: str = "python", instance: int = 0) -> int: ...
171elif sys.platform == "linux":
172    def memusage(_proc_pid_stat: StrOrBytesPath | None = None) -> int | None: ...
173else:
174    def memusage() -> NoReturn: ...
175
176if sys.platform == "linux":
177    def jiffies(_proc_pid_stat: StrOrBytesPath | None = None, _load_time: list[float] | None = None) -> int: ...
178else:
179    def jiffies(_load_time: list[float] = []) -> int: ...
180
181#
182def build_err_msg(
183    arrays: Iterable[object],
184    err_msg: object,
185    header: str = "Items are not equal:",
186    verbose: bool = True,
187    names: Sequence[str] = ("ACTUAL", "DESIRED"),  # = ('ACTUAL', 'DESIRED')
188    precision: SupportsIndex | None = 8,
189) -> str: ...
190
191#
192def print_assert_equal(test_string: str, actual: object, desired: object) -> None: ...
193
194#
195def assert_(val: object, msg: str | Callable[[], str] = "") -> None: ...
196
197#
198def assert_equal(
199    actual: object,
200    desired: object,
201    err_msg: object = "",
202    verbose: bool = True,
203    *,
204    strict: bool = False,
205) -> None: ...
206
207def assert_almost_equal(
208    actual: _NumericArrayLike,
209    desired: _NumericArrayLike,
210    decimal: int = 7,
211    err_msg: object = "",
212    verbose: bool = True,
213) -> None: ...
214
215#
216def assert_approx_equal(
217    actual: ConvertibleToFloat,
218    desired: ConvertibleToFloat,
219    significant: int = 7,
220    err_msg: object = "",
221    verbose: bool = True,
222) -> None: ...
223
224#
225def assert_array_compare(
226    comparison: _ComparisonFunc,
227    x: ArrayLike,
228    y: ArrayLike,
229    err_msg: object = "",
230    verbose: bool = True,
231    header: str = "",
232    precision: SupportsIndex = 6,
233    equal_nan: bool = True,
234    equal_inf: bool = True,
235    *,
236    strict: bool = False,
237    names: tuple[str, str] = ("ACTUAL", "DESIRED"),
238) -> None: ...
239
240#
241def assert_array_equal(
242    actual: object,
243    desired: object,
244    err_msg: object = "",
245    verbose: bool = True,
246    *,
247    strict: bool = False,
248) -> None: ...
249
250#
251def assert_array_almost_equal(
252    actual: _NumericArrayLike,
253    desired: _NumericArrayLike,
254    decimal: float = 6,
255    err_msg: object = "",
256    verbose: bool = True,
257) -> None: ...
258
259@overload
260def assert_array_less(
261    x: _ArrayLikeDT64_co,
262    y: _ArrayLikeDT64_co,
263    err_msg: object = "",
264    verbose: bool = True,
265    *,
266    strict: bool = False,
267) -> None: ...
268@overload
269def assert_array_less(
270    x: _ArrayLikeTD64_co,
271    y: _ArrayLikeTD64_co,
272    err_msg: object = "",
273    verbose: bool = True,
274    *,
275    strict: bool = False,
276) -> None: ...
277@overload
278def assert_array_less(
279    x: _NumericArrayLike,
280    y: _NumericArrayLike,
281    err_msg: object = "",
282    verbose: bool = True,
283    *,
284    strict: bool = False,
285) -> None: ...
286
287#
288def assert_string_equal(actual: str, desired: str) -> None: ...
289
290#
291@overload
292def assert_raises(
293    exception_class: _ExceptionSpec[_ET],
294    /,
295    *,
296    msg: str | None = None,
297) -> unittest.case._AssertRaisesContext[_ET]: ...
298@overload
299def assert_raises(
300    exception_class: _ExceptionSpec,
301    callable: Callable[_Tss, Any],
302    /,
303    *args: _Tss.args,
304    **kwargs: _Tss.kwargs,
305) -> None: ...
306
307#
308@overload
309def assert_raises_regex(
310    exception_class: _ExceptionSpec[_ET],
311    expected_regexp: _RegexLike,
312    *,
313    msg: str | None = None,
314) -> unittest.case._AssertRaisesContext[_ET]: ...
315@overload
316def assert_raises_regex(
317    exception_class: _ExceptionSpec,
318    expected_regexp: _RegexLike,
319    callable: Callable[_Tss, Any],
320    *args: _Tss.args,
321    **kwargs: _Tss.kwargs,
322) -> None: ...
323
324#
325@overload
326def assert_allclose(
327    actual: _ArrayLikeTD64_co,
328    desired: _ArrayLikeTD64_co,
329    rtol: float = 1e-7,
330    atol: float = 0,
331    equal_nan: bool = True,
332    err_msg: object = "",
333    verbose: bool = True,
334    *,
335    strict: bool = False,
336) -> None: ...
337@overload
338def assert_allclose(
339    actual: _NumericArrayLike,
340    desired: _NumericArrayLike,
341    rtol: float = 1e-7,
342    atol: float = 0,
343    equal_nan: bool = True,
344    err_msg: object = "",
345    verbose: bool = True,
346    *,
347    strict: bool = False,
348) -> None: ...
349
350#
351def assert_array_almost_equal_nulp(
352    x: _ArrayLikeNumber_co,
353    y: _ArrayLikeNumber_co,
354    nulp: float = 1,
355) -> None: ...
356
357#
358def assert_array_max_ulp(
359    a: _ArrayLikeNumber_co,
360    b: _ArrayLikeNumber_co,
361    maxulp: float = 1,
362    dtype: DTypeLike | None = None,
363) -> NDArray[Any]: ...
364
365#
366@overload
367@deprecated("Please use warnings.catch_warnings or pytest.warns instead")
368def assert_warns(warning_class: _WarningSpec) -> _GeneratorContextManager[None]: ...
369@overload
370@deprecated("Please use warnings.catch_warnings or pytest.warns instead")
371def assert_warns(warning_class: _WarningSpec, func: Callable[_Tss, _T], *args: _Tss.args, **kwargs: _Tss.kwargs) -> _T: ...
372
373#
374@overload
375def assert_no_warnings() -> _GeneratorContextManager[None]: ...
376@overload
377def assert_no_warnings(func: Callable[_Tss, _T], /, *args: _Tss.args, **kwargs: _Tss.kwargs) -> _T: ...
378
379#
380@overload
381def assert_no_gc_cycles() -> _GeneratorContextManager[None]: ...
382@overload
383def assert_no_gc_cycles(func: Callable[_Tss, Any], /, *args: _Tss.args, **kwargs: _Tss.kwargs) -> None: ...
384
385###
386
387#
388@overload
389def tempdir(
390    suffix: None = None,
391    prefix: None = None,
392    dir: None = None,
393) -> _GeneratorContextManager[str]: ...
394@overload
395def tempdir(
396    suffix: AnyStr | None = None,
397    prefix: AnyStr | None = None,
398    *,
399    dir: GenericPath[AnyStr],
400) -> _GeneratorContextManager[AnyStr]: ...
401@overload
402def tempdir(
403    suffix: AnyStr | None = None,
404    *,
405    prefix: AnyStr,
406    dir: GenericPath[AnyStr] | None = None,
407) -> _GeneratorContextManager[AnyStr]: ...
408@overload
409def tempdir(
410    suffix: AnyStr,
411    prefix: AnyStr | None = None,
412    dir: GenericPath[AnyStr] | None = None,
413) -> _GeneratorContextManager[AnyStr]: ...
414
415#
416@overload
417def temppath(
418    suffix: None = None,
419    prefix: None = None,
420    dir: None = None,
421    text: bool = False,
422) -> _GeneratorContextManager[str]: ...
423@overload
424def temppath(
425    suffix: AnyStr | None,
426    prefix: AnyStr | None,
427    dir: GenericPath[AnyStr],
428    text: bool = False,
429) -> _GeneratorContextManager[AnyStr]: ...
430@overload
431def temppath(
432    suffix: AnyStr | None = None,
433    prefix: AnyStr | None = None,
434    *,
435    dir: GenericPath[AnyStr],
436    text: bool = False,
437) -> _GeneratorContextManager[AnyStr]: ...
438@overload
439def temppath(
440    suffix: AnyStr | None,
441    prefix: AnyStr,
442    dir: GenericPath[AnyStr] | None = None,
443    text: bool = False,
444) -> _GeneratorContextManager[AnyStr]: ...
445@overload
446def temppath(
447    suffix: AnyStr | None = None,
448    *,
449    prefix: AnyStr,
450    dir: GenericPath[AnyStr] | None = None,
451    text: bool = False,
452) -> _GeneratorContextManager[AnyStr]: ...
453@overload
454def temppath(
455    suffix: AnyStr,
456    prefix: AnyStr | None = None,
457    dir: GenericPath[AnyStr] | None = None,
458    text: bool = False,
459) -> _GeneratorContextManager[AnyStr]: ...
460
461#
462def check_support_sve(__cache: list[bool] = ..., /) -> bool: ...  # stubdefaulter: ignore[missing-default]
463
464#
465def decorate_methods(
466    cls: type,
467    decorator: Callable[[Callable[..., Any]], Any],
468    testmatch: _RegexLike | None = None,
469) -> None: ...
470
471#
472@overload
473def run_threaded(
474    func: Callable[[], None],
475    max_workers: int = 8,
476    pass_count: bool = False,
477    pass_barrier: bool = False,
478    outer_iterations: int = 1,
479    prepare_args: None = None,
480) -> None: ...
481@overload
482def run_threaded(
483    func: Callable[[*_Ts], None],
484    max_workers: int,
485    pass_count: bool,
486    pass_barrier: bool,
487    outer_iterations: int,
488    prepare_args: tuple[*_Ts],
489) -> None: ...
490@overload
491def run_threaded(
492    func: Callable[[*_Ts], None],
493    max_workers: int = 8,
494    pass_count: bool = False,
495    pass_barrier: bool = False,
496    outer_iterations: int = 1,
497    *,
498    prepare_args: tuple[*_Ts],
499) -> None: ...
500
501#
502def runstring(astr: _StrLike | types.CodeType, dict: dict[str, Any] | None) -> Any: ...  # noqa: ANN401
503def rundocs(filename: StrPath | None = None, raise_on_error: bool = True) -> None: ...
504def measure(code_str: _StrLike | ast.AST, times: int = 1, label: str | None = None) -> float: ...
505def break_cycles() -> None: ...
506