Python specific recommendations¶
Style guide & tools¶
We’re mostly following PEP8 and the Google Python Style Guide.
We’ve been using automated code checkers (mostly Flake8 nowadays) with appropriate settings to ensure that deviations from the coding standard, as well as some non-stylistic issues, are detected.
Furthermore, we’re using YAPF with the
We’re also using isort to sort imports according to semantic and cosmetic rules.
We plan to use Git commit hooks to ensure that every new commit in the future fully respects these standards.
Python 2 vs. Python 3¶
We’re currently still using Python 2 in our production code.
From 2017 on, we plan to start new projects using only Python 3, unless there are strong technical reasons not to do so.
We’ve started work to support Python 3 (alongside Python 2) on our open source projects, using the “six” library. We plan to finish it in 2017.
pylint --py3k is quite useful to help identify issues in current Python 2
code preventing migration to Python 3.
- <http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/> (NB: we don’t follow Armin’s advice of not using six).
General Python recommandations¶
TODO: add more.
In this section, we list tools that directly support our Python development process.
- YAPF (see above)
- Flake8 (see above)
- isort (see above)
- Mypy (static checking using annotations)
Not used yet:
- Pylint (static checker, more powerful than Flake8 but needs more tuning). Currently used only to check for py3k compatibility (see above).
We manage dependencies for our projects and build them using pip.
Mandatory read: <https://caremad.io/2013/07/setup-vs-requirement/>.
Use pip-tools (<https://github.com/nvie/pip-tools>).
Virtualenv is a tool to create isolated Python environments. Why is this good? You can create a new Python environment to run a Python/Flask/whatever app and install all package dependencies into the virtualenv without affecting your system’s site-packages. Need to upgrade a package to see how it affects your app? Create a new virtualenv, install/copy your app into it, run your tests, and delete it when you are done. Just like git makes branching inexpensive and easy, virtualenv makes creating and managing new Python environments inexpensive and easy.
The doc: <https://virtualenv.pypa.io/en/stable/>.
Note: as of early 2017, this is not true anymore.
We have set up an internal PyPI mirror, using the devpi project.
Its main use is for our CI server (Jenkins).
Of course, our public open source projects should be buildable without depending on it.
We package our Python projects using the standard tools (distutils, setuptools, pip).
The packaging allows us to distribute our modules for all developers who would like to use them.
The packages are hosted on Pypi mirror and can be installed with pip or easyinstall.
Standard structure for a Python project¶
A Python project MUST have the following files:
README.rst: we prefer
.mdbecause that’s the markup language to use if you want your project to look good on PyPI.
Makefile: cf. supra.
It SHOULD also have the following files:
setup.cfg: used to contain config for additional files (ex: Babel, pep8, pyflakes, Sphinx…)
etc/: containing additional configuration files for tools that don’t support
It MAY also contain:
deploy/: for scripts related to deployment (bash, Ansible…)