Development Guide

Welcome! Thank you for wanting to make the project better. This section provides an overview on how repository structure and how to work with the code base.

Before you dive into this, it is best to read:

• The Contributing guide

Docker

The aiograpi project uses Docker to ease setting up a consistent development environment. The Docker documentation has details on how to install docker on your computer.

Once that is configured, the test suite can be run locally:

docker-compose run --rm test

If you want to be able to execute code in the container:

docker-compose run --rm devbox
(your code here)

In the devbox environment you’ll be able to enter a python shell and import aiograpi or any dependencies.

Debugging

The docker container has pdb++ install that can be used as a debugger. (However, you are welcome to set up a different debugger if you would like.)

This allows you to easily create a breakpoint anywhere in the code.

def my_function():
    breakpoint()
    ...

When your the code, you will drop into an interactive pdb++ debugger.

See the documentation on pdb and pdb++ for more information.

Testing

You’ll be unable to merge code unless the linting and tests pass. You can run these in your container via:

docker-compose run --rm test

This will run the same tests, linting, and code coverage that are run by the CI pipeline. The only difference is that, when run locally, black and isort are configured to automatically correct issues they detect.

Generally we should endeavor to write tests for every feature. Every new feature branch should increase the test coverage rather than decreasing it.

We use pytest as our testing framework.

Stages

To customize / override a specific testing stage, please read the documentation specific to that tool:

1. PyTest
2. MyPy
3. Isort
4. Flake8
5. Bandit

setup.py

Setuptools is used to packaging the library.

setup.py must not import anything from the package When installing from source, the user may not have the packages dependencies installed, and importing the package is likely to raise an ImportError. For this reason, the package version should be obtained without importing. This is explains why setup.py uses a regular expression to grabs the version from __init__.py without actually importing.

Requirements

• requirements.txt - Lists all direct dependencies (packages imported by the library).
• requirements-test.txt - Lists all direct requirements needed to run the test suite & lints.

This will trigger the CI system to build a wheel and a source distributions of the package and push them to PyPI.

Continuous Integration Pipeline

TODO: Add CI documentation.