atoti.experimental()

atoti.experimental(feature_keys, /)

Create a context allowing to use the experimental features with the passed keys.

Warning

Experimental features are subject to breaking changes in any release.

Parameters:

feature_keys (Set[str] | Callable[[set[str]], Set[str]]) –

The keys of the experimental features allowed to be used inside the context.

If a Callable is passed, it will be called with the keys of all the experimental features and it must return the keys to allow.

Return type:

Generator[None, None, None]

Example

By default, calling an experimental function/method raises an error:

>>> foo()
Traceback (most recent call last):
    ...
RuntimeError: This API is experimental, use `with tt.experimental({'foo'}): ...` to allow it.

>>> bar = Bar()
>>> bar.prop
Traceback (most recent call last):
    ...
RuntimeError: This API is experimental, use `with tt.experimental({'Bar.prop'}): ...` to allow it.

An experimental feature can be used by passing its key to this function:

>>> with tt.experimental({"foo"}):
...     foo()

Multiple keys can be passed:

>>> with tt.experimental({"foo", "Bar.prop"}):
...     foo()
...     bar.prop

Nesting is supported too:

>>> with tt.experimental({"foo"}):
...     foo()
...     with tt.experimental({"Bar.prop"}):
...         foo()
...         bar.prop
...     foo()

Once a feature is stabilized, passing its key to this function will raise a deprecation warning:

>>> with tt.experimental({"baz"}):
...     None
Traceback (most recent call last):
    ...
FutureWarning: Experimental feature with key `baz` has been stabilized, stop passing its key.

Passing a key that does not match any feature will raise an error:

>>> with tt.experimental({"quux"}):  
...     None
Traceback (most recent call last):
    ...
ValueError: No experimental feature with key `quux`, existing keys are ...