def list_topics(self, project, page_size=0, page_token=None):
"""List topics for the project associated with this API.
See:
https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/list
:type project: str
:param project: project ID
: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: str
:param page_token: opaque marker for the next "page" of topics. If not
passed, the API will return the first page of
topics.
:rtype: :class:`~google.cloud.iterator.Iterator`
:returns: Iterator of :class:`~google.cloud.pubsub.topic.Topic`
accessible to the current API.
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
path = 'projects/%s' % (project,)
page_iter = self._gax_api.list_topics(
path, page_size=page_size, options=options)
page_iter = functools.partial(_recast_page_iterator, page_iter)
return Iterator(client=self._client, path=path,
item_to_value=_item_to_topic,
page_iter=page_iter)
def list_sinks(self, project, page_size=0, page_token=None):
"""List sinks for the project associated with this client.
:type project: str
:param project: ID of the project whose sinks are to be listed.
:type page_size: int
:param page_size: maximum number of sinks to return, If not passed,
defaults to a value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of sinks. If not
passed, the API will return the first page of
sinks.
:rtype: tuple, (list, str)
:returns: list of mappings, plus a "next page token" string:
if not None, indicates that more sinks can be retrieved
with another call (pass that value as ``page_token``).
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
path = 'projects/%s' % (project, )
page_iter = self._gax_api.list_sinks(path,
page_size=page_size,
options=options)
return GAXIterator(self._client, page_iter, _item_to_sink)
def test_call_kwargs(self):
settings = _CallSettings(kwargs={'key': 'value'})
my_callable = api_callable.create_api_call(
lambda _req, _timeout, **kwargs: kwargs['key'], settings)
self.assertEqual(my_callable(None), 'value')
self.assertEqual(my_callable(None, CallOptions(key='updated')),
'updated')
def list_metrics(self, project, page_size=0, page_token=None):
"""List metrics for the project associated with this client.
:type project: str
:param project: ID of the project whose metrics are to be listed.
:type page_size: int
:param page_size: maximum number of metrics to return, If not passed,
defaults to a value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of metrics. If not
passed, the API will return the first page of
metrics.
:rtype: tuple, (list, str)
:returns: list of mappings, plus a "next page token" string:
if not None, indicates that more metrics can be retrieved
with another call (pass that value as ``page_token``).
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
path = 'projects/%s' % (project,)
page_iter = self._gax_api.list_log_metrics(
path, page_size=page_size, options=options)
metrics = [MessageToDict(log_metric_pb)
for log_metric_pb in page_iter.next()]
token = page_iter.page_token or None
return metrics, token
def list_metrics(self, project, page_size=0, page_token=None):
"""List metrics for the project associated with this client.
:type project: str
:param project: ID of the project whose metrics are to be listed.
:type page_size: int
:param page_size: maximum number of metrics to return, If not passed,
defaults to a value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of metrics. If not
passed, the API will return the first page of
metrics.
:rtype: :class:`~google.cloud.iterator.Iterator`
:returns: Iterator of
:class:`~google.cloud.logging.metric.Metric`
accessible to the current API.
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
path = 'projects/%s' % (project, )
page_iter = self._gax_api.list_log_metrics(path,
page_size=page_size,
options=options)
return GAXIterator(self._client, page_iter, _item_to_metric)
def test_settings_merge_options1(self):
options = CallOptions(timeout=46)
settings = CallSettings(timeout=9, page_descriptor=None, retry=None)
final = settings.merge(options)
self.assertEqual(final.timeout, 46)
self.assertIsNone(final.retry)
self.assertIsNone(final.page_descriptor)
def list_subscriptions(self, project, page_size=0, page_token=None):
"""List subscriptions for the project associated with this API.
See:
https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/list
:type project: str
:param project: project ID
:type page_size: int
:param page_size: maximum number of subscriptions to return, If not
passed, defaults to a value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of subscriptions.
If not passed, the API will return the first page
of subscriptions.
:rtype: tuple, (list, str)
:returns: list of ``Subscription`` resource dicts, 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``).
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
path = 'projects/%s' % (project,)
page_iter = self._gax_api.list_subscriptions(
path, page_size=page_size, options=options)
subscriptions = [_subscription_pb_to_mapping(sub_pb)
for sub_pb in page_iter.next()]
token = page_iter.page_token or None
return subscriptions, token
def topic_list_subscriptions(self, topic_path):
"""API call: list subscriptions bound to a topic
See:
https://cloud.google.com/pubsub/reference/rest/v1/projects.topics.subscriptions/list
:type topic_path: string
:param topic_path: fully-qualified path of the topic, in format
``projects/<PROJECT>/topics/<TOPIC_NAME>``.
:rtype: list of strings
:returns: fully-qualified names of subscriptions for the supplied
topic.
:raises: :exc:`gcloud.exceptions.NotFound` if the topic does not
exist
"""
options = CallOptions(is_page_streaming=False)
try:
response = self._gax_api.list_topic_subscriptions(
topic_path, options)
except GaxError as exc:
if exc_to_code(exc.cause) == StatusCode.NOT_FOUND:
raise NotFound(topic_path)
raise
subs = [{
'topic': topic_path,
'name': subscription
} for subscription in response.subscriptions]
return subs, response.next_page_token
def topic_publish(self, topic_path, messages):
"""API call: publish one or more messages to a topic
See:
https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/publish
:type topic_path: str
:param topic_path: fully-qualified path of the topic, in format
``projects/<PROJECT>/topics/<TOPIC_NAME>``.
:type messages: list of dict
:param messages: messages to be published.
:rtype: list of string
:returns: list of opaque IDs for published messages.
:raises: :exc:`google.cloud.exceptions.NotFound` if the topic does not
exist
"""
options = CallOptions(is_bundling=False)
message_pbs = [_message_pb_from_mapping(message)
for message in messages]
try:
result = self._gax_api.publish(topic_path, message_pbs,
options=options)
except GaxError as exc:
if exc_to_code(exc.cause) == StatusCode.NOT_FOUND:
raise NotFound(topic_path)
raise
return result.message_ids
def list_traces(self,
project_id,
view=None,
page_size=None,
start_time=None,
end_time=None,
filter_=None,
order_by=None,
page_token=None):
"""
Returns of a list of traces that match the filter conditions.
Args:
project_id (Optional[str]): ID of the Cloud project where the trace
data is stored.
view (Optional[~google.cloud.trace_v1.gapic.enums.
ListTracesRequest.ViewType]): Type of data returned for traces
in the list. Default is ``MINIMAL``.
page_size (Optional[int]): Maximum number of traces to return. If
not specified or <= 0, the implementation selects a reasonable
value. The implementation may return fewer traces than the
requested page size.
start_time (Optional[~datetime.datetime]): Start of the time
interval (inclusive) during which the trace data was collected
from the application.
end_time (Optional[~datetime.datetime]): End of the time interval
(inclusive) during which the trace data was collected from the
application.
filter_ (Optional[str]): An optional filter for the request.
order_by (Optional[str]): Field used to sort the returned traces.
page_token (Optional[str]): opaque marker for the next "page" of
entries. If not passed, the API will return the first page of
entries.
Returns:
A :class:`~google.api_core.page_iterator.Iterator` of traces that
match the specified filter conditions.
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
page_iter = self._gax_api.list_traces(project_id=project_id,
view=view,
page_size=page_size,
start_time=start_time,
end_time=end_time,
filter_=filter_,
order_by=order_by,
options=options)
item_to_value = _item_to_mapping
return page_iterator._GAXIterator(self.client, page_iter,
item_to_value)
def test_settings_merge_options_page_streaming(self):
retry = RetryOptions(None, None)
options = CallOptions(timeout=46, is_page_streaming=False)
settings = CallSettings(timeout=9, retry=retry)
final = settings.merge(options)
self.assertEqual(final.timeout, 46)
self.assertIsNone(final.page_descriptor)
self.assertEqual(final.retry, retry)
def test_settings_merge_options2(self):
retry = RetryOptions(None, None)
options = CallOptions(retry=retry)
settings = _CallSettings(
timeout=9, page_descriptor=None, retry=RetryOptions(None, None))
final = settings.merge(options)
self.assertEqual(final.timeout, 9)
self.assertIsNone(final.page_descriptor)
self.assertEqual(final.retry, retry)
def test_call_merge_options_metadata(self):
settings_kwargs = {
'key': 'value',
'metadata': [('key1', 'val1'), ('key2', 'val2')]
}
settings = _CallSettings(kwargs=settings_kwargs)
my_callable = api_callable.create_api_call(
lambda _req, _timeout, **kwargs: kwargs, settings)
# Merge empty options, settings.kwargs['metadata'] remain unchanged
expected_kwargs = settings_kwargs
self.assertEqual(my_callable(None), expected_kwargs)
# Override an existing key in settings.kwargs['metadata']
expected_kwargs = {
'key': 'value',
'metadata': [('key1', '_val1'), ('key2', 'val2')]
}
self.assertEqual(
my_callable(None, CallOptions(metadata=[('key1', '_val1')])),
expected_kwargs)
# Add a new key in settings.kwargs['metadata']
expected_kwargs = {
'key': 'value',
'metadata': [('key3', 'val3'), ('key1', 'val1'), ('key2', 'val2')]
}
self.assertEqual(
my_callable(None, CallOptions(metadata=[('key3', 'val3')])),
expected_kwargs)
# Do all: add a new key and override an existing one in
# settings.kwargs['metadata']
expected_kwargs = {
'key': 'value',
'metadata': [('key3', 'val3'), ('key2', '_val2'), ('key1', 'val1')]
}
self.assertEqual(
my_callable(
None,
CallOptions(metadata=[('key3', 'val3'), ('key2', '_val2')])),
expected_kwargs)
def test_settings_merge_options_page_streaming(self):
retry = RetryOptions(None, None)
page_descriptor = object()
options = CallOptions(timeout=46, page_token=INITIAL_PAGE)
settings = _CallSettings(timeout=9, retry=retry,
page_descriptor=page_descriptor)
final = settings.merge(options)
self.assertEqual(final.timeout, 46)
self.assertEqual(final.page_descriptor, page_descriptor)
self.assertEqual(final.page_token, INITIAL_PAGE)
self.assertFalse(final.flatten_pages)
self.assertEqual(final.retry, retry)
def list_entries(self,
projects,
filter_='',
order_by='',
page_size=0,
page_token=None):
"""Return a page of log entry resources.
:type projects: list of strings
:param projects: project IDs to include. If not passed,
defaults to the project bound to the API's client.
:type filter_: str
:param filter_:
a filter expression. See
https://cloud.google.com/logging/docs/view/advanced_filters
:type order_by: str
:param order_by: One of :data:`~google.cloud.logging.ASCENDING`
or :data:`~google.cloud.logging.DESCENDING`.
:type page_size: int
:param page_size: maximum number of entries to return, If not passed,
defaults to a value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of entries. If not
passed, the API will return the first page of
entries.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns: Iterator of :class:`~google.cloud.logging.entries._BaseEntry`
accessible to the current API.
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
page_iter = self._gax_api.list_log_entries([],
project_ids=projects,
filter_=filter_,
order_by=order_by,
page_size=page_size,
options=options)
# We attach a mutable loggers dictionary so that as Logger
# objects are created by entry_from_resource, they can be
# re-used by other log entries from the same logger.
loggers = {}
item_to_value = functools.partial(_item_to_entry, loggers=loggers)
return page_iterator._GAXIterator(self._client, page_iter,
item_to_value)
def _options_with_prefix(prefix, **kw):
"""Create GAPIC options w/ prefix.
:type prefix: str
:param prefix: appropriate resource path
:type kw: dict
:param kw: other keyword arguments passed to the constructor
:rtype: :class:`~google.gax.CallOptions`
:returns: GAPIC call options with supplied prefix
"""
return CallOptions(metadata=[('google-cloud-resource-prefix', prefix)],
**kw)
def list_entries(self,
projects,
filter_='',
order_by='',
page_size=0,
page_token=None):
"""Return a page of log entry resources.
:type projects: list of strings
:param projects: project IDs to include. If not passed,
defaults to the project bound to the API's client.
:type filter_: str
:param filter_: a filter expression. See:
https://cloud.google.com/logging/docs/view/advanced_filters
:type order_by: str
:param order_by: One of :data:`~google.cloud.logging.ASCENDING`
or :data:`~google.cloud.logging.DESCENDING`.
:type page_size: int
:param page_size: maximum number of entries to return, If not passed,
defaults to a value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of entries. If not
passed, the API will return the first page of
entries.
:rtype: tuple, (list, str)
:returns: list of mappings, plus a "next page token" string:
if not None, indicates that more entries can be retrieved
with another call (pass that value as ``page_token``).
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
page_iter = self._gax_api.list_log_entries(projects,
filter_=filter_,
order_by=order_by,
page_size=page_size,
options=options)
entries = [
_log_entry_pb_to_mapping(entry_pb)
for entry_pb in page_iter.next()
]
token = page_iter.page_token or None
return entries, token
def topic_list_subscriptions(self, topic, page_size=0, page_token=None):
"""API call: list subscriptions bound to a topic
See:
https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics.subscriptions/list
:type topic: :class:`~google.cloud.pubsub.topic.Topic`
:param topic: The topic that owns the subscriptions.
:type page_size: int
:param page_size: maximum number of subscriptions to return, If not
passed, defaults to a value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of subscriptions.
If not passed, the API will return the first page
of subscriptions.
:rtype: :class:`~google.cloud.iterator.Iterator`
:returns: Iterator of
:class:`~google.cloud.pubsub.subscription.Subscription`
accessible to the current API.
:raises: :exc:`~google.cloud.exceptions.NotFound` if the topic does
not exist.
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
topic_path = topic.full_name
try:
page_iter = self._gax_api.list_topic_subscriptions(
topic_path, page_size=page_size, options=options)
except GaxError as exc:
if exc_to_code(exc.cause) == StatusCode.NOT_FOUND:
raise NotFound(topic_path)
raise
iter_kwargs = {}
if page_size: # page_size can be 0 or explicit None.
iter_kwargs['max_results'] = page_size
iterator = GAXIterator(self._client, page_iter, _item_to_subscription,
**iter_kwargs)
iterator.topic = topic
return iterator
def list_topics(self, project):
"""List topics for the project associated with this API.
See:
https://cloud.google.com/pubsub/reference/rest/v1/projects.topics/list
:type project: string
:param project: project ID
:rtype: tuple, (list, str)
:returns: list of ``Topic`` resource dicts, 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``).
"""
options = CallOptions(is_page_streaming=False)
path = 'projects/%s' % (project, )
response = self._gax_api.list_topics(path, options)
topics = [{'name': topic_pb.name} for topic_pb in response.topics]
return topics, response.next_page_token
def topic_list_subscriptions(self,
topic_path,
page_size=0,
page_token=None):
"""API call: list subscriptions bound to a topic
See:
https://cloud.google.com/pubsub/reference/rest/v1/projects.topics.subscriptions/list
:type topic_path: string
:param topic_path: fully-qualified path of the topic, in format
``projects/<PROJECT>/topics/<TOPIC_NAME>``.
:type page_size: int
:param page_size: maximum number of subscriptions 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 subscriptions.
If not passed, the API will return the first page
of subscriptions.
:rtype: list of strings
:returns: fully-qualified names of subscriptions for the supplied
topic.
:raises: :exc:`gcloud.exceptions.NotFound` if the topic does not
exist
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
try:
page_iter = self._gax_api.list_topic_subscriptions(
topic_path, page_size=page_size, options=options)
except GaxError as exc:
if exc_to_code(exc.cause) == StatusCode.NOT_FOUND:
raise NotFound(topic_path)
raise
subs = page_iter.next()
token = page_iter.page_token or None
return subs, token
def list_subscriptions(self, project, page_size=0, page_token=None):
"""List subscriptions for the project associated with this API.
See
https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/list
:type project: str
:param project: project ID
:type page_size: int
:param page_size: maximum number of subscriptions to return, If not
passed, defaults to a value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of subscriptions.
If not passed, the API will return the first page
of subscriptions.
:rtype: :class:`~google.api.core.page_iterator.Iterator`
:returns: Iterator of
:class:`~google.cloud.pubsub.subscription.Subscription`
accessible to the current API.
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
path = 'projects/%s' % (project, )
page_iter = self._gax_api.list_subscriptions(path,
page_size=page_size,
options=options)
# We attach a mutable topics dictionary so that as topic
# objects are created by Subscription.from_api_repr, they
# can be re-used by other subscriptions from the same topic.
topics = {}
item_to_value = functools.partial(_item_to_sub_for_client,
topics=topics)
return page_iterator._GAXIterator(self._client, page_iter,
item_to_value)
def list_traces(self,
project_id,
view=None,
page_size=None,
start_time=None,
end_time=None,
filter_=None,
order_by=None,
page_token=None):
"""Returns of a list of traces that match the specified filter
conditions.
:type project_id: str
:param project_id: ID of the Cloud project where the trace data is
stored.
:type view: :class:`google.cloud.gapic.trace.v1.enums.
ListTracesRequest.ViewType`
:param view: (Optional) Type of data returned for traces in the list.
Default is ``MINIMAL``.
:type page_size: int
:param page_size: (Optional) Maximum number of traces to return.
If not specified or <= 0, the implementation selects
a reasonable value. The implementation may return
fewer traces than the requested page size.
:type start_time: :class:`google.protobuf.timestamp_pb2.Timestamp`
:param start_time: (Optional) Start of the time interval (inclusive)
during which the trace data was collected from the
application.
:type end_time: :class:`google.protobuf.timestamp_pb2.Timestamp`
:param end_time: (Optional) End of the time interval (inclusive)
during which the trace data was collected from the
application.
:type filter_: str
:param filter_: (Optional) An optional filter for the request.
:type order_by: str
:param order_by: (Optional) Field used to sort the returned traces.
:type page_token: str
:param page_token: opaque marker for the next "page" of entries. If not
passed, the API will return the first page of
entries.
:rtype: :class:`~google.api.core.page_iterator.Iterator`
:returns: Traces that match the specified filter conditions.
"""
if page_token is None:
page_token = INITIAL_PAGE
options = CallOptions(page_token=page_token)
page_iter = self._gax_api.list_traces(project_id=project_id,
view=view,
page_size=page_size,
start_time=start_time,
end_time=end_time,
filter_=filter_,
order_by=order_by,
options=options)
item_to_value = _item_to_mapping
return page_iterator._GAXIterator(self.client, page_iter,
item_to_value)
def _build_paging_options(page_token=None):
"""Helper for :meth:'_PublisherAPI.list_topics' et aliae."""
if page_token is None:
page_token = INITIAL_PAGE
options = {'page_token': page_token}
return CallOptions(**options)
def test_call_override(self):
settings = _CallSettings(timeout=10)
my_callable = api_callable.create_api_call(
lambda _req, timeout: timeout, settings)
self.assertEqual(my_callable(None, CallOptions(timeout=20)), 20)
def test_page_streaming(self):
# A mock grpc function that page streams a list of consecutive
# integers, returning `page_size` integers with each call and using
# the next integer to return as the page token, until `pages_to_stream`
# pages have been returned.
# pylint:disable=too-many-locals
page_size = 3
pages_to_stream = 5
# pylint: disable=abstract-method, too-few-public-methods
class PageStreamingRequest(object):
def __init__(self, page_token=0):
self.page_token = page_token
class PageStreamingResponse(object):
def __init__(self, nums=(), next_page_token=0):
self.nums = nums
self.next_page_token = next_page_token
fake_grpc_func_descriptor = PageDescriptor('page_token',
'next_page_token', 'nums')
def grpc_return_value(request, *dummy_args, **dummy_kwargs):
start = int(request.page_token)
if start > 0 and start < page_size * pages_to_stream:
return PageStreamingResponse(nums=list(
range(start, start + page_size)),
next_page_token=start + page_size)
elif start >= page_size * pages_to_stream:
return PageStreamingResponse()
else:
return PageStreamingResponse(nums=list(range(page_size)),
next_page_token=page_size)
with mock.patch('grpc.UnaryUnaryMultiCallable') as mock_grpc:
mock_grpc.side_effect = grpc_return_value
settings = _CallSettings(page_descriptor=fake_grpc_func_descriptor,
timeout=0)
my_callable = api_callable.create_api_call(mock_grpc,
settings=settings)
self.assertEqual(list(my_callable(PageStreamingRequest())),
list(range(page_size * pages_to_stream)))
unflattened_option = CallOptions(page_token=INITIAL_PAGE)
# Expect a list of pages_to_stream pages, each of size page_size,
# plus one empty page
expected = [
list(range(page_size * n, page_size * (n + 1)))
for n in range(pages_to_stream)
] + [()]
self.assertEqual(
list(my_callable(PageStreamingRequest(), unflattened_option)),
expected)
pages_already_read = 2
explicit_page_token_option = CallOptions(
page_token=str(page_size * pages_already_read))
# Expect a list of pages_to_stream pages, each of size page_size,
# plus one empty page, minus the pages_already_read
expected = [
list(range(page_size * n, page_size * (n + 1)))
for n in range(pages_already_read, pages_to_stream)
]
expected += [()]
self.assertEqual(
list(
my_callable(PageStreamingRequest(),
explicit_page_token_option)), expected)
def test_call_options_simple(self):
options = CallOptions(timeout=23)
self.assertEqual(options.timeout, 23)
self.assertEqual(options.retry, OPTION_INHERIT)
self.assertEqual(options.page_token, OPTION_INHERIT)
