Add spanner samples (#804)

.travis.yml

@@ -12,7 +12,7 @@ cache:
   - $HOME/.cache
 env:
   global:
-    secure: V8kTaIK8NYMEUVzaekLoVgJzz5/9yA/KKL8CVgOmiPEjt1o1wAXy+ojyXCgjGmB16OOcTYKtXKvOBndDg99MxUzMc9uLrHF4ub2fJZy3ZoCfPaxHNOpIOTTAhB8J/nog/JpW5NnJOBGE8fAQ/TUy8nSvOwe27n4qKO5eWqTy5kA=
+    secure: RPClDmwFZnpBIKtMvlzjzZVam4flvJtSvxFD8mHCQVQ//KqyBbQxl970kqStOK7p0RXkOB3XuFDvVixqyuptoQ8wTdgSBEPAub4DwRpcmCc1exzErHIt9zep3cQhSUuzl8N/tNl3o6GG04NsZTeErORqxfDvk3WbqFa9593G358=
 addons:
   apt:
     sources:
@@ -24,7 +24,6 @@ addons:
 install:
 - pip install --upgrade pip wheel virtualenv
 - pip install --upgrade nox-automation coverage
-# Temporarily install this from source.
 - pip install --upgrade git+https://github.com/dhermes/ci-diff-helper.git
 script:
 - ./scripts/travis.sh

conftest.py

@@ -32,6 +32,7 @@ def cloud_config():
         storage_bucket=os.environ.get('CLOUD_STORAGE_BUCKET'),
         client_secrets=os.environ.get('GOOGLE_CLIENT_SECRETS'),
         bigtable_instance=os.environ.get('BIGTABLE_CLUSTER'),
+        spanner_instance=os.environ.get('SPANNER_INSTANCE'),
         api_key=os.environ.get('API_KEY'))
 
 

nox.py

@@ -138,7 +138,7 @@ def _setup_appengine_sdk(session):
     '--cov-report', 'term']
 
 FLAKE8_COMMON_ARGS = [
-    '--show-source', '--builtin', 'gettext', '--max-complexity', '15',
+    '--show-source', '--builtin', 'gettext', '--max-complexity', '20',
     '--import-order-style', 'google',
     '--exclude', '.nox,.cache,env,lib,generated_pb2',
 ]

spanner/cloud-client/README.rst

@@ -0,0 +1,151 @@
+.. This file is automatically generated. Do not edit this file directly.
+
+Google Cloud Spanner Python Samples
+===============================================================================
+
+This directory contains samples for Google Cloud Spanner. `Google Cloud Spanner`_ is a highly scalable, transactional, managed, NewSQL database service. Cloud Spanner solves the need for a horizontally-scaling database with consistent global transactions and SQL semantics.
+
+
+
+
+.. _Google Cloud Spanner: https://cloud.google.com/spanner/docs 
+
+Setup
+-------------------------------------------------------------------------------
+
+
+Authentication
+++++++++++++++
+
+Authentication is typically done through `Application Default Credentials`_,
+which means you do not have to change the code to authenticate as long as
+your environment has credentials. You have a few options for setting up
+authentication:
+
+#. When running locally, use the `Google Cloud SDK`_
+
+    .. code-block:: bash
+
+        gcloud beta auth application-default login
+
+
+#. When running on App Engine or Compute Engine, credentials are already
+   set-up. However, you may need to configure your Compute Engine instance
+   with `additional scopes`_.
+
+#. You can create a `Service Account key file`_. This file can be used to
+   authenticate to Google Cloud Platform services from any environment. To use
+   the file, set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to
+   the path to the key file, for example:
+
+    .. code-block:: bash
+
+        export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service_account.json
+
+.. _Application Default Credentials: https://cloud.google.com/docs/authentication#getting_credentials_for_server-centric_flow
+.. _additional scopes: https://cloud.google.com/compute/docs/authentication#using
+.. _Service Account key file: https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount
+
+Install Dependencies
+++++++++++++++++++++
+
+#. Install `pip`_ and `virtualenv`_ if you do not already have them.
+
+#. Create a virtualenv. Samples are compatible with Python 2.7 and 3.4+.
+
+    .. code-block:: bash
+
+        $ virtualenv env
+        $ source env/bin/activate
+
+#. Install the dependencies needed to run the samples.
+
+    .. code-block:: bash
+
+        $ pip install -r requirements.txt
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/
+
+Samples
+-------------------------------------------------------------------------------
+
+Snippets
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+
+
+To run this sample:
+
+.. code-block:: bash
+
+    $ python snippets.py
+
+    usage: snippets.py [-h] [--database-name DATABASE_NAME]
+                       instance_name
+                       {insert_data,query_data,read_data,update_data,read_write_transaction,query_data_with_index,read_data_with_index,read_data_with_storing_index}
+                       ...
+    
+    This application demonstrates how to do basic operations using Cloud
+    Spanner.
+    
+    For more information, see the README.rst under /spanner.
+    
+    positional arguments:
+      instance_name         Your Cloud Spanner instance name.
+      {insert_data,query_data,read_data,update_data,read_write_transaction,query_data_with_index,read_data_with_index,read_data_with_storing_index}
+        insert_data         Inserts sample data into the given database. The
+                            database and table must already exist and can be
+                            created using `create_database`.
+        query_data          Queries sample data from the database using SQL.
+        read_data           Reads sample data from the database.
+        update_data         Updates sample data in the database. This updates the
+                            `MarketingBudget` column which must be created before
+                            running this sample. Run the following query on your
+                            database to create the column: ALTER TABLE Albums ADD
+                            COLUMN MarketingBudget INT64
+        read_write_transaction
+                            Performs a read-write transaction to update two sample
+                            records in the database. This will transfer 200,000
+                            from the `MarketingBudget` field for the first Album
+                            to the second Album. If the `MarketingBudget` is too
+                            low, it will raise an exception. Before running this
+                            sample, you will need to run the `update_data` sample
+                            to populate the fields.
+        query_data_with_index
+                            Inserts sample data into the given database. The
+                            database and table must already exist and can be
+                            created using `create_database`.
+        read_data_with_index
+                            Inserts sample data into the given database. The
+                            database and table must already exist and can be
+                            created using `create_database`.
+        read_data_with_storing_index
+                            Inserts sample data into the given database. The
+                            database and table must already exist and can be
+                            created using `create_database`.
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      --database-name DATABASE_NAME
+                            Your Cloud Spanner database name.
+
+
+
+
+The client library
+-------------------------------------------------------------------------------
+
+This sample uses the `Google Cloud Client Library for Python`_.
+You can read the documentation for more details on API usage and use GitHub
+to `browse the source`_ and  `report issues`_.
+
+.. Google Cloud Client Library for Python:
+    https://googlecloudplatform.github.io/google-cloud-python/
+.. browse the source:
+    https://github.com/GoogleCloudPlatform/google-cloud-python
+.. report issues:
+    https://github.com/GoogleCloudPlatform/google-cloud-python/issues
+
+
+.. _Google Cloud SDK: https://cloud.google.com/sdk/

