Prep spanner release.

googleapis · Feb 14, 2017 · 6449b1c · 6449b1c
1 parent e4661b0
commit 6449b1c
Show file tree

Hide file tree

Showing 64 changed files with 12,402 additions and 18 deletions.
diff --git a/README.rst b/README.rst
@@ -42,6 +42,7 @@ Cloud Platform services:
 -  `Google Cloud Vision`_ (`Vision README`_)
 -  `Google Cloud Bigtable - HappyBase`_ (`HappyBase README`_)
 -  `Google Cloud Runtime Configuration`_ (`Runtime Config README`_)
+-  `Cloud Spanner`_ (`Cloud Spanner README`_)
 
 **Alpha** indicates that the client library for a particular service is
 still a work-in-progress and is more likely to get backwards-incompatible
@@ -79,6 +80,8 @@ updates. See `versioning`_ for more details.
 .. _HappyBase README: https://github.com/GoogleCloudPlatform/google-cloud-python-happybase
 .. _Google Cloud Runtime Configuration: https://cloud.google.com/deployment-manager/runtime-configurator/
 .. _Runtime Config README: https://github.com/GoogleCloudPlatform/google-cloud-python/tree/master/runtimeconfig
+.. _Cloud Spanner: https://cloud.google.com/spanner/
+.. _Cloud Spanner README: https://github.com/GoogleCloudPlatform/google-cloud-python/tree/master/spanner
 .. _versioning: https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/CONTRIBUTING.rst#versioning
 
 If you need support for other Google APIs, check out the

diff --git a/bigtable/google/cloud/bigtable/client.py b/bigtable/google/cloud/bigtable/client.py
@@ -18,12 +18,14 @@
 
 In the hierarchy of API concepts
 
-* a :class:`Client` owns an :class:`.Instance`
-* an :class:`.Instance` owns a :class:`~google.cloud.bigtable.table.Table`
+* a :class:`~google.cloud.bigtable.client.Client` owns an
+  :class:`~google.cloud.bigtable.instance.Instance`
+* an :class:`~google.cloud.bigtable.instance.Instance` owns a
+  :class:`~google.cloud.bigtable.table.Table`
 * a :class:`~google.cloud.bigtable.table.Table` owns a
   :class:`~.column_family.ColumnFamily`
