Move google.cloud.future to google.api.core (googleapis#3764)

bigquery/google/cloud/bigquery/job.py

@@ -19,6 +19,7 @@
 import six
 from six.moves import http_client
 
+import google.api.core.future.polling
 from google.cloud import exceptions
 from google.cloud.exceptions import NotFound
 from google.cloud._helpers import _datetime_from_microseconds
@@ -31,7 +32,6 @@
 from google.cloud.bigquery._helpers import UDFResourcesProperty
 from google.cloud.bigquery._helpers import _EnumProperty
 from google.cloud.bigquery._helpers import _TypedProperty
-import google.cloud.future.polling
 
 _DONE_STATE = 'DONE'
 _STOPPED_REASON = 'stopped'
@@ -140,7 +140,7 @@ class WriteDisposition(_EnumProperty):
     WRITE_EMPTY = 'WRITE_EMPTY'
 
 
-class _AsyncJob(google.cloud.future.polling.PollingFuture):
+class _AsyncJob(google.api.core.future.polling.PollingFuture):
     """Base class for asynchronous jobs.
 
     :type name: str
@@ -496,7 +496,7 @@ def cancelled(self):
 
         This always returns False. It's not possible to check if a job was
         cancelled in the API. This method is here to satisfy the interface
-        for :class:`google.cloud.future.Future`.
+        for :class:`google.api.core.future.Future`.
 
         :rtype: bool
         :returns: False

bigtable/google/cloud/bigtable/cluster.py

@@ -17,11 +17,11 @@
 
 import re
 
+from google.api.core import operation
 from google.cloud.bigtable._generated import (
     instance_pb2 as data_v2_pb2)
 from google.cloud.bigtable._generated import (
     bigtable_instance_admin_pb2 as messages_v2_pb2)
-from google.cloud.future import operation
 
 _CLUSTER_NAME_RE = re.compile(r'^projects/(?P<project>[^/]+)/'
                               r'instances/(?P<instance>[^/]+)/clusters/'

bigtable/google/cloud/bigtable/instance.py

@@ -17,6 +17,7 @@
 
 import re
 
+from google.api.core import operation
 from google.cloud.bigtable._generated import (
     instance_pb2 as data_v2_pb2)
 from google.cloud.bigtable._generated import (
@@ -26,7 +27,6 @@
 from google.cloud.bigtable.cluster import Cluster
 from google.cloud.bigtable.cluster import DEFAULT_SERVE_NODES
 from google.cloud.bigtable.table import Table
-from google.cloud.future import operation
 
 
 _EXISTING_INSTANCE_LOCATION_ID = 'see-existing-cluster'

bigtable/tests/unit/test_cluster.py

@@ -233,8 +233,8 @@ def test_reload(self):
         self.assertEqual(cluster.location, LOCATION)
 
     def test_create(self):
+        from google.api.core import operation
         from google.longrunning import operations_pb2
-        from google.cloud.future import operation
         from google.cloud.bigtable._generated import (
             bigtable_instance_admin_pb2 as messages_v2_pb2)
         from tests.unit._testing import _FakeStub
@@ -275,8 +275,8 @@ def test_create(self):
 
     def test_update(self):
         import datetime
+        from google.api.core import operation
         from google.longrunning import operations_pb2
-        from google.cloud.future import operation
         from google.protobuf.any_pb2 import Any
         from google.cloud._helpers import _datetime_to_pb_timestamp
         from google.cloud.bigtable._generated import (

bigtable/tests/unit/test_instance.py

@@ -232,13 +232,13 @@ def test_reload(self):
 
     def test_create(self):
         import datetime
+        from google.api.core import operation
         from google.longrunning import operations_pb2
         from google.protobuf.any_pb2 import Any
         from google.cloud.bigtable._generated import (
             bigtable_instance_admin_pb2 as messages_v2_pb2)
         from google.cloud._helpers import _datetime_to_pb_timestamp
         from tests.unit._testing import _FakeStub
-        from google.cloud.future import operation
         from google.cloud.bigtable.cluster import DEFAULT_SERVE_NODES
 
         NOW = datetime.datetime.utcnow()
@@ -285,11 +285,11 @@ def test_create(self):
         self.assertEqual(kwargs, {})
 
     def test_create_w_explicit_serve_nodes(self):
+        from google.api.core import operation
         from google.longrunning import operations_pb2
         from google.cloud.bigtable._generated import (
             bigtable_instance_admin_pb2 as messages_v2_pb2)
         from tests.unit._testing import _FakeStub
-        from google.cloud.future import operation
 
         SERVE_NODES = 5
 

core/google/cloud/future/__init__.py → core/google/api/core/future/__init__.py

@@ -14,7 +14,7 @@
 
 """Futures for dealing with asynchronous operations."""
 
-from google.cloud.future.base import Future
+from google.api.core.future.base import Future
 
 __all__ = [
     'Future',

core/google/cloud/future/polling.py → core/google/api/core/future/polling.py

@@ -22,8 +22,8 @@
 import six
 import tenacity
 
-from google.cloud.future import _helpers
-from google.cloud.future import base
+from google.api.core.future import _helpers
+from google.api.core.future import base
 
 
 class PollingFuture(base.Future):

core/google/cloud/future/operation.py → core/google/api/core/operation.py

@@ -12,14 +12,36 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Futures for long-running operations returned from Google Cloud APIs."""
+"""Futures for long-running operations returned from Google Cloud APIs.
+
+These futures can be used to synchronously wait for the result of a
+long-running operation using :meth:`Operation.result`:
+
+
+.. code-block:: python
+
+    operation = my_api_client.long_running_method()
+    result = operation.result()
+
+Or asynchronously using callbacks and :meth:`Operation.add_done_callback`:
+
+.. code-block:: python
+
+    operation = my_api_client.long_running_method()
+
+    def my_callback(future):
+        result = future.result()
+
+    operation.add_done_callback(my_callback)
+
+"""
 
 import functools
 import threading
 
+from google.api.core import exceptions
+from google.api.core.future import polling
 from google.cloud import _helpers
-from google.cloud import exceptions
-from google.cloud.future import polling
 from google.longrunning import operations_pb2
 from google.protobuf import json_format
 from google.rpc import code_pb2
@@ -85,12 +107,13 @@ def _set_result_from_operation(self):
                     self._result_type, self._operation.response)
                 self.set_result(response)
             elif self._operation.HasField('error'):
