References

Collection of references, blogs, documentation pages for used packages, tools.

Black

Code formatter for python. Used during development of this service inside pre-commit. Is configured inside the pyproject.toml.

As described in official documentation:

Blackened code looks the same regardless of the project you're reading. Formatting becomes transparent after a while and you can focus on the content instead.

Black makes code review faster by producing the smallest diffs possible.

Documentation and useful additional resources:

Codespell

Check misspellings in code. Used during development of this service inside pre-commit. Is configured inside the .pre-commit-config.yml.

Documentation and useful additional resources:

Cookiecutter

Cookiecutter creates projects from project templates using jinja2.

Cookiecutter is used inside create_service of fastapi-serviceutils to create new service using template as defined at fastapi_serviceutils_template.

Documentation and useful additional resources:

Databases

Simple asyncio support for a range of databases. Allows to make queries using SQLAlchemy.

As recommended by fastapi-documentation, fastapi-serviceutils services use the package databases to interact with databases.

Documentation and useful additional resources:

Dephell

Dephell is a tool for project management for Python.

In our workflow we use it to convert the dependencies of a project as defined inside the pyproject.toml to a requirements.txt as it is used inside the Dockerfile to convert a service to a docker-image.

Usage is configured inside the pyproject.toml.

It is automatically used inside make docker and make finalize (see makefile).

Documentation and useful additional resources:

Docker

Used to containerize the service in deployment.

As described in official docker-documentation:

Docker is an open platform for developing, shipping, and running applications. Docker enables you to separate your applications from your infrastructure so you can deliver software quickly. With Docker, you can manage your infrastructure in the same ways you manage your applications. By taking advantage of Docker’s methodologies for shipping, testing, and deploying code quickly, you can significantly reduce the delay between writing code and running it in production.

Documentation and useful additional resources:

Docker-compose

Used to wrap the docker-command at deployment of the service and easier usage of port-mappings and environment-variable definition.

As described in the official docker-compose-documentation:

Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. ...

Compose works in all environments: production, staging, development, testing, as well as CI workflows. ...

Using Compose is basically a three-step process:

  • Define your app’s environment with a Dockerfile so it can be reproduced anywhere.
  • Define the services that make up your app in docker-compose.yml so they can be run together in an isolated environment.
  • Run docker-compose up and Compose starts and runs your entire app.

Documentation and useful additional resources:

Environment variable

As described at wikipedia:

An environment variable is a dynamic-named value that can affect the way running processes will behave on a computer.

Inside the service Environment variables are used to be able to overwrite service-settings from the config.yml.

For details about how to configure the service, see configuration.

Documentation and useful additional resources:

FastAPI

