Coding standards

django-ca uses linting and type hints to ensure consistent and readable code. It uses ruff and pylint for linting and mypy for type checking. YAML, JSON and TOML files are checked using pre-commit. Sphinx documentation is checked using doc8 and spell-checked using sphinxcontrib.spelling.

If you have tox installed, you can perform all checks by running it with these environments:

$ tox -e lint,pylint,mypy,docs

Overrides

ruff, pylint and mypy support overriding warnings. Follow these general rules:

• Use overrides as rarely as possible.

• Exclude specific errors (so e.g. use # NOQA: E501 instead of # NOQA).

• Add a comment explaining the exclude. If possible, comment in the same line:

  import unused  # NOQA: F401  # Import this for some important reason
  

  If your comment does not fit in the same line, add a comment above prefixed with $SW NOTE::

  # PYLINT NOTE: A really long explanation why we have the bar argument that is not used.
  # TYPE NOTE: We don't type this, since it's only a demo.
  def func(foo, bar):  # type: ignore # pylint: disable=unused-argument
      """Comment to make pylint happy."""
      print(foo)
  

Type hints imports

The code generally imports the typing module as a whole, with the most common types imported directly to increase readability. The following types should be imported directly: Any, Dict, Iterable, Iterator, List, Optional, Tuple and Type, Union.

Thus:

import typing  # for most (but rarer) types
from typing import List, Optional, Any

Manually run linters

To run all linters, simply run (pylint runs separate as it is very slow):

$ ./dev.py code-quality
$ pylint ca/ca/ ca/django_ca/ devscripts/ docs/source/django_ca_sphinx/ *.py

For type-checking, run:

$ mypy .

To check the documentation, run:

$ doc8 docs/source/
$ make -C docs clean spelling html