Slots#

This module defines base classes for slots and some concrete implementations of them.

SlotName#

A string to identify slots.

Top-level slots are identified by their key in a GroupSlot.

E.g.

GroupSlot(
    user=RegexpSlot(),
    password=FunctionSlot,
)

Has two slots with names “user” and “password”.

For nested group slots use dots to separate names:

GroupSlot(
    user=GroupSlot(
        name=FunctionSlot,
        password=FunctionSlot,
    )
)

Has two slots with names “user.name” and “user.password”.

recursive_getattr(obj, slot_name)[source]#

recursive_setattr(obj, slot_name, value)[source]#

exception SlotNotExtracted[source]#

Bases: Exception

This exception can be returned or raised by slot extractor if slot extraction is unsuccessful.

class ExtractedSlot(**data)[source]#

Bases: BaseModel, ABC

Represents value of an extracted slot.

Instances of this class are managed by framework and are stored in slot_manager. They can be accessed via the ctx.framework_data.slot_manager.get_extracted_slot method.

class ExtractedValueSlot(**data)[source]#

Bases: ExtractedSlot

Value extracted from ValueSlot.

is_slot_extracted: bool#

extracted_value: Any#

default_value: Any#

pickle_serialize_values(value)[source]#: Cast values to string via pickle. Allows storing arbitrary data in these fields when using context storages.

classmethod pickle_validate_values(value)[source]#: Restore values after being processed with pickle_serialize_values().

property value#: Extracted value or the default value if the slot is not extracted.

class ExtractedGroupSlot(**data)[source]#

Bases: ExtractedSlot

update(old)[source]#

Rebase this extracted groups slot on top of another one. This is required to merge slot storage in-context with a potentially different slot configuration passed to pipeline.

Parameters:: old (ExtractedGroupSlot) – An instance of ExtractedGroupSlot stored in-context. Extracted values will be transferred to this object.

class BaseSlot(**data)[source]#

Bases: BaseModel

BaseSlot is a base class for all slots.

abstract async get_value(ctx)[source]#

Extract slot value from Context and return an instance of ExtractedSlot.

Return type:: ExtractedSlot

abstract init_value()[source]#

Provide an initial value to fill slot storage with.

Return type:: ExtractedSlot

class ValueSlot(**data)[source]#

Bases: BaseSlot

Value slot is a base class for all slots that are designed to extract concrete values. Subclass it, if you want to declare your own slot type.

default_value: Any#

abstract async extract_value(ctx)[source]#

Return value extracted from context.

Return SlotNotExtracted to mark extraction as unsuccessful.

Raising exceptions is also allowed and will result in an unsuccessful extraction as well.

Return type:: Union[Any, SlotNotExtracted]

async get_value(ctx)[source]#

Wrapper for extract_value() to handle exceptions.

Return type:: ExtractedValueSlot

init_value()[source]#

Provide an initial value to fill slot storage with.

Return type:: ExtractedValueSlot

class GroupSlot(**kwargs)[source]#

Bases: BaseSlot

Base class for RootSlot and GroupSlot.

async get_value(ctx)[source]#

Extract slot value from Context and return an instance of ExtractedSlot.

Return type:: ExtractedGroupSlot

init_value()[source]#

Provide an initial value to fill slot storage with.

Return type:: ExtractedGroupSlot

class RegexpSlot(**data)[source]#

Bases: ValueSlot

RegexpSlot is a slot type that extracts its value using a regular expression. You can pass a compiled or a non-compiled pattern to the regexp argument. If you want to extract a particular group, but not the full match, change the match_group_idx parameter.

regexp: str#

match_group_idx: int#: Index of the group to match.

async extract_value(ctx)[source]#

Return value extracted from context.

Return SlotNotExtracted to mark extraction as unsuccessful.

Raising exceptions is also allowed and will result in an unsuccessful extraction as well.

Return type:: Union[str, SlotNotExtracted]

class FunctionSlot(**data)[source]#

Bases: ValueSlot

A simpler version of ValueSlot.

Uses a user-defined func to extract slot value from the last_request Message.

func: Callable[[Message], Union[Awaitable[Union[Any, SlotNotExtracted]], Any, SlotNotExtracted]]#

async extract_value(ctx)[source]#

Return value extracted from context.

Return SlotNotExtracted to mark extraction as unsuccessful.

Raising exceptions is also allowed and will result in an unsuccessful extraction as well.

Return type:: Union[Any, SlotNotExtracted]

class SlotManager(**data)[source]#

Bases: BaseModel

Provides API for managing slots.

An instance of this class can be accessed via ctx.framework_data.slot_manager.

slot_storage: ExtractedGroupSlot#: Slot storage. Stored inside ctx.framework_data.

root_slot: GroupSlot#: Slot configuration passed during pipeline initialization.

set_root_slot(root_slot)[source]#

Set root_slot configuration from pipeline. Update extracted slots with the new configuration:

New slots are added with their init_value(). Old extracted slot values are preserved only if their configuration did not change. That is if they are still present in the config and if their fundamental type did not change (i.e. GroupSlot did not turn into a ValueSlot or vice versa).

This method is called by pipeline and is not supposed to be used otherwise.

get_slot(slot_name)[source]#

Get slot configuration from the slot name.

Raises:: KeyError – If the slot with the specified name does not exist.
Return type:: BaseSlot

async extract_slot(slot_name, ctx, success_only)[source]#

Extract slot slot_name and store extracted value in slot_storage.

Raises:

KeyError – If the slot with the specified name does not exist.

Parameters:

slot_name (str) – Name of the slot to extract.
ctx (Context) – Context.
success_only (bool) – Whether to store the value only if it is successfully extracted.

Return type:

None

async extract_all(ctx)[source]#: Extract all slots from slot configuration root_slot and set slot_storage to the extracted value.

get_extracted_slot(slot_name)[source]#

Retrieve extracted value from slot_storage.

Raises:: KeyError – If the slot with the specified name does not exist.
Return type:: Union[ExtractedValueSlot, ExtractedGroupSlot]

is_slot_extracted(slot_name)[source]#

Return if the specified slot is extracted.

Raises:: KeyError – If the slot with the specified name does not exist.
Return type:: bool

all_slots_extracted()[source]#

Return if all slots are extracted.

Return type:: bool

unset_slot(slot_name)[source]#

Mark specified slot as not extracted and clear extracted value.

Raises:: KeyError – If the slot with the specified name does not exist.
Return type:: None

unset_all_slots()[source]#

Mark all slots as not extracted and clear all extracted values.

Return type:: None

class KwargOnlyFormatter[source]#

Bases: Formatter

get_value(key, args, kwargs)[source]#

fill_template(template)[source]#

Fill template string with extracted slot values and return a formatted string or None if an exception has occurred while trying to fill template.

template should be a format-string:

E.g. “Your username is {profile.username}”.

For the example above, if profile.username slot has value “admin”, it would return the following text: “Your username is admin”.

Return type:: Optional[str]