Grappler Bases

grappler.grapplers.bases

This module contains base classes for Grapplers.

BasicGrappler provides a very barebones base to build a grappler onto. It helps to properly implement the Grappler.find context managed interface.

PluginPairGrapplerBase

Bases: BasicGrappler[Dict[Plugin, T_Cache]], ABC, Generic[T_Cache]

A grappler base that allows to pair arbitrary data with each iterated plugin, allowing for easier loading later.

See grappler.grapplers.CompositeGrappler for example usage.

To implement this, you must implement the iter_plugins and load_with_pair methods.

iter_plugins(topic: Optional[str], exit_stack: ExitStack) -> Iterable[Tuple[Plugin, T_Cache]] abstractmethod

Return an iterator for (plugin, pair) pairs.

It a topic is given, each iterated plugin must support it. If no topic is given, the any plugin may be iterated.

The value returned for pair will be used with load_with_pair

Source code in grappler/grapplers/bases/_plugin_pair.py

@abstractmethod
def iter_plugins(
    self, topic: Optional[str], exit_stack: ExitStack, /
) -> Iterable[Tuple[Plugin, T_Cache]]:
    """
    Return an iterator for (plugin, pair) pairs.

    It a topic is given, each iterated plugin must support it.
    If no topic is given, the any plugin may be iterated.

    The value returned for `pair` will be used with
    [`load_with_pair`][grappler.grapplers.bases.PluginPairGrapplerBase.load_with_pair]
    """

load_with_pair(plugin: Plugin, pair: T_Cache) -> Any abstractmethod

Load a plugin and return it.

The value for pair is passed unmodifier from iter_plugins

Source code in grappler/grapplers/bases/_plugin_pair.py

@abstractmethod
def load_with_pair(self, plugin: Plugin, pair: T_Cache, /) -> Any:
    """Load a plugin and return it.

    The value for `pair` is passed unmodifier from
    [`iter_plugins`][grappler.grapplers.bases.PluginPairGrapplerBase.iter_plugins]
    """

BasicGrappler() -> None

Bases: ABC, Generic[T_ItConfig]

An abstract base class for a Grappler

To properly implement this abstract class, both create_iteration_context() and load_from_context() must be implemented.

In return, you will receive a class that is compliant with the Grappler protocol, which uses context variables to isolate iterations.

It is implemented as a generic class that allows a subclass store typed state before iteration, and receive it later when loading plugins. See EntryPointGrappler source code for an example.

Source code in grappler/grapplers/bases/_basic.py

def __init__(self) -> None:
    self.__iteration_configs: Dict[int, T_ItConfig] = {}

id() -> str property abstractmethod

Return a globally unqiue id for the grappler.

Source code in grappler/grapplers/bases/_basic.py

@property
@abstractmethod
def id(self) -> str:
    """Return a globally unqiue id for the grappler."""

create_iteration_context(topic: Optional[str], exit_stack: ExitStack) -> Tuple[Iterable[Plugin], T_ItConfig] abstractmethod

Return an iteration context for the grappler.

Parameters:

Name	Type	Description	Default
topic	Optional[str]	Optionally a topic to which the iterated plugins should be limited, or None if no limiting should occur.	required
exit_stack	ExitStack	A contextlib.ExitStack instance representing the iteration context. This can be used to setup context managers, ensuring that they will be torn down at the end of the iteration context.	required

The return value is a pair of values:

• an iterable of plugins
• a value that can store config for when load_from_context() is called.

Source code in grappler/grapplers/bases/_basic.py

@abstractmethod
def create_iteration_context(
    self, topic: Optional[str], exit_stack: ExitStack, /
) -> Tuple[Iterable[Plugin], T_ItConfig]:
    """
    Return an iteration context for the grappler.

    Args:
        topic: Optionally a topic to which the iterated plugins
               should be limited, or `None` if no limiting should
               occur.
        exit_stack: A `contextlib.ExitStack` instance representing
                    the iteration context. This can be used to
                    setup context managers, ensuring that they will
                    be torn down at the end of the iteration context.


    The return value is a pair of values:

    - an iterable of plugins
    - a value that can store config for when
    [`load_from_context()`][grappler.grapplers.bases.BasicGrappler.load_from_context]
    is called.

    """
    raise NotImplementedError

load_from_context(plugin: Plugin, context: T_ItConfig) -> Any abstractmethod

Load a plugin and return its value.

Parameters:

Name	Type	Description	Default
plugin	Plugin	Plugin to be loaded, which comes from the iterator returned from create_iteration_context()	required
context	T_ItConfig	Context value which was returned from create_iteration_context.	required

Source code in grappler/grapplers/bases/_basic.py

@abstractmethod
def load_from_context(self, plugin: Plugin, context: T_ItConfig, /) -> Any:
    """
    Load a plugin and return its value.

    Args:
        plugin: Plugin to be loaded, which comes from the iterator
                returned from
                [`create_iteration_context()`][grappler.grapplers.bases.BasicGrappler.create_iteration_context]
        context: Context value which was returned from
                 `create_iteration_context`.
    """
    raise NotImplementedError

cleanup_iteration_context(context: T_ItConfig) -> None

Cleanup an iteration context.

This method can be used to cleanup dangling resources that were created in create_iteration_context(). The default implementation does nothing.

Source code in grappler/grapplers/bases/_basic.py

def cleanup_iteration_context(self, context: T_ItConfig) -> None:
    """
    Cleanup an iteration context.

    This method can be used to cleanup dangling resources that
    were created in
    [`create_iteration_context()`][grappler.grapplers.bases.BasicGrappler.create_iteration_context].
    The default implementation does nothing.

    """