docs(samples): Updated Samples for v2.0.0 Client Library (#365)

* docs(samples): Updated Samples for v2.0.0 Client Library

- Added Examples for FetchProcessorTypes, CreateProcessor, ListProcessors, DeleteProcessor, DisableProcessor, EnableProcessor
- Added example parameters for processorVersion and FieldMask
- Removed references to 'v1' in imports (default is v1)
- Changed File types Documentation link in comments
- Corrected Human Review test method name

* docs(samples): Added Sample Code for Operations Functions

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* docs(samples): Added GetProcessor Sample

- Also removed extra test function call

* docs(samples): Addressed unit test issues

* docs(samples): Adjusted imports to resovle presubmit errors

Co-authored-by: Anthonios Partheniou <[email protected]>
Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: 3 people

documentai/snippets/batch_process_documents_sample.py

@@ -17,13 +17,13 @@
 import re
 
 from google.api_core.client_options import ClientOptions
-from google.cloud import documentai_v1 as documentai
-from google.cloud import storage
+from google.cloud import documentai, storage
 
 # TODO(developer): Uncomment these variables before running the sample.
 # project_id = 'YOUR_PROJECT_ID'
 # location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
-# processor_id = 'YOUR_PROCESSOR_ID' # Create processor in Cloud Console
+# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
+# processor_version = "pretrained" # Optional. Processor version to use
 # gcs_input_uri = "YOUR_INPUT_URI" # Format: gs://bucket/directory/file.pdf
 # input_mime_type = "application/pdf"
 # gcs_output_bucket = "YOUR_OUTPUT_BUCKET_NAME" # Format: gs://bucket
@@ -76,6 +76,14 @@ def batch_process_documents(
     # You must create new processors in the Cloud Console first
     name = client.processor_path(project_id, location, processor_id)
 
+    # NOTE: Alternatively, specify the processor_version to specify a particular version of the processor to use
+    # projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processorVersion}
+    #
+    # name = client.processor_version_path(
+    #     project_id, location, processor_id, processor_version
+    # )
+    #
+
     request = documentai.BatchProcessRequest(
         name=name,
         input_documents=input_config,

documentai/snippets/batch_process_documents_sample_bad_input_test.py

@@ -42,6 +42,6 @@ def test_batch_process_documents_with_bad_input(capsys):
             timeout=450,
         )
         out, _ = capsys.readouterr()
-        assert "Failed to process" in out
+        assert "Failed" in out
     except Exception as e:
-        assert "Failed to process" in e.message
+        assert "Internal error" in e.message

documentai/snippets/cancel_operation_sample.py

@@ -0,0 +1,44 @@
+# 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.
+#
+
+# [START documentai_cancel_operation]
+
+from google.api_core.client_options import ClientOptions
+from google.api_core.exceptions import FailedPrecondition, NotFound
+from google.cloud import documentai
+from google.longrunning.operations_pb2 import CancelOperationRequest
+
+# TODO(developer): Uncomment these variables before running the sample.
+# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
+# operation_name = 'YOUR_OPERATION_NAME' # Format is 'projects/project_id/locations/location/operations/operation_id'
+
+
+def cancel_operation_sample(location: str, operation_name: str):
+    # You must set the api_endpoint if you use a location other than 'us', e.g.:
+    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")
+
+    client = documentai.DocumentProcessorServiceClient(client_options=opts)
+
+    request = CancelOperationRequest(name=operation_name)
+
+    # Make CancelOperation request
+    try:
+        client.cancel_operation(request=request)
+        print(f"Operation {operation_name} cancelled")
+    except (FailedPrecondition, NotFound) as e:
+        print(e.message)
+
+
+# [END documentai_cancel_operation]

documentai/snippets/cancel_operation_sample_test.py

@@ -0,0 +1,33 @@
+# 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.
+#
+
+import os
+
+from samples.snippets import cancel_operation_sample
+
+location = "us"
+project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
+operation_id = "4311241022337572151"
+operation_name = f"projects/{project_id}/locations/{location}/operations/{operation_id}"
+
+
+def test_cancel_operation(capsys):
+    cancel_operation_sample.cancel_operation_sample(
+        location=location, operation_name=operation_name
+    )
+    out, _ = capsys.readouterr()
+
+    assert "Operation" in out
+    assert "cancelled" in out

documentai/snippets/create_processor_sample.py

@@ -0,0 +1,54 @@
+# 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.
+#
+
+# [START documentai_create_processor]
+
+from google.api_core.client_options import ClientOptions
+from google.cloud import documentai
+
+# TODO(developer): Uncomment these variables before running the sample.
+# project_id = 'YOUR_PROJECT_ID'
+# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
+# processor_display_name = 'YOUR_PROCESSOR_DISPLAY_NAME' # Must be unique per project, e.g.: 'My Processor'
+# processor_type = 'YOUR_PROCESSOR_TYPE' # Use fetch_processor_types to get available processor types
+
+
+def create_processor_sample(
+    project_id: str, location: str, processor_display_name: str, processor_type: str
+):
+    # You must set the api_endpoint if you use a location other than 'us', e.g.:
+    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")
+
+    client = documentai.DocumentProcessorServiceClient(client_options=opts)
+
+    # The full resource name of the location
+    # e.g.: projects/project_id/locations/location
+    parent = client.common_location_path(project_id, location)
+
+    # Create a processor
+    processor = client.create_processor(
+        parent=parent,
+        processor=documentai.Processor(
+            display_name=processor_display_name, type_=processor_type
+        ),
+    )
+
+    # Print the processor information
+    print(f"Processor Name: {processor.name}")
+    print(f"Processor Display Name: {processor.display_name}")
+    print(f"Processor Type: {processor.type_}")
+
+
+# [END documentai_create_processor]

documentai/snippets/create_processor_sample_test.py

@@ -0,0 +1,47 @@
+# 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.
+#
+
+import os
+from uuid import uuid4
+
+import mock
+
+from samples.snippets import create_processor_sample
+
+location = "us"
+project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
+processor_display_name = f"test-processor-{uuid4()}"
+processor_type = "OCR_PROCESSOR"
+
+
+@mock.patch("google.cloud.documentai.DocumentProcessorServiceClient.create_processor")
+@mock.patch("google.cloud.documentai.Processor")
+def test_create_processor(create_processor_mock, processor_mock, capsys):
+    create_processor_mock.return_value = processor_mock
+
+    create_processor_sample.create_processor_sample(
+        project_id=project_id,
+        location=location,
+        processor_display_name=processor_display_name,
+        processor_type=processor_type,
+    )
+
+    create_processor_mock.assert_called_once()
+
+    out, _ = capsys.readouterr()
+
+    assert "Processor Name:" in out
+    assert "Processor Display Name:" in out
+    assert "Processor Type:" in out

documentai/snippets/delete_processor_sample.py

@@ -0,0 +1,49 @@
+# 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.
+#
+
+# [START documentai_delete_processor]
+
+from google.api_core.client_options import ClientOptions
+from google.api_core.exceptions import NotFound
+from google.cloud import documentai
+
+# TODO(developer): Uncomment these variables before running the sample.
+# project_id = 'YOUR_PROJECT_ID'
+# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
+# processor_id = 'YOUR_PROCESSOR_ID'
+
+
+def delete_processor_sample(project_id: str, location: str, processor_id: str):
+    # You must set the api_endpoint if you use a location other than 'us', e.g.:
+    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")
+
+    client = documentai.DocumentProcessorServiceClient(client_options=opts)
+
+    # The full resource name of the processor
+    # e.g.: projects/project_id/locations/location/processors/processor_id
+    processor_name = client.processor_path(project_id, location, processor_id)
+
+    # Delete a processor
+    try:
+        operation = client.delete_processor(name=processor_name)
+        # Print operation details
+        print(operation.operation.name)
+        # Wait for operation to complete
+        operation.result()
+    except NotFound as e:
+        print(e.message)
+
+
+# [END documentai_delete_processor]

documentai/snippets/delete_processor_sample_test.py

@@ -0,0 +1,41 @@
+# 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.
+#
+
+import os
+
+import mock
+
+from samples.snippets import delete_processor_sample
+
+location = "us"
+project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
+processor_id = "aaaaaaaaa"
+parent = f"projects/{project_id}/locations/{location}/processors/{processor_id}"
+
+
+@mock.patch("google.cloud.documentai.DocumentProcessorServiceClient.delete_processor")
+@mock.patch("google.api_core.operation.Operation")
+def test_delete_processor(operation_mock, delete_processor_mock, capsys):
+    delete_processor_mock.return_value = operation_mock
+
+    delete_processor_sample.delete_processor_sample(
+        project_id=project_id, location=location, processor_id=processor_id
+    )
+
+    delete_processor_mock.assert_called_once()
+
+    out, _ = capsys.readouterr()
+
+    assert "operation" in out

documentai/snippets/disable_processor_sample.py

@@ -0,0 +1,52 @@
+# 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.
+#
+
+# [START documentai_disable_processor]
+
+from google.api_core.client_options import ClientOptions
+from google.api_core.exceptions import FailedPrecondition
+from google.cloud import documentai
+
+# TODO(developer): Uncomment these variables before running the sample.
+# project_id = 'YOUR_PROJECT_ID'
+# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
+# processor_id = 'YOUR_PROCESSOR_ID'
+
+
+def disable_processor_sample(project_id: str, location: str, processor_id: str):
+    # You must set the api_endpoint if you use a location other than 'us', e.g.:
+    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")
+
+    client = documentai.DocumentProcessorServiceClient(client_options=opts)
+
+    # The full resource name of the processor
+    # e.g.: projects/project_id/locations/location/processors/processor_id
+    processor_name = client.processor_path(project_id, location, processor_id)
+    request = documentai.DisableProcessorRequest(name=processor_name)
+
+    # Make DisableProcessor request
+    try:
+        operation = client.disable_processor(request=request)
+
+        # Print operation name
+        print(operation.operation.name)
+        # Wait for operation to complete
+        operation.result()
+    # Cannot disable a processor that is already disabled
+    except FailedPrecondition as e:
+        print(e.message)
+
+
+# [END documentai_disable_processor]