How to modify Lightbus

Contributions to Lightbus are very welcome. This will talk you though setting up a development installation of Lightbus. Using this installation you will be able to:

  • Modify the Lightbus source code and/or documentation
  • Run the Lightbus test suite
  • View any modified documentation locally
  • Use your development Lightbus install within another project


You will need:

  • Redis running locally

Getting the code

Checkout the Lightbus repository from GitHub:

git clone
cd lightbus

Environment setup

It is a good idea to put asyncio into debug mode. You can do this by setting the following in your shell's environment:


The testing framework will also need to know where your redis instance is running. This is set using the REDIS_URL and REDIS_URL_B environment variables:

# Default values shown below


You will need to install Lightbus' standard dependencies, as well as Lightbus' development dependencies. Note that you may need to install poetry if you do not already have it:

You can install both of these groups as follows:

# Install standard & dev dependencies into a virtual environment
poetry install

# Enter the virtual environment you have created,
# thereby giving you access the the pytest and mkdocs commands (below)
poetry shell

Running the tests

You can run the tests once you have completed the above steps:


Note that you can run subsets of the tests as follows:

pytest -m unit  # Fast with high coverage
pytest -m integration
pytest -m reliability
pytest -m benchmark

Viewing the Lightbus documentation locally

You can view the documentation of your local Lightbus install as follows:

# Serve the docs locally
mkdocs serve

You can now view the documentation The documentation source can be found in docs/.

You can also check for broken links within the docs by running the script:

# Check for broken links

Using within your project

You can install your development Lightbus install within your project as follows:

# Within your own project

# Make sure you remove any existing lightbus version
pip uninstall lightbus

# Install your local development lightbus
pip install --editable /path/to/your/local/lightbus

See also

Being familiar with the explanation section is highly recommended if modifying the Lightbus source