.. _python:

Python Guidelines
=================

.. _starting:

Getting Started
---------------

The modular architecture of PynPoint allows for easy implementation of new pipeline modules and we welcome contributions from users. Before writing a new PynPoint module, it is helpful to have a look at the :ref:`architecture` section. In addition, some basic knowledge on Python is required and some understanding on the following items can be helpful:

    * Python |types| such as lists, tuples, and dictionaries.
    * |classes|, in particular the concept of inheritance.
    * |abc| as interfaces.

.. |types| raw:: html

   <a href="https://docs.python.org/3/library/stdtypes.html" target="_blank">types</a>

.. |classes| raw:: html

   <a href="https://docs.python.org/3/tutorial/classes.html" target="_blank">Classes</a>

.. |abc| raw:: html

   <a href="https://docs.python.org/3/library/abc.html" target="_blank">Abstract classes</a>

.. _conventions:

Conventions
-----------

Before we start writing a new PynPoint module, please take notice of the following style conventions:

    * |pep8| -- style guide for Python code
    * We recommend using |pylint| and |pycodestyle| to analyze newly written code in order to keep PynPoint well structured, readable, and documented.
    * Names of class member should start with ``m_``.
    * Images should ideally not be read from and written to the central database at once but in amounts of ``MEMORY``.

.. |pep8| raw:: html

   <a href="https://www.python.org/dev/peps/pep-0008/" target="_blank">PEP 8</a>

.. |pylint| raw:: html

   <a href="https://www.pylint.org" target="_blank">pylint</a>

.. |pycodestyle| raw:: html

   <a href="https://pypi.org/project/pycodestyle/" target="_blank">pycodestyle</a>

Unit tests
----------

PynPoint is a robust pipeline package with 95% of the code covered by |unittest|. Testing of the package is done by running ``make test`` in the cloned repository. This requires the installation of:

   * |pytest|
   * |pytest-cov|

The unit tests ensure that the output from existing functionalities will not change whenever new code. With these things in mind, we are now ready to code!

.. |unittest| raw:: html

   <a href="https://docs.python.org/3/library/unittest.html" target="_blank">unit tests</a>

.. |pytest| raw:: html

   <a href="https://docs.pytest.org/en/latest/getting-started.html" target="_blank">pytest</a>

.. |pytest-cov| raw:: html

   <a href="https://pytest-cov.readthedocs.io/en/latest/readme.html" target="_blank">pytest-cov</a>
