Merge pull request #1574 from tseaver/logging-logger_list_entries

Add 'Logger.list_entries'.

Author: tseaver

docs/logging-usage.rst

@@ -98,7 +98,7 @@ Sort entries in descending timestamp order.
    >>> client = logging.Client()
    >>> entries, token = client.list_entries(order_by=logging.DESCENDING)  # API call
 
-Retrieve entities in batches of 10, iterating until done.
+Retrieve entries in batches of 10, iterating until done.
 
 .. doctest::
 
@@ -112,6 +112,14 @@ Retrieve entities in batches of 10, iterating until done.
    ...     if token is None:
    ...         break
 
+Retrieve entries for a single logger, sorting in descending timestamp order:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> logger = client.logger('log_name')
+   >>> entries, token = logger.list_entries(order_by=logging.DESCENDING)  # API call
 
 Delete all entries for a logger
 -------------------------------

gcloud/logging/logger.py

@@ -128,3 +128,46 @@ def delete(self, client=None):
         client = self._require_client(client)
         client.connection.api_request(
             method='DELETE', path='/%s' % self.full_name)
+
+    def list_entries(self, projects=None, filter_=None, order_by=None,
+                     page_size=None, page_token=None):
+        """Return a page of log entries.
+
+        See:
+        https://cloud.google.com/logging/docs/api/ref_v2beta1/rest/v2beta1/entries/list
+
+        :type projects: list of strings
+        :param projects: project IDs to include. If not passed,
+                            defaults to the project bound to the client.
+
+        :type filter_: string
+        :param filter_: a filter expression. See:
+                        https://cloud.google.com/logging/docs/view/advanced_filters
+
+        :type order_by: string
+        :param order_by: One of :data:`gcloud.logging.ASCENDING` or
+                         :data:`gcloud.logging.DESCENDING`.
+
+        :type page_size: int
+        :param page_size: maximum number of topics to return, If not passed,
+                          defaults to a value set by the API.
+
+        :type page_token: string
+        :param page_token: opaque marker for the next "page" of topics. If not
+                           passed, the API will return the first page of
+                           topics.
+
+        :rtype: tuple, (list, str)
+        :returns: list of :class:`gcloud.logging.entry.TextEntry`, plus a
+                  "next page token" string:  if not None, indicates that
+                  more topics can be retrieved with another call (pass that
+                  value as ``page_token``).
+        """
+        log_filter = 'logName:%s' % (self.name,)
+        if filter_ is not None:
+            filter_ = '%s AND %s' % (filter_, log_filter)
+        else:
+            filter_ = log_filter
+        return self.client.list_entries(
+            projects=projects, filter_=filter_, order_by=order_by,
+            page_size=page_size, page_token=page_token)

gcloud/logging/test_logger.py

@@ -152,6 +152,48 @@ def test_delete_w_alternate_client(self):
         self.assertEqual(req['method'], 'DELETE')
         self.assertEqual(req['path'], '/%s' % PATH)
 
+    def test_list_entries_defaults(self):
+        LISTED = {
+            'projects': None,
+            'filter_': 'logName:%s' % (self.LOGGER_NAME),
+            'order_by': None,
+            'page_size': None,
+            'page_token': None,
+        }
+        TOKEN = 'TOKEN'
+        conn = _Connection()
+        client = _Client(self.PROJECT, conn)
+        client._token = TOKEN
+        logger = self._makeOne(self.LOGGER_NAME, client=client)
+        entries, token = logger.list_entries()
+        self.assertEqual(len(entries), 0)
+        self.assertEqual(token, TOKEN)
+        self.assertEqual(client._listed, LISTED)
+
+    def test_list_entries_explicit(self):
+        from gcloud.logging import DESCENDING
+        PROJECT1 = 'PROJECT1'
+        PROJECT2 = 'PROJECT2'
+        FILTER = 'resource.type:global'
+        TOKEN = 'TOKEN'
+        PAGE_SIZE = 42
+        LISTED = {
+            'projects': ['PROJECT1', 'PROJECT2'],
+            'filter_': '%s AND logName:%s' % (FILTER, self.LOGGER_NAME),
+            'order_by': DESCENDING,
+            'page_size': PAGE_SIZE,
+            'page_token': TOKEN,
+        }
+        conn = _Connection()
+        client = _Client(self.PROJECT, conn)
+        logger = self._makeOne(self.LOGGER_NAME, client=client)
+        entries, token = logger.list_entries(
+            projects=[PROJECT1, PROJECT2], filter_=FILTER, order_by=DESCENDING,
+            page_size=PAGE_SIZE, page_token=TOKEN)
+        self.assertEqual(len(entries), 0)
+        self.assertEqual(token, None)
+        self.assertEqual(client._listed, LISTED)
+
 
 class _Connection(object):
 
@@ -167,6 +209,13 @@ def api_request(self, **kw):
 
 class _Client(object):
 
+    _listed = _token = None
+    _entries = ()
+
     def __init__(self, project, connection=None):
         self.project = project
         self.connection = connection
+
+    def list_entries(self, **kw):
+        self._listed = kw
+        return self._entries, self._token