-                exception = exceptions.GoogleCloudError(
+                exception = exceptions.GoogleAPICallError(
                     self._operation.error.message,
-                    errors=(self._operation.error))
+                    errors=(self._operation.error),
+                    response=self._operation)
                 self.set_exception(exception)
             else:
-                exception = exceptions.GoogleCloudError(
+                exception = exceptions.GoogleAPICallError(
                     'Unexpected state: Long-running operation had neither '
                     'response nor error set.')
                 self.set_exception(exception)

core/tests/unit/future/test__helpers.py → core/tests/unit/api_core/future/test__helpers.py

@@ -14,7 +14,7 @@
 
 import mock
 
-from google.cloud.future import _helpers
+from google.api.core.future import _helpers
 
 
 @mock.patch('threading.Thread', autospec=True)

core/tests/unit/future/test_polling.py → core/tests/unit/api_core/future/test_polling.py

@@ -19,7 +19,7 @@
 import mock
 import pytest
 
-from google.cloud.future import polling
+from google.api.core.future import polling
 
 
 class PollingFutureImpl(polling.PollingFuture):

core/tests/unit/future/test_operation.py → core/tests/unit/api_core/test_operation.py

@@ -15,7 +15,7 @@
 
 import mock
 
-from google.cloud.future import operation
+from google.api.core import operation
 from google.longrunning import operations_pb2
 from google.protobuf import struct_pb2
 from google.rpc import code_pb2

spanner/google/cloud/spanner/database.py

@@ -185,7 +185,7 @@ def create(self):
         See
         https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase
 
-        :rtype: :class:`~google.cloud.future.operation.Operation`
+        :rtype: :class:`~google.api.core.operation.Operation`
         :returns: a future used to poll the status of the create request
         :raises Conflict: if the database already exists
         :raises NotFound: if the instance owning the database does not exist
@@ -269,7 +269,7 @@ def update_ddl(self, ddl_statements):
         See
         https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabase
 
-        :rtype: :class:`google.cloud.future.operation.Operation`
+        :rtype: :class:`google.api.core.operation.Operation`
         :returns: an operation instance
         :raises NotFound: if the database does not exist
         :raises GaxError:

spanner/google/cloud/spanner/instance.py

@@ -198,7 +198,7 @@ def create(self):
 
            before calling :meth:`create`.
 
-        :rtype: :class:`google.cloud.future.operation.Operation`
+        :rtype: :class:`google.api.core.operation.Operation`
         :returns: an operation instance
         :raises Conflict: if the instance already exists
         :raises GaxError:
@@ -289,7 +289,7 @@ def update(self):
 
             before calling :meth:`update`.
 
-        :rtype: :class:`google.cloud.future.operation.Operation`
+        :rtype: :class:`google.api.core.operation.Operation`
         :returns: an operation instance
         :raises NotFound: if the instance does not exist
         :raises GaxError: for other errors returned from the call