fix(documentai): refactor sample 'quickstart' (#13258)

- Move the creation and deletion of the Processor to a fixture not in the sample
- Cleanup test based on David Cavazos advice
- Refactor sample to make it consistent with other languages in https://cloud.google.com/document-ai/docs/process-documents-client-libraries#using_the_client_library

Author: eapl-gemugami

documentai/snippets/quickstart_sample.py

@@ -13,52 +13,48 @@
 # limitations under the License.
 
 from google.cloud.documentai_v1.types.document import Document
-from google.cloud.documentai_v1.types.processor import Processor
 
 
 def quickstart(
     project_id: str,
+    processor_id: str,
     location: str,
     file_path: str,
-    processor_display_name: str,
-) -> tuple[Processor, Document]:
+) -> Document:
     # [START documentai_quickstart]
     from google.api_core.client_options import ClientOptions
-    from google.cloud import documentai_v1  # type: ignore
+    from google.cloud import documentai_v1
+
+    # TODO(developer): Create a processor of type "OCR_PROCESSOR".
 
     # TODO(developer): Update and uncomment these variables before running the sample.
     # project_id = "MY_PROJECT_ID"
 
+    # Processor ID as hexadecimal characters.
+    # Not to be confused with the Processor Display Name.
+    # processor_id = "MY_PROCESSOR_ID"
+
     # Processor location. For example: "us" or "eu".
     # location = "MY_PROCESSOR_LOCATION"
 
     # Path for file to process.
     # file_path = "/path/to/local/pdf"
 
-    # Processor display name must be unique per project.
-    # processor_display_name = "MY_PROCESSOR_DISPLAY_NAME"
-
     # Set `api_endpoint` if you use a location other than "us".
     opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")
 
     # Initialize Document AI client.
     client = documentai_v1.DocumentProcessorServiceClient(client_options=opts)
 
-    # Get the full resource name of the location.
-    # For example: `projects/{project_id}/locations/{location}`
-    parent = client.common_location_path(project_id, location)
-
-    # Create a Processor.
-    # For available types, refer to https://cloud.google.com/document-ai/docs/create-processor
-    processor = client.create_processor(
-        parent=parent,
-        processor=documentai_v1.Processor(
-            type_="OCR_PROCESSOR",
-            display_name=processor_display_name,
-        ),
-    )
+    # Get the Fully-qualified Processor path.
+    full_processor_name = client.processor_path(project_id, location, processor_id)
 
-    # Print the processor information.
+    # Get a Processor reference.
+    request = documentai_v1.GetProcessorRequest(name=full_processor_name)
+    processor = client.get_processor(request=request)
+
+    # `processor.name` is the full resource name of the processor.
+    # For example: `projects/{project_id}/locations/{location}/processors/{processor_id}`
     print(f"Processor Name: {processor.name}")
 
     # Read the file into memory.
@@ -72,11 +68,8 @@ def quickstart(
         mime_type="application/pdf",
     )
 
-    # Configure the process request.
-    # `processor.name` is the full resource name of the processor,
-    # For example: `projects/{project_id}/locations/{location}/processors/{processor_id}`
+    # Send a request and get the processed document.
     request = documentai_v1.ProcessRequest(name=processor.name, raw_document=raw_document)
-
     result = client.process_document(request=request)
     document = result.document
 
@@ -87,4 +80,4 @@ def quickstart(
     print(document.text)
     # [END documentai_quickstart]
 
-    return processor, document
+    return document

documentai/snippets/quickstart_sample_test.py

@@ -20,30 +20,63 @@
 from google.api_core.client_options import ClientOptions
 from google.cloud import documentai_v1
 
+from google.cloud.documentai_v1.types.processor import Processor
+
+import pytest
+
 LOCATION = "us"
 PROJECT_ID = os.environ["GOOGLE_CLOUD_PROJECT"]
-PROCESSOR_DISPLAY_NAME = f"test-processor-{uuid4()}"
 FILE_PATH = "resources/invoice.pdf"
 
 
-def test_quickstart() -> None:
-    processor, document = quickstart_sample.quickstart(
-        project_id=PROJECT_ID,
-        location=LOCATION,
-        processor_display_name=PROCESSOR_DISPLAY_NAME,
-        file_path=FILE_PATH,
+@pytest.fixture(scope="module")
+def client() -> documentai_v1.DocumentProcessorServiceClient:
+    opts = ClientOptions(api_endpoint=f"{LOCATION}-documentai.googleapis.com")
+
+    client = documentai_v1.DocumentProcessorServiceClient(client_options=opts)
+
+    return client
+
+
+@pytest.fixture(scope="module")
+def processor_id(client: documentai_v1.DocumentProcessorServiceClient) -> Processor:
+    processor_display_name = f"test-processor-{uuid4()}"
+
+    # Get the full resource name of the location.
+    # For example: `projects/{project_id}/locations/{location}`
+    parent = client.common_location_path(PROJECT_ID, LOCATION)
+
+    # Create a Processor.
+    # https://cloud.google.com/document-ai/docs/create-processor#available_processors
+    processor = client.create_processor(
+        parent=parent,
+        processor=documentai_v1.Processor(
+            type_="OCR_PROCESSOR",
+            display_name=processor_display_name,
+        ),
     )
 
-    assert processor is not None
-    assert "Invoice" in document.text
+    # `processor.name` (Full Processor Path) has this form:
+    # `projects/{project_id}/locations/{location}/processors/{processor_id}`
+    # Return only the `processor_id` section.
+    last_slash_index = processor.name.rfind('/')
+    yield processor.name[last_slash_index + 1:]
 
-    # Delete created processor
+    # Delete processor.
     client = documentai_v1.DocumentProcessorServiceClient(
         client_options=ClientOptions(
             api_endpoint=f"{LOCATION}-documentai.googleapis.com"
         )
     )
-    operation = client.delete_processor(name=processor.name)
+    client.delete_processor(name=processor.name)
+
 
-    # Wait for operation to complete
-    operation.result()
+def test_quickstart(processor_id: str) -> None:
+    document = quickstart_sample.quickstart(
+        project_id=PROJECT_ID,
+        processor_id=processor_id,
+        location=LOCATION,
+        file_path=FILE_PATH,
+    )
+
+    assert "Invoice" in document.text