High-performance web framework for building APIs with python 3.6+. Based on open standard for APIs (OpenAPI). For the definition of the input- and output-models of endpoints [Pydantic][#pydantic] is used.

This service is mainly based on this framework! All additional packages are used around this package.

Documentation and useful additional resources:

fastapi-serviceutils

Additional utils and functions for easier creation and usage of FastAPI.

Documentation and useful additional resources:

Flake8

Modular source code checker for pep8, pyflakes and co. Used during development of this service inside pre-commit. Is configured inside the setup.cfg.

Documentation and useful additional resources:

Flake8-bugbear

A plugin for Flake8 finding likely bugs and design problems in your program. Contains warnings that don't belong in pyflakes and pycodestyle.

Used in pre-Commit of the service. Is configured inside the setup.cfg.

Documentation and useful additional resources:

Git

Git is a free and open source distributed version control system.

The service is versioned using git. For additional information about the git-workflow used in this service see git-workflow.

Documentation and useful additional resources:

git-extras

Contain some additional git commands for easier git workflow.

Documentation and useful additional resources:

Loguru

For better traceback in log-files and usage of request-id as context inside log-entries, the default logging of fastapi is extended by usage of loguru inside services based on fastapi-serviceutils.

Documentation and useful additional resources:

Make

To wrap common tasks during development of the service, commands are wrapped inside a makefile.

Is configured inside Makefile. For available make-commands during development of the service see makefile.

Documentation and useful additional resources:

Markdown

Description from commonmark.org:

Markdown is a simple way to format text that looks great on any device. It doesn’t do anything fancy like change the font size, color, or type — just the essentials, using keyboard symbols you already know.

Alternative to restructured text format like it is used in Sphinx-Documentations.

This service is documented using Markdown files inside the docs/source folder. The tools required for this documentation are MkDocs and PyDoc-Markdown.

Documentation and useful additional resources:

MkDocs

From official documentation page:

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

It's mostly the same like Sphinx, but oriented on Markdown and a more modern output and usage design.

This service is documented using PyDoc-Markdown which is a wrapper around MkDocs with additional functionality.

Documentation and useful additional resources:

MkDocs-Material

Used theme in this service for MkDocs (over PyDoc-Markdown).

Documentation and useful additional resources:

OpenAPI

Description from wikipedia:

The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services. Originally part of the Swagger framework, it became a separate project in 2016, overseen by the OpenAPI Initiative, an open-source collaboration project of the Linux Foundation. Swagger and some other tools can generate code, documentation and test cases given an interface file.

OpenAPI-documentations are sometimes yet named Swagger-documentations.

Used in the service to create the interactive documentation pages for the service at routes:

  • /docs
  • /redoc

To create these documentation-pages, the package FastAPI is used.

Documentation and useful additional resources:

Poetry

Poetry is used in our workflow for python packaging and dependency management. All relevant poetry commands like create new environment, update environment, etc. are wrapped inside the Makefile, reducing the manual poetry commands to execute to poetry shell when starting a new development-session.

Documentation and useful additional resources:

Pre-Commit

Enables git-hooks for the service. Is configured using the .pre-commit-config.yml. Run a couple of linters, checkers and formatters like Black, Flake8, PyCodeStyle, etc.

Documentation and useful additional resources:

Pydoc-Markdown

Pydocmd uses MkDocs and extended Markdown syntax to generate Python API documentation.

Used in this service to create this documentation. Configured inside the pydocmd.yml. Markdown files used for the documentation are inside docs/source.

Documentation and useful additional resources:

PyDocStyle

Pydocstyle is a static analysis tool for checking compliance with Python docstring conventions.

Used inside pre-commit configured for the service in .pre-commit-config.yml.

Documentation and useful additional resources:

Pytest

Tests inside this service are using the pytest-package.

Tested code is easier to refactor and more stable.

Documentation and useful additional resources:

PyYAML

PyYAML is a full-featured YAML framework for the Python programming language.

Used inside fastapi-serviceutils to read the config.yml to configure the service. For additional information about how to configure the service see configuration.

Documentation and useful additional resources:

Requests

Documentation and useful additional resources:

Semantic Versioning (semver)

Services based on fastapi-serviceutils (like this service) use the semantic-versioning style. It is also named SemVer. Alternative to other versioning styles like 0ver, CalVer, etc.

Semantic versioning in short:

A version is built of three elements separated by dots (even more elements are possible but we are focusing on this short style in this service without special cases like pre-releases, alpha, beta, etc.): <MAJOR>.<MINOR>.<PATCH>

Note

If a bugfix is made in the service, the patch-version will be increased. If additional functionality is added without changing previous behaviour of the service, the minor-version is increased. If breaking changes are made we increase the major-version.

The versioning style is defined in the pyproject.toml inside [tool.dephell.main].

Documentation and useful additional resources:

SQLAlchemy

From official documentation:

SQLAlchemy is the Python SQL toolkit and Object Relational Mapper that gives application developers the full power and flexibility of SQL.

It provides a full suite of well known enterprise-level persistence patterns, designed for efficient and high-performing database access, adapted into a simple and Pythonic domain language.

This service uses Databases in combination with SQLAlchemy to interact with databases.

Documentation and useful additional resources:

Tmux

tmux is a terminal multiplexer. It lets you switch easily between several programs in one terminal, detach them (they keep running in the background) and reattach them to a different terminal.

It is used in the service during development in Tmuxp.

Documentation and useful additional resources:

Tmuxp

Is a tmux session manager. Sessions and workflows can be configured inside a .tmuxp.yml.

This service contains such a tmuxp.yml for easier development.

Documentation and useful additional resources:

PyToolz

From official documentation:

Toolz provides a set of utility functions for iterators, functions, and dictionaries. These functions interoperate well and form the building blocks of common data analytic operations. They extend the standard libraries itertools and functools and borrow heavily from the standard libraries of contemporary functional languages.

Toolz provides a suite of functions which have the following functional virtues:

  • Composable: They interoperate due to their use of core data structures.
  • Pure: They don’t change their inputs or rely on external state.
  • Lazy: They don’t run until absolutely necessary, allowing them to support large streaming data sets.

Toolz functions are pragmatic. They understand that most programmers have deadlines.

  • Low Tech: They’re just functions, no syntax or magic tricks to learn
  • Tuned: They’re profiled and optimized
  • Serializable: They support common solutions for parallel computing

This gives developers the power to write powerful programs to solve complex problems with relatively simple code. This code can be easy to understand without sacrificing performance. Toolz enables this approach, commonly associated with functional programming, within a natural Pythonic style suitable for most developers.

Toolz is used in fastapi-serviceutils on which this service is based on.

It is recommended to use functions from this package in this service, too.

Documentation and useful additional resources:

Type Annotations

Also named type hints. Annotate types of function- / method-parameters and return values to increase readability and easier understanding of what a function requires and what it produces.

Also used in FastAPI based services, like this service, to generate the OpenAPI-documentation.

Documentation and useful additional resources:

YAML

YAML is a human friendly data serialization standard for all programming languages.

Mostly used for config-files. Alternative to JSON-file format.

The config.yml of this service is such a yaml-file. Inside the service (over fastapi-serviceutils) we use PyYAML to read the configuration-file (config.yml) of the service.

Documentation and useful additional resources: