Skip to content

Python One Pager

About this doc

This is a shorter, and hopefully more up to date, version of the Abilian Developer Guide (unfortunately currently partly obsolete).

Project organisation

Tooling

The tools below are the standard tools we’re using to keep project quality and developer efficiency high at Abilian.

Source control

  • Git + GitHub
  • Branching model: use short-lived feature branches.

Project management (including dependencies)

Code formatting

  • Black (format Python code - use default options)
  • Isort (sort imports - use the “black” profile)
  • DocFormatter (format docstrings)
  • Pyupgrade / flynt (upgrade to take advantage of newer Python features)

Linting / static analysis

  • Ruff
  • Mypy
  • Flake8 + additional plugins (Bandit…)
  • pre-commit

TDD

  • Pytest
  • Nox (or Tox, for older projects)
  • Coverage.py
  • Hypothesis

We don’t recommend using the unittest package from the standard library, as its class-based design can lead to hard to understand test hierarchies.

More: Testing

CI

  • GitHub Workflow
  • Sourcehut CI

Note: the main CI script, for Python projects, is always the Nox or Tox file (noxfile.py / tox.ini). The GitHub Workflow config leverages it using proper plugins.

Debugging / profiling

Deployment

  • We used to use Fabric but we’re now switching to PaaS deployment (using the 12 factor principles). This is a WIP.

Documentation

Documentation starts with a good README (see: https://tom.preston-werner.com/2010/08/23/readme-driven-development.html).

Additionally, we use Sphinx but MkDocs can also be used. Portray could be useful.

Project templates

Use cookiecutter templates to set up new projects.

Even better, use Cruft because it can update boilerplate after the initial project inception. (Narative here)

We have a project template here: https://github.com/abilian/cookiecutter-abilian-python (it needs to be updated regularly to keep up with best practices).

General principles

Use Attrs and favor immutability when possible:

Things to know about subclassing:

(TBC)

Other resources

Similar docs

Great online Python docs / information sources

Great Python books

#one-pager

Page last modified: 2023-11-07 07:03:54