Development

If you want to hack on this little library clone it via git

git clone https://github.com/Corvan/mailpit-api-client.git

or

git clone git@github.com:Corvan/mailpit-api-client.git

Of course you can fork it first on GitHub. Then you are easily able to open PRs, which is the preferred way of contributing code.

Install dependencies

It is recommended to use a virtual environment, in order to separate the dependencies for this project from dependencies of other projects. There are several tools out there to manage virtual environments, so please consult the respective documentantion if you’re not using venv or poetry

If you want to run the tests for all possible versions of Python you have to install Docker Engine, and the Docker Compose plugin on Linux. Or you install Docker Desktop on other operating system and on Linux.

pip

in order to install the Python dependencies enter the directory of your just cloned git repository, activate your virtual environment and type:

pip install -e ".[docs,test,pytest,build]"

Now you can start hacking.

poetry

If you want to use poetry as the manager for your virtual environment, install it if necessary and run

poetry update

inside the project’s directory.

In order to run the Invoke tasks you have to prefix all commands given there with

poetry run

so running the Invoke task of unittests you have to type

poetry run invoke tests.unit

Running the tests

This project uses pytest as testing framework. Even the unittest parts are tested themselves with pytest.

There are two kinds of tests in this project:

test type	description
unit tests	unit tests are tests that check if a functionality works isolated from everything else
integration tests	integration tests are tests that include dependencies, and check if functionalities work together

You can run the tests locally, but then you have to provide a running Mailpit by yourself for running the integration tests.

Invoke tasks

In order to run the tests inside Docker containers, there are Invoke tasks that use Docker Compose to set-up all the necessary containers and run the checks and tests in them afterwards. At the end things are cleaned up again.

$ invoke -l

Available tasks:

tests.checks
tests.integration
tests.unit

There are some more tasks, but you can concentrate on those three.

task	description
tests.checks	runs code checks, like black (code formatting), ruff (linting), and mypy (static code analysis)
tests.integration	runs the integration tests
tests.unit	runs the unit tests

To run a task, simply type

invoke <task>

It is also possible to run multiple tasks at once

invoke tests.checks tests.unit tests.integration

For running the tests all the logging outputs are set to debug. So running them will produce a lot of output, but you will want to know why things go wrong. If you want to reduce the amount, have a look at pyproject.toml

Build the documentation

cd docs

make clean sphinx-apidoc -d 4 -eM -f -o generated ../mailpit make html