-* a :class:`~google.cloud.bigtable.table.Table` owns a :class:`~.row.Row`
-  (and all the cells in the row)
+* a :class:`~google.cloud.bigtable.table.Table` owns a
+  :class:`~google.cloud.bigtable.row.Row` (and all the cells in the row)
 """
 
 
@@ -342,7 +344,7 @@ def instance(self, instance_id, location=_EXISTING_INSTANCE_LOCATION_ID,
         :param serve_nodes: (Optional) The number of nodes in the instance's
                             cluster; used to set up the instance's cluster.
 
-        :rtype: :class:`.Instance`
+        :rtype: :class:`~google.cloud.bigtable.instance.Instance`
         :returns: an instance owned by this client.
         """
         return Instance(instance_id, self, location,
@@ -353,8 +355,9 @@ def list_instances(self):
 
         :rtype: tuple
         :returns: A pair of results, the first is a list of
-                  :class:`.Instance` objects returned and the second is a
-                  list of strings (the failed locations in the request).
+                  :class:`~google.cloud.bigtable.instance.Instance` objects
+                  returned and the second is a list of strings (the failed
+                  locations in the request).
         """
         request_pb = bigtable_instance_admin_pb2.ListInstancesRequest(
             parent=self.project_name)

diff --git a/bigtable/google/cloud/bigtable/cluster.py b/bigtable/google/cloud/bigtable/cluster.py
@@ -72,7 +72,7 @@ class Cluster(object):
     :type cluster_id: str
     :param cluster_id: The ID of the cluster.
 
-    :type instance: :class:`.instance.Instance`
+    :type instance: :class:`~google.cloud.bigtable.instance.Instance`
     :param instance: The instance where the cluster resides.
 
     :type serve_nodes: int
@@ -104,7 +104,7 @@ def from_pb(cls, cluster_pb, instance):
         :type cluster_pb: :class:`instance_pb2.Cluster`
         :param cluster_pb: A cluster protobuf object.
 
-        :type instance: :class:`.instance.Instance>`
+        :type instance: :class:`~google.cloud.bigtable.instance.Instance>`
         :param instance: The instance that owns the cluster.
 
         :rtype: :class:`Cluster`

diff --git a/bigtable/google/cloud/bigtable/table.py b/bigtable/google/cloud/bigtable/table.py
@@ -49,7 +49,7 @@ class Table(object):
     :type table_id: str
     :param table_id: The ID of the table.
 
-    :type instance: :class:`Instance <.instance.Instance>`
+    :type instance: :class:`~google.cloud.bigtable.instance.Instance`
     :param instance: The instance that owns the table.
     """
 

diff --git a/datastore/google/cloud/datastore/client.py b/datastore/google/cloud/datastore/client.py
@@ -253,7 +253,8 @@ def get(self, key, missing=None, deferred=None, transaction=None):
         :param deferred: (Optional) If a list is passed, the keys returned
                          by the backend as "deferred" will be copied into it.
 
-        :type transaction: :class:`~.transaction.Transaction`
+        :type transaction:
+            :class:`~google.cloud.datastore.transaction.Transaction`
         :param transaction: (Optional) Transaction to use for read consistency.
                             If not passed, uses current transaction, if set.
 
@@ -281,7 +282,8 @@ def get_multi(self, keys, missing=None, deferred=None, transaction=None):
                          by the backend as "deferred" will be copied into it.
                          If the list is not empty, an error will occur.
 
-        :type transaction: :class:`~.transaction.Transaction`
+        :type transaction:
+            :class:`~google.cloud.datastore.transaction.Transaction`
         :param transaction: (Optional) Transaction to use for read consistency.
                             If not passed, uses current transaction, if set.
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -197,6 +197,32 @@
   runtimeconfig-config
   runtimeconfig-variable
 
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+  :caption: Spanner
+
+  spanner-usage
+  spanner-client-usage
+  spanner-instance-usage
+  spanner-database-usage
+  spanner-session-crud-usage
+  spanner-session-implicit-txn-usage
+  spanner-session-pool-usage
+  spanner-batch-usage
+  spanner-snapshot-usage
+  spanner-transaction-usage
+
+  spanner-client-api
+  spanner-instance-api
+  spanner-database-api
+  spanner-session-api
+  spanner-keyset-api
+  spanner-snapshot-api
+  spanner-batch-api
+  spanner-transaction-api
+  spanner-streamed-api
+
 .. toctree::
   :maxdepth: 0
   :hidden:

diff --git a/docs/spanner-batch-api.rst b/docs/spanner-batch-api.rst
@@ -0,0 +1,8 @@
+Batch API
+=========
+
+.. automodule:: google.cloud.spanner.batch
+  :members:
+  :show-inheritance:
+
+
diff --git a/docs/spanner-batch-usage.rst b/docs/spanner-batch-usage.rst
@@ -0,0 +1,179 @@
+Batching Modifications
+######################
+
+A :class:`~google.cloud.spanner.batch.Batch` represents a set of data
+modification operations to be performed on tables in a dataset.  Use of a
+``Batch`` does not require creating an explicit
+:class:`~google.cloud.spanner.snapshot.Snapshot` or
+:class:`~google.cloud.spanner.transaction.Transaction`.  Until
+:meth:`~google.cloud.spanner.batch.Batch.commit` is called on a ``Batch``,
+no changes are propagated to the back-end.
+
+
+Starting a Batch
+----------------
+
+.. code:: python
+
+    batch = session.batch()
+
+
+Inserting records using a Batch
+-------------------------------
+
+:meth:`Batch.insert` adds one or more new records to a table.  Fails if
+any of the records already exists.
+
+.. code:: python
+
+    batch.insert(
+        'citizens', columns=['email', 'first_name', 'last_name', 'age'],
+        values=[
+            ['[email protected]', 'Phred', 'Phlyntstone', 32],
+            ['[email protected]', 'Bharney', 'Rhubble', 31],
+        ])
+
+.. note::
+
+    Ensure that data being sent for ``STRING`` columns uses a text string
+    (``str`` in Python 3; ``unicode`` in Python 2).
+
+    Additionally, if you are writing data intended for a ``BYTES`` column, you
+    must base64 encode it.
+
+
+Update records using a Batch
+-------------------------------
+
+:meth:`Batch.update` updates one or more existing records in a table.  Fails
+if any of the records does not already exist.
+
+.. code:: python
+
+    batch.update(
+        'citizens', columns=['email', 'age'],
+        values=[
+            ['[email protected]', 33],
+            ['[email protected]', 32],
+        ])
+
+.. note::
+
+    Ensure that data being sent for ``STRING`` columns uses a text string
+    (``str`` in Python 3; ``unicode`` in Python 2).
+
+    Additionally, if you are writing data intended for a ``BYTES`` column, you
+    must base64 encode it.
+
+
+Insert or update records using a Batch
+--------------------------------------
+
+:meth:`Batch.insert_or_update` inserts *or* updates one or more records in a
+table.  Existing rows have values for the supplied columns overwritten;  other
+column values are preserved.
+
+.. code:: python
+
+    batch.insert_or_update(
+        'citizens', columns=['email', 'first_name', 'last_name', 'age'],
+        values=[
+            ['[email protected]', 'Phred', 'Phlyntstone', 31],
+            ['[email protected]', 'Wylma', 'Phlyntstone', 29],
+        ])
+
+.. note::
+
+    Ensure that data being sent for ``STRING`` columns uses a text string
+    (``str`` in Python 3; ``unicode`` in Python 2).
+
+    Additionally, if you are writing data intended for a ``BYTES`` column, you
+    must base64 encode it.
+
+
+Replace records using a Batch
+-----------------------------
+
+:meth:`Batch.replace` inserts *or* updates one or more records in a
+table.  Existing rows have values for the supplied columns overwritten;  other
+column values are set to null.
+
+.. code:: python
+
+    batch.replace(
+        'citizens', columns=['email', 'first_name', 'last_name', 'age'],
+        values=[
+            ['[email protected]', 'Bharney', 'Rhubble', 30],
+            ['[email protected]', 'Bhettye', 'Rhubble', 30],
+        ])
+
+.. note::
+
+    Ensure that data being sent for ``STRING`` columns uses a text string
+    (``str`` in Python 3; ``unicode`` in Python 2).
+
+    Additionally, if you are writing data intended for a ``BYTES`` column, you
+    must base64 encode it.
+
+
+Delete records using a Batch
+----------------------------
+
+:meth:`Batch.delete` removes one or more records from a table.  Non-existent
+rows do not cause errors.
+
+.. code:: python
+
+    batch.delete('citizens',
+        keyset['[email protected]', '[email protected]'])
+
+
+Commit changes for a Batch
+--------------------------
+
+After describing the modifications to be made to table data via the
+:meth:`Batch.insert`, :meth:`Batch.update`, :meth:`Batch.insert_or_update`,
+:meth:`Batch.replace`, and :meth:`Batch.delete` methods above, send them to
+the back-end by calling :meth:`Batch.commit`, which makes the ``Commit``
+API call.
+
+.. code:: python
+
+    batch.commit()
+
+
+Use a Batch as a Context Manager
+--------------------------------
+
+Rather than calling :meth:`Batch.commit` manually, you can use the
+:class:`Batch` instance as a context manager, and have it called automatically
+if the ``with`` block exits without raising an exception.
+
+.. code:: python
+
+    with session.batch() as batch:
+
+        batch.insert(
+            'citizens', columns=['email', 'first_name', 'last_name', 'age'],
+            values=[
+                ['[email protected]', 'Phred', 'Phlyntstone', 32],
+                ['[email protected]', 'Bharney', 'Rhubble', 31],
+            ])
+
+        batch.update(
+            'citizens', columns=['email', 'age'],
+            values=[
+                ['[email protected]', 33],
+                ['[email protected]', 32],
+            ])
+
+        ...
+
+        batch.delete('citizens',
+            keyset['[email protected]', '[email protected]'])
+
+
+Next Step
+---------
+
+Next, learn about :doc:`spanner-snapshot-usage`.
diff --git a/docs/spanner-client-api.rst b/docs/spanner-client-api.rst
@@ -0,0 +1,7 @@
+Spanner Client
+==============
+
+.. automodule:: google.cloud.spanner.client
+  :members:
+  :show-inheritance:
+