docs: add samples from bigquery/cloud-client

.github/CODEOWNERS

@@ -0,0 +1,9 @@
+# Code owners file.
+# This file controls who is tagged for review for any given pull request.
+#
+# For syntax help see:
+# https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners#codeowners-syntax
+
+
+/samples/   @shollyman @googleapis/python-samples-owners
+

docs/conf.py

@@ -90,7 +90,12 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build"]
+exclude_patterns = [
+    "_build",
+    "samples/AUTHORING_GUIDE.md",
+    "samples/CONTRIBUTING.md",
+    "samples/snippets/README.rst",
+]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

noxfile.py

@@ -113,8 +113,10 @@ def snippets(session):
     session.install("-e", ".[all]")
 
     # Run py.test against the snippets tests.
+    # Skip tests in samples/snippets, as those are run in a different session
+    # using the nox config from that directory.
     session.run("py.test", os.path.join("docs", "snippets.py"), *session.posargs)
-    session.run("py.test", "samples", *session.posargs)
+    session.run("py.test", "samples", "--ignore=samples/snippets", *session.posargs)
 
 
 @nox.session(python="3.8")

samples/AUTHORING_GUIDE.md

@@ -0,0 +1 @@
+See https://github.com/GoogleCloudPlatform/python-docs-samples/blob/master/AUTHORING_GUIDE.md

samples/CONTRIBUTING.md

@@ -0,0 +1 @@
+See https://github.com/GoogleCloudPlatform/python-docs-samples/blob/master/CONTRIBUTING.md

samples/snippets/.gitignore

@@ -0,0 +1,2 @@
+client_secrets.json
+service_account.json

samples/snippets/README.rst

@@ -0,0 +1,166 @@
+
+.. This file is automatically generated. Do not edit this file directly.
+
+Google BigQuery Python Samples
+===============================================================================
+
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+   :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor=bigquery/cloud-client/README.rst
+
+
+This directory contains samples for Google BigQuery. `Google BigQuery`_ is Google's fully managed, petabyte scale, low cost analytics data warehouse. BigQuery is NoOps—there is no infrastructure to manage and you don't need a database administrator—so you can focus on analyzing data to find meaningful insights, use familiar SQL, and take advantage of our pay-as-you-go model.
+
+
+
+
+.. _Google BigQuery: https://cloud.google.com/bigquery/docs
+
+
+Setup
+-------------------------------------------------------------------------------
+
+
+
+Authentication
+++++++++++++++
+
+This sample requires you to have authentication setup. Refer to the
+`Authentication Getting Started Guide`_ for instructions on setting up
+credentials for applications.
+
+.. _Authentication Getting Started Guide:
+    https://cloud.google.com/docs/authentication/getting-started
+
+
+
+
+Install Dependencies
+++++++++++++++++++++
+
+#. Clone python-docs-samples and change directory to the sample directory you want to use.
+
+    .. code-block:: bash
+
+        $ git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
+
+#. Install `pip`_ and `virtualenv`_ if you do not already have them. You may want to refer to the `Python Development Environment Setup Guide`_ for Google Cloud Platform for instructions.
+
+   .. _Python Development Environment Setup Guide:
+       https://cloud.google.com/python/setup
+
+#. Create a virtualenv. Samples are compatible with Python 3.6+.
+
+    .. 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
+-------------------------------------------------------------------------------
+
+
+Quickstart
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+   :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor=bigquery/cloud-client/quickstart.py,bigquery/cloud-client/README.rst
+
+
+
+
+To run this sample:
+
+.. code-block:: bash
+
+    $ python quickstart.py
+
+
+
+
+Simple Application
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+   :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor=bigquery/cloud-client/simple_app.py,bigquery/cloud-client/README.rst
+
+
+
+
+To run this sample:
+
+.. code-block:: bash
+
+    $ python simple_app.py
+
+
+
+
+User Credentials
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+   :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor=bigquery/cloud-client/user_credentials.py,bigquery/cloud-client/README.rst
+
+
+
+
+To run this sample:
+
+.. code-block:: bash
+
+    $ python user_credentials.py
+
+
+    usage: user_credentials.py [-h] [--launch-browser] project
+
+    Command-line application to run a query using user credentials.
+
+    You must supply a client secrets file, which would normally be bundled with
+    your application.
+
+    positional arguments:
+      project           Project to use for BigQuery billing.
+
+    optional arguments:
+      -h, --help        show this help message and exit
+      --launch-browser  Use a local server flow to authenticate.
+
+
+
+
+
+
+
+
+
+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/

samples/snippets/README.rst.in

@@ -0,0 +1,31 @@
+# This file is used to generate README.rst
+
+product:
+  name: Google BigQuery
+  short_name: BigQuery
+  url: https://cloud.google.com/bigquery/docs
+  description: >
+    `Google BigQuery`_ is Google's fully managed, petabyte scale, low cost
+    analytics data warehouse. BigQuery is NoOps—there is no infrastructure to
+    manage and you don't need a database administrator—so you can focus on
+    analyzing data to find meaningful insights, use familiar SQL, and take
+    advantage of our pay-as-you-go model.
+
+required_role: BigQuery Admin
+
+setup:
+- auth
+- install_deps
+
+samples:
+- name: Quickstart
+  file: quickstart.py
+- name: Simple Application
+  file: simple_app.py
+- name: User Credentials
+  file: user_credentials.py
+  show_help: true
+
+cloud_client_library: true
+
+folder: bigquery/cloud-client

samples/snippets/authenticate_service_account.py

@@ -0,0 +1,39 @@
+# Copyright 2019 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.
+
+import os
+
+
+def main():
+    key_path = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
+
+    # [START bigquery_client_json_credentials]
+    from google.cloud import bigquery
+    from google.oauth2 import service_account
+
+    # TODO(developer): Set key_path to the path to the service account key
+    #                  file.
+    # key_path = "path/to/service_account.json"
+
+    credentials = service_account.Credentials.from_service_account_file(
+        key_path, scopes=["https://www.googleapis.com/auth/cloud-platform"],
+    )
+
+    client = bigquery.Client(credentials=credentials, project=credentials.project_id,)
+    # [END bigquery_client_json_credentials]
+    return client
+
+
+if __name__ == "__main__":
+    main()

samples/snippets/authenticate_service_account_test.py

@@ -0,0 +1,33 @@
+# Copyright 2019 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.
+
+import google.auth
+
+import authenticate_service_account
+
+
+def mock_credentials(*args, **kwargs):
+    credentials, _ = google.auth.default(
+        ["https://www.googleapis.com/auth/cloud-platform"]
+    )
+    return credentials
+
+
+def test_main(monkeypatch):
+    monkeypatch.setattr(
+        "google.oauth2.service_account.Credentials.from_service_account_file",
+        mock_credentials,
+    )
+    client = authenticate_service_account.main()
+    assert client is not None