.. _coding-guide:

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 :file:`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()



.. _PEP8: https://peps.python.org/pep-0008/
.. _Ruff: https://docs.astral.sh/ruff/
.. _Pyflakes: https://github.com/PyCQA/pyflakes
.. _isort: https://pycqa.github.io/isort/
.. _pre-commit: https://pre-commit.com
.. _LGPL: https://www.gnu.org/licenses/lgpl.html
.. _Sphinx: https://www.sphinx-doc.org/
.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html