doc: update resource docstrings (#60)

* changes without context

        autosynth cannot find the source of changes triggered by earlier changes in this
        repository, or by version upgrades to tools such as linters.

* chore(python): use BUILD_SPECIFIC_GCLOUD_PROJECT for samples

https://github.com/googleapis/python-talent/blob/ef045e8eb348db36d7a2a611e6f26b11530d273b/samples/snippets/noxfile_config.py#L27-L32

`BUILD_SPECIFIC_GCLOUD_PROJECT` is an alternate project used for sample tests that do poorly with concurrent runs on the same project.

Source-Author: Bu Sun Kim <8822365+busunkim96@users.noreply.github.com>
Source-Date: Wed Sep 30 13:06:03 2020 -0600
Source-Repo: googleapis/synthtool
Source-Sha: 9b0da5204ab90bcc36f8cd4e5689eff1a54cc3e4
Source-Link: googleapis/synthtool@9b0da52

* chore(python): use 'setup.py' to detect repo root

Closes #792

Source-Author: Bu Sun Kim <8822365+busunkim96@users.noreply.github.com>
Source-Date: Fri Oct 9 15:06:33 2020 -0600
Source-Repo: googleapis/synthtool
Source-Sha: e0ae456852bf22f38796deb79cff30b516fde244
Source-Link: googleapis/synthtool@e0ae456

* build(python): samples tests should pass if no samples exist

Source-Author: Daniel Sanche <d.sanche14@gmail.com>
Source-Date: Wed Oct 14 08:00:06 2020 -0700
Source-Repo: googleapis/synthtool
Source-Sha: 477764cc4ee6db346d3febef2bb1ea0abf27de52
Source-Link: googleapis/synthtool@477764c

.kokoro/samples/python3.6/common.cfg

@@ -13,6 +13,12 @@ env_vars: {
     value: "py-3.6"
 }
 
+# Declare build specific Cloud project.
+env_vars: {
+    key: "BUILD_SPECIFIC_GCLOUD_PROJECT"
+    value: "python-docs-samples-tests-py36"
+}
+
 env_vars: {
     key: "TRAMPOLINE_BUILD_FILE"
     value: "github/python-bigquery-storage/.kokoro/test-samples.sh"

.kokoro/samples/python3.7/common.cfg

@@ -13,6 +13,12 @@ env_vars: {
     value: "py-3.7"
 }
 
+# Declare build specific Cloud project.
+env_vars: {
+    key: "BUILD_SPECIFIC_GCLOUD_PROJECT"
+    value: "python-docs-samples-tests-py37"
+}
+
 env_vars: {
     key: "TRAMPOLINE_BUILD_FILE"
     value: "github/python-bigquery-storage/.kokoro/test-samples.sh"

.kokoro/samples/python3.8/common.cfg

@@ -13,6 +13,12 @@ env_vars: {
     value: "py-3.8"
 }
 
+# Declare build specific Cloud project.
+env_vars: {
+    key: "BUILD_SPECIFIC_GCLOUD_PROJECT"
+    value: "python-docs-samples-tests-py38"
+}
+
 env_vars: {
     key: "TRAMPOLINE_BUILD_FILE"
     value: "github/python-bigquery-storage/.kokoro/test-samples.sh"

.kokoro/test-samples.sh

@@ -28,6 +28,12 @@ if [[ $KOKORO_BUILD_ARTIFACTS_SUBDIR = *"periodic"* ]]; then
     git checkout $LATEST_RELEASE
 fi
 
+# Exit early if samples directory doesn't exist
+if [ ! -d "./samples" ]; then
+  echo "No tests run. `./samples` not found"
+  exit 0
+fi
+
 # Disable buffering, so that the logs stream through.
 export PYTHONUNBUFFERED=1
 
@@ -101,4 +107,4 @@ cd "$ROOT"
 # Workaround for Kokoro permissions issue: delete secrets
 rm testing/{test-env.sh,client-secrets.json,service-account.json}
 
-exit "$RTN"
+exit "$RTN"

google/cloud/bigquery_storage_v1/services/big_query_read/client.py

@@ -19,10 +19,10 @@
 from distutils import util
 import os
 import re
-from typing import Callable, Dict, Iterable, Sequence, Tuple, Type, Union
+from typing import Callable, Dict, Optional, Iterable, Sequence, Tuple, Type, Union
 import pkg_resources
 
-import google.api_core.client_options as ClientOptions  # type: ignore
+from google.api_core import client_options as client_options_lib  # type: ignore
 from google.api_core import exceptions  # type: ignore
 from google.api_core import gapic_v1  # type: ignore
 from google.api_core import retry as retries  # type: ignore
@@ -170,9 +170,9 @@ def parse_read_stream_path(path: str) -> Dict[str, str]:
     def __init__(
         self,
         *,
-        credentials: credentials.Credentials = None,
-        transport: Union[str, BigQueryReadTransport] = None,
-        client_options: ClientOptions = None,
+        credentials: Optional[credentials.Credentials] = None,
+        transport: Union[str, BigQueryReadTransport, None] = None,
+        client_options: Optional[client_options_lib.ClientOptions] = None,
         client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
     ) -> None:
         """Instantiate the big query read client.
@@ -186,8 +186,8 @@ def __init__(
             transport (Union[str, ~.BigQueryReadTransport]): The
                 transport to use. If set to None, a transport is chosen
                 automatically.
-            client_options (ClientOptions): Custom options for the client. It
-                won't take effect if a ``transport`` instance is provided.
+            client_options (client_options_lib.ClientOptions): Custom options for the
+                client. It won't take effect if a ``transport`` instance is provided.
                 (1) The ``api_endpoint`` property can be used to override the
                 default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
                 environment variable can also be used to override the endpoint:
@@ -213,9 +213,9 @@ def __init__(
                 creation failed for any reason.
         """
         if isinstance(client_options, dict):
-            client_options = ClientOptions.from_dict(client_options)
+            client_options = client_options_lib.from_dict(client_options)
         if client_options is None:
-            client_options = ClientOptions.ClientOptions()
+            client_options = client_options_lib.ClientOptions()
 
         # Create SSL credentials for mutual TLS if needed.
         use_client_cert = bool(

samples/quickstart/noxfile.py

@@ -199,6 +199,11 @@ def _get_repo_root():
             break
         if Path(p / ".git").exists():
             return str(p)
+        # .git is not available in repos cloned via Cloud Build
+        # setup.py is always in the library's root, so use that instead
+        # https://github.com/googleapis/synthtool/issues/792
+        if Path(p / "setup.py").exists():
+            return str(p)
         p = p.parent
     raise Exception("Unable to detect repository root.")
 

samples/to_dataframe/noxfile.py

@@ -199,6 +199,11 @@ def _get_repo_root():
             break
         if Path(p / ".git").exists():
             return str(p)
+        # .git is not available in repos cloned via Cloud Build
+        # setup.py is always in the library's root, so use that instead
+        # https://github.com/googleapis/synthtool/issues/792
+        if Path(p / "setup.py").exists():
+            return str(p)
         p = p.parent
     raise Exception("Unable to detect repository root.")
 

synth.metadata

@@ -3,22 +3,30 @@
     {
       "git": {
         "name": ".",
-        "remote": "git@github.com:plamut/python-bigquery-storage.git",
-        "sha": "bb1fdd26638add930e6601663ca92b76cbd9064c"
+        "remote": "https://github.com/googleapis/python-bigquery-storage.git",
+        "sha": "6254bf2a588e69e2175df1c67edb514655d93e9d"
+      }
+    },
+    {
+      "git": {
+        "name": "googleapis",
+        "remote": "https://github.com/googleapis/googleapis.git",
+        "sha": "062f46f246c78fde2160524db593fa0fa7bdbe64",
+        "internalRef": "337404700"
       }
     },
     {
       "git": {
         "name": "synthtool",
         "remote": "https://github.com/googleapis/synthtool.git",
-        "sha": "da29da32b3a988457b49ae290112b74f14b713cc"
+        "sha": "477764cc4ee6db346d3febef2bb1ea0abf27de52"
       }
     },
     {
       "git": {
         "name": "synthtool",
         "remote": "https://github.com/googleapis/synthtool.git",
-        "sha": "da29da32b3a988457b49ae290112b74f14b713cc"
+        "sha": "477764cc4ee6db346d3febef2bb1ea0abf27de52"
       }
     }
   ],
@@ -32,5 +40,100 @@
         "generator": "bazel"
       }
     }
+  ],
+  "generatedFiles": [
+    ".flake8",
+    ".github/CONTRIBUTING.md",
+    ".github/ISSUE_TEMPLATE/bug_report.md",
+    ".github/ISSUE_TEMPLATE/feature_request.md",
+    ".github/ISSUE_TEMPLATE/support_request.md",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    ".github/release-please.yml",
+    ".github/snippet-bot.yml",
+    ".gitignore",
+    ".kokoro/build.sh",
+    ".kokoro/continuous/common.cfg",
+    ".kokoro/continuous/continuous.cfg",
+    ".kokoro/docker/docs/Dockerfile",
+    ".kokoro/docker/docs/fetch_gpg_keys.sh",
+    ".kokoro/docs/common.cfg",
+    ".kokoro/docs/docs-presubmit.cfg",
+    ".kokoro/docs/docs.cfg",
+    ".kokoro/populate-secrets.sh",
+    ".kokoro/presubmit/common.cfg",
+    ".kokoro/presubmit/presubmit.cfg",
+    ".kokoro/publish-docs.sh",
+    ".kokoro/release.sh",
+    ".kokoro/release/common.cfg",
+    ".kokoro/release/release.cfg",
+    ".kokoro/samples/lint/common.cfg",
+    ".kokoro/samples/lint/continuous.cfg",
+    ".kokoro/samples/lint/periodic.cfg",
+    ".kokoro/samples/lint/presubmit.cfg",
+    ".kokoro/samples/python3.6/common.cfg",
+    ".kokoro/samples/python3.6/continuous.cfg",
+    ".kokoro/samples/python3.6/periodic.cfg",
+    ".kokoro/samples/python3.6/presubmit.cfg",
+    ".kokoro/samples/python3.7/common.cfg",
+    ".kokoro/samples/python3.7/continuous.cfg",
+    ".kokoro/samples/python3.7/periodic.cfg",
+    ".kokoro/samples/python3.7/presubmit.cfg",
+    ".kokoro/samples/python3.8/common.cfg",
+    ".kokoro/samples/python3.8/continuous.cfg",
+    ".kokoro/samples/python3.8/periodic.cfg",
+    ".kokoro/samples/python3.8/presubmit.cfg",
+    ".kokoro/test-samples.sh",
+    ".kokoro/trampoline.sh",
+    ".kokoro/trampoline_v2.sh",
+    ".trampolinerc",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.rst",
+    "LICENSE",
+    "MANIFEST.in",
+    "docs/_static/custom.css",
+    "docs/_templates/layout.html",
+    "docs/bigquery_storage_v1/services.rst",
+    "docs/bigquery_storage_v1/types.rst",
+    "docs/conf.py",
+    "docs/multiprocessing.rst",
+    "google/cloud/bigquery_storage/__init__.py",
+    "google/cloud/bigquery_storage/py.typed",
+    "google/cloud/bigquery_storage_v1/proto/arrow.proto",
+    "google/cloud/bigquery_storage_v1/proto/avro.proto",
+    "google/cloud/bigquery_storage_v1/proto/storage.proto",
+    "google/cloud/bigquery_storage_v1/proto/stream.proto",
+    "google/cloud/bigquery_storage_v1/py.typed",
+    "google/cloud/bigquery_storage_v1/services/__init__.py",
+    "google/cloud/bigquery_storage_v1/services/big_query_read/__init__.py",
+    "google/cloud/bigquery_storage_v1/services/big_query_read/async_client.py",
+    "google/cloud/bigquery_storage_v1/services/big_query_read/client.py",
+    "google/cloud/bigquery_storage_v1/services/big_query_read/transports/__init__.py",
+    "google/cloud/bigquery_storage_v1/services/big_query_read/transports/base.py",
+    "google/cloud/bigquery_storage_v1/services/big_query_read/transports/grpc.py",
+    "google/cloud/bigquery_storage_v1/services/big_query_read/transports/grpc_asyncio.py",
+    "google/cloud/bigquery_storage_v1/types/__init__.py",
+    "google/cloud/bigquery_storage_v1/types/arrow.py",
+    "google/cloud/bigquery_storage_v1/types/avro.py",
+    "google/cloud/bigquery_storage_v1/types/storage.py",
+    "google/cloud/bigquery_storage_v1/types/stream.py",
+    "mypy.ini",
+    "noxfile.py",
+    "renovate.json",
+    "samples/AUTHORING_GUIDE.md",
+    "samples/CONTRIBUTING.md",
+    "samples/quickstart/noxfile.py",
+    "samples/to_dataframe/noxfile.py",
+    "scripts/decrypt-secrets.sh",
+    "scripts/fixup_bigquery_storage_v1_keywords.py",
+    "scripts/readme-gen/readme_gen.py",
+    "scripts/readme-gen/templates/README.tmpl.rst",
+    "scripts/readme-gen/templates/auth.tmpl.rst",
+    "scripts/readme-gen/templates/auth_api_key.tmpl.rst",
+    "scripts/readme-gen/templates/install_deps.tmpl.rst",
+    "scripts/readme-gen/templates/install_portaudio.tmpl.rst",
+    "setup.cfg",
+    "testing/.gitignore",
+    "tests/unit/gapic/bigquery_storage_v1/__init__.py",
+    "tests/unit/gapic/bigquery_storage_v1/test_big_query_read.py"
   ]
 }