fingerprint
===========

.. py:module:: fingerprint

.. autoapi-nested-parse::

   Fingerprints handling.

   Fingerprints objects provides a synthetic view of a set of elements.
   The purpose is to allow users to build fingerprints based on that
   set of elements, and then use fingerprint comparison as fast method
   for determining whether the same set of elements might have changed
   since the last time those elements were checked.

   One possible usage for fingerprints is determine whether something
   we built is still up to date, or should be rebuilt. For that,
   what we would do at the end of a successful build is we create
   a fingerprint using elements such as the sources we used to perform
   the build, the dependencies for our build, the version of the compiler,
   etc etc. Later on, when asking ourselves whether we need to re-build
   or not, we would compute a new fingerprint using the same elements,
   but updated to the current situation, and compare it with the one
   we previously computed. If different, we should rebuild.



Attributes
----------

.. autoapisummary::

   fingerprint.logger
   fingerprint.FINGERPRINT_VERSION


Classes
-------

.. autoapisummary::

   fingerprint.Fingerprint


Module Contents
---------------

.. py:data:: logger

.. py:data:: FINGERPRINT_VERSION
   :value: '1.2'


.. py:class:: Fingerprint

   Fingerprint class.

   :ivar elements: a dictionary containing the checksum/id for each element
       part of the fingerprint. The key a string identifying the
       element.


   .. py:attribute:: elements
      :type:  dict[str, str]


   .. py:method:: add(name: str, value: str) -> None

      Add a fingerprint element.

      :param name: name of the new element
      :param value: associated value (should be a string)
      :raise: E3Error



   .. py:method:: add_dir(path: str) -> None

      Add a file tree to the fingerprint.

      :param path: a path to a directory



   .. py:method:: add_file(filename: str) -> None

      Add a file element to the fingerprint.

      :param filename: a path

      Adding a filename element to a fingerprint is equivalent to do add
      an element for which key is the basename of the file and value is
      is the sha256 of the content



   .. py:method:: __eq__(other: object) -> bool

      Implement == operator for two fingerprints.

      :param other: object to compare with

      Two fingerprints are considered equals if both arguments are
      fingerprints and all elements of the fingerprint are equal



   .. py:method:: __ne__(other: object) -> bool

      Implement != operator for two fingerprints.

      See __eq__ functions.



   .. py:method:: compare_to(other: object) -> dict[str, set[str]] | None

      Compare two fingerprints and return the differences.

      :return: a dictionary that list the differences or None if the two
        Fingerprint are equals. The returned dictionary contains three
        items. 'updated' list the elements that are in both fingerprints but
        that are different, 'obsolete' list the elements that are only in
        self, and 'new' the elements that are only in other
      :raise AssertError: if other is not a Fingerprint



   .. py:method:: __str__() -> str

      Return a string representation of the fingerprint.



   .. py:method:: checksum() -> str

      Return the fingerprint's checksum.

      At the moment, the fingerprint uses the SHA256 hashing algorithm
      to compute the checksum.

      The function ensures that if two fingerprints are equal then
      the returned checksum for each of the fingerprint is equal.



   .. py:method:: save_to_file(filename: str) -> None

      Save the fingerprint to the given file.

      :param filename: The name of the file where to save the fingerprint.



   .. py:method:: load_from_file(filename: str) -> Fingerprint | None
      :classmethod:


      Return the fingerprint saved in the given file.

      Return None in the following situations:
          - The file does not contain a fingerprint we recognize;
          - The fingerprint has a version number we do not support.
          - If the fingerprint file does not exist

      :param filename: The name of the file where to load the fingerprint
          from.



