Fetching Resources
==================

Resources may be fetched individually or as feeds.

.. contents::


Retrieving a list of resources
------------------------------

To retrieve a list of feeds, use the :py:meth:`gdata.docs.client.GetResources`
method, for example::

    resource_feed = client.GetResources()

The return value is an instance of :py:class:`gdata.docs.data.ResourceFeed`,
and individual entries can be accessed in the `entry` attribute.

Mostly, all resources will not be available in a single request, and for this
purpose, the next page of results should be fetched. The URI for the next page
is available as the :py:meth:`gdata.docs.data.ResourceFeed.GetNextLink` method, and can
be used as::

    resource_feed = client.GetResources()
    nextpage_feed = client.GetResources(uri=resource_feed.GetNextLink().href)


Retrieving all resources
------------------------

Paging through the entire set of resources is handled using the convenience
method :py:meth:`gdata.docs.client.GetAllResources` method.::

    all_entries = client.GetAllResources()

This returns a list of entries (not a feed) and takes care of paging the
individual feeds and collecting the results.


Retrieving an individual entry
------------------------------

An entry can be retrieved again if you have an
:py:class:`gdata.docs.data.Resource` instance, or by fetching it from its
resource id.

To refetch a resource, use :py:meth:`gdata.docs.client.GetResource` method,
like so::

    # First fetch the entry as the first entry in a feed
    entry = client.GetResources().entry[0]

    # Refetch the entry sometime later
    refetched_entry = client.GetResource(entry)


Retrieving an entry from its resource id
----------------------------------------

If a resource id is known, this can be used to fetch an entry, using the
py:meth:`gdata.docs.client.GetResourceById` method, line so::

    resource_id = 'AB56C6D8E9AB56C6D8E9AB56C6D8E9AB56C6D8E9'
    entry = client.GetResourceById(resource_id)