Python guidelines

Welcome to the Python guidelines we use for network-health code. Below is a list of tools we use when working on network-health code and some additional tools that could help with Python code.

Conventions and tools we use

Style

Conventions:

• PEP 8 -- Style Guide for Python Code
• PEP 257 -- Docstring Conventions
• PEP 287 -- reStructuredText Docstring Format

Tools to use to automatically test style and/or fix it.

• editorconfig: helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. Example configuration
• Black: mostly follows PEP8, automatic formatter, smallest diffs possible. Use default configuration except for the maximum number of characters per line. Example configuration
• flake8: mostly follows PEP8, linter. Example configuration
• flake8-docstring: follows PEP257.
• isort: sort imports alphabetically and automatically separated into sections and by type.

Documentation

Tools:

• reStructuredText
• Sphinx: makes it easy to create intelligent and beautiful documentation.

Testing

• pytest: makes it easy to write small tests.
• tox: virtualenv-based automation of test activities. Example configuration, including testing style and coverage
• coverage: a tool for measuring code coverage of Python programs. Example configuration

Packaging

In general, develop with the latest versions of the dependencies. When packaging, ensure your application works with older stable dependencies.

• setuptools
• distributing packages

Why to use setuptools instead of requirements.txt:

• install your own package, not only the dependencies
• don't depend on specific "snapshot" versions
• facilitates the creation of system packages

See also: install requires vs requirements, setup vs requirements

Other conventions and tools

Style

• in Emacs:
  • elpy can run flake8 or black checks automatically (or manually)
  • flycheck can warn you, "on the fly", about style issues in Python

https://realpython.com/python-code-quality/

https://firefox-source-docs.mozilla.org/code-quality/index.html

Human language:

• codespell: Fix common misspellings in text files. It’s designed primarily for checking misspelled words in source code, but it can be used with other files as well.

Security:

• bandit: a security oriented static analyzer for python code
• safety: check installed dependencies for known vulnerabilities