spade package

Submodules

spade.agent module

class spade.agent.Agent(jid: str, password: str, port: int = 5222, verify_security: bool = False)

Bases: object

add_behaviour(behaviour: BehaviourType, template: Optional[Template] = None) → None

Adds and starts a behaviour to the agent. If template is not None it is used to match new messages and deliver them to the behaviour.

Args:

behaviour (Type[spade.behaviour.CyclicBehaviour]): the behaviour to be started template (spade.template.Template, optional): the template to match messages with (Default value = None)

property avatar: str

Generates a unique avatar for the agent based on its JID. Uses Gravatar service with MonsterID option.

Returns:

str: the url of the agent’s avatar

static build_avatar_url(jid: str) → str

Static method to build a gravatar url with the agent’s JID

Args:

jid (aioxmpp.JID): an XMPP identifier

Returns:

str: a URL for the gravatar

dispatch(msg: Message) → List[Task]

Dispatch the message to every behaviour that is waiting for it using their templates match.

Args:

msg (spade.message.Message): the message to dispatch.

Returns:

list(asyncio.Future): a list of tasks for each message queuing in each matching behavior.

get(name: str) → Any

Recovers a knowledge item from the agent’s knowledge base.

Args:

name(str): name of the item

Returns:

object: the object retrieved or None

has_behaviour(behaviour: Type[CyclicBehaviour]) → bool

Checks if a behaviour is added to an agent.

Args:

behaviour (Type[spade.behaviour.CyclicBehaviour]): the behaviour instance to check

Returns:

bool: a boolean that indicates wether the behaviour is inside the agent.

is_alive() → bool

Checks if the agent is alive.

Returns:

bool: wheter the agent is alive or not

property name: str

Returns the name of the agent (the string before the ‘@’)

Returns:

str: the name of the agent (the string before the ‘@’)

remove_behaviour(behaviour: Type[CyclicBehaviour]) → None

Removes a behaviour from the agent. The behaviour is first killed.

Args:

behaviour (Type[spade.behaviour.CyclicBehaviour]): the behaviour instance to be removed

set(name: str, value: Any)

Stores a knowledge item in the agent knowledge base.

Args:

name (str): name of the item value (object): value of the item

set_container(container: Container) → None

Sets the container to which the agent is attached

Args:

container (spade.container.Container): the container to be attached to

set_loop(loop) → None

async setup() → None

Setup agent before startup. This coroutine may be overloaded.

async start(auto_register: bool = True) → None

Starts this agent.

Args:

auto_register (bool): register the agent in the server (Default value = True)

Returns:

None

async stop() → None

Stops this agent.

submit(coro: Coroutine) → Task

Runs a coroutine in the event loop of the agent. this call is not blocking.

Args:

coro (Coroutine): the coroutine to be run

Returns:

asyncio.Task: the Task assigned to the coroutine execution

exception spade.agent.AuthenticationFailure

Bases: Exception

exception spade.agent.DisconnectedException

Bases: Exception

spade.behaviour module

exception spade.behaviour.BehaviourNotFinishedException

Bases: Exception

class spade.behaviour.CyclicBehaviour

Bases: object

This behaviour is executed cyclically until it is stopped.

async enqueue(message: Message) → None

Enqueues a message in the behaviour’s mailbox

Args:

message (spade.message.Message): the message to be enqueued

property exit_code: Any

Returns the exit_code of the behaviour. It only works when the behaviour is done or killed, otherwise it raises an exception.

Returns:

object: the exit code of the behaviour

Raises:

BehaviourNotFinishedException: if the behaviour is not yet finished

get(name: str) → Any

Recovers a knowledge item from the agent’s knowledge base.

Args:

name (str): name of the item

Returns:

Any: the object retrieved or None

is_done() → bool

Check if the behaviour is finished

Returns:

bool: whether the behaviour is finished or not

is_killed() → bool

Checks if the behaviour was killed by means of the kill() method.

Returns:

bool: whether the behaviour is killed or not

async join(timeout: Optional[float] = None) → None

Wait for the behaviour to complete

Args:

timeout (Optional[float]): an optional timeout to wait to join (if None, the join is blocking)

Returns:

None

Raises:

TimeoutError: if the timeout is reached

kill(exit_code: Optional[Any] = None) → None

Stops the behaviour

Args:

