Boilerplate code for BrewBlox Service implementations

There is some boilerplate code involved when creating a Brewblox service. This repository can be forked to avoid having to do the boring configuration.

Everything listed under Required Changes must be done before the package works as intended.

How to use

• Fork this repository to your own Github account or project.
• Follow all steps outlined under the various Required Changes.
• Start coding your service =)
  • To test, run pipenv run pytest

Files

---

setup.py

Used to create a distributable and installable Python package. See https://docs.python.org/3.6/distutils/setupscript.html for more information.

Required Changes:

• Change the name variable to your project name. This is generally the same as the repository name. This name is used when installing the package through Pip.
  It is common for this name to equal the package name, but using "-" as separator instead of "_".
• Change the url parameter to the url of your repository.
• Change the author parameter to your name.
• Change the author_email parameter to your email.

---

tox.ini

Developer tools such as Tox, Pytest, Flake8, and Autopep8 use this file to find configuration options.

Required Changes:

• Change --cov=YOUR_PACKAGE to refer to your module name.
• The --cov-fail-under=100 makes the build fail if code coverage is less than 100%. It is optional, but recommended. Remove the # comment character to enable it.

---

.env

Project-specific environment variables can be stored here. Pipenv will automatically load it when executing a command in pipenv run.

For a basic service (not deployed to PyPi or Docker Hub), you do not need to add or edit anything here.

---

Pipfile

Pipenv is used to streamline development. It manages dependencies and virtual environments. It also automatically loads environment variables declared in .env.

Pipfile lists all dependencies. Everything under [packages] is needed for the package to run, while everything under [dev-packages] is needed to run the tests.

You can use pipenv install <package name> or pipenv install --dev <package name> to add dependencies.

Note: There is overlap between the [packages] section in Pipfile, and the install_requires=[] list in setup.py. The rule of thumb is that if you need an external package to run, you should add it to both.

Required Changes:

• Install pipenv (run sudo pip3 install pipenv)
• Update the Pipfile.lock file (run pipenv lock)

---

MANIFEST.in

This file lists all non-code files that should be part of the package. See https://docs.python.org/3.6/distutils/sourcedist.html#specifying-the-files-to-distribute for more info.

For a basic service, you do not need to change anything in this file.

---

.editorconfig

This file contains EditorConfig configuration for this project.
Among other things, it describes per file type whether it uses tabs or spaces.

For a basic service, you do not need to change anything in this file. However, it is recommended to use an editor that recognizes and uses .editorconfig files.

---

README.md

Your module readme (this file). It will be the package description on Pypi.org, and automatically be displayed in Github.

Required Changes:

• Add all important info about your package here. What does your package do? How do you use it? What is your favorite color?

---

YOUR_PACKAGE/

Your module. This name is used when importing your code in Python.

Required Changes:

• Rename to the desired module name. This name can't include "-" characters.
  It is common for single-module projects to use "-" as a separator for the project name, and "_" for the module.
  For example: your-package and your_package.

---

test/conftest.py

Project-level pytest fixtures. Some useful fixtures for testing any brewblox_service implementation are defined here. See tests in https://github.com/BrewBlox/brewblox-service/tree/develop/test for examples on how to use.

For a basic implementation, you do not need to change anything in this file.

---

test/test_hello.py

An example on how to test aiohttp endpoints you added. Feel free to remove this once you no longer need it.

---

docker/amd/Dockerfile

A docker file for running your package. To build, you need to copy the local version of your python package to docker/dist/ first.

The Dockerfiles are set up so both the AMD (desktop) and ARM variants can use the same input files.

Example:

python3 setup.py sdist

rm docker/dist/*
cp dist/* docker/dist/

docker build \
    --tag your-package:your-version \
    --file docker/amd/Dockerfile \
    docker/

# run it
docker run your-package:your-version

Required Changes:

• Rename instances of YOUR-PACKAGE and YOUR_PACKAGE in the docker file to desired project and package names.

---

docker/arm/Dockerfile

The same as for docker/amd/Dockerfile, but for Raspberry Pi targets.

In order to build for Raspberry, you must also first enable the ARM compiler.

Example:

python3 setup.py sdist

rm docker/dist/*
cp dist/* docker/dist/

# Enable ARM compiler
docker run --rm --privileged multiarch/qemu-user-static:register --reset

# Build the Raspberry Pi version
docker build \
    --tag your-package:rpi-your-version \
    --file docker/arm/Dockerfile \
    docker/

# Try to run Raspberry version
# On the desktop, this will fail with "standard_init_linux.go:190: exec user process caused "exec format error""
docker run --detach your-package:rpi-your-version

Required Changes:

• Rename instances of YOUR-PACKAGE and YOUR_PACKAGE in the docker file to desired project and package names.

---

.travis.yml

Travis can automatically test and deploy all commits you push to GitHub. If you haven't enabled travis for your repository: don't worry, it won't do anything.

You can enable Travis for your repository using https://travis-ci.org/. To deploy your software with Travis, you will also need PyPi and Docker Hub accounts.