Safe-global Registration for Model Loading

Process-wide and context-scoped safe-global registration for model loading.

darts.utils.serialization.registry.add_safe_globals(safe_globals)

Register globals as safe for loading.

For example, functions added to this list can be called during unpickling, classes could be instantiated and have state set.

Each item in the list can either be a function/class or a tuple of the form (function/class, string) where string is the full path of the function/class.

Within the serialized format, each function is identified with its full path as {__module__}.{__qualname__}. When calling this API, you can provide this full path that should match the one in the checkpoint otherwise the default {fn.__module__}.{fn.__qualname__} will be used.

Parameters:

safe_globals (list[Callable[..., object] | tuple[Callable[..., object], str]]) – List of globals to mark as safe. The elements must either be callables, or a tuple of (callable, full path).

Return type:

None

Examples

>>> import pandas as pd
>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import LinearRegressionModel
>>> from darts.utils.serialization import add_safe_globals
>>>
>>> def my_encoder(idx: pd.DatetimeIndex):
>>>     # custom encoder example adding the series month value
>>>     return idx.month
>>>
>>> # add encoder as a future covariate, fit and save the model
>>> model = LinearRegressionModel(
>>>     lags=12,
>>>     lags_future_covariates=[0],
>>>     add_encoders={"custom": {"future": [my_encoder]}}
>>> )
>>> series = AirPassengersDataset().load()
>>> model.fit(series)
>>> model.save("model.pkl")
>>>
>>> # calling `load()` directly will fail since `my_encoder` is not an allow-listed global;
>>> # you can globally add it to the safe globals and loading will succeed
>>> add_safe_globals([my_encoder])
>>> model = LinearRegressionModel.load("model.pkl")

darts.utils.serialization.registry.clear_safe_globals()

Clear all user-added safe globals.

Clears both the process-wide globals added with add_safe_globals() and any globals currently added by an enclosing safe_globals() block. Inside such a block the context manager restores the globals it added when the block exits, so clearing does not reach past it.

Return type:

None

Examples

>>> from darts.utils.serialization import add_safe_globals, clear_safe_globals, get_safe_globals
>>>
>>> class MyClass:
>>>     pass
>>>
>>> add_safe_globals([MyClass])
>>> clear_safe_globals()
>>> get_safe_globals()
[]

darts.utils.serialization.registry.get_safe_globals()

Returns a list of the current user-added safe globals.

Return type:

list[Callable[..., object] | tuple[Callable[..., object], str]]

Examples

>>> from darts.utils.serialization import add_safe_globals, get_safe_globals
>>>
>>> class MyClass:
>>>     pass
>>>
>>> add_safe_globals([MyClass])
>>> get_safe_globals()
[<class '__main__.MyClass'>]

darts.utils.serialization.registry.safe_globals(safe_globals)

Temporarily add safe globals for loads within the with block.

Parameters:

safe_globals (list[Callable[..., object] | tuple[Callable[..., object], str]]) – List of globals to mark as safe. The elements must either be callables, or a tuples of (callable, full path).

Return type:

Generator[None, None, None]

Examples

>>> import pandas as pd
>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import LinearRegressionModel
>>> from darts.utils.serialization import safe_globals
>>>
>>> def my_encoder(idx: pd.DatetimeIndex):
>>>     # custom encoder example adding the series month value
>>>     return idx.month
>>>
>>> # add encoder as a future covariate, fit and save the model
>>> model = LinearRegressionModel(
>>>     lags=12,
>>>     lags_future_covariates=[0],
>>>     add_encoders={"custom": {"future": [my_encoder]}}
>>> )
>>> series = AirPassengersDataset().load()
>>> model.fit(series)
>>> model.save("model.pkl")
>>>
>>> # calling `load()` directly will fail since `my_encoder` is not an allow-listed global;
>>> # you can temporarily add it to the safe globals and loading will succeed
>>> with safe_globals([my_encoder]):
>>>     model = LinearRegressionModel.load("model.pkl")