exit_code (object, optional): the exit code of the behaviour (Default value = None)

mailbox_size() → int

Checks if there is a message in the mailbox

Returns:

int: the number of messages in the mailbox

match(message: Message) → bool

Matches a message with the behaviour’s template

Args:

message(spade.message.Message): the message to match with

Returns:

bool: wheter the messaged matches or not

async on_end() → None

Coroutine called after the behaviour is done or killed.

async on_start() → None

Coroutine called before the behaviour is started.

async receive(timeout: Optional[float] = None) → Optional[Message]

Receives a message for this behaviour. If timeout is not None it returns the message or “None” after timeout is done.

Args:

timeout (float, optional): number of seconds until return

Returns:

spade.message.Message: a Message or None

abstract async run() → None

Body of the behaviour. To be implemented by user.

async send(msg: Message) → None

Sends a message.

Args:

msg (spade.message.Message): the message to be sent.

set(name: str, value: Any) → None

Stores a knowledge item in the agent knowledge base.

Args:

name (str): name of the item value (Any): value of the item

set_agent(agent) → None

Links behaviour with its owner agent

Args:

agent (spade.agent.Agent): the agent who owns the behaviour

set_template(template: Template) → None

Sets the template that is used to match incoming messages with this behaviour.

Args:

template (spade.template.Template): the template to match with

start() → None

starts behaviour in the event loop

class spade.behaviour.FSMBehaviour

Bases: CyclicBehaviour

A behaviour composed of states (oneshotbehaviours) that may transition from one state to another.

add_state(name: str, state: State, initial: bool = False) → None

Adds a new state to the FSM.

Args:

name (str): the name of the state, which is used as its identifier. state (spade.behaviour.State): The state class initial (bool, optional): wether the state is the initial state or not. (Only one initial state is allowed) (Default value = False)

add_transition(source: str, dest: str) → None

Adds a transition from one state to another.

Args:

source (str): the name of the state from where the transition starts dest (str): the name of the state where the transition ends

get_state(name) → State

get_states() → Dict[str, State]

is_valid_transition(source: str, dest: str) → bool

Checks if a transitions is registered in the FSM

Args:

source (str): the source state name dest (str): the destination state name

Returns:

bool: wether the transition is valid or not

async run() → None

In this kind of behaviour there is no need to overload run. The run methods to be overloaded are in the State class.

setup() → None

to_graphviz() → str

Converts the FSM behaviour structure to Graphviz syntax

Returns:

str: the graph in Graphviz syntax

exception spade.behaviour.NotValidState

Bases: Exception

exception spade.behaviour.NotValidTransition

Bases: Exception

class spade.behaviour.OneShotBehaviour

Bases: CyclicBehaviour

This behaviour is only executed once

class spade.behaviour.PeriodicBehaviour(period: float, start_at: Optional[datetime] = None)

Bases: CyclicBehaviour

This behaviour is executed periodically with an interval

property period: timedelta

Get the period.

class spade.behaviour.State

Bases: OneShotBehaviour

A state of a FSMBehaviour is a OneShotBehaviour

set_next_state(state_name: str) → None

Set the state to transition to when this state is finished. state_name must be a valid state and the transition must be registered. If set_next_state is not called then current state is a final state.

Args:

state_name (str): the name of the state to transition to

class spade.behaviour.TimeoutBehaviour(start_at)

Bases: OneShotBehaviour

This behaviour is executed once at after specified datetime

spade.behaviour.now(tz=None)

Returns new datetime object representing current time local to tz.

tz

Timezone object.

If no tz is specified, uses local timezone.

spade.cli module

spade.cli.check_port_in_use(port, host='0.0.0.0')

Checks if a port is in use

spade.cli.create_cli()

Factory function to create the CLI

spade.container module

class spade.container.Container

Bases: Container

The container class allows agents to exchange messages without using the XMPP socket if they are in the same process. The container is a singleton.

spade.container.get_or_create_eventloop()

Create or retrieve the appropriate event loop, using uvloop on Linux/macOS and winloop on Windows if available.

spade.container.run_container(main_func: Coroutine) → None

spade.message module

class spade.message.Message(to: Optional[str] = None, sender: Optional[str] = None, body: Optional[str] = None, thread: Optional[str] = None, metadata: Optional[Dict[str, str]] = None)

Bases: MessageBase

