feat: add methods for listing snapshots (via synth) (#66)

* feat: add methods for listing snapshots (via synth) (#66)

* chore: manual regen

Co-authored-by: Bu Sun Kim <[email protected]>
Co-authored-by: Peter Lamut <[email protected]>

.coveragerc

@@ -1,3 +1,19 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Generated by synthtool. DO NOT EDIT!
 [run]
 branch = True

.flake8

@@ -1,3 +1,19 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Generated by synthtool. DO NOT EDIT!
 [flake8]
 ignore = E203, E266, E501, W503

.github/ISSUE_TEMPLATE/bug_report.md

@@ -11,8 +11,7 @@ Thanks for stopping by to let us know something could be better!
 Please run down the following list and make sure you've tried the usual "quick fixes":
 
   - Search the issues already opened: https://github.com/googleapis/python-pubsub/issues
-  - Search the issues on our "catch-all" repository: https://github.com/googleapis/google-cloud-python
-  - Search StackOverflow: http://stackoverflow.com/questions/tagged/google-cloud-platform+python
+  - Search StackOverflow: https://stackoverflow.com/questions/tagged/google-cloud-platform+python
 
 If you are still having issues, please be sure to include as much information as possible:
 

CONTRIBUTING.rst

@@ -22,7 +22,7 @@ In order to add a feature:
   documentation.
 
 - The feature must work fully on the following CPython versions:  2.7,
-  3.5, 3.6, and 3.7 on both UNIX and Windows.
+  3.5, 3.6, 3.7 and 3.8 on both UNIX and Windows.
 
 - The feature must not add unnecessary dependencies (where
   "unnecessary" is of course subjective, but new dependencies should
@@ -214,26 +214,18 @@ We support:
 -  `Python 3.5`_
 -  `Python 3.6`_
 -  `Python 3.7`_
+-  `Python 3.8`_
 
 .. _Python 3.5: https://docs.python.org/3.5/
 .. _Python 3.6: https://docs.python.org/3.6/
 .. _Python 3.7: https://docs.python.org/3.7/
+.. _Python 3.8: https://docs.python.org/3.8/
 
 
 Supported versions can be found in our ``noxfile.py`` `config`_.
 
 .. _config: https://github.com/googleapis/python-pubsub/blob/master/noxfile.py
 
-We explicitly decided not to support `Python 2.5`_ due to `decreased usage`_
-and lack of continuous integration `support`_.
-
-.. _Python 2.5: https://docs.python.org/2.5/
-.. _decreased usage: https://caremad.io/2013/10/a-look-at-pypi-downloads/
-.. _support: https://blog.travis-ci.com/2013-11-18-upcoming-build-environment-updates/
-
-We have `dropped 2.6`_ as a supported version as well since Python 2.6 is no
-longer supported by the core development team.
-
 Python 2.7 support is deprecated. All code changes should maintain Python 2.7 compatibility until January 1, 2020.
 
 We also explicitly decided to support Python 3 beginning with version
@@ -247,7 +239,6 @@ We also explicitly decided to support Python 3 beginning with version
 .. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django
 .. _projects: http://flask.pocoo.org/docs/0.10/python3/
 .. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/
-.. _dropped 2.6: https://github.com/googleapis/google-cloud-python/issues/995
 
 **********
 Versioning

MANIFEST.in

@@ -1,3 +1,19 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Generated by synthtool. DO NOT EDIT!
 include README.rst LICENSE
 recursive-include google *.json *.proto

google/cloud/pubsub_v1/gapic/publisher_client.py

@@ -364,10 +364,9 @@ def update_topic(
                 message :class:`~google.cloud.pubsub_v1.types.Topic`
             update_mask (Union[dict, ~google.cloud.pubsub_v1.types.FieldMask]): Required. Indicates which fields in the provided topic to update. Must
                 be specified and non-empty. Note that if ``update_mask`` contains
-                "message\_storage\_policy" then the new value will be determined based
-                on the policy configured at the project or organization level. The
-                ``message_storage_policy`` must not be set in the ``topic`` provided
-                above.
+                "message\_storage\_policy" but the ``message_storage_policy`` is not set
+                in the ``topic`` provided above, then the updated value is determined by
+                the policy configured at the project or organization level.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.pubsub_v1.types.FieldMask`
@@ -774,6 +773,113 @@ def list_topic_subscriptions(
         )
         return iterator
 
+    def list_topic_snapshots(
+        self,
+        topic,
+        page_size=None,
+        retry=google.api_core.gapic_v1.method.DEFAULT,
+        timeout=google.api_core.gapic_v1.method.DEFAULT,
+        metadata=None,
+    ):
+        """
+        Lists the names of the snapshots on this topic. Snapshots are used in
+        <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a>
+        operations, which allow
+        you to manage message acknowledgments in bulk. That is, you can set the
+        acknowledgment state of messages in an existing subscription to the state
+        captured by a snapshot.
+
+        Example:
+            >>> from google.cloud import pubsub_v1
+            >>>
+            >>> client = pubsub_v1.PublisherClient()
+            >>>
+            >>> topic = client.topic_path('[PROJECT]', '[TOPIC]')
+            >>>
+            >>> # Iterate over all results
+            >>> for element in client.list_topic_snapshots(topic):
+            ...     # process element
+            ...     pass
+            >>>
+            >>>
+            >>> # Alternatively:
+            >>>
+            >>> # Iterate over results one page at a time
+            >>> for page in client.list_topic_snapshots(topic).pages:
+            ...     for element in page:
+            ...         # process element
+            ...         pass
+
+        Args:
+            topic (str): Required. The name of the topic that snapshots are attached to. Format
+                is ``projects/{project}/topics/{topic}``.
+            page_size (int): The maximum number of resources contained in the
+                underlying API response. If page streaming is performed per-
+                resource, this parameter does not affect the return value. If page
+                streaming is performed per-page, this determines the maximum number
+                of resources in a page.
+            retry (Optional[google.api_core.retry.Retry]):  A retry object used
+                to retry requests. If ``None`` is specified, requests will
+                be retried using a default configuration.
+            timeout (Optional[float]): The amount of time, in seconds, to wait
+                for the request to complete. Note that if ``retry`` is
+                specified, the timeout applies to each individual attempt.
+            metadata (Optional[Sequence[Tuple[str, str]]]): Additional metadata
+                that is provided to the method.
+
+        Returns:
+            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.
+
+        Raises:
+            google.api_core.exceptions.GoogleAPICallError: If the request
+                    failed for any reason.
+            google.api_core.exceptions.RetryError: If the request failed due
+                    to a retryable error and retry attempts failed.
+            ValueError: If the parameters are invalid.
+        """
+        # Wrap the transport method to add retry and timeout logic.
+        if "list_topic_snapshots" not in self._inner_api_calls:
+            self._inner_api_calls[
+                "list_topic_snapshots"
+            ] = google.api_core.gapic_v1.method.wrap_method(
+                self.transport.list_topic_snapshots,
+                default_retry=self._method_configs["ListTopicSnapshots"].retry,
+                default_timeout=self._method_configs["ListTopicSnapshots"].timeout,
+                client_info=self._client_info,
+            )
+
+        request = pubsub_pb2.ListTopicSnapshotsRequest(topic=topic, page_size=page_size)
+        if metadata is None:
+            metadata = []
+        metadata = list(metadata)
+        try:
+            routing_header = [("topic", topic)]
+        except AttributeError:
+            pass
+        else:
+            routing_metadata = google.api_core.gapic_v1.routing_header.to_grpc_metadata(
+                routing_header
+            )
+            metadata.append(routing_metadata)
+
+        iterator = google.api_core.page_iterator.GRPCIterator(
+            client=None,
+            method=functools.partial(
+                self._inner_api_calls["list_topic_snapshots"],
+                retry=retry,
+                timeout=timeout,
+                metadata=metadata,
+            ),
+            request=request,
+            items_field="snapshots",
+            request_token_field="page_token",
+            response_token_field="next_page_token",
+        )
+        return iterator
+
     def delete_topic(
         self,
         topic,
@@ -858,15 +964,16 @@ def set_iam_policy(
         Sets the access control policy on the specified resource. Replaces
         any existing policy.
 
-        Can return Public Errors: NOT_FOUND, INVALID_ARGUMENT and
-        PERMISSION_DENIED
+        Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED`
+        errors.
 
         Example:
             >>> from google.cloud import pubsub_v1
             >>>
             >>> client = pubsub_v1.PublisherClient()
             >>>
-            >>> resource = client.topic_path('[PROJECT]', '[TOPIC]')
+            >>> # TODO: Initialize `resource`:
+            >>> resource = ''
             >>>
             >>> # TODO: Initialize `policy`:
             >>> policy = {}
@@ -948,7 +1055,8 @@ def get_iam_policy(
             >>>
             >>> client = pubsub_v1.PublisherClient()
             >>>
-            >>> resource = client.topic_path('[PROJECT]', '[TOPIC]')
+            >>> # TODO: Initialize `resource`:
+            >>> resource = ''
             >>>
             >>> response = client.get_iam_policy(resource)
 
@@ -1021,7 +1129,7 @@ def test_iam_permissions(
         """
         Returns permissions that a caller has on the specified resource. If the
         resource does not exist, this will return an empty set of
-        permissions, not a NOT_FOUND error.
+        permissions, not a `NOT_FOUND` error.
 
         Note: This operation is designed to be used for building
         permission-aware UIs and command-line tools, not for authorization
@@ -1032,7 +1140,8 @@ def test_iam_permissions(
             >>>
             >>> client = pubsub_v1.PublisherClient()
             >>>
-            >>> resource = client.topic_path('[PROJECT]', '[TOPIC]')
+            >>> # TODO: Initialize `resource`:
+            >>> resource = ''
             >>>
             >>> # TODO: Initialize `permissions`:
             >>> permissions = []

google/cloud/pubsub_v1/gapic/publisher_client_config.py

@@ -4,6 +4,7 @@
             "retry_codes": {
                 "idempotent": ["ABORTED", "UNAVAILABLE", "UNKNOWN"],
                 "non_idempotent": ["UNAVAILABLE"],
+                "idempotent2": ["DEADLINE_EXCEEDED", "UNAVAILABLE"],
                 "none": [],
                 "publish": [
                     "ABORTED",
@@ -73,6 +74,11 @@
                     "retry_codes_name": "idempotent",
                     "retry_params_name": "default",
                 },
+                "ListTopicSnapshots": {
+                    "timeout_millis": 60000,
+                    "retry_codes_name": "idempotent2",
+                    "retry_params_name": "default",
+                },
                 "DeleteTopic": {
                     "timeout_millis": 60000,
                     "retry_codes_name": "non_idempotent",