Python Guidelines

Code Formatting

Overview

All Python code must be formatted using Black, the uncompromising Python code formatter. Each project should contain a pyproject.toml configuration file that limits line length to 79 characters.

Examples

• Black configuration (pyproject.toml): GitHub Search · org:creativecommons filename:pyproject.toml
• GitHub Actions workflow: GitHub Search · org:creativecommons "pipenv run black"

Style and Quality

Overview

All Python code must be checked using flake8, a python tool that glues together pep8, pyflakes, mccabe, and third-party plugins to check the style and quality of some python code.

Conflicts with Black

Where flake8 conflicts with Black, the flake8 check should be skipped. For example, there are instances where black formats code that generates flake8 warning for Whitespace before ':' (E203).

Examples

• flake8 configuration (.flake8): GitHub Search · org:creativecommons filename:.flake8
• flake8 skip E203 warning: GitHub Search · org:creativecommons "noqa: E203"
• GitHub Actions workflow: GitHub Search · org:creativecommons "pipenv run flake8"

Development Environment

Overview

Please work to minimize the number of development related technologies. This helps minimize the overhead of contributing to multiple projects. Most of our projects use either Pipenv, the Python Development Workflow for Humans, or docker-compose, a tool for defining and running multi-container Docker applications.

Examples

• Pipenv configuration: GitHub Search · org:creativecommons filename:Pipfile
• Docker-compose example: docker-compose.yml for cccatalog and the related README.md

Additional Guidance

Thankfully, Black removes a lot of style work and worry. Where there is room for developer discretion, the following guides are excellent resources:

• Google Python Style Guide
• Code Style — The Hitchhiker's Guide to Python