Action starter packs

conatus.actions.starter_packs.ActionStarterPack

ActionStarterPack(
    *raw_actions: Action
    | ActionBlueprint
    | FunctionType
    | Self,
)

A starter pack, or collection, of actions.

Starter packs are meant to be used as a substitute to a list of Action or ActionBlueprint objects in constructors.

In other words:

from conatus import action, Task
from conatus.actions.starter_packs import ActionStarterPack

@action
def action_0(): ...

@action
def action_1(): ...

# Ok, but a bit verbose
task = Task(
    description="This is a task",
    name="task",
    actions=[action_0, action_1],
)

starter_pack = ActionStarterPack(action_0, action_1)

# Cleaner
task = Task(
    description="This is a task",
    name="task",
    actions=starter_pack,
)

This is especially useful to pass browsing actions, which tend to be plentiful and not easily remembered.

Other classes like BaseTask will expect that the actions are in the form of a list of Action instances, and that they can be retrieved with the actions property.

You can also use:

• the + and - operators to add and remove actions from the starter pack.
• the len function to get the number of actions in the starter pack.

You just pass the actions you want to include in the starter pack, one after the other:

from conatus.actions.starter_packs import ActionStarterPack
from conatus.actions.preloaded.browsing import (
    browser_close,
    browser_goto,
    browser_start,
)

browsing_actions = ActionStarterPack(
    browser_start,
    browser_goto,
    browser_close,
)

PARAMETER	DESCRIPTION
raw_actions	The actions to include in the starter pack, in 'raw form', meaning that they can be any of the following: - Action - ActionBlueprint - FunctionType - ActionStarterPack TYPE: Action | ActionBlueprint | FunctionType | Self DEFAULT: ()

Source code in conatus/actions/starter_packs.py

def __init__(
    self, *raw_actions: Action | ActionBlueprint | FunctionType | Self
) -> None:
    """Initialize the starter pack.

    You just pass the actions you want to include in the starter pack,
    one after the other:

    ```python
    from conatus.actions.starter_packs import ActionStarterPack
    from conatus.actions.preloaded.browsing import (
        browser_close,
        browser_goto,
        browser_start,
    )

    browsing_actions = ActionStarterPack(
        browser_start,
        browser_goto,
        browser_close,
    )
    ```

    Args:
        raw_actions: The actions to include in the starter pack, in
            'raw form', meaning that they can be any of the following:
            - [`Action`][conatus.actions.action.Action]
            - [`ActionBlueprint`][conatus.actions.action.ActionBlueprint]
            - [`FunctionType`][conatus._types.FunctionType]
            - [`ActionStarterPack`
              ][conatus.actions.starter_packs.ActionStarterPack]
    """
    self._actions: list[Action] = []
    for raw_action in raw_actions:
        if isinstance(raw_action, ActionStarterPack):
            self._actions.extend(raw_action.actions)
        else:
            self._actions.append(convert_to_action(raw_action))
    self._actions_with_original: list[
        tuple[Action, Action | ActionBlueprint | FunctionType | Self]
    ] = list(
        zip(
            self._actions,
            raw_actions,
            strict=False,
        )
    )

actions property

actions: list[Action]

The actions in the starter pack.

from_existing classmethod

from_existing(
    actions: list[Action],
    actions_with_original: list[
        tuple[
            Action,
            Action | ActionBlueprint | FunctionType | Self,
        ]
    ],
) -> Self

Create a new starter pack from an existing one.

PARAMETER	DESCRIPTION
actions	The actions to include in the starter pack. TYPE: list[Action]
actions_with_original	The actions with original to include in the starter pack. TYPE: list[tuple[Action, Action | ActionBlueprint | FunctionType | Self]]

RETURNS	DESCRIPTION
Self	The new starter pack.

Source code in conatus/actions/starter_packs.py

