Taurus coding guide

  • Code in Taurus should follow the standard Python style conventions described in PEP8. Formatting and linting are performed with Ruff and enforced by the continuous integration tests.

    The Ruff formatter uses a target line length of 88 characters by default. This is a formatting target rather than a strict maximum: Ruff may leave some lines longer when they cannot be split automatically.

    The linting rules enabled by the project are defined in the Ruff configuration. Currently, they include selected pycodestyle errors (E4, E7 and E9), Pyflakes (F) and isort (I) rules.

    In particular:

    • Use 4 spaces for indentation.

    • Follow the formatting produced by ruff format, including its default target line length of 88 characters.

    • Surround top-level function and class definitions with two blank lines.

    • Use lower_case for module names. If possible, prefix module names with the word taurus (like taurusutil.py) to avoid import mistakes.

    • Use CamelCase for class names.

    • Use lower_case for method names, except in the context of taurus.qt, where the prevailing convention is mixedCase due to the influence of PyQt.

    • Keep imports sorted according to Ruff’s isort rules.

  • Code must be compatible with the Python versions supported by Taurus.

  • Every Python module file should contain license information (see template below). The preferred license is the LGPL. If you need or want to use a different one, it should be compatible with LGPL v3+.

  • Avoid polluting the namespace by marking internal definitions with a leading underscore (_) and/or explicitly defining the public API with __all__ (see template below).

  • Whenever a Python module can be executed from the command line, it should contain a main function and call it from an if __name__ == "__main__" statement (see template below).

  • All public API code (modules, classes, methods and functions) should be documented using Sphinx-compatible reStructuredText docstrings.

Tip

Taurus ships a pre-commit configuration containing the formatting and linting checks used by the project. Run:

pre-commit run --all-files

to run the checks locally on the whole repository.

You can also install the hooks with:

pre-commit install

so that the configured checks are run automatically before each commit.

The following code can serve as a template for writing new python modules to taurus:

#!/usr/bin/env python

#############################################################################
##
# This file is part of Taurus
##
# https://taurus-scada.org
##
# Copyright 2011 CELLS / ALBA Synchrotron, Bellaterra, Spain
##
# Taurus is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
##
# Taurus is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
##
# You should have received a copy of the GNU Lesser General Public License
# along with Taurus.  If not, see <https://www.gnu.org/licenses/>.
##
#############################################################################

"""A :mod:`taurus` module written for template purposes only"""

__all__ = ["TaurusDemo"]

__docformat__ = "restructuredtext"

class TaurusDemo(object):
    """This class is written for template purposes only"""

def main():
    print("TaurusDemo")

if __name__ == "__main__":
    main()