docs(samples): Add sample for PolicyTagManagerClient.create_taxonomy (#37)

* fix(samples): add sample for create_taxonomy

* lint

* typo in import

* refactor sample to match expected pattern

Co-authored-by: Anthonios Partheniou <partheniou@google.com>
Co-authored-by: Tim Swast <swast@google.com>

Author: 3 people

samples/snippets/conftest.py

@@ -12,7 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 import datetime
 import uuid
 
@@ -22,9 +21,6 @@
 
 import pytest
 
-datacatalog = datacatalog_v1.DataCatalogClient()
-
-
 LOCATION = "us-central1"
 
 
@@ -62,7 +58,7 @@ def valid_member_id(client, project_id, random_existing_tag_template_id):
     )
 
     # Retrieve Template's current IAM Policy.
-    policy = datacatalog.get_iam_policy(resource=template_name)
+    policy = client.get_iam_policy(resource=template_name)
     yield policy.bindings[0].members[0]
 
 
@@ -127,3 +123,25 @@ def random_existing_tag_template_id(client, project_id, resources_to_delete):
     )
     yield random_tag_template_id
     resources_to_delete["templates"].append(random_tag_template.name)
+
+
+@pytest.fixture(scope="session")
+def policy_tag_manager_client(credentials):
+    return datacatalog_v1.PolicyTagManagerClient(credentials=credentials)
+
+
+@pytest.fixture
+def random_taxonomy_display_name(policy_tag_manager_client, project_id):
+    now = datetime.datetime.now()
+    random_display_name = f'example_taxonomy' \
+                          f'_{now.strftime("%Y%m%d%H%M%S")}' \
+                          f'_{uuid.uuid4().hex[:8]}'
+    yield random_display_name
+    parent = datacatalog_v1.PolicyTagManagerClient.common_location_path(
+        project_id, 'us'
+    )
+    taxonomies = policy_tag_manager_client.list_taxonomies(parent=parent)
+    taxonomy = next(
+        (t for t in taxonomies if t.display_name == random_display_name), None)
+    if taxonomy:
+        policy_tag_manager_client.delete_taxonomy(name=taxonomy.name)

samples/snippets/data_catalog_ptm_create_taxonomy.py

@@ -0,0 +1,50 @@
+# Copyright 2021 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.
+
+# [START data_catalog_ptm_create_taxonomy]
+from google.cloud import datacatalog_v1
+
+
+def create_taxonomy(
+    # TODO(developer): Set project_id to the ID of the project the
+    #  taxonomy will belong to.
+    project_id: str = "your-project-id",
+
+    # TODO(developer): Specify the geographic location where the
+    #  taxonomy should reside.
+    location_id: str = "us",
+
+    # TODO(developer): Set the display name of the taxonomy.
+    display_name: str = "example-taxonomy",
+):
+    # TODO(developer): Construct a Policy Tag Manager client object. To avoid
+    # extra delays due to authentication, create a single client for your
+    # program and share it across operations.
+    client = datacatalog_v1.PolicyTagManagerClient()
+
+    # Construct a full location path to be the parent of the taxonomy.
+    parent = datacatalog_v1.PolicyTagManagerClient.common_location_path(
+        project_id, location_id
+    )
+
+    # TODO(developer): Construct a full Taxonomy object to send to the API.
+    taxonomy = datacatalog_v1.Taxonomy()
+    taxonomy.display_name = display_name
+    taxonomy.description = 'This Taxonomy represents ...'
+
+    # Send the taxonomy to the API for creation.
+    taxonomy = client.create_taxonomy(parent=parent, taxonomy=taxonomy)
+    print(f'Created taxonomy {taxonomy.name}')
+
+# [END data_catalog_ptm_create_taxonomy]

samples/snippets/data_catalog_ptm_create_taxonomy_test.py

@@ -0,0 +1,29 @@
+# Copyright 2021 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 data_catalog_ptm_create_taxonomy
+
+
+def test_create_taxonomy(capsys,
+                         project_id: str,
+                         random_taxonomy_display_name: str):
+
+    data_catalog_ptm_create_taxonomy.create_taxonomy(
+        project_id=project_id, location_id="us", display_name=random_taxonomy_display_name)
+    out, _ = capsys.readouterr()
+    assert (
+        f'Created taxonomy projects/{project_id}/locations/us/taxonomies/'
+        in out
+    )