Pub/Sub: update docstrings for client kwargs and fix return types uris

pubsub/google/cloud/pubsub_v1/gapic/publisher_client.py

@@ -618,7 +618,7 @@ def list_topics(
                 that is provided to the method.
 
         Returns:
-            A :class:`~google.api_core.page_iterator.PageIterator` instance.
+            A :class:`~google.api_core.page_iterator.GRPCIterator` instance.
             An iterable of :class:`~google.cloud.pubsub_v1.types.Topic` instances.
             You can also iterate over the pages of the response
             using its `pages` property.
@@ -720,7 +720,7 @@ def list_topic_subscriptions(
                 that is provided to the method.
 
         Returns:
-            A :class:`~google.api_core.page_iterator.PageIterator` instance.
+            A :class:`~google.api_core.page_iterator.GRPCIterator` instance.
             An iterable of :class:`str` instances.
             You can also iterate over the pages of the response
             using its `pages` property.

pubsub/google/cloud/pubsub_v1/gapic/subscriber_client.py

@@ -603,7 +603,7 @@ def list_subscriptions(
                 that is provided to the method.
 
         Returns:
-            A :class:`~google.api_core.page_iterator.PageIterator` instance.
+            A :class:`~google.api_core.page_iterator.GRPCIterator` instance.
             An iterable of :class:`~google.cloud.pubsub_v1.types.Subscription` instances.
             You can also iterate over the pages of the response
             using its `pages` property.
@@ -1202,7 +1202,7 @@ def list_snapshots(
                 that is provided to the method.
 
         Returns:
-            A :class:`~google.api_core.page_iterator.PageIterator` instance.
+            A :class:`~google.api_core.page_iterator.GRPCIterator` instance.
             An iterable of :class:`~google.cloud.pubsub_v1.types.Snapshot` instances.
             You can also iterate over the pages of the response
             using its `pages` property.

pubsub/google/cloud/pubsub_v1/publisher/client.py

@@ -1,4 +1,4 @@
-# Copyright 2017, Google LLC All rights reserved.
+# Copyright 2019, Google LLC All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -53,14 +53,45 @@ class Client(object):
             settings for batch publishing.
         kwargs (dict): Any additional arguments provided are sent as keyword
             arguments to the underlying
-            :class:`~.gapic.pubsub.v1.publisher_client.PublisherClient`.
-            Generally, you should not need to set additional keyword arguments.
-            Before being passed along to the GAPIC constructor, a channel may
-            be added if ``credentials`` are passed explicitly or if the
-            Pub / Sub emulator is detected as running.
-            Regional endpoints can be set via ``client_options`` that takes a
-            single key-value pair that defines the endpoint, i.e.
-            ``client_options={"api_endpoint": REGIONAL_ENDPOINT}``.
+            :class:`~google.cloud.pubsub_v1.gapic.publisher_client.PublisherClient`.
+            Generally you should not need to set additional keyword
+            arguments. Optionally, publish retry settings can be set via
+            ``client_config`` where user-provided retry configurations are
+            applied to default retry settings. And regional endpoints can be
+            set via ``client_options`` that takes a single key-value pair that
+            defines the endpoint.
+
+    Example:
+
+    .. code-block:: python
+
+        from google.cloud import pubsub_v1
+
+        publisher_client = pubsub_v1.PublisherClient(
+            # Optional
+            batch_settings = pubsub_v1.types.BatchSettings(
+                max_bytes=1024,  # One kilobyte
+                max_latency=1,   # One second
+            ),
+
+            # Optional
+            client_config = {
+                "interfaces": {
+                    "google.pubsub.v1.Publisher": {
+                        "retry_params": {
+                            "messaging": {
+                                'total_timeout_millis': 650000,  # default: 600000
+                            }
+                        }
+                    }
+                }
+            },
+
+            # Optional
+            client_options = {
+                "api_endpoint": REGIONAL_ENDPOINT
+            }
+        )
     """
 
     _batch_class = thread.Batch
@@ -117,7 +148,8 @@ def from_service_account_file(cls, filename, batch_settings=(), **kwargs):
             kwargs: Additional arguments to pass to the constructor.
 
         Returns:
-            PublisherClient: The constructed client.
+            A Publisher :class:`~google.cloud.pubsub_v1.publisher.client.Client`
+            instance that is the constructed client.
         """
         credentials = service_account.Credentials.from_service_account_file(filename)
         kwargs["credentials"] = credentials
@@ -206,9 +238,10 @@ def publish(self, topic, data, **attrs):
                 sent as metadata. (These may be text strings or byte strings.)
 
         Returns:
-            ~google.api_core.future.Future: An object conforming to the
-            ``concurrent.futures.Future`` interface (but not an instance
-            of that class).
+            A :class:`~google.cloud.pubsub_v1.publisher.futures.Future`
+            instance that conforms to Python Standard library's
+            :class:`~concurrent.futures.Future` interface (but not an
+            instance of that class).
         """
         # Sanity check: Is the data being sent as a bytestring?
         # If it is literally anything else, complain loudly about it.

pubsub/google/cloud/pubsub_v1/subscriber/client.py

@@ -1,4 +1,4 @@
-# Copyright 2017, Google LLC All rights reserved.
+# Copyright 2019, Google LLC All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,8 +14,8 @@
 
 from __future__ import absolute_import
 
-import pkg_resources
 import os
+import pkg_resources
 
 import grpc
 
@@ -50,12 +50,24 @@ class Client(object):
     Args:
         kwargs (dict): Any additional arguments provided are sent as keyword
             keyword arguments to the underlying
-            :class:`~.gapic.pubsub.v1.subscriber_client.SubscriberClient`.
-            Generally, you should not need to set additional keyword
-            arguments.
-            Regional endpoints can be set via ``client_options`` that takes a
-            single key-value pair that defines the endpoint, i.e.
-            ``client_options={"api_endpoint": REGIONAL_ENDPOINT}``.
+            :class:`~google.cloud.pubsub_v1.gapic.subscriber_client.SubscriberClient`.
+            Generally you should not need to set additional keyword
+            arguments. Optionally, regional endpoints can be set via
+            ``client_options`` that takes a single key-value pair that
+            defines the endpoint.
+
+    Example:
+
+    .. code-block:: python
+
+        from google.cloud import pubsub_v1
+
+        subscriber_client = pubsub_v1.SubscriberClient(
+            # Optional
+            client_options = {
+                "api_endpoint": REGIONAL_ENDPOINT
+            }
+        )
     """
 
     def __init__(self, **kwargs):
@@ -105,7 +117,8 @@ def from_service_account_file(cls, filename, **kwargs):
             kwargs: Additional arguments to pass to the constructor.
 
         Returns:
-            PublisherClient: The constructed client.
+            A Subscriber :class:`~google.cloud.pubsub_v1.subscriber.client.Client`
+            instance that is the constructed client.
         """
         credentials = service_account.Credentials.from_service_account_file(filename)
         kwargs["credentials"] = credentials
@@ -201,8 +214,8 @@ def callback(message):
                 how callbacks are executed concurrently.
 
         Returns:
-            google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture: A
-                Future object that can be used to manage the background stream.
+            A :class:`~google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture`
+            instance that can be used to manage the background stream.
         """
         flow_control = types.FlowControl(*flow_control)
 

pubsub/synth.metadata

@@ -1,19 +1,19 @@
 {
-  "updateTime": "2019-08-06T12:34:22.031743Z",
+  "updateTime": "2019-08-16T22:21:02.392751Z",
   "sources": [
     {
       "generator": {
         "name": "artman",
-        "version": "0.32.1",
-        "dockerImage": "googleapis/artman@sha256:a684d40ba9a4e15946f5f2ca6b4bd9fe301192f522e9de4fff622118775f309b"
+        "version": "0.33.0",
+        "dockerImage": "googleapis/artman@sha256:c6231efb525569736226b1f7af7565dbc84248efafb3692a5bb1d2d8a7975d53"
       }
     },
     {
       "git": {
         "name": "googleapis",
         "remote": "https://github.com/googleapis/googleapis.git",
-        "sha": "e699b0cba64ffddfae39633417180f1f65875896",
-        "internalRef": "261759677"
+        "sha": "f6cc01ff6d13bda19ed717dfde6e92c593dfc590",
+        "internalRef": "263831339"
       }
     },
     {

pubsub/synth.py

@@ -167,6 +167,18 @@ def _merge_dict(d1, d2):
     """
 )
 
+s.replace(
+    "google/cloud/pubsub_v1/gapic/publisher_client.py",
+    "~google.api_core.page_iterator.PageIterator",
+    "~google.api_core.page_iterator.GRPCIterator"
+)
+
+s.replace(
+    "google/cloud/pubsub_v1/gapic/subscriber_client.py",
+    "~google.api_core.page_iterator.PageIterator",
+    "~google.api_core.page_iterator.GRPCIterator"
+)
+
 # Temporary fixup for 'grpc-google-iam-vi 0.12.4' (before generation).
 s.replace(
     "google/cloud/pubsub_v1/gapic/transports/*_grpc_transport.py",