API Reference

This page outlines sparkplug’s API.

sparkplug.host

This module contains the sparkplug command hosts and errors they might raise.

class sparkplug.host.CommandHost(use_fallback_strategy=False)

Provides a modular command system.

Parameters:use_fallback_strategy – Whether or not a default fallback strategy (that provides None) should be used in the event of an undefined strategy.
add_local_strategy(unit_name, annotation, strategy)

Adds a local strategy to this CommandHandler. A local strategy functions similarly to a normal, global one, but takes takes precedence over global ones for a specific unit.

Parameters:
  • unit_name – Unit to apply this strategy to.
  • annotation – Parameter annotation to match to the given strategy.
  • strategy – Callable strategy to get an appropriate object from.
add_strategy(annotation, strategy)

Adds a strategy to this CommandHandler.

Parameters:
  • annotation – Parameter annotation to match to the given strategy.
  • strategy – Callable strategy to get an appropriate object from.
call(command_call, context=None)

Calls a command and fulfills its parameters using known strategies with the given call as a string.

Parameters:
  • command_call – Name and parameters given to the command as a string.
  • context – Optional context object that is passed to any strategies that will accept it.
Returns:

Return value from the command.
get_parameter(annotation, text_args, context=None, domain=None)

Gets the value for a parameter using known strategies and given arguments. If given a domain, local strategies will take priority over global ones.

Parameters:
  • annotation – Parameter annotation, determines which strategy to use.
  • text_args – Arguments that can be used to determine parameters.
  • context – Optional context object that is passed to the strategy. defaults to None.
  • domain – Name of the unit that the parameter applies to, used to prioritize local strategies.
Returns:

Extracted parameter and remaining arguments afterwards.
get_strategy(annotation, unit_name=None)

Gets a strategy to resolve a parameter, optionally with a specific domain.

Parameters:
  • annotation – Parameter annotation find a strategy for.
  • unit_name – Domain to check a local strategy for first.
Raises:

NonexistentStrategyError – if use_fallback_strategy is false and a strategy was not found.
Returns:

Strategy for getting a parameter with the given annotation.
class sparkplug.host.AsyncCommandHost(use_fallback_strategy=False)

An extension of CommandHost which awaits strategies and commands.

class sparkplug.host.CommandHostError

Represents an exception that was raised by a CommandHost.

class sparkplug.host.NonexistentCommandError(attempted_command, available_commands)

Represents an exception that occurred from attempting to call a command that does not exist.

class sparkplug.host.NonexistentUnitError(unit_name)

Represents an exception that occurred from attempting to access a unit that does not exist.

class sparkplug.host.NonexistentStrategyError(wanted_type)

Represents an exception that occurred from attempting to fulfill a parameter with an annotation that no strategy is defined for.

class sparkplug.host.AmbiguityError(attempted_command)

Represents an exception that occurred from attempting to call a command that is defined in multiple units without explicity specifying a domain.

sparkplug.strategies

This module contains simple strategies for use with command hosts.

sparkplug.strategies.int_getter(text)

Gets an integer from the beginning of the given text.

Parameters:text – Parameters to work with.
Raises:ValueError – if text does not begin with an integer.
Returns:Tuple of extracted number and remaining parameters.
sparkplug.strategies.default_int_getter(default)

Returns an integer getter that returns a default value if the given parameters don’t start with an integer.

Parameters:default – Default value to return in the event of invalid input.
Returns:Wrapped integer getter function.
sparkplug.strategies.word_getter(text)

Gets the first word separated by a space from text.

Parameters:text – Parameters to work with.
Returns:Tuple of the first word of the parameters and the remaining text.
sparkplug.strategies.remaining_text_getter(text)

Consumes all of the remaining parameters.

Parameters:text – Parameters to work with.
Returns:Tuple of the given parameters and an empty string.