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


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.


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 helper script to execute them in order: GitHub Search · org:creativecommons

Handling Imports (isort)


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.


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)


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.


Style and Quality (flake8)


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).


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: