Coding style

If you follow the instructions to set up your development environment, the AiiDA coding style is largely enforced automatically using pre-commit hooks.

This document mainly acts as a reference.

AiiDA Coding Style

• Code should conform to the PEP8 guidelines (https://www.python.org/dev/peps/pep-0008/).
• When compatible, adhere to the Google Python Styleguide
• Concerning documentation, see Writing documentation
• Concerning tests, see Writing tests

AiiDA-specific conventions

• Opening files:
  • When opening a general file for reading or writing, use open, and specify UTF-8 encoding for formatted files (e.g. open(path, 'w', encoding='utf8')).
  • When opening a file from the AiiDA repository, use aiida.common.folders.Folder.open().

Source file headers

Each source file should start with a common header (will be added automatically by helper scripts that are run just before a new release):

1. Optional she-bang line e.g. #!/usr/bin/env python
2. Coding declaration conforming to PEP 263: e.g. # -*- coding: utf-8 -*-
3. A copyright header defined below
4. Linter directives e.g. # pylint: disable=too-many-arguments
5. Module docstrings

The copyright header is currently defined to be:

###########################################################################
# Copyright (c), The AiiDA team. All rights reserved.                     #
# This file is part of the AiiDA code.                                    #
#                                                                         #
# The code is hosted on GitHub at https://github.com/aiidateam/aiida_core #
# For further information on the license, see the LICENSE.txt file        #
# For further information please visit http://www.aiida.net               #
###########################################################################

Python style

Below are some Python features that we use in aiida-core.

F-strings

Yet another way to format strings in Python, but the one string-formatting-method to rule them all. So far you may have been formatting your strings as follows:

value = 'test'
'Variable {}'.format(value)
'Variable %s' % value

As of Python 3.6, you can use f-strings that does the conversion implicitly as follow

value = 'test'
f'Variable {test}'

You can even put expressions in there that will be automatically evaluated:

a = 1
b = 2
f'{a} + {b} = {a + b}'  # '1 + 2 = 3'

This new method of formatting is not just easier to read, it also saves characters and is more efficient. One exception when it is ok to still use the old .format method is if you have a string with many placeholders. In that case it is easier to define a dictionary with the replacement values and use .format(**dictionary).

Pathlib

File system manipulation is typically done using the os built in module. As of Python 3.6 the built in module pathlib is supported by all other built in modules, and provides an interface that is a lot more intuitive. We should now strive to use only pathlib when manipulating files and folders. Refer to the official documentation, to get a handy translation table between os and pathlib.

Type hinting

Technically, this new syntax feature was already introduced in Python 3.5, but with Python 3.6 it also adds support to type hint variables. From its inception, Python has been mostly used and seen as a dynamically typed language where you don't explicitly declare the type of variables or arguments in function signatures. This has advantages as it allows for fast development and prototyping, but can become a disadvantage as the complexity of a project grows. This is why Python has added type hinting where you can optionally declare the type of variables and arguments. This allows static type checkers to validate the code and IDE's to provide improved auto-completion. It also makes the code easier to read for humans. We have now started to use type hinting in aiida-core and suggest you do the same for any code you add, and adapt existing code where you can. The pre-commit already includes the tool mypy which makes sure that the type hinting is valid and consistent. If you add a file with type hinting, please add it to the include list in the .pre-commit-config.yaml file in the repository.