Class CacheFetcher

Known Subclasses:

DiscoCacheFetcherBase

Base class for cache object fetchers -- classes responsible for
retrieving objects from network.

An instance of a fetcher class is created for each object requested and
not found in the cache, then `fetch` method is called to initialize
the asynchronous retrieval process. Fetcher object's `got_it` method
should be called on a successfull retrieval and `error` otherwise.
`timeout` will be called when the request timeouts.

:Ivariables:
    - `cache`: cache object which created this fetcher.
    - `address`: requested item address.
    - `timeout_time`: timeout time.
    - `active`: `True` as long as the fetcher is active and requestor
      expects one of the handlers to be called.
:Types:
    - `cache`: `Cache`
    - `address`: any hashable
    - `timeout_time`: `datetime`
    - `active`: `bool`

Initialize an `CacheFetcher` object.

:Parameters:
    - `cache`: cache object which created this fetcher.
    - `address`: requested item address.
    - `item_freshness_period`: freshness period for the requested item.
    - `item_expiration_period`: expiration period for the requested item.
    - `item_purge_period`: purge period for the requested item.
    - `object_handler`: function to be called after the item is fetched.
    - `error_handler`: function to be called on error.
    - `timeout_handler`: function to be called on timeout
    - `timeout_period`: timeout interval.
    - `backup_state`: when not `None` and the fetch fails than an
      object from cache of at least this state will be passed to the
      `object_handler`. If such object is not available, then
      `error_handler` is called.
:Types:
    - `cache`: `Cache`
    - `address`: any hashable
    - `item_freshness_period`: `timedelta`
    - `item_expiration_period`: `timedelta`
    - `item_purge_period`: `timedelta`
    - `object_handler`: callable(address, value, state)
    - `error_handler`: callable(address, error_data)
    - `timeout_handler`: callable(address)
    - `timeout_period`: `timedelta`
    - `backup_state`: `bool`

Handle a retrieval error and call apriopriate handler.

Should be called when retrieval fails.

Do nothing when the fetcher is not active any more (after
one of handlers was already called).

:Parameters:
    - `error_data`: additional information about the error (e.g. `StanzaError` instance).
:Types:
    - `error_data`: fetcher dependant

Start the retrieval process.

This method must be implemented in any fetcher class.

Handle a successfull retrieval and call apriopriate handler.

Should be called when retrieval succeeds.

Do nothing when the fetcher is not active any more (after
one of handlers was already called).

:Parameters:
    - `value`: fetched object.
    - `state`: initial state of the object.
:Types:
    - `value`: any
    - `state`: `str`

Handle fetcher timeout and call apriopriate handler.

Is called by the cache object and should _not_ be called by fetcher or
application.

Do nothing when the fetcher is not active any more (after
one of handlers was already called).