code/hello-world/ $ tomodachi run service/


Installation via poetry is fully supported and battle-tested, but pip works just as fine.

Install tomodachi in your preferred way, wether it be poetry, pip, pipx, etc. Installation will give your environment access to the tomodachi package for imports as well as a shortcut to the CLI alias, which later is used to run the microservices you build.

Installing from PyPI

app/ $ pip install tomodachi
> ...
> Installing collected packages: ..., ..., ..., tomodachi
> Successfully installed ... ... ... tomodachi-x.xx.xx

app/ $ tomodachi --version
> tomodachi x.xx.xx


The services you build, their installed dependencies, together with runtime utilities like tomodachi, should preferably always be installed in isolated environments like Docker containers or virtual environments. Microservices benefit a lot from containerization, both during development and when deployed, so get acquainted with tools like Docker unless you haven't already.

Instructions for contributors

Please help out to add features in the library that are missing or prepare pull requests with solutions to any bug you may encounter during execution.

Clone the repo and install the required dependencies. poetry is the default way of installing the development environment.

code/ $ git clone [email protected]:kalaspuff/tomodachi
code/ $ cd tomodachi

# Using poetry
tomodachi/ $ poetry install -E uvloop -E protobuf -E aiodns

# or alternatively with pip (version 20.2.4 tested)
tomodachi/ $ pip install --use-feature=2020-resolver -U .[uvloop,protobuf,aiodns]

# Verify that the tomodachi CLI is installed
tomodachi/ $ tomodachi --version
tomodachi/ $ python -m tomodachi --version

# If you prefer to not use the CLI entrypoint there's a script available
# as
tomodachi/ $ python --version

# Finally to start services
tomodachi/ $ tomodachi run examples/basic_examples/

# Alternative – instead of tomodachi cli, use as a module
tomodachi/ $ python -m examples/basic_examples/

It's highly recommended to use poetry for building and handling the dependencies, and poetry is probably best installed using pipx or via the installation script provided in the poetry documentation. Read more about both poetry and pipx at:

Development – linting and tests

This section is only relevant if you're adding functionality to the tomodachi repo.

There are GitHub actions enabled on "push" to automate test cases for the most common use-cases, as well as performing lint tests, type hint checking, etc. You can also run them on your own, see Makefile for a helping hand.

tomodachi/ $ make test
tomodachi/ $ make flake8
tomodachi/ $ make mypy

Note that the code must conform to the black code style and imports must be sorted alphabetically, and automatically separated into sections and by type. These code format styles will be checked in CI and must be followed for any branch or PR to pass all of the tests runs πŸ–€

Use the following make commands to run these tasks on demand:

tomodachi/ $ make black
# Runs: black tomodachi/ examples/ tests/

tomodachi/ $ make isort
# Runs: isort tomodachi/ examples/ tests/