From 8edc10d019bd96defebc4f92a47774901e9b956f Mon Sep 17 00:00:00 2001
From: Tim Swast <swast@google.com>
Date: Mon, 14 Feb 2022 16:02:30 -0600
Subject: [PATCH] docs: show common job properties in `get_job` and
 `cancel_job` samples (#1137)

* docs: show common job properties in `get_job` and `cancel_job` samples

* flake8
---
 docs/snippets.py                      |  1 +
 samples/snippets/manage_job_cancel.py | 26 ++++++++++++++++++
 samples/snippets/manage_job_get.py    | 33 +++++++++++++++++++++++
 samples/snippets/manage_job_test.py   | 39 +++++++++++++++++++++++++++
 4 files changed, 99 insertions(+)
 create mode 100644 samples/snippets/manage_job_cancel.py
 create mode 100644 samples/snippets/manage_job_get.py
 create mode 100644 samples/snippets/manage_job_test.py

diff --git a/docs/snippets.py b/docs/snippets.py
index c62001fc0..499285eeb 100644
--- a/docs/snippets.py
+++ b/docs/snippets.py
@@ -757,6 +757,7 @@ def test_client_query_total_rows(client, capsys):
 
 
 def test_manage_job(client):
+    # TODO(b/199162556): delete after migrating docs
     sql = """
         SELECT corpus
         FROM `bigquery-public-data.samples.shakespeare`
diff --git a/samples/snippets/manage_job_cancel.py b/samples/snippets/manage_job_cancel.py
new file mode 100644
index 000000000..3e0fc5218
--- /dev/null
+++ b/samples/snippets/manage_job_cancel.py
@@ -0,0 +1,26 @@
+# Copyright 2016-2022 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
+#
+#     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.
+
+# [START bigquery_cancel_job]
+from google.cloud import bigquery
+
+
+def cancel_job(
+    client: bigquery.Client, location: str = "us", job_id: str = "abcd-efgh-ijkl-mnop",
+):
+    job = client.cancel_job(job_id, location=location)
+    print(f"{job.location}:{job.job_id} cancelled")
+
+
+# [END bigquery_cancel_job]
diff --git a/samples/snippets/manage_job_get.py b/samples/snippets/manage_job_get.py
new file mode 100644
index 000000000..256d79e5b
--- /dev/null
+++ b/samples/snippets/manage_job_get.py
@@ -0,0 +1,33 @@
+# Copyright 2016-2022 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
+#
+#     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.
+
+# [START bigquery_get_job]
+from google.cloud import bigquery
+
+
+def get_job(
+    client: bigquery.Client, location: str = "us", job_id: str = "abcd-efgh-ijkl-mnop",
+):
+    job = client.get_job(job_id, location=location)
+
+    # All job classes have "location" and "job_id" string properties.
+    # Use these properties for job operations such as "cancel_job" and
+    # "delete_job".
+    print(f"{job.location}:{job.job_id}")
+    print(f"Type: {job.job_type}")
+    print(f"State: {job.state}")
+    print(f"Created: {job.created.isoformat()}")
+
+
+# [END bigquery_get_job]
diff --git a/samples/snippets/manage_job_test.py b/samples/snippets/manage_job_test.py
new file mode 100644
index 000000000..745b7bbbe
--- /dev/null
+++ b/samples/snippets/manage_job_test.py
@@ -0,0 +1,39 @@
+# Copyright 2022 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
+#
+#     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 bigquery
+import pytest
+
+import manage_job_cancel
+import manage_job_get
+
+
+def test_manage_job(capsys: pytest.CaptureFixture):
+    client = bigquery.Client()
+    sql = """
+        SELECT corpus
+        FROM `bigquery-public-data.samples.shakespeare`
+        GROUP BY corpus;
+    """
+    location = "us"
+    job = client.query(sql, location=location)
+
+    manage_job_cancel.cancel_job(client, location=location, job_id=job.job_id)
+    out, _ = capsys.readouterr()
+    assert f"{job.location}:{job.job_id} cancelled" in out
+
+    manage_job_get.get_job(client, location=location, job_id=job.job_id)
+    out, _ = capsys.readouterr()
+    assert f"{job.location}:{job.job_id}" in out
+    assert "Type: query" in out