Coding Style Guide¶
Follow PEP8 (the official style guide for Python). Most PEP8 formatting conventions are enforced in the build by
flake8, and a combination of
isort. Therefore, if you do not follow them, the build may not pass.
However, for Ion, we limit the lengths of lines to 150 characters, not 80 characters.
Note: CSS/JS/template formatting is enforced by
scripts/static_templates_format.sh. Currently, this just strips trailing whitespace.
Indent using 4 spaces.
Use underscores in favor of camel case for all names except the names of classes.
Limit the line length of docstrings or comments to 72 characters.
Separate top-level functions and class definitions with two blank lines.
Separate method definitions inside a class with a single blank line.
Use two spaces before inline comments and one space between the pound sign and comment.
Use a plugin for your text editor to check for/remind you of PEP8 conventions.
When in doubt, running
./scripts/format.shwill fix a lot of things.
Capitalize and punctuate comments and Git commit messages properly.
What is enforced in the build¶
At the time of this writing, the GitHub Actions build runs the following commands:
flake8 --max-line-length 150 --exclude=*/migrations/* . pylint --jobs=0 --disable=fixme,broad-except,global-statement,attribute-defined-outside-init intranet/ isort --check --recursive intranet ./scripts.format.sh ./scripts/static_templates_format.sh # Static/template files
Note: When the
./scripts/static_templates_format.sh checks are run, the build will fail if they have to make any changes.
flake8 is a PEP8 style checker,
pylint is a linter (but it also enforces some PEP8 conventions), and
isort, when called with these options, checks that all imports are sorted alphabetically.
black intranet && autopep8 --in-place --recursive intranet && isort --recursive intranet. The reason for the multiple commands is that
black introduces certain formatting changes which
pylint do not agree with (and offers no options to change them), so we have
autopep8 fix it.
It is recommended that you run all of these locally before opening a pull request (though the Ion developers sometimes skip running the
pylint check locally because it takes a long time to run). All of them are intended to be run from the root directory of the Git repository.
pylint throw errors, the error messages are usually human-readable. if
isort gives any errors, you can have it automatically correct the order of all imports by running
isort --recursive intranet. If the build fails because running
scripts/format.sh resulted in changes, you can simply run
./scripts/format.sh to fix your formatting.
- Group imports in the following order:
Standard library imports
Imports from Django
Within these groups, place
from ... import ...imports after
import ...imports, and order imports alphabetically within those groups.
from ... import *.
Explicitly import each module used.
Use relative imports to avoid hardcoding a module’s package name. This greatly improves portability and is useful when importing from another module in the current app.
Standard library imports:
from math import sqrt from os.path import abspath
Core Django imports:
from django.db import models
Third-party app imports:
from django_extensions.db.models import TimeStampedModel
from .models import SomeModel # explicit relative import from otherdjangoapp.models import OtherModel # absolute import
# intranet/apps/users/views.py from intranet.apps.users.models import MyModel # absolute import within same package