Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

A simple command framework designed with chat bots in mind.

Project Description

Sparkplug is a simple command framework designed with chat bots in mind. It supports both synchronous and asynchronous command execution.

Quickstart Guide

Commands are modularized into units, like the one below. A unit can be anything with callable attributes. Any callable attribute that doesn’t begin with an underscore is assumed to be a user-facing command.

The parameters of commands should be annotated in order to tell the command host how to fill them in based on the user input.

>>> class SomeCommands:
...     def add_one(self, number: int):
...         return number + 1
...     def say_hello(self, person: 'word', times: int):
...         return ' '.join(['Hello ' + person] * times)
...     def repeat(self, text: 'my_text_getter'):
...         return text

A command host contains units like this in which it calls commands from.

>>> host = CommandHost()

An async variant is available, but just note that it will await both commands and strategies.

>>> host = AsyncCommandHost()

We’ll stick with the synchronous command host for this example.

Units can be added in a few different ways:

>>> host += 'foo', SomeCommands()     # Name specified explicitly
>>> host['foo'] = SomeCommands()      # Name specified explicitly
>>> host += SomeCommands()            # __name__ used to guess name

A command host also contains strategies, which are used to fill in the annotated types of commands. They are functions that should accept parameters in string form, and return a tuple of the object interpreted from the string and the remaining parameters that were not used.

If invalid input is given, a strategy can handle this however it wants (i.e. raising an error, using a default value).

>>> host.add_strategy(int, strategies.int_getter) # Default strategies for common types are available
>>> host.add_strategy('word', strategies.word_getter)
>>> host.add_strategy('text', lambda s: (s, '')) # Returns the entire input. Everything is consumed, so '' is returned

Once all of the desired commands and strategies are set up, call can be used with a command string to parse and execute it.

>>>'add_one 41')
>>>'say_hello John 3')
'Hello John Hello John Hello John'
>>> host_call('repeat after me')
'after me'

In the event of a command clash (suppose we had a unit 'bar' that also had a command named repeat), unit names can explicitly be specified.

>>>'foo:repeat after me')
'after me'

Finally, if for some reason a unit needs to be unloaded, it can be done by subtracting its name from the host.

>>> host -= 'foo'

Release History

This version
History Node


Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(7.9 kB) Copy SHA256 Hash SHA256
Wheel py3 Mar 5, 2018
(5.2 kB) Copy SHA256 Hash SHA256
Source None Mar 5, 2018

Supported By

Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Google Google Cloud Servers DreamHost DreamHost Log Hosting