Code style#

The code making up orix is formatted closely following the Style Guide for Python Code with The Black Code style and isort to handle module imports. We use pre-commit to run black and isort automatically prior to each local commit. Please install it in your environment:

pre-commit install

Next time you commit some code, your code will be formatted inplace according to the default black configuration.

Note that black won’t format docstrings. We follow the numpydoc standard (with some exceptions), and docstrings are checked against this standard when the documentation is built.

Package imports should be structured into three blocks with blank lines between them (descending order): standard library (like os and typing), third party packages (like numpy and matplotlib) and finally first party orix imports. isort will structure the import order in this way by default. Note that if imports must be sorted in a certain order, for example to avoid recursion, then isort provides commands that may be used to prevent sorting.

Comment and docstring lines should preferably be limited to 72 characters (including leading whitespaces).

We use type hints in the function definition without type duplication in the function docstring, for example:

def my_function(arg1: int, arg2: Optional[bool] = None) -> Tuple[float, np.ndarray]:
    """This is a new function.

        Explanation about argument 1.
        Explanation about flag argument 2. Default is None.

        Explanation about returned values.

When working with classes in orix, often a method argument will require another instance of the class. An example of this is, where the first argument to this function other is another instance of Vector3d. In this case, to allow for the correct type hinting behaviour, the following import is required at the top of the file:

from __future__ import annotations

Type hints for various built-in classes are available from the typing module. np.ndarray should be used for arrays.

Mathematical notation#

See Mathematical notation.