feat(bigquery): create cloud-client samples (#13147)

* docs(bigquery): delete README.rst

- Samples must be moved back to this directory.

* feat(bigquery): add dependencies to cloud-client directory

* feat(bigquery): create sample 'view dataset access policy'

* feat(bigquery): fix license headers

* feat(bigquery): improve view_dataset_access_policy sample

- Change function name and region tag from '_policies' to '_policy', to match documentation
- Add more explanation to how the Access policy is retreived as a list of Access Entries
- Add a validation to check if 'access_entries' has elements

* feat(bigquery): replace .format() with f-strings

* feat(bigquery): apply feedback from PR review 2609806365

- Change typing imports as per PEP-585 and PEP-604
- Remove dependencies for Python < 3.9
- Refactor overriding values
- Remove CLI entry point

* feat(bigquery): apply feedback from PR review 2309806365 part 2

- Refactor creating and deleting datasets into a single fixture.
- Refactor reading stdout/stderr to returning the dataset and asserting it has the right name.
- Validate that the dataset was deleted successfully.

* feat(bigquery): refactor sample view_dataset_access_policy

- Assert over an Access policy, not the Dataset itself

* feat(bigquery): add sample 'view_table_or_view_access_policy'

* feat(bigquery): remove CLI entry point

* feat(bigquery): WIP draft sample 'revoke_access_to_table_or_view'

* feat(bigquery): apply feedback from PR review 2616192713

- Leave only one way to print access_entries, and refactor with a for to show all list elements.
- Remove unnecessary validation for deleting dataset.
- Remove unnecessary fixture for a second table when first one could be used to create the view.
- Remove magic value for empty policy.

* feat(bigquery): refactor printing dataset.access_entries

- Works better when there is an empty AccessEntry list.

* feat(bigquery): WIP draft sample 'grant_access_to_table_or_view'

* feat(bigquery): start refactor to use conftest.py feature

* feat(bigquery): WIP refactor samples to use conftest.py

- Simplify use of fixtures.
- Apply diverse feedback from the team.

* feat(bigquery): remove EntityTypes dependency

- Hardcoding the EntityType to simplify the sample.

* feat(bitquery): refactor sample 'revoke_access_to_table_or_view' to unify it to Node.JS one

- Allow to revoke access by role or by principal_id.

* feat(bigquery): update conftest.py

- Add entity_id
- Remove unused comments

* feat(bigquery): add test for grant_access_to_table_or_view

* feat(bigquery): add test for revoke_access_to_table_or_view

* feat(bigquery): fix samples for gran_access

- Update principal_id sample with a valid identifier.

* feat(bigquery): minor cleanup

* feat(bigquery): add test for 'revoke_dataset_access'

* feat(bigquery): add sample 'revoke_dataset_access'

* feat(bigquery): refactor samples and tests for consistency

- Remove unnecesary code.
- Rewrite comments and documentation references.
- Add __future__ annotations for Python 3.9

* feat(bigquery): improve comments on sample 'revoke_access_to_table_or_view'

* feat(bigquery): improve comment in 'revoke_access_to_table_or_view'

* feat(bigquery): cleanup and unify with Go samples

- Rename 'bigquery_client' to 'client' to make it consistent across samples.
- Add validation for empty bindings list in 'view_table_or_access_policy'.
- Add '_id' suffix to placeholder.

Author: eapl-gemugami

bigquery/cloud-client/README.rst

@@ -0,0 +1,77 @@
+# Copyright 2020 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
+from google.cloud.bigquery.dataset import Dataset
+from google.cloud.bigquery.table import Table
+
+import pytest
+import test_utils.prefixer
+
+prefixer = test_utils.prefixer.Prefixer("python-docs-samples", "bigquery/cloud-client")
+
+PREFIX = prefixer.create_prefix()
+ENTITY_ID = "cloud-developer-relations@google.com"  # Group account
+DATASET_ID = f"{PREFIX}_cloud_client"
+TABLE_NAME = f"{PREFIX}_view_access_policies_table"
+VIEW_NAME = f"{PREFIX}_view_access_policies_view"
+
+
+@pytest.fixture(scope="module")
+def client() -> bigquery.Client:
+    return bigquery.Client()
+
+
+@pytest.fixture(scope="module")
+def project_id(client: bigquery.Client) -> str:
+    return client.project
+
+
+@pytest.fixture(scope="module")
+def entity_id() -> str:
+    return ENTITY_ID
+
+
+@pytest.fixture(scope="module")
+def dataset(client: bigquery.Client) -> Dataset:
+    dataset = client.create_dataset(DATASET_ID)
+    yield dataset
+    client.delete_dataset(dataset, delete_contents=True)
+
+
+@pytest.fixture(scope="module")
+def table(client: bigquery.Client, project_id: str) -> Table:
+    FULL_TABLE_NAME = f"{project_id}.{DATASET_ID}.{TABLE_NAME}"
+
+    sample_schema = [
+        bigquery.SchemaField("id", "INTEGER", mode="REQUIRED"),
+    ]
+
+    table = bigquery.Table(FULL_TABLE_NAME, schema=sample_schema)
+    client.create_table(table)
+
+    return table
+
+
+@pytest.fixture()
+def view(client: bigquery.Client, project_id: str, table: str) -> str:
+    FULL_VIEW_NAME = f"{project_id}.{DATASET_ID}.{VIEW_NAME}"
+    view = bigquery.Table(FULL_VIEW_NAME)
+
+    # f"{table}" will inject the full table name,
+    # with project_id and dataset_id, as required by
+    # .create_table()
+    view.view_query = f"SELECT * FROM `{table}`"
+    view = client.create_table(view)
+    return view

bigquery/cloud-client/conftest.py

@@ -0,0 +1,95 @@
+# Copyright 2025 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.
+
+from google.cloud.bigquery.dataset import AccessEntry
+
+
+def grant_access_to_dataset(
+    dataset_id: str,
+    entity_id: str,
+    role: str
+) -> list[AccessEntry]:
+    # [START bigquery_grant_access_to_dataset]
+    from google.api_core.exceptions import PreconditionFailed
+    from google.cloud import bigquery
+    from google.cloud.bigquery.enums import EntityTypes
+
+    # TODO(developer): Update and un-comment below lines
+
+    # ID of the dataset to revoke access to.
+    # dataset_id = "my_project_id.my_dataset"
+
+    # ID of the user or group from whom you are adding access.
+    # Alternatively, the JSON REST API representation of the entity,
+    # such as a view's table reference.
+    # entity_id = "user-or-group-to-add@example.com"
+
+    # One of the "Basic roles for datasets" described here:
+    # https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
+    # role = "READER"
+
+    # Type of entity you are granting access to.
+    # Find allowed allowed entity type names here:
+    # https://cloud.google.com/python/docs/reference/bigquery/latest/enums#class-googlecloudbigqueryenumsentitytypesvalue
+    entity_type = EntityTypes.GROUP_BY_EMAIL
+
+    # Instantiate a client.
+    client = bigquery.Client()
+
+    # Get a reference to the dataset.
+    dataset = client.get_dataset(dataset_id)
+
+    # The `access_entries` list is immutable. Create a copy for modifications.
+    entries = list(dataset.access_entries)
+
+    # Append an AccessEntry to grant the role to a dataset.
+    # Find more details about the AccessEntry object here:
+    # https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.dataset.AccessEntry
+    entries.append(
+        bigquery.AccessEntry(
+            role=role,
+            entity_type=entity_type,
+            entity_id=entity_id,
+        )
+    )
+
+    # Assign the list of AccessEntries back to the dataset.
+    dataset.access_entries = entries
+
+    # Update will only succeed if the dataset
+    # has not been modified externally since retrieval.
+    #
+    # See the BigQuery client library documentation for more details on `update_dataset`:
+    # https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.client.Client#google_cloud_bigquery_client_Client_update_dataset
+    try:
+        # Update just the `access_entries` property of the dataset.
+        dataset = client.update_dataset(
+            dataset,
+            ["access_entries"],
+        )
+
+        # Show a success message.
+        full_dataset_id = f"{dataset.project}.{dataset.dataset_id}"
+        print(
+            f"Role '{role}' granted for entity '{entity_id}'"
+            f" in dataset '{full_dataset_id}'."
+        )
+    except PreconditionFailed:  # A read-modify-write error
+        print(
+            f"Dataset '{dataset.dataset_id}' was modified remotely before this update. "
+            "Fetch the latest version and retry."
+        )
+    # [END bigquery_grant_access_to_dataset]
+
+    return dataset.access_entries

bigquery/cloud-client/grant_access_to_dataset.py

@@ -0,0 +1,33 @@
+# Copyright 2025 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.
+
+from google.cloud.bigquery.dataset import Dataset
+
+from grant_access_to_dataset import grant_access_to_dataset
+
+
+def test_grant_access_to_dataset(
+    dataset: Dataset,
+    entity_id: str
+) -> None:
+    dataset_access_entries = grant_access_to_dataset(
+        dataset_id=dataset.dataset_id,
+        entity_id=entity_id,
+        role="READER"
+    )
+
+    updated_dataset_entity_ids = {
+        entry.entity_id for entry in dataset_access_entries
+    }
+    assert entity_id in updated_dataset_entity_ids

bigquery/cloud-client/grant_access_to_dataset_test.py

@@ -0,0 +1,79 @@
+# Copyright 2024 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.
+
+from google.api_core.iam import Policy
+
+
+def grant_access_to_table_or_view(
+    project_id: str,
+    dataset_id: str,
+    resource_name: str,
+    principal_id: str,
+    role: str,
+) -> Policy:
+
+    # [START bigquery_grant_access_to_table_or_view]
+    from google.cloud import bigquery
+
+    # TODO(developer): Update and un-comment below lines
+
+    # Google Cloud Platform project.
+    # project_id = "my_project_id"
+
+    # Dataset where the table or view is.
+    # dataset_id = "my_dataset"
+
+    # Table or view name to get the access policy.
+    # resource_name = "my_table"
+
+    # The principal requesting access to the table or view.
+    # Find more details about principal identifiers here:
+    # https://cloud.google.com/iam/docs/principal-identifiers
+    # principal_id = "user:bob@example.com"
+
+    # Role to assign to the member.
+    # role = "roles/bigquery.dataViewer"
+
+    # Instantiate a client.
+    client = bigquery.Client()
+
+    # Get the full table or view name.
+    full_resource_name = f"{project_id}.{dataset_id}.{resource_name}"
+
+    # Get the IAM access policy for the table or view.
+    policy = client.get_iam_policy(full_resource_name)
+
+    # To grant access to a table or view,
+    # add bindings to the Table or View policy.
+    #
+    # Find more details about Policy and Binding objects here:
+    # https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Policy
+    # https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Binding
+    binding = {
+        "role": role,
+        "members": [principal_id, ],
+    }
+    policy.bindings.append(binding)
+
+    # Set the IAM acces spolicy with updated bindings
+    updated_policy = client.set_iam_policy(full_resource_name, policy)
+
+    # Show a success message.
+    print(
+        f"Role '{role}' granted for principal '{principal_id}'"
+        f" on resource '{full_resource_name}'."
+    )
+    # [END bigquery_grant_access_to_table_or_view]
+
+    return updated_policy.bindings

bigquery/cloud-client/grant_access_to_table_or_view.py

@@ -0,0 +1,52 @@
+# Copyright 2025 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.
+
+from google.cloud import bigquery
+from google.cloud.bigquery.dataset import Dataset
+from google.cloud.bigquery.table import Table
+
+from grant_access_to_table_or_view import grant_access_to_table_or_view
+
+
+def test_grant_access_to_table_or_view(
+    client: bigquery.Client,
+    dataset: Dataset,
+    project_id: str,
+    table: Table,
+    entity_id: str,
+) -> None:
+    ROLE = "roles/bigquery.dataViewer"
+    PRINCIPAL_ID = f"group:{entity_id}"
+
+    empty_policy = client.get_iam_policy(table)
+
+    # In an empty policy the role and principal is not present
+    assert not any(p for p in empty_policy if p["role"] == ROLE)
+    assert not any(p for p in empty_policy if PRINCIPAL_ID in p["members"])
+
+    updated_policy = grant_access_to_table_or_view(
+        project_id,
+        dataset.dataset_id,
+        table.table_id,
+        principal_id=PRINCIPAL_ID,
+        role=ROLE,
+    )
+
+    # A binding with that role exists
+    assert any(p for p in updated_policy if p["role"] == ROLE)
+    # A binding for that principal exists
+    assert any(
+        p for p in updated_policy
+        if PRINCIPAL_ID in p["members"]
+    )

bigquery/cloud-client/grant_access_to_table_or_view_test.py

@@ -0,0 +1,3 @@
+# samples/snippets should be runnable with no "extras"
+google-cloud-testutils==1.5.0
+pytest==8.3.4

bigquery/cloud-client/requirements-test.txt

@@ -0,0 +1,2 @@
+# samples/snippets should be runnable with no "extras"
+google-cloud-bigquery==3.29.0