:py:mod:`calliope.cache`
========================

.. py:module:: calliope.cache


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

Classes
~~~~~~~

.. autoapisummary::

   calliope.cache.Cache
   calliope.cache.SqliteCache



Functions
~~~~~~~~~

.. autoapisummary::

   calliope.cache.save_cache_path
   calliope.cache.open



Attributes
~~~~~~~~~~

.. autoapisummary::

   calliope.cache.CacheLookupResult


.. py:function:: save_cache_path(*resource)

   Ensure ``$XDG_CACHE_HOME/<resource>/`` exists, and return its path.
   'resource' should normally be the name of your application or a shared
   resource.


.. py:data:: CacheLookupResult

   The result of looking for a value in a cache.

   Tuple with named values: ``(found_timestamp, value)``.

   If the value is found, ``found_timestamp`` will be set to the
   datetime of when it was stored. Otherwise, ``found_timestamp`` will be ``None``.

.. py:exception:: CacheError


   Bases: :py:obj:`Exception`

   Common base class for all non-exit exceptions.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:class:: Cache(namespace, cachedir=None)


   Abstract base class that defines the Cache interface.

   Do not use this class directly. Call the `open()` module method instead.


   .. py:method:: lookup(key)
      :abstractmethod:

      Lookup 'key' in the cache.

      Returns a :class:`CacheLookupResult` tuple.



   .. py:method:: store(key, value, timestamp=None)
      :abstractmethod:

      Store 'value' in the cache under the given key.

      The contents of 'value' must be representable as JSON data.

      The value will be marked with the current timestamp so cache expiry
      can be done. The ``timestamp`` parameter overrides this if needed.



   .. py:method:: wrap(key, call, expiry = None)

      Either run call() and save the result, or return cached result.

      This is intended for use when calling remote APIs. Lots of network access
      can be avoided if the result is saved for future use. For example, this
      snipped is used in the lastfm.similar_artists() function:

          def similar_artists(lastfm, artist_name):
              entry = lastfm.cache.wrap('artist-similar:{}'.format(artist_name),
                  lambda: lastfm.api.artist.get_similar(artist_name, limit=count))

      By default, items in the cache never expire. You can pass a
      `datetime.timedelta` instance to force entries to expire after a
      certain time period. This may be an hour, a day or a week depending
      how soon changes in the remote API result need to be detected.



   .. py:method:: sync()

      Ensure data is synchronised to disk.

      This may be a no-op. Or, it may block for an unknown amount time.



.. py:class:: SqliteCache(namespace, cachedir=None, retry_timeout=30)


   Bases: :py:obj:`Cache`

   Cache implemention which uses the SQLite database library.

   .. py:method:: lookup(key)

      Lookup 'key' in the cache.

      Returns a tuple of (found_timestamp, value). If the value is not
      found in the cache, both values will be None.



   .. py:method:: store(key, value, timestamp=None)

      Store 'value' in the cache under the given key.

      The contents of 'value' must be representable as JSON data.

      The value will be marked with the current timestamp so cache expiry
      can be done. The ``timestamp`` parameter overrides this if needed.



   .. py:method:: close()

      Close cache.

      This maybe needed to flush data to disk, depending on the implementation.




.. py:function:: open(namespace, cachedir=None)

   Open a cache using the best available cache implementation.

   The 'namespace' parameter should usually correspond with the name of tool
   or module using the cache.

   The 'cachedir' parameter is mainly for use during automated tests.