@classmethod
def from_existing(
    cls,
    actions: list[Action],
    actions_with_original: list[
        tuple[Action, Action | ActionBlueprint | FunctionType | Self]
    ],
) -> Self:
    """Create a new starter pack from an existing one.

    Args:
        actions: The actions to include in the starter pack.
        actions_with_original: The actions with original to include in the
            starter pack.

    Returns:
        The new starter pack.
    """
    self = cls.__new__(cls)
    self._actions = actions
    self._actions_with_original = actions_with_original
    return self

__add__

__add__(
    other: Action | ActionBlueprint | FunctionType | Self,
) -> Self

Add an action to the starter pack.

PARAMETER	DESCRIPTION
other	The action to add to the starter pack. TYPE: Action | ActionBlueprint | FunctionType | Self

RETURNS	DESCRIPTION
Self	The starter pack with the action added.

Source code in conatus/actions/starter_packs.py

def __add__(
    self, other: Action | ActionBlueprint | FunctionType | Self
) -> Self:
    """Add an action to the starter pack.

    Args:
        other: The action to add to the starter pack.

    Returns:
        The starter pack with the action added.
    """
    if isinstance(other, ActionStarterPack):
        other = cast("Self", other)  # pyright: ignore[reportUnnecessaryCast]
        return self.__class__.from_existing(
            [*self._actions, *other._actions],
            [
                *self._actions_with_original,
                *other._actions_with_original,
            ],
        )
    new_action = convert_to_action(other)
    return self.__class__.from_existing(
        [*self._actions, new_action],
        [*self._actions_with_original, (new_action, other)],
    )

__radd__

__radd__(
    other: Action | ActionBlueprint | FunctionType | Self,
) -> Self

Add an action to the starter pack.

This is the same as __add__ .

PARAMETER	DESCRIPTION
other	The action to add to the starter pack. TYPE: Action | ActionBlueprint | FunctionType | Self

RETURNS	DESCRIPTION
Self	The starter pack with the action added.

Source code in conatus/actions/starter_packs.py

def __radd__(
    self, other: Action | ActionBlueprint | FunctionType | Self
) -> Self:
    """Add an action to the starter pack.

    This is the same as [`__add__`
    ][conatus.actions.starter_packs.ActionStarterPack.__add__].

    Args:
        other: The action to add to the starter pack.

    Returns:
        The starter pack with the action added.
    """
    return self.__add__(other)

__iadd__

__iadd__(
    other: Action | ActionBlueprint | FunctionType | Self,
) -> Self

Add an action to the starter pack.

This is the same as __add__ .

PARAMETER	DESCRIPTION
other	The action to add to the starter pack. TYPE: Action | ActionBlueprint | FunctionType | Self

RETURNS	DESCRIPTION
Self	The starter pack with the action added.

Source code in conatus/actions/starter_packs.py

def __iadd__(
    self, other: Action | ActionBlueprint | FunctionType | Self
) -> Self:
    """Add an action to the starter pack.

    This is the same as [`__add__`
    ][conatus.actions.starter_packs.ActionStarterPack.__add__].

    Args:
        other: The action to add to the starter pack.

    Returns:
        The starter pack with the action added.
    """
    return self.__add__(other)

__sub__

__sub__(
    other: Action | ActionBlueprint | FunctionType | Self,
) -> Self

Remove an action from the starter pack.

Note that if you pass a class instance, or a function, we will do our best effort to remove it from the starter pack, but this might not always be possible.

PARAMETER	DESCRIPTION
other	The action to remove from the starter pack. TYPE: Action | ActionBlueprint | FunctionType | Self

RETURNS	DESCRIPTION
Self	The starter pack with the action removed.

RAISES	DESCRIPTION
ValueError	If the action is not found in the starter pack.

Source code in conatus/actions/starter_packs.py

