Skip to content

Commit 8998983

Browse files
anguillanneufplamut
anguillanneuf
authored and
plamut
committed
Pub/Sub: update docstrings for client kwargs and fix return types uris (googleapis#9037)
* Update kwargs docs * lint * Fix return object type * Put back changes in setup.cfg and noxfile.py * fix no new line * fix various return types uris
1 parent 6029022 commit 8998983

6 files changed

Lines changed: 91 additions & 33 deletions

File tree

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -618,7 +618,7 @@ def list_topics(
618618
that is provided to the method.
619619
620620
Returns:
621-
A :class:`~google.api_core.page_iterator.PageIterator` instance.
621+
A :class:`~google.api_core.page_iterator.GRPCIterator` instance.
622622
An iterable of :class:`~google.cloud.pubsub_v1.types.Topic` instances.
623623
You can also iterate over the pages of the response
624624
using its `pages` property.
@@ -720,7 +720,7 @@ def list_topic_subscriptions(
720720
that is provided to the method.
721721
722722
Returns:
723-
A :class:`~google.api_core.page_iterator.PageIterator` instance.
723+
A :class:`~google.api_core.page_iterator.GRPCIterator` instance.
724724
An iterable of :class:`str` instances.
725725
You can also iterate over the pages of the response
726726
using its `pages` property.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -603,7 +603,7 @@ def list_subscriptions(
603603
that is provided to the method.
604604
605605
Returns:
606-
A :class:`~google.api_core.page_iterator.PageIterator` instance.
606+
A :class:`~google.api_core.page_iterator.GRPCIterator` instance.
607607
An iterable of :class:`~google.cloud.pubsub_v1.types.Subscription` instances.
608608
You can also iterate over the pages of the response
609609
using its `pages` property.
@@ -1202,7 +1202,7 @@ def list_snapshots(
12021202
that is provided to the method.
12031203
12041204
Returns:
1205-
A :class:`~google.api_core.page_iterator.PageIterator` instance.
1205+
A :class:`~google.api_core.page_iterator.GRPCIterator` instance.
12061206
An iterable of :class:`~google.cloud.pubsub_v1.types.Snapshot` instances.
12071207
You can also iterate over the pages of the response
12081208
using its `pages` property.

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

Lines changed: 46 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Copyright 2017, Google LLC All rights reserved.
1+
# Copyright 2019, Google LLC All rights reserved.
22
#
33
# Licensed under the Apache License, Version 2.0 (the "License");
44
# you may not use this file except in compliance with the License.
@@ -53,14 +53,45 @@ class Client(object):
5353
settings for batch publishing.
5454
kwargs (dict): Any additional arguments provided are sent as keyword
5555
arguments to the underlying
56-
:class:`~.gapic.pubsub.v1.publisher_client.PublisherClient`.
57-
Generally, you should not need to set additional keyword arguments.
58-
Before being passed along to the GAPIC constructor, a channel may
59-
be added if ``credentials`` are passed explicitly or if the
60-
Pub / Sub emulator is detected as running.
61-
Regional endpoints can be set via ``client_options`` that takes a
62-
single key-value pair that defines the endpoint, i.e.
63-
``client_options={"api_endpoint": REGIONAL_ENDPOINT}``.
56+
:class:`~google.cloud.pubsub_v1.gapic.publisher_client.PublisherClient`.
57+
Generally you should not need to set additional keyword
58+
arguments. Optionally, publish retry settings can be set via
59+
``client_config`` where user-provided retry configurations are
60+
applied to default retry settings. And regional endpoints can be
61+
set via ``client_options`` that takes a single key-value pair that
62+
defines the endpoint.
63+
64+
Example:
65+
66+
.. code-block:: python
67+
68+
from google.cloud import pubsub_v1
69+
70+
publisher_client = pubsub_v1.PublisherClient(
71+
# Optional
72+
batch_settings = pubsub_v1.types.BatchSettings(
73+
max_bytes=1024, # One kilobyte
74+
max_latency=1, # One second
75+
),
76+
77+
# Optional
78+
client_config = {
79+
"interfaces": {
80+
"google.pubsub.v1.Publisher": {
81+
"retry_params": {
82+
"messaging": {
83+
'total_timeout_millis': 650000, # default: 600000
84+
}
85+
}
86+
}
87+
}
88+
},
89+
90+
# Optional
91+
client_options = {
92+
"api_endpoint": REGIONAL_ENDPOINT
93+
}
94+
)
6495
"""
6596

6697
_batch_class = thread.Batch
@@ -117,7 +148,8 @@ def from_service_account_file(cls, filename, batch_settings=(), **kwargs):
117148
kwargs: Additional arguments to pass to the constructor.
118149
119150
Returns:
120-
PublisherClient: The constructed client.
151+
A Publisher :class:`~google.cloud.pubsub_v1.publisher.client.Client`
152+
instance that is the constructed client.
121153
"""
122154
credentials = service_account.Credentials.from_service_account_file(filename)
123155
kwargs["credentials"] = credentials
@@ -206,9 +238,10 @@ def publish(self, topic, data, **attrs):
206238
sent as metadata. (These may be text strings or byte strings.)
207239
208240
Returns:
209-
~google.api_core.future.Future: An object conforming to the
210-
``concurrent.futures.Future`` interface (but not an instance
211-
of that class).
241+
A :class:`~google.cloud.pubsub_v1.publisher.futures.Future`
242+
instance that conforms to Python Standard library's
243+
:class:`~concurrent.futures.Future` interface (but not an
244+
instance of that class).
212245
"""
213246
# Sanity check: Is the data being sent as a bytestring?
214247
# If it is literally anything else, complain loudly about it.

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

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Copyright 2017, Google LLC All rights reserved.
1+
# Copyright 2019, Google LLC All rights reserved.
22
#
33
# Licensed under the Apache License, Version 2.0 (the "License");
44
# you may not use this file except in compliance with the License.
@@ -14,8 +14,8 @@
1414

1515
from __future__ import absolute_import
1616

17-
import pkg_resources
1817
import os
18+
import pkg_resources
1919

2020
import grpc
2121

@@ -50,12 +50,24 @@ class Client(object):
5050
Args:
5151
kwargs (dict): Any additional arguments provided are sent as keyword
5252
keyword arguments to the underlying
53-
:class:`~.gapic.pubsub.v1.subscriber_client.SubscriberClient`.
54-
Generally, you should not need to set additional keyword
55-
arguments.
56-
Regional endpoints can be set via ``client_options`` that takes a
57-
single key-value pair that defines the endpoint, i.e.
58-
``client_options={"api_endpoint": REGIONAL_ENDPOINT}``.
53+
:class:`~google.cloud.pubsub_v1.gapic.subscriber_client.SubscriberClient`.
54+
Generally you should not need to set additional keyword
55+
arguments. Optionally, regional endpoints can be set via
56+
``client_options`` that takes a single key-value pair that
57+
defines the endpoint.
58+
59+
Example:
60+
61+
.. code-block:: python
62+
63+
from google.cloud import pubsub_v1
64+
65+
subscriber_client = pubsub_v1.SubscriberClient(
66+
# Optional
67+
client_options = {
68+
"api_endpoint": REGIONAL_ENDPOINT
69+
}
70+
)
5971
"""
6072

6173
def __init__(self, **kwargs):
@@ -105,7 +117,8 @@ def from_service_account_file(cls, filename, **kwargs):
105117
kwargs: Additional arguments to pass to the constructor.
106118
107119
Returns:
108-
PublisherClient: The constructed client.
120+
A Subscriber :class:`~google.cloud.pubsub_v1.subscriber.client.Client`
121+
instance that is the constructed client.
109122
"""
110123
credentials = service_account.Credentials.from_service_account_file(filename)
111124
kwargs["credentials"] = credentials
@@ -201,8 +214,8 @@ def callback(message):
201214
how callbacks are executed concurrently.
202215
203216
Returns:
204-
google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture: A
205-
Future object that can be used to manage the background stream.
217+
A :class:`~google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture`
218+
instance that can be used to manage the background stream.
206219
"""
207220
flow_control = types.FlowControl(*flow_control)
208221

‎pubsub/synth.metadata‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
{
2-
"updateTime": "2019-08-06T12:34:22.031743Z",
2+
"updateTime": "2019-08-16T22:21:02.392751Z",
33
"sources": [
44
{
55
"generator": {
66
"name": "artman",
7-
"version": "0.32.1",
8-
"dockerImage": "googleapis/artman@sha256:a684d40ba9a4e15946f5f2ca6b4bd9fe301192f522e9de4fff622118775f309b"
7+
"version": "0.33.0",
8+
"dockerImage": "googleapis/artman@sha256:c6231efb525569736226b1f7af7565dbc84248efafb3692a5bb1d2d8a7975d53"
99
}
1010
},
1111
{
1212
"git": {
1313
"name": "googleapis",
1414
"remote": "https://github.com/googleapis/googleapis.git",
15-
"sha": "e699b0cba64ffddfae39633417180f1f65875896",
16-
"internalRef": "261759677"
15+
"sha": "f6cc01ff6d13bda19ed717dfde6e92c593dfc590",
16+
"internalRef": "263831339"
1717
}
1818
},
1919
{

‎pubsub/synth.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,18 @@ def _merge_dict(d1, d2):
167167
"""
168168
)
169169

170+
s.replace(
171+
"google/cloud/pubsub_v1/gapic/publisher_client.py",
172+
"~google.api_core.page_iterator.PageIterator",
173+
"~google.api_core.page_iterator.GRPCIterator"
174+
)
175+
176+
s.replace(
177+
"google/cloud/pubsub_v1/gapic/subscriber_client.py",
178+
"~google.api_core.page_iterator.PageIterator",
179+
"~google.api_core.page_iterator.GRPCIterator"
180+
)
181+
170182
# Temporary fixup for 'grpc-google-iam-vi 0.12.4' (before generation).
171183
s.replace(
172184
"google/cloud/pubsub_v1/gapic/transports/*_grpc_transport.py",

0 commit comments

Comments
 (0)