make_reply() → Message

Creates a copy of the message, exchanging sender and receiver

Returns:

spade.message.Message: a new message with exchanged sender and receiver

prepare(client: ClientXMPP) → Message

Returns a slixmpp.stanza.Message built from the Message and prepared to be sent.

Args:

client (ClientXMPP): An XMPP client, whose stream will be used to send the message

Returns:

slixmpp.stanza.Message: the message prepared to be sent

class spade.message.MessageBase(to: Optional[str] = None, sender: Optional[str] = None, body: Optional[str] = None, thread: Optional[str] = None, metadata: Optional[Dict[str, str]] = None)

Bases: object

property body: str

Get body of the message Returns:

str: the body of the message

classmethod from_node(node: Message) → Type[MessageBase]

Creates a new spade.message.Message from a slixmpp.stanza.Message

Args:

node (slixmpp.stanza.Message): a slixmpp Message

Returns:

spade.message.Message: a new spade Message

get_metadata(key: str) → str

Get the value of a metadata. Returns None if metadata does not exist.

Args:

key (str): name of the metadata

Returns:

str: the value of the metadata (or None)

property id: int

match(message: Type[MessageBase]) → bool

Returns wether a message matches with this message or not. The message can be a Message object or a Template object.

Args:

message (spade.message.Message): the message to match to

Returns:

bool: wether the message matches or not

property sender: JID

Get jid of the sender

Returns:

slixmpp.JID: jid of the sender

set_metadata(key: str, value: str) → None

Add a new metadata to the message

Args:

key (str): name of the metadata value (str): value of the metadata

property thread: str

Get Thread of the message

Returns:

str: thread id

property to: JID

Gets the jid of the receiver.

Returns:

slixmpp.JID: jid of the receiver

spade.presence module

class spade.presence.Contact(jid: JID, name: str, subscription: str, ask: str, groups: list)

Bases: object

get_presence(resource: Optional[str] = None) → PresenceInfo

is_available() → bool

is_subscribed() → bool

update_presence(resource: str, presence_info: PresenceInfo)

update_subscription(subscription: str, ask: str)

exception spade.presence.ContactNotFound

Bases: Exception

class spade.presence.PresenceInfo(presence_type: PresenceType, show: PresenceShow, status: Optional[str] = '', priority: int = 0)

Bases: object

is_available() → bool

class spade.presence.PresenceManager(agent, approve_all: bool = False)

Bases: object

approve_subscription(jid: str)

get_contact(jid: Union[str, JID]) → Contact

get_contact_presence(jid: Union[str, JID], resource: Optional[str] = None) → PresenceInfo

get_contacts() → Dict[str, Contact]

get_presence() → PresenceInfo

get_priority() → int

get_show() → PresenceShow

get_status() → Optional[str]

handle_presence(presence: Presence)

handle_roster_update(event)

Executed when the roster is received or updated.

handle_subscription(presence: Presence)

is_available() → bool

on_available(peer_jid: str, presence_info: PresenceInfo, last_presence: Optional[PresenceInfo])

on_presence_received(presence: Presence)

on_subscribe(peer_jid: str)

on_subscribed(peer_jid: str)

on_unavailable(peer_jid: str, presence_info: PresenceInfo, last_presence: Optional[PresenceInfo])

on_unsubscribe(peer_jid: str)

on_unsubscribed(peer_jid: str)

set_available()

set_presence(presence_type: PresenceType = PresenceType.AVAILABLE, show: PresenceShow = PresenceShow.CHAT, status: Optional[str] = '', priority: int = 0)

set_unavailable()

subscribe(jid: str)

subscribed(jid: str)

unsubscribe(jid: str)

unsubscribed(jid: str)

exception spade.presence.PresenceNotFound

Bases: Exception

