debuglevel / document-archiver

Python Microservice Template

Python microservice template, inspired by my Kotlin based microservice template https://github.com/debuglevel/greeting-microservice, but with way less enthusiasm; and I'm not too sure that too much works here, because I just copied a bunch of stuff from my various other projects to have them at one place at least.

Development environment

• Python environment
  • Python 3.8
  • venv
• Code quality
  • Formatting
    • black
  • Type annotations
    • mypy
  • Testing
    • pytest
    • tox
• REST
  • FastAPI
• Deployment
  • Docker
  • docker-compose
• IDE
  • PyCharm Community

TODO

• Logging that does not completely suck
  • would nice to be configurable via ENV
• Testing?
  • tox (which seems to test against different Python versions. WTF compatibility? But it does not install those environments/python versions!)
• linting?
• Formatting?

Development

Environment

Initialize virtual environment (using venv)

python3 -m venv venv

Activate virtual environment

source ./venv/bin/activate

Note: If created on Windows, the directory is named Scripts because Python is weird.

.\venv\Scripts\Activate.ps1

Dependencies

Install dependencies

pip install -r requirements-dev.txt

Dependency updates

pip list --outdated shows outdated (transitive) dependencies.

Formatting / Linting

black

black is used for formatting, because black does not ask about your opinion about how Python code should be formatted.

black .

mypy

mypy checks the type annotations:

mypy app tests

Testing

Run tests

pytest

Run tests on every file change

pytest-watch -c # -c clears terminal before pytest runs

Run test against different environments

tox

Documentation

OpenAPI documentation

• Open Swagger UI or ReDoc
• OpenAPI specs are available (as JSON) at http://localhost:8080/openapi.json
• Update openapi.json via python update-openapi.py

All-in-one

tox.ini is also configured to run some additional commands (like a Makefile):

• black . for formatting
• python update-openapi.py to update openapi.yaml
• pytest for testing

Deployment

Development (with auto reloading changed files)

uvicorn app.rest.main:fastapi --port=8080 --reload --log-config=app/logging-config.yaml

Production

This should be quite okay:

uvicorn app.rest.main:fastapi --port=8080 --log-config=app/logging-config.yaml

But some docs mention that gunicorn can be used as a manager.

Production (via docker compose)

docker compose up --build