-il2%SrSSKJr SSKrSSKrSSKrSSKJrJrJ r SSK J r SSK J r SSKJrJrJrJrJr SS KJrJr SS KJrJrJr S S /r\(aSSKrSS KJrJrJ r SSK!J"r" O\#r Sr"\"S5r$\"S5r%0r&S\'S'"SS\RP5r)\)RTr*SS\*\*S.SSjjr+SSjr,"SS\ 5r-S Sjr.g)!z] Public testing utilities. See also _lib._testing for additional private testing utilities. ) annotationsN)CallableIteratorSequence)wraps) ModuleType) TYPE_CHECKINGAny ParamSpecTypeVarcast)is_dask_namespaceis_jax_namespace) jax_autojitpickle_flattenpickle_unflattenlazy_xp_functionpatch_lazy_xp_functions)GraphKeySchedulerGetCallable)overridecU$N)funcs U/var/www/html/venv/lib/python3.13/site-packages/scipy/_lib/array_api_extra/testing.pyrr s PTzdict[object, dict[str, Any]] _ufuncs_tagsc\rSrSrSrSrSrg) Deprecated*z&Unique type for deprecated parameters.rrN)__name__ __module__ __qualname____firstlineno____doc__ DEPRECATED__static_attributes__rrrr$r$*s 0Jrr$FT)allow_dask_computejax_jitstatic_argnumsstatic_argnamescU[Ld U[La[R"S[SS9 UUS.nXPlg![ a U[ U'gf=f)a Tag a function to be tested on lazy backends. Tag a function so that when any tests are executed with ``xp=jax.numpy`` the function is replaced with a jitted version of itself, and when it is executed with ``xp=dask.array`` the function will raise if it attempts to materialize the graph. This will be later expanded to provide test coverage for other lazy backends. In order for the tag to be effective, the test or a fixture must call :func:`patch_lazy_xp_functions`. Parameters ---------- func : callable Function to be tested. allow_dask_compute : bool | int, optional Whether `func` is allowed to internally materialize the Dask graph, or maximum number of times it is allowed to do so. This is typically triggered by ``bool()``, ``float()``, or ``np.asarray()``. Set to 1 if you are aware that `func` converts the input parameters to NumPy and want to let it do so at least for the time being, knowing that it is going to be extremely detrimental for performance. If a test needs values higher than 1 to pass, it is a canary that the conversion to NumPy/bool/float is happening multiple times, which translates to multiple computations of the whole graph. Short of making the function fully lazy, you should at least add explicit calls to ``np.asarray()`` early in the function. *Note:* the counter of `allow_dask_compute` resets after each call to `func`, so a test function that invokes `func` multiple times should still work with this parameter set to 1. Set to True to allow `func` to materialize the graph an unlimited number of times. Default: False, meaning that `func` must be fully lazy and never materialize the graph. jax_jit : bool, optional Set to True to replace `func` with a smart variant of ``jax.jit(func)`` after calling the :func:`patch_lazy_xp_functions` test helper with ``xp=jax.numpy``. Set to False if `func` is only compatible with eager (non-jitted) JAX. Unlike with vanilla ``jax.jit``, all arguments and return types that are not JAX arrays are treated as static; the function can accept and return arbitrary wrappers around JAX arrays. This difference is because, in real life, most users won't wrap the function directly with ``jax.jit`` but rather they will use it within their own code, which is itself then wrapped by ``jax.jit``, and internally consume the function's outputs. In other words, the pattern that is being tested is:: >>> @jax.jit ... def user_func(x): ... y = user_prepares_inputs(x) ... z = func(y, some_static_arg=True) ... return user_consumes(z) Default: True. static_argnums : Deprecated; ignored static_argnames : Deprecated; ignored See Also -------- patch_lazy_xp_functions : Companion function to call from the test or fixture. jax.jit : JAX function to compile a function for performance. Examples -------- In ``test_mymodule.py``:: from array_api_extra.testing import lazy_xp_function from mymodule import myfunc lazy_xp_function(myfunc) def test_myfunc(xp): a = xp.asarray([1, 2]) # When xp=jax.numpy, this is similar to `b = jax.jit(myfunc)(a)` # When xp=dask.array, crash on compute() or persist() b = myfunc(a) Notes ----- In order for this tag to be effective, the test function must be imported into the test module globals without its namespace; alternatively its namespace must be declared in a ``lazy_xp_modules`` list in the test module globals. Example 1:: from mymodule import myfunc lazy_xp_function(myfunc) def test_myfunc(xp): x = myfunc(xp.asarray([1, 2])) Example 2:: import mymodule lazy_xp_modules = [mymodule] lazy_xp_function(mymodule.myfunc) def test_myfunc(xp): x = mymodule.myfunc(xp.asarray([1, 2])) A test function can circumvent this monkey-patching system by using a namespace outside of the two above patterns. You need to sanitize your code to make sure this only happens intentionally. Example 1:: import mymodule from mymodule import myfunc lazy_xp_function(myfunc) def test_myfunc(xp): a = xp.asarray([1, 2]) b = myfunc(a) # This is wrapped when xp=jax.numpy or xp=dask.array c = mymodule.myfunc(a) # This is not Example 2:: import mymodule class naked: myfunc = mymodule.myfunc lazy_xp_modules = [mymodule] lazy_xp_function(mymodule.myfunc) def test_myfunc(xp): a = xp.asarray([1, 2]) b = mymodule.myfunc(a) # This is wrapped when xp=jax.numpy or xp=dask.array c = naked.myfunc(a) # This is not z{The `static_argnums` and `static_argnames` parameters are deprecated and ignored. They will be removed in a future version.) stacklevel)r-r.N)r+warningswarnDeprecationWarning_lazy_xp_functionAttributeErrorr")rr-r.r/r0tagss rrr3sadZ'?*+L I   1 D "!% "! T"s:AAc ^ [[UR5nU/[[[[ US/55Qm S U 4Sjjn[ U5(aCU"5H7up5pgUSnUSLaSnOUSLaSn[ Xh5n URX5U 5 M9 g [U5(a;U"5H/up5pgUS(dM[U5n URX5U 5 M1 g g ) a` Test lazy execution of functions tagged with :func:`lazy_xp_function`. If ``xp==jax.numpy``, search for all functions which have been tagged with :func:`lazy_xp_function` in the globals of the module that defines the current test, as well as in the ``lazy_xp_modules`` list in the globals of the same module, and wrap them with :func:`jax.jit`. Unwrap them at the end of the test. If ``xp==dask.array``, wrap the functions with a decorator that disables ``compute()`` and ``persist()`` and ensures that exceptions and warnings are raised eagerly. This function should be typically called by your library's `xp` fixture that runs tests on multiple backends:: @pytest.fixture(params=[numpy, array_api_strict, jax.numpy, dask.array]) def xp(request, monkeypatch): patch_lazy_xp_functions(request, monkeypatch, xp=request.param) return request.param but it can be otherwise be called by the test itself too. Parameters ---------- request : pytest.FixtureRequest Pytest fixture, as acquired by the test itself or by one of its fixtures. monkeypatch : pytest.MonkeyPatch Pytest fixture, as acquired by the test itself or by one of its fixtures. xp : array_namespace Array namespace to be tested. See Also -------- lazy_xp_function : Tag a function to be tested on lazy backends. pytest.FixtureRequest : `request` test function parameter. lazy_xp_modulesc3># THnURR5HuupSn[R"[5 UR nSSS5 Uc1[R"[ [5 [UnSSS5 UcMoXX#4v Mw M g!,(df  NV=f!,(df  N3=f7fr) __dict__items contextlibsuppressr8r7KeyError TypeErrorr")modnamerr9modss r iter_tagged,patch_lazy_xp_functions..iter_taggedsC!ll002 .2((811D9<#,,XyA+D1B#T//398BAs<AC B!*C; B2 CC! B/ +C2 C <Cr-Ti@BFrr.N)returnzDIterator[tuple[ModuleType, str, Callable[..., Any], dict[str, Any]]]) r rmodulelistgetattrr _dask_wrapsetattrrr) request monkeypatchxprCrFrDrr9nwrappedrEs @rrrsN z7>> *C  N$tJ'6G)LM ND 0L 0%0] !Ct)*ADye )G   7 3&3 "  %0] !CtI%d+##Cw7&3 rcV\rSrSr%SrS\S'S\S'S\S'S Sjr\S S j5rS r g )CountingDaskScheduleri"af Dask scheduler that counts how many times `dask.compute` is called. If the number of times exceeds 'max_count', it raises an error. This is a wrapper around Dask's own 'synchronous' scheduler. Parameters ---------- max_count : int Maximum number of allowed calls to `dask.compute`. msg : str Assertion to raise when the count exceeds `max_count`. intcount max_countstrmsgc*SUlXlX lg)NrrVrWrY)selfrWrYs r__init__CountingDaskScheduler.__init__5s "rc SSKnU=RS- slURUR::dUR5eUR"X40UD6$)Nrr)daskrVrWrYget)r\dskkeyskwargsr`s r__call__CountingDaskScheduler.__call__:sG a zzT^^+5TXX5+xx,V,,rr[N)rWrUrYrX)rbrrczSequence[Key] | Keyrdr rHr ) r&r'r(r)r*__annotations__r]rrer,rrrrTrT"s1  JN H --rrTc ^^^^^SSKmSSKJm [TS[ T55nT(aST3OSnSTS-SUS US TS-S 3 m[ T5S UUUUU4S jj5nU$)z Wrap `func` to raise if it attempts to call `dask.compute` more than `n` times. After the function returns, materialize the graph in order to re-raise exceptions. rNr&z only up to noz,Called `dask.compute()` or `dask.persist()` rz times, but z* calls are allowed. Set `lazy_xp_function(z, allow_dask_compute=zA)` to allow for more (but note that this will harm performance). c>[T T 5nTRRSU05 T"U0UD6nSSS5 [WTR5upETR USS9Sn[ XE5$!,(df  ND=f)N schedulerthreads)rkr)rTconfigsetrArraypersistr) argsrdrkoutarraysrestdar`rrYrQs rwrapper_dask_wrap..wrapperZsw)!S1 [[__k95 6''C7 &c2884 f :1=--7 6s A22 B)rqzP.argsrdzP.kwargsrHr!)r` dask.arrayarrayrKrXr)rrQ func_namen_strrvrur`rYs`` @@@rrLrLFsj#d)4I!"k! E 6q1ug>g&K'rsA # 88??DOO 8 9<<*"cN CL-/ */  " " &+!+", c" c"#c" c"  c"  c" c"LF8 "F81CF8LVF8 F8R!-0!-H! ! !!r