def __sub__(
    self, other: Action | ActionBlueprint | FunctionType | Self
) -> Self:
    """Remove an action from the starter pack.

    Note that if you pass a class instance, or a function, we will
    do our best effort to remove it from the starter pack, but this
    might not always be possible.

    Args:
        other: The action to remove from the starter pack.

    Returns:
        The starter pack with the action removed.

    Raises:
        ValueError: If the action is not found in the starter pack.
    """
    self_actions = self._actions
    self_actions_with_original = self._actions_with_original
    if isinstance(other, ActionStarterPack):
        other_actions = other.actions
        return self.__class__.from_existing(
            [
                action
                for action in self_actions
                if action not in other_actions
            ],
            [
                (action, original)
                for action, original in self_actions_with_original
                if action not in other_actions
            ],
        )
    detected_action = next(
        (
            action
            for action, original in self._actions_with_original
            if original == other
        ),
        None,
    )
    if detected_action is None:
        msg = f"Action {other} not found in starter pack"
        raise ValueError(msg)
    return self.__class__.from_existing(
        [action for action in self._actions if action != detected_action],
        [
            (action, original)
            for action, original in self._actions_with_original
            if action != detected_action
        ],
    )

__rsub__

__rsub__(
    other: Action | ActionBlueprint | FunctionType | Self,
) -> Self

Remove an action from the starter pack.

This is the same as __sub__ .

PARAMETER	DESCRIPTION
other	The action to remove from the starter pack. TYPE: Action | ActionBlueprint | FunctionType | Self

RETURNS	DESCRIPTION
Self	The starter pack with the action removed.

Source code in conatus/actions/starter_packs.py

def __rsub__(
    self, other: Action | ActionBlueprint | FunctionType | Self
) -> Self:
    """Remove an action from the starter pack.

    This is the same as [`__sub__`
    ][conatus.actions.starter_packs.ActionStarterPack.__sub__].

    Args:
        other: The action to remove from the starter pack.

    Returns:
        The starter pack with the action removed.
    """
    return self.__sub__(other)

__isub__

__isub__(
    other: Action | ActionBlueprint | FunctionType | Self,
) -> Self

Remove an action from the starter pack.

This is the same as __sub__ .

PARAMETER	DESCRIPTION
other	The action to remove from the starter pack. TYPE: Action | ActionBlueprint | FunctionType | Self

RETURNS	DESCRIPTION
Self	The starter pack with the action removed.

Source code in conatus/actions/starter_packs.py

def __isub__(
    self, other: Action | ActionBlueprint | FunctionType | Self
) -> Self:
    """Remove an action from the starter pack.

    This is the same as [`__sub__`
    ][conatus.actions.starter_packs.ActionStarterPack.__sub__].

    Args:
        other: The action to remove from the starter pack.

    Returns:
        The starter pack with the action removed.
    """
    return self.__sub__(other)

__len__

__len__() -> int

The number of actions in the starter pack.

This is the same as the length of the actions property.

RETURNS	DESCRIPTION
int	The number of actions in the starter pack.

Source code in conatus/actions/starter_packs.py

def __len__(self) -> int:
    """The number of actions in the starter pack.

    This is the same as the length of the [`actions`
    ][conatus.actions.starter_packs.ActionStarterPack.actions] property.

    Returns:
        The number of actions in the starter pack.
    """
    return len(self._actions)

__eq__

__eq__(other: object) -> bool

Check if two starter packs are equal.

PARAMETER	DESCRIPTION
other	The other starter pack to compare to. TYPE: object

RETURNS	DESCRIPTION
bool	Whether the two starter packs are equal.

Source code in conatus/actions/starter_packs.py

@override
def __eq__(self, other: object) -> bool:
    """Check if two starter packs are equal.

    Args:
        other: The other starter pack to compare to.

    Returns:
        Whether the two starter packs are equal.
    """
    if not isinstance(other, ActionStarterPack):
        return False
    return self._actions == other._actions

__hash__

__hash__() -> int

Hash the starter pack.

This is the same as the hash of the actions property.

RETURNS	DESCRIPTION
int	The hash of the starter pack.

Source code in conatus/actions/starter_packs.py

@override
def __hash__(self) -> int:
    """Hash the starter pack.

    This is the same as the hash of the [`actions`
    ][conatus.actions.starter_packs.ActionStarterPack.actions] property.

    Returns:
        The hash of the starter pack.
    """
    return hash(tuple(self._actions))