class spade.presence.PresenceShow(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

AWAY = 'away'

CHAT = 'chat'

DND = 'dnd'

EXTENDED_AWAY = 'xa'

NONE = 'none'

class spade.presence.PresenceType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

AVAILABLE = 'available'

ERROR = 'error'

PROBE = 'probe'

SUBSCRIBE = 'subscribe'

SUBSCRIBED = 'subscribed'

UNAVAILABLE = 'unavailable'

UNSUBSCRIBE = 'unsubscribe'

UNSUBSCRIBED = 'unsubscribed'

spade.template module

class spade.template.ANDTemplate(expr1, expr2)

Bases: BaseTemplate

match(message)

class spade.template.BaseTemplate

Bases: object

Template operators

class spade.template.NOTTemplate(expr)

Bases: BaseTemplate

match(message)

class spade.template.ORTemplate(expr1, expr2)

Bases: BaseTemplate

match(message)

class spade.template.Template(to: Optional[str] = None, sender: Optional[str] = None, body: Optional[str] = None, thread: Optional[str] = None, metadata: Optional[Dict[str, str]] = None)

Bases: BaseTemplate, MessageBase

Template for message matching

class spade.template.XORTemplate(expr1, expr2)

Bases: BaseTemplate

match(message)

spade.trace module

class spade.trace.TraceStore(size: int)

Bases: object

Stores and allows queries about events.

all(limit: Optional[int] = None) → List[Message]

Returns all the events, until a limit if defined

Args:

limit (int, optional): the max length of the events to return (Default value = None)

Returns:

list: a list of events

append(event: Message, category: Optional[str] = None) → None

Adds a new event to the trace store. The event may hava a category

Args:

event (spade.message.Message): the event to be stored category (str, optional): a category to classify the event (Default value = None)

filter(limit: Optional[int] = None, to: Optional[str] = None, category: Optional[str] = None) → List[Message]

Returns the events that match the filters

Args:

limit (int, optional): the max length of the events to return (Default value = None) to (str, optional): only events that have been sent or received by ‘to’ (Default value = None) category (str, optional): only events belonging to the category (Default value = None)

Returns:

list: a list of filtered events

len() → int

Length of the store

Returns:

int: the size of the trace store

received(limit: Optional[int] = None) → List[Message]

Returns all the events that have been received (excluding sent events), until a limit if defined

Args:

limit (int, optional): the max length of the events to return (Default value = None)

Returns:

list: a list of received events

reset() → None

Resets the trace store

spade.web module

class spade.web.WebApp(agent)

Bases: object

Module to handle agent’s web interface

add_get(path: str, controller: Coroutine, template: str, raw: Optional[bool] = False) → None

Setup a route of type GET

Args:

path (str): URL to listen to controller (coroutine): the coroutine to handle the request template (str): the template to render the response or None if it is a JSON response raw (bool): indicates if post-processing (jinja, json, etc) is needed or not

add_menu_entry(name: str, url: str, icon='fa fa-circle') → None

Adds a new entry to the menu.

Args:

name (str): name of the entry url (str): url to be redirected to icon (str): icon to be displayed (Default value = “fa fa-circle”)

add_post(path: str, controller: Coroutine, template: str, raw: Optional[bool] = False) → None

Setup a route of type POST

Args:

path (str): URL to listen to controller (coroutine): the coroutine to handle the request template (str): the template to render the response or None if it is a JSON response raw (bool): indicates if post-processing (jinja, json, etc) is needed or not

add_template_path(templates_path)

async agent_processor(request)

find_behaviour(behaviour_str: str) → Optional[Type[CyclicBehaviour]]

async get_agent(request)

async get_behaviour(request)

async get_messages(request)

async index(request)

is_started() → bool

async kill_behaviour(request)

async send_agent(request)

setup_routes() → None

start(hostname: Optional[str] = None, port: Optional[int] = None, templates_path: Optional[str] = None)

Starts the web interface.

Args:

hostname (str, optional): host name to listen from. (Default value = None) port (int, optional): port to listen from. (Default value = None) templates_path (str, optional): path to look for templates. (Default value = None)

async stop_agent(request)

async stop_now(request)

static timeago(date)

async unsubscribe_agent(request)

async spade.web.start_server_in_loop(runner: AppRunner, hostname: str, port: int, agent)

Listens to http requests and sends them to the webapp.

Args:

runner (AppRunner): AppRunner to process the http requests hostname (str): host name to listen from. port (int): port to listen from. agent (spade.agent.Agent): agent that owns the web app.

spade.web.unused_port(hostname: str) → None

Return a port that is unused on the current host.

spade.xmpp_client module

exception spade.xmpp_client.RegistrationException

Bases: Exception

class spade.xmpp_client.XMPPClient(jid, password, verify_security, auto_register)

Bases: ClientXMPP

async register(event)

session_start(event)

Module contents