*******
Caching
*******

lazr.restfulclient automatically decompresses the documents it
receives, and caches the responses in a temporary directory.

    >>> import httplib2
    >>> httplib2.debuglevel = 1

    >>> from lazr.restfulclient.tests.example import CookbookWebServiceClient
    >>> service_with_cache = CookbookWebServiceClient()
    send: 'GET /1.0/ ...
    reply: ...200...
    ...
    header: Transfer-Encoding: deflate
    ...
    header: Content-Type: application/vd.sun.wadl+xml
    send: 'GET /1.0/ ...
    reply: ...200...
    ...
    header: Transfer-Encoding: deflate
    ...
    header: Content-Type: application/json

    >>> print service_with_cache.recipes[4].instructions
    send: 'GET /1.0/recipes/4 ...
    reply: ...200...
    ...
    Preheat oven to...

The second and subsequent times you request some object, it's likely
that lazr.restfulclient will make a conditional HTTP GET request instead of
a normal request. The HTTP response code will be 304 instead of 200,
and lazr.restfulclient will use the cached representation of the object.

    >>> print service_with_cache.recipes[4].instructions
    send: 'GET /1.0/recipes/4 ...
    reply: ...304...
    ...
    Preheat oven to...

This is true even if you initially got the object as part of a
collection.

    >>> recipes = service_with_cache.recipes[:10]
    send: ...
    reply: ...200...

    >>> first_recipe = recipes[0]
    >>> first_recipe.lp_refresh()
    send: ...
    reply: ...304...

Note that if you get an object as part of a collection and then get it
some other way, a conditional GET request will *not* be made. This is
a shortcoming of the library.

    >>> service_with_cache.recipes[first_recipe.id]
    send: ...
    reply: ...200...

The default lazr.restfulclient cache directory is a temporary directory
that's deleted when the Python process ends. (If the process is
killed, the directory will stick around in /tmp.) It's much more
efficient to keep a cache directory across multiple uses of
lazr.restfulclient.

You can provide a cache directory name as argument when creating a
Service object. This directory will fill up with cached HTTP
responses, and since it's a directory you control it will persist
across lazr.restfulclient sessions.

    >>> import tempfile
    >>> tempdir = tempfile.mkdtemp()

    >>> first_service = CookbookWebServiceClient(cache=tempdir)
    send: 'GET /1.0/ ...
    reply: ...200...
    ...
    send: 'GET /1.0/ ...
    reply: ...200...
    ...

    >>> print first_service.recipes[4].instructions
    send: 'GET /1.0/recipes/4 ...
    reply: ...200...
    ...
    Preheat oven to...

This will save you a *lot* of time in subsequent sessions, because
you'll be able to use cached versions of the initial (very expensive)
documents.

    >>> second_service = CookbookWebServiceClient(cache=tempdir)
    send: 'GET /1.0/ ...
    reply: ...304...
    ...
    send: 'GET /1.0/ ...
    reply: ...304...
    ...

    >>> print second_service.recipes[4].instructions
    send: 'GET /1.0/recipes/4 ...
    reply: ...304...
    ...
    Preheat oven to...

Of course, if you ever need to clear the cache directory, you'll have
to do it yourself.

    >>> httplib2.debuglevel = 0
    >>> import shutil
    >>> shutil.rmtree(tempdir)
