Python Guidelines

These Python Guidelines (style guide) empower the community to focus on the intent of the code and work together with a minimum of friction.

Need of Guidelines

These Python Guidelines provides context to the developers who are new to the codebase and wishes to make any real-world contribution with org:creativecommons and be a part of the organization and learn new things with the organization.

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 Pipenv, the Python Development Workflow for Humans, and/or docker-compose, a tool for defining and running multi-container Docker applications.

Examples

Development Tools

Tool Order

The recommended order to execute the tools described below is:

  1. isort (will make changes)
  2. black (will make changes)
  3. flake8 (issues warnings)

Many of the Python repositories have a tools.sh helper script to execute them in order: GitHub Search · org:creativecommons filename:tools.sh.

Handling Imports (isort)

Overview

All the imports in the Python code must be done via isort, a Python utility/library to sort imports alphabetically, and automatically separated into sections and by type. It provides a command line utility, Python library and plugins for various editors to quickly sort all your imports. It requires Python 3.6+ to run but supports formatting Python 2 code too.

Configuration

There's a good isort config which one should follow while contributing in the Python projects of the creativecommons. These configurations should be a part of pyproject.toml labelled as [tools.isort]

Code Formatting (black)

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

Style and Quality (flake8)

Overview

All Python code must be checked using flake8, a python tool that glues together pycodestyle, 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

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: