:mod:`memote.utils`
===================

.. py:module:: memote.utils

.. autoapi-nested-parse::

   Utility functions used by memote and its tests.

   ..
       !! processed by numpydoc !!



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


Functions
~~~~~~~~~

.. autoapisummary::

   memote.utils.register_with
   memote.utils.annotate
   memote.utils.get_ids
   memote.utils.get_ids_and_bounds
   memote.utils.truncate
   memote.utils.log_json_incompatible_types
   memote.utils.show_versions
   memote.utils.jsonify
   memote.utils.is_modified
   memote.utils.stdout_notifications


.. data:: wrapper
   

   

.. function:: register_with(registry)

   Register a passed in object.

   Intended to be used as a decorator on model building functions with a
   ``dict`` as a registry.












   .. rubric:: Examples

   .. code-block:: python

       REGISTRY = dict()
       @register_with(REGISTRY)
       def build_empty(base):
           return base



   ..
       !! processed by numpydoc !!


.. function:: annotate(title, format_type, message=None, data=None, metric=1.0)

   Annotate a test case with info that should be displayed in the reports.


   :Parameters:

       **title** : str
           A human-readable descriptive title of the test case.

       **format_type** : str
           A string that determines how the result data is formatted in the
           report. It is expected not to be None.
           
           * 'number' : 'data' is a single number which can be an integer or
             float and should be represented as such.
           * 'count' : 'data' is a list, set or tuple. Choosing 'count' will
             display the length of that list e.g. number of metabolites without
             formula.
           * 'percent' : Instead of 'data' the content of 'metric' ought to be
             displayed e.g. percentage of metabolites without charge.
             'metric' is expected to be a floating point number.
           * 'raw' : 'data' is ought to be displayed "as is" without formatting.
             This option is appropriate for single strings or a boolean output.

       **message** : str
           A short written explanation that states and possibly explains the test
           result.

       **data**
           Raw data which the test case generates and assesses. Can be of the
           following types: list, set, tuple, string, float, integer, and boolean.

       **metric: float**
           A value x in the range of 0 <= x <= 1 which represents the fraction of
           'data' to the total in the model. For example, if 'data' are all
           metabolites without formula, 'metric' should be the fraction of
           metabolites without formula from the total of metabolites in the model.

   :Returns:

       function
           The decorated function, now extended by the attribute 'annotation'.








   .. rubric:: Notes

   Adds "annotation" attribute to the function object, which stores values for
   predefined keys as a dictionary.





   ..
       !! processed by numpydoc !!


.. function:: get_ids(iterable)

   Retrieve the identifier of a number of objects.
















   ..
       !! processed by numpydoc !!


.. function:: get_ids_and_bounds(iterable)

   Retrieve the identifier and bounds of a number of objects.
















   ..
       !! processed by numpydoc !!


.. function:: truncate(sequence)

   Create a potentially shortened text display of a list.


   :Parameters:

       **sequence** : list
           An indexable sequence of elements.

   :Returns:

       str
           The list as a formatted string.













   ..
       !! processed by numpydoc !!


.. function:: log_json_incompatible_types(obj)

   Log types that are not JSON compatible.

   Explore a nested dictionary structure and log types that are not JSON
   compatible.

   :Parameters:

       **obj** : dict
           A potentially nested dictionary.














   ..
       !! processed by numpydoc !!


.. function:: show_versions()

   Print formatted dependency information to stdout.
















   ..
       !! processed by numpydoc !!


.. function:: jsonify(obj, pretty=False)

   Turn a nested object into a (compressed) JSON string.


   :Parameters:

       **obj** : dict
           Any kind of dictionary structure.

       **pretty** : bool, optional
           Whether to format the resulting JSON in a more legible way (
           default False).














   ..
       !! processed by numpydoc !!


.. function:: is_modified(path, commit)

   Test whether a given file was present and modified in a specific commit.


   :Parameters:

       **path** : str
           The path of a file to be checked.

       **commit** : git.Commit
           A git commit object.

   :Returns:

       bool
           Whether or not the given path is among the modified files
           and was not deleted in this commit.













   ..
       !! processed by numpydoc !!


.. function:: stdout_notifications(notifications)

   Print each entry of errors and warnings to stdout.


   :Parameters:

       **notifications: dict**
           A simple dictionary structure containing a list of errors and warnings.














   ..
       !! processed by numpydoc !!