data.core.caching
=================

.. py:module:: data.core.caching


Classes
-------

.. autoapisummary::

   data.core.caching.Cache


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

.. py:class:: Cache

   Class controlling the cache.

   See :ref:`caching` for details.


   .. py:method:: check_size(*args, **kwargs)

      Check the cache size and trim it down when needed.

      Automatically runs when a new entry is added to the cache or the
      :ref:`cache_config` change. Does not work when the
      ``cache-policy`` is "off".

      The algorithm includes three steps:

      - first, the cache size is determined
      - next, if the size is larger than the limit defined by
        the ``maximum-cache-size`` config the oldest cache entries are
        removed until the desired size reached
      - finally, if the size is larger than the limit defined by the
        ``maximum-cache-disk-usage`` config the oldest cache entries are
        removed until the desired size reached




   .. py:method:: directory()

      Return the path to the current (cache) directory.

      :returns: The cache directory when ``cache-policy`` is "user" or "temporary".
                The temporary directory when ``cache-policy`` is "off".
      :rtype: :class:`str`



   .. py:method:: entries(*args, **kwargs)

      Dump the entries stored in the cache.

      Does not work when the ``cache-policy`` is "off".

      :returns: One dict per cache entry.
      :rtype: :class:`list` of :class:`dict`



   .. py:property:: policy

      Get the current cache policy.

      :type: CachePolicy


   .. py:method:: purge(*args, **kwargs)

      Delete entries from the cache.

      Does not work when the ``cache-policy`` is "off".

      :param \*\*kwargs: Other keyword arguments:

                         * matcher: callable
                             Method to match the cache entries to delete. Its only argument
                             is a cache entry and should return True if the entry is to be
                             deleted.
      :type \*\*kwargs: :class:`dict`, *optional*

      .. rubric:: Examples

      Delete all entries.

      >>> from earthkit.data import cache
      >>> cache.purge()

      Delete all entries where the "owner" is "test_cache".

      >>> from earthkit.data import cache
      >>> cache.purge(matcher=lambda e: ["owner"] == "test_cache")



   .. py:method:: size(*args, **kwargs)

      Return the total number of bytes stored in the cache.

      Does not work when the ``cache-policy`` is "off".



   .. py:method:: summary_dump_database(*args, **kwargs)

      Return the number of items and total size of the cache.

      Does not work when the ``cache-policy`` is "off".

      :returns: * **num** (:class:`int`) -- number of items in the cache
                * **size** (:class:`int`) -- total number of bytes stored in the cache

      .. rubric:: Examples

      >>> from earthkit.data import cache
      >>> cache.summary_dump_database()
      (40, 846785699)