spanner/cloud-client/README.rst.in

@@ -0,0 +1,22 @@
+# This file is used to generate README.rst
+
+product:
+  name: Google Cloud Spanner
+  short_name: Cloud Spanner
+  url: https://cloud.google.com/spanner/docs
+  description: > 
+    `Google Cloud Spanner`_ is a highly scalable, transactional, managed,
+    NewSQL database service. Cloud Spanner solves the need for a
+    horizontally-scaling database with consistent global transactions and
+    SQL semantics.
+
+setup:
+- auth
+- install_deps
+
+samples:
+- name: Snippets
+  file: snippets.py
+  show_help: true
+
+cloud_client_library: true

spanner/cloud-client/quickstart.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+
+# Copyright 2016 Google Inc. 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.
+# You may obtain a copy of the License at
+#
+#     http://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.
+
+
+def run_quickstart():
+    # [START spanner_quickstart]
+    # Imports the Google Cloud Client Library.
+    from google.cloud import spanner
+
+    # Instantiate a client.
+    spanner_client = spanner.Client()
+
+    # Your Cloud Spanner instance ID.
+    instance_id = 'my-instance-id'
+
+    # Get a Cloud Spanner instance by ID.
+    instance = spanner_client.instance(instance_id)
+
+    # Your Cloud Spanner database ID.
+    database_id = 'my-database-id'
+
+    # Get a Cloud Spanner database by ID.
+    database = instance.database(database_id)
+
+    # Execute a simple SQL statement.
+    results = database.execute_sql('SELECT 1')
+
+    for row in results:
+        print(row)
+    # [END spanner_quickstart]
+
+
+if __name__ == '__main__':
+    run_quickstart()

spanner/cloud-client/quickstart_test.py

@@ -0,0 +1,55 @@
+# Copyright 2016 Google Inc. 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.
+# You may obtain a copy of the License at
+#
+#     http://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.
+
+from google.cloud import spanner
+import google.cloud.exceptions
+import google.cloud.spanner.client
+import mock
+import pytest
+
+import quickstart
+
+
+@pytest.fixture
+def patch_instance(cloud_config):
+    original_instance = google.cloud.spanner.client.Client.instance
+
+    def new_instance(self, unused_instance_name):
+        return original_instance(self, cloud_config.spanner_instance)
+
+    instance_patch = mock.patch(
+        'google.cloud.spanner.client.Client.instance',
+        side_effect=new_instance,
+        autospec=True)
+
+    with instance_patch:
+        yield
+
+
+@pytest.fixture
+def example_database(cloud_config):
+    spanner_client = spanner.Client()
+    instance = spanner_client.instance(cloud_config.spanner_instance)
+    database = instance.database('my-database-id')
+
+    if not database.exists():
+        database.create()
+
+    yield
+
+
+def test_quickstart(capsys, patch_instance, example_database):
+    quickstart.run_quickstart()
+    out, _ = capsys.readouterr()
+    assert '[1]' in out

spanner/cloud-client/requirements.txt

@@ -0,0 +1 @@
+google-cloud-spanner==0.23.0