Code Style¶

For code consistency, we have a pre-commit configuration file so that you can easily install pre-commit hooks to run style checks before you commit your files. You can setup our pre-commit hooks by running:

$ pip install -r requirements-dev.txt
$ pre-commit install

Or, just run:

$ make dev

Now, each time you commit, checks will be run using the packages explained below.

We use black as our Python code formatter with its default settings. Black helps minimize the line diffs and allows you to not worry about formatting during your own development. Just run black on each of your files before committing them.

Tip

Whatever editor you use, we recommend checking out black editor integrations to help make the code formatting process just a few keystrokes.

For sorting imports, we reply on isort. Our repository already includes a .isort.cfg that is compatible with black. You can run a code style check on your local machine by running our checks:

$ make check

Docstring format¶

We use Sphinx to build documentation. While Sphinx’s autodoc extension, which automatically generates documentation from docstring, supports several docstring formats, we use Sphinx docstring format. A typical Sphinx docstring looks like the following:

A typical Sphinx docstring¶

"""[Summary]

:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]
"""

where :type and :rtype can be omitted. Since we annotate functions with types (PEP 484), :type and :rtype in the docstring are redundant and hence not allowed in Fonduer. An example Fonduer docstring looks like:

An example Fonduer docstring¶

def greeting(name: str) -> str:
    """Return a greeting to a person.

    :param name: a person's name to greet.
    :return: a greeting string.
    """
    return 'Hello ' + name

Note that :type and :rtype are omitted and that the function is annotated with types.