From bdc353513ba753b4181d7be109c8789fd580753c Mon Sep 17 00:00:00 2001 From: Tianzi Cai Date: Thu, 15 Aug 2019 17:43:22 -0700 Subject: [PATCH 1/6] Update kwargs docs --- .../cloud/pubsub_v1/publisher/client.py | 45 ++++++++++++++++--- .../cloud/pubsub_v1/subscriber/client.py | 22 ++++++--- 2 files changed, 55 insertions(+), 12 deletions(-) diff --git a/pubsub/google/cloud/pubsub_v1/publisher/client.py b/pubsub/google/cloud/pubsub_v1/publisher/client.py index d0f42e55c50e..e7bfbad1b9f4 100644 --- a/pubsub/google/cloud/pubsub_v1/publisher/client.py +++ b/pubsub/google/cloud/pubsub_v1/publisher/client.py @@ -54,13 +54,44 @@ class Client(object): 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}``. + 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 diff --git a/pubsub/google/cloud/pubsub_v1/subscriber/client.py b/pubsub/google/cloud/pubsub_v1/subscriber/client.py index 8c7ce59846c4..d677690823e4 100644 --- a/pubsub/google/cloud/pubsub_v1/subscriber/client.py +++ b/pubsub/google/cloud/pubsub_v1/subscriber/client.py @@ -51,11 +51,23 @@ class Client(object): 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}``. + 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): From 2846186daf419e981c18c541da6f9679ea593762 Mon Sep 17 00:00:00 2001 From: Tianzi Cai Date: Fri, 16 Aug 2019 14:47:24 -0700 Subject: [PATCH 2/6] lint --- pubsub/google/cloud/pubsub_v1/publisher/client.py | 6 +++--- pubsub/google/cloud/pubsub_v1/subscriber/client.py | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pubsub/google/cloud/pubsub_v1/publisher/client.py b/pubsub/google/cloud/pubsub_v1/publisher/client.py index e7bfbad1b9f4..d8ac2c7aa703 100644 --- a/pubsub/google/cloud/pubsub_v1/publisher/client.py +++ b/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. @@ -55,12 +55,12 @@ class Client(object): arguments to the underlying :class:`~.gapic.pubsub.v1.publisher_client.PublisherClient`. Generally you should not need to set additional keyword - arguments. Optionally, publish retry settings can be set via + 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 diff --git a/pubsub/google/cloud/pubsub_v1/subscriber/client.py b/pubsub/google/cloud/pubsub_v1/subscriber/client.py index d677690823e4..baa6f76ab603 100644 --- a/pubsub/google/cloud/pubsub_v1/subscriber/client.py +++ b/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 @@ -52,7 +52,7 @@ class Client(object): keyword arguments to the underlying :class:`~.gapic.pubsub.v1.subscriber_client.SubscriberClient`. Generally you should not need to set additional keyword - arguments. Optionally, regional endpoints can be set via + arguments. Optionally, regional endpoints can be set via ``client_options`` that takes a single key-value pair that defines the endpoint. From 69d368803175e74a303505b6156d881767e5c8e9 Mon Sep 17 00:00:00 2001 From: Tianzi Cai Date: Fri, 16 Aug 2019 15:28:54 -0700 Subject: [PATCH 3/6] Fix return object type --- .../cloud/pubsub_v1/gapic/publisher_client.py | 4 +- .../pubsub_v1/gapic/subscriber_client.py | 4 +- .../cloud/pubsub_v1/subscriber/client.py | 2 +- pubsub/noxfile.py | 56 +++++++++---------- pubsub/setup.cfg | 1 - pubsub/synth.metadata | 10 ++-- pubsub/synth.py | 12 ++++ 7 files changed, 50 insertions(+), 39 deletions(-) diff --git a/pubsub/google/cloud/pubsub_v1/gapic/publisher_client.py b/pubsub/google/cloud/pubsub_v1/gapic/publisher_client.py index 6ea062166878..774fda25d622 100644 --- a/pubsub/google/cloud/pubsub_v1/gapic/publisher_client.py +++ b/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. diff --git a/pubsub/google/cloud/pubsub_v1/gapic/subscriber_client.py b/pubsub/google/cloud/pubsub_v1/gapic/subscriber_client.py index dd5ef7fbe659..094e0ce8aa23 100644 --- a/pubsub/google/cloud/pubsub_v1/gapic/subscriber_client.py +++ b/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. diff --git a/pubsub/google/cloud/pubsub_v1/subscriber/client.py b/pubsub/google/cloud/pubsub_v1/subscriber/client.py index baa6f76ab603..fb73b59aeade 100644 --- a/pubsub/google/cloud/pubsub_v1/subscriber/client.py +++ b/pubsub/google/cloud/pubsub_v1/subscriber/client.py @@ -214,7 +214,7 @@ def callback(message): Returns: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture: A - Future object that can be used to manage the background stream. + StreamingPullFuture object that can be used to manage the background stream. """ flow_control = types.FlowControl(*flow_control) diff --git a/pubsub/noxfile.py b/pubsub/noxfile.py index a2eefbb6765f..0f528b7f3902 100644 --- a/pubsub/noxfile.py +++ b/pubsub/noxfile.py @@ -14,8 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Generated by synthtool. DO NOT EDIT! - from __future__ import absolute_import import os import shutil @@ -24,12 +22,6 @@ LOCAL_DEPS = (os.path.join("..", "api_core"), os.path.join("..", "core")) -BLACK_VERSION = "black==19.3b0" -BLACK_PATHS = ["docs", "google", "tests", "noxfile.py", "setup.py"] - -if os.path.exists("samples"): - BLACK_PATHS.append("samples") - @nox.session(python="3.7") def lint(session): @@ -38,8 +30,14 @@ def lint(session): Returns a failure if the linters find linting errors or sufficiently serious code quality issues. """ - session.install("flake8", BLACK_VERSION, *LOCAL_DEPS) - session.run("black", "--check", *BLACK_PATHS) + session.install("flake8", "black", *LOCAL_DEPS) + session.run( + "black", + "--check", + "google", + "tests", + "docs", + ) session.run("flake8", "google", "tests") @@ -48,13 +46,18 @@ def blacken(session): """Run black. Format code to uniform standard. - + This currently uses Python 3.6 due to the automated Kokoro run of synthtool. That run uses an image that doesn't have 3.6 installed. Before updating this check the state of the `gcp_ubuntu_config` we use for that Kokoro run. """ - session.install(BLACK_VERSION) - session.run("black", *BLACK_PATHS) + session.install("black") + session.run( + "black", + "google", + "tests", + "docs", + ) @nox.session(python="3.7") @@ -80,7 +83,7 @@ def default(session): "--cov-append", "--cov-config=.coveragerc", "--cov-report=", - "--cov-fail-under=0", + "--cov-fail-under=97", os.path.join("tests", "unit"), *session.posargs, ) @@ -137,24 +140,21 @@ def cover(session): session.run("coverage", "erase") - @nox.session(python="3.7") def docs(session): """Build the docs for this library.""" - session.install("-e", ".") - session.install("sphinx", "alabaster", "recommonmark") + session.install('-e', '.') + session.install('sphinx', 'alabaster', 'recommonmark') - shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True) + shutil.rmtree(os.path.join('docs', '_build'), ignore_errors=True) session.run( - "sphinx-build", - "-W", # warnings as errors - "-T", # show full traceback on exception - "-N", # no colors - "-b", - "html", - "-d", - os.path.join("docs", "_build", "doctrees", ""), - os.path.join("docs", ""), - os.path.join("docs", "_build", "html", ""), + 'sphinx-build', + '-W', # warnings as errors + '-T', # show full traceback on exception + '-N', # no colors + '-b', 'html', + '-d', os.path.join('docs', '_build', 'doctrees', ''), + os.path.join('docs', ''), + os.path.join('docs', '_build', 'html', ''), ) diff --git a/pubsub/setup.cfg b/pubsub/setup.cfg index 3bd555500e37..2a9acf13daa9 100644 --- a/pubsub/setup.cfg +++ b/pubsub/setup.cfg @@ -1,3 +1,2 @@ -# Generated by synthtool. DO NOT EDIT! [bdist_wheel] universal = 1 diff --git a/pubsub/synth.metadata b/pubsub/synth.metadata index ac0b324745e3..798a0aef3a08 100644 --- a/pubsub/synth.metadata +++ b/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" } }, { diff --git a/pubsub/synth.py b/pubsub/synth.py index c4601afbdb51..a65bf2bf4f56 100644 --- a/pubsub/synth.py +++ b/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", From 27b48ed78ec0678f17b1c9f3b2a28a08e876fa0b Mon Sep 17 00:00:00 2001 From: Tianzi Cai Date: Fri, 16 Aug 2019 15:34:47 -0700 Subject: [PATCH 4/6] Put back changes in setup.cfg and noxfile.py --- pubsub/noxfile.py | 56 +++++++++++++++++++++++------------------------ pubsub/setup.cfg | 3 ++- 2 files changed, 30 insertions(+), 29 deletions(-) diff --git a/pubsub/noxfile.py b/pubsub/noxfile.py index 0f528b7f3902..a2eefbb6765f 100644 --- a/pubsub/noxfile.py +++ b/pubsub/noxfile.py @@ -14,6 +14,8 @@ # See the License for the specific language governing permissions and # limitations under the License. +# Generated by synthtool. DO NOT EDIT! + from __future__ import absolute_import import os import shutil @@ -22,6 +24,12 @@ LOCAL_DEPS = (os.path.join("..", "api_core"), os.path.join("..", "core")) +BLACK_VERSION = "black==19.3b0" +BLACK_PATHS = ["docs", "google", "tests", "noxfile.py", "setup.py"] + +if os.path.exists("samples"): + BLACK_PATHS.append("samples") + @nox.session(python="3.7") def lint(session): @@ -30,14 +38,8 @@ def lint(session): Returns a failure if the linters find linting errors or sufficiently serious code quality issues. """ - session.install("flake8", "black", *LOCAL_DEPS) - session.run( - "black", - "--check", - "google", - "tests", - "docs", - ) + session.install("flake8", BLACK_VERSION, *LOCAL_DEPS) + session.run("black", "--check", *BLACK_PATHS) session.run("flake8", "google", "tests") @@ -46,18 +48,13 @@ def blacken(session): """Run black. Format code to uniform standard. - + This currently uses Python 3.6 due to the automated Kokoro run of synthtool. That run uses an image that doesn't have 3.6 installed. Before updating this check the state of the `gcp_ubuntu_config` we use for that Kokoro run. """ - session.install("black") - session.run( - "black", - "google", - "tests", - "docs", - ) + session.install(BLACK_VERSION) + session.run("black", *BLACK_PATHS) @nox.session(python="3.7") @@ -83,7 +80,7 @@ def default(session): "--cov-append", "--cov-config=.coveragerc", "--cov-report=", - "--cov-fail-under=97", + "--cov-fail-under=0", os.path.join("tests", "unit"), *session.posargs, ) @@ -140,21 +137,24 @@ def cover(session): session.run("coverage", "erase") + @nox.session(python="3.7") def docs(session): """Build the docs for this library.""" - session.install('-e', '.') - session.install('sphinx', 'alabaster', 'recommonmark') + session.install("-e", ".") + session.install("sphinx", "alabaster", "recommonmark") - shutil.rmtree(os.path.join('docs', '_build'), ignore_errors=True) + shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True) session.run( - 'sphinx-build', - '-W', # warnings as errors - '-T', # show full traceback on exception - '-N', # no colors - '-b', 'html', - '-d', os.path.join('docs', '_build', 'doctrees', ''), - os.path.join('docs', ''), - os.path.join('docs', '_build', 'html', ''), + "sphinx-build", + "-W", # warnings as errors + "-T", # show full traceback on exception + "-N", # no colors + "-b", + "html", + "-d", + os.path.join("docs", "_build", "doctrees", ""), + os.path.join("docs", ""), + os.path.join("docs", "_build", "html", ""), ) diff --git a/pubsub/setup.cfg b/pubsub/setup.cfg index 2a9acf13daa9..24eab5e15c1b 100644 --- a/pubsub/setup.cfg +++ b/pubsub/setup.cfg @@ -1,2 +1,3 @@ +# Generated by synthtool. DO NOT EDIT! [bdist_wheel] -universal = 1 +universal = 1 \ No newline at end of file From 6d0fda994023465b204ba8d58482722cfa59d437 Mon Sep 17 00:00:00 2001 From: Tianzi Cai Date: Fri, 16 Aug 2019 15:36:58 -0700 Subject: [PATCH 5/6] fix no new line --- pubsub/setup.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pubsub/setup.cfg b/pubsub/setup.cfg index 24eab5e15c1b..3bd555500e37 100644 --- a/pubsub/setup.cfg +++ b/pubsub/setup.cfg @@ -1,3 +1,3 @@ # Generated by synthtool. DO NOT EDIT! [bdist_wheel] -universal = 1 \ No newline at end of file +universal = 1 From aa2867816d2f51d11da39b2dd297739abf59be6f Mon Sep 17 00:00:00 2001 From: Tianzi Cai Date: Fri, 16 Aug 2019 16:31:31 -0700 Subject: [PATCH 6/6] fix various return types uris --- pubsub/google/cloud/pubsub_v1/publisher/client.py | 12 +++++++----- pubsub/google/cloud/pubsub_v1/subscriber/client.py | 9 +++++---- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/pubsub/google/cloud/pubsub_v1/publisher/client.py b/pubsub/google/cloud/pubsub_v1/publisher/client.py index d8ac2c7aa703..05a4161e889a 100644 --- a/pubsub/google/cloud/pubsub_v1/publisher/client.py +++ b/pubsub/google/cloud/pubsub_v1/publisher/client.py @@ -53,7 +53,7 @@ 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`. + :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 @@ -148,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 @@ -237,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. diff --git a/pubsub/google/cloud/pubsub_v1/subscriber/client.py b/pubsub/google/cloud/pubsub_v1/subscriber/client.py index fb73b59aeade..b255fe4767ca 100644 --- a/pubsub/google/cloud/pubsub_v1/subscriber/client.py +++ b/pubsub/google/cloud/pubsub_v1/subscriber/client.py @@ -50,7 +50,7 @@ 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`. + :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 @@ -117,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 @@ -213,8 +214,8 @@ def callback(message): how callbacks are executed concurrently. Returns: - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture: A - StreamingPullFuture 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)