Development
-----------

This repository uses multiple automatic tools in order to reach a high standard.
The tools used are:

#. ``ruff`` as a linter & formatter for the code.
#. ``mypy`` is used for type validation.

There is also pre-commit hook which uses executes ``ruff`` automatically before every commit.
In order to activate this hook one should execute the following command:

.. code-block:: bash

   pre-commit install

This tool installs into ``.git/hooks/`` the hook which activates ``ruff``.

There is an issue when it comes to using ``mypy`` as a pre-commit hook as well, for more details you can look at `this issue <https://github.com/python/mypy/issues/13916>`_.

In earlier stages of this project, we've used ``black``, ``isort`` & ``pylint``, however we've seen that ``ruff`` offers the same functionality (and more) but takes only a fraction of the execution time (real world, wall clock time).
Even though we've ditched ``isort`` & ``black`` in favor of ``ruff`` you can still use them since ``ruff`` maintains compatibility with those tools.
You could also still use ``pylint`` as it isn't checks the same rules as ``ruff`` and the project still maintains a high score of over 9.9 with ``pylint``.


Executation of Automatic Tools by Hand
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All the automatic tools can be also used manually as follows:

.. list-table::
   :widths: 1 1 1 1
   :header-rows: 1

   *  -  Automatic Tool Name
      -  Purpose of the Tool
      -  Commands
      -  Replaced by ``ruff``

   *  -  Ruff
      -  Formatted & Linter
      -  .. code-block:: bash

            ruff check --preview .
            ruff format .

      -

   *  -  mypy
      -  Types Validation
      -  .. code-block:: bash

            mypy .

      -  No

   *  -  Black
      -  Formatter
      -  .. code-block:: bash

            black .

      -  Yes

   *  -  isort
      -  Formatter of ``import`` statements
      -  .. code-block:: bash

            isort .

      -  Yes

   *  -  pylint
      -  Linter
      -  .. code-block:: bash

            pylint .

      -  Yes (Partially)


Using Pre-Commit Git Hooks
~~~~~~~~~~~~~~~~~~~~~~~~~~

We use ``pre-commit`` instead of some CI\CD like Github Action or Travis CI since We haven't configured any runners yet.
However enforcing the usage of those automatic tools is still very important and therefore we've settled for enforcing them through ``git`` hooks.
In order to allow those hooks you should execute the following command once (the installation of the hook).

.. list-table::
   :widths: 1 1
   :header-rows: 1

   *  -  Purpose
      -  Command

   *  -  Install the hook (needs to be executed only once)
      -  .. code-block:: bash

            pre-commit install

   *  -  Uninstall the hook
      -  .. code-block:: bash

            pre-commit uninstall

   *  -  Run all checks on the entire repository
      -  .. code-block:: bash

            pre-commit run --all-files


.. note::

        By default ``pre-commit`` tries to optimize the actual time it takes to run the checks by running them **ONLY** on the editted files rather than on the entire repository.