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)¶
- Poetry
- Make
- Abilian Devtools
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¶
- https://github.com/benfred/py-spy
- https://pypi.org/project/devtools/
- https://pypi.org/project/q/ (there are better, newer alternatives but I don’t remember them)
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:
- https://glyph.twistedmatrix.com/2016/08/attrs.html
- https://threeofwands.com/why-i-use-attrs-instead-of-pydantic/
Things to know about subclassing:
(TBC)
Other resources¶
Similar docs¶
- The Best of the Best Practices (BOBP) Guide for Python (partly obsolete).
- Our own Abilian Developer Guide (unfortunately currently partly obsolete too).
- Google’s Python Style Guide
- Python Project Setup
Great online Python docs / information sources¶
Great Python books¶
- Python Distilled
- Fluent Python (2nd ed.)
- Robust Python (focusses on typed Python)
#one-pager
#pytest #git #devtools #python
Page last modified: 2024-11-13 09:17:00