Spanner Beta

README.rst

@@ -34,6 +34,7 @@ The following client libraries have **beta** support:
 -  `Google BigQuery`_ (`BigQuery README`_)
 -  `Google Cloud Natural Language`_ (`Natural Language README`_)
 -  `Google Cloud Pub/Sub`_ (`Pub/Sub README`_)
+-  `Google Cloud Spanner`_ (`Spanner README`_)
 -  `Google Cloud Speech`_ (`Speech README`_)
 -  `Google Cloud Video Intelligence`_ (`Video Intelligence README`_)
 -  `Google Cloud Vision`_ (`Vision README`_)
@@ -50,7 +51,6 @@ Cloud Platform services:
 -  `Google Cloud DNS`_ (`DNS README`_)
 -  `Google Cloud Resource Manager`_ (`Resource Manager README`_)
 -  `Google Cloud Runtime Configuration`_ (`Runtime Config README`_)
--  `Google Cloud Spanner`_ (`Spanner README`_)
 -  `Stackdriver Error Reporting`_ (`Error Reporting README`_)
 -  `Stackdriver Monitoring`_ (`Monitoring README`_)
 

docs/conf.py

@@ -122,7 +122,6 @@
     'github_user': 'GoogleCloudPlatform',
     'github_repo': 'google-cloud-python',
     'github_banner': True,
-    'travis_button': True,
     'font_family': "'Roboto', Georgia, sans",
     'head_font_family': "'Roboto', Georgia, serif",
     'code_font_family': "'Roboto Mono', 'Consolas', monospace",

docs/spanner/api-reference.rst

@@ -0,0 +1,33 @@
+API Reference
+=============
+
+The following classes and methods constitute the Spanner client.
+Most likely, you will be interacting almost exclusively with these:
+
+.. toctree::
+    :maxdepth: 1
+
+    client-api
+    instance-api
+    database-api
+    session-api
+    keyset-api
+    snapshot-api
+    batch-api
+    transaction-api
+    streamed-api
+
+
+The classes and methods above depend on the following, lower-level
+classes and methods. Documentation for these is provided for completion,
+and some advanced use cases may wish to interact with these directly:
+
+.. toctree::
+    :maxdepth: 1
+
+    gapic/v1/api
+    gapic/v1/types
+    gapic/v1/admin_database_api
+    gapic/v1/admin_database_types
+    gapic/v1/admin_instance_api
+    gapic/v1/admin_instance_types

docs/spanner/batch-api.rst

@@ -1,8 +1,6 @@
 Batch API
 =========
 
-.. automodule:: google.cloud.spanner.batch
+.. automodule:: google.cloud.spanner_v1.batch
   :members:
   :show-inheritance:
-
-

docs/spanner/client-api.rst

@@ -1,7 +1,7 @@
 Spanner Client
 ==============
 
-.. automodule:: google.cloud.spanner.client
+.. automodule:: google.cloud.spanner_v1.client
   :members:
   :show-inheritance:
 

docs/spanner/database-api.rst

@@ -1,7 +1,7 @@
 Database API
 ============
 
-.. automodule:: google.cloud.spanner.database
+.. automodule:: google.cloud.spanner_v1.database
   :members:
   :show-inheritance:
 

docs/spanner/database-usage.rst

@@ -1,5 +1,5 @@
-Database Admin API
-==================
+Database Admin
+==============
 
 After creating a :class:`~google.cloud.spanner.instance.Instance`, you can
 interact with individual databases for that instance.
@@ -8,12 +8,16 @@ interact with individual databases for that instance.
 List Databases
 --------------
 
-To list of all existing databases for an instance, use its
+To iterate over all existing databases for an instance, use its
 :meth:`~google.cloud.spanner.instance.Instance.list_databases` method:
 
 .. code:: python
 
-    databases, token = instance.list_databases()
+    for database in instance.list_databases():
+        # `database` is a `Database` object.
+
+This method yields :class:`~.spanner_admin_database_v1.types.Database`
+objects.
 
 
 Database Factory
@@ -49,9 +53,9 @@ trigger its creation on the server:
 .. note::
 
     Creating an instance triggers a "long-running operation" and
-    returns an :class:`google.cloud.spanner.database.Operation`
-    object.  See :ref:`check-on-current-database-operation` for polling
-    to find out if the operation is completed.
+    returns an :class:`~concurrent.futures.Future`-like object. Use
+    the :meth:`~concurrent.futures.Future.result` method to wait for
+    and inspect the result.
 
 
 Update an existing Database
@@ -96,26 +100,13 @@ Check on Current Database Operation
 The :meth:`~google.cloud.spanner.database.Database.create` and
 :meth:`~google.cloud.spanner.database.Database.update` methods of instance
 object trigger long-running operations on the server, and return instances
-of the :class:`~google.cloud.spanner.database.Operation` class.
-
-You can check if a long-running operation has finished
-by using its :meth:`~google.cloud.spanner.database.Operation.finished`
-method:
+conforming to the :class:`~.concurrent.futures.Future` class.
 
 .. code:: python
 
     >>> operation = instance.create()
-    >>> operation.finished()
-    True
+    >>> operation.result()
 
-.. note::
-
-    Once an :class:`~google.cloud.spanner.instance.Operation` object
-    has returned :data:`True` from its
-    :meth:`~google.cloud.spanner.instance.Operation.finished` method, the
-    object should not be re-used. Subsequent calls to
-    :meth:`~google.cloud.spanner.instance.Operation.finished`
-    will result in an :exc`ValueError` being raised.
 
 Non-Admin Database Usage
 ========================
@@ -220,12 +211,15 @@ constructor:
 
 .. code-block:: python
 
-   from google.cloud.spanner import Client
-   from google.cloud.spanner import FixedSizePool
-   client = Client()
-   instance = client.instance(INSTANCE_NAME)
-   pool = FixedSizePool(size=10, default_timeout=5)
-   database = instanc.database(DATABASE_NAME, pool=pool)
+    from google.cloud import spanner
+
+    # Instantiate the Spanner client, and get the appropriate instance.
+    client = spanner.Client()
+    instance = client.instance(INSTANCE_NAME)
+
+    # Create a database with a pool of a fixed size.
+    pool = spanner.FixedSizePool(size=10, default_timeout=5)
+    database = instance.database(DATABASE_NAME, pool=pool)
 
 Note that creating a database with a pool may presume that its database
 already exists, as it may need to pre-create sessions (rather than creating

docs/spanner/gapic/v1/admin_database_api.rst

@@ -0,0 +1,6 @@
+Spanner Admin Database Client API
+=================================
+
+.. automodule:: google.cloud.spanner_admin_database_v1
+  :members:
+  :inherited-members:

docs/spanner/gapic/v1/admin_database_types.rst

@@ -0,0 +1,5 @@
+Spanner Admin Database Client Types
+===================================
+
+.. automodule:: google.cloud.spanner_admin_database_v1.types
+  :members:

docs/spanner/gapic/v1/admin_instance_api.rst

@@ -0,0 +1,6 @@
+Spanner Admin Instance Client API
+=================================
+
+.. automodule:: google.cloud.spanner_admin_instance_v1
+  :members:
+  :inherited-members:

docs/spanner/gapic/v1/admin_instance_types.rst

@@ -0,0 +1,5 @@
+Spanner Admin Instance Client Types
+===================================
+
+.. automodule:: google.cloud.spanner_admin_instance_v1.types
+  :members:

docs/spanner/gapic/v1/api.rst

@@ -0,0 +1,6 @@
+Spanner Client API
+==================
+
+.. automodule:: google.cloud.spanner_v1
+  :members:
+  :inherited-members: