docs(samples): add batch mode sample and test (GoogleCloudPlatform#10458)

* docs(samples): add batch mode sample and test

* add typehinting to arguments and returned values

* use return value to verify a delete operation succeeded

Author: irataxy

video/transcoder/create_job_from_ad_hoc.py

@@ -30,14 +30,23 @@
 )
 
 
-def create_job_from_ad_hoc(project_id, location, input_uri, output_uri):
+def create_job_from_ad_hoc(
+    project_id: str,
+    location: str,
+    input_uri: str,
+    output_uri: str,
+) -> transcoder_v1.types.resources.Job:
     """Creates a job based on an ad-hoc job configuration.
 
     Args:
         project_id: The GCP project ID.
         location: The location to start the job in.
         input_uri: Uri of the video in the Cloud Storage bucket.
-        output_uri: Uri of the video output folder in the Cloud Storage bucket."""
+        output_uri: Uri of the video output folder in the Cloud Storage bucket.
+
+    Returns:
+        The job resource.
+    """
 
     client = TranscoderServiceClient()
 

video/transcoder/create_job_from_preset.py

@@ -30,15 +30,25 @@
 )
 
 
-def create_job_from_preset(project_id, location, input_uri, output_uri, preset):
+def create_job_from_preset(
+    project_id: str,
+    location: str,
+    input_uri: str,
+    output_uri: str,
+    preset: str,
+) -> transcoder_v1.types.resources.Job:
     """Creates a job based on a job preset.
 
     Args:
         project_id: The GCP project ID.
         location: The location to start the job in.
         input_uri: Uri of the video in the Cloud Storage bucket.
         output_uri: Uri of the video output folder in the Cloud Storage bucket.
-        preset: The preset template (for example, 'preset/web-hd')."""
+        preset: The preset template (for example, 'preset/web-hd').
+
+    Returns:
+        The job resource.
+    """
 
     client = TranscoderServiceClient()
 

video/transcoder/create_job_from_preset_batch_mode.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python
+
+# Copyright 2023 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.
+
+"""Google Cloud Transcoder sample for creating a job in batch mode based on a
+    job preset.
+
+Example usage:
+    python create_job_from_preset_batch_mode.py --project_id <project-id> --location <location> --input_uri <uri> --output_uri <uri> [--preset <preset>]
+"""
+
+# [START transcoder_create_job_from_preset_batch_mode]
+
+import argparse
+
+from google.cloud.video import transcoder_v1
+from google.cloud.video.transcoder_v1.services.transcoder_service import (
+    TranscoderServiceClient,
+)
+
+
+def create_job_from_preset_batch_mode(
+    project_id: str,
+    location: str,
+    input_uri: str,
+    output_uri: str,
+    preset: str,
+) -> transcoder_v1.types.resources.Job:
+    """Creates a job in batch mode based on a job preset.
+
+    Args:
+        project_id: The GCP project ID.
+        location: The location to start the job in.
+        input_uri: Uri of the video in the Cloud Storage bucket.
+        output_uri: Uri of the video output folder in the Cloud Storage bucket.
+        preset: The preset template (for example, 'preset/web-hd').
+
+    Returns:
+        The job resource.
+    """
+
+    client = TranscoderServiceClient()
+
+    parent = f"projects/{project_id}/locations/{location}"
+    job = transcoder_v1.types.Job()
+    job.input_uri = input_uri
+    job.output_uri = output_uri
+    job.template_id = preset
+    job.mode = transcoder_v1.types.Job.ProcessingMode.PROCESSING_MODE_BATCH
+    job.batch_mode_priority = 10
+
+    response = client.create_job(parent=parent, job=job)
+    print(f"Job: {response.name}")
+    return response
+
+
+# [END transcoder_create_job_from_preset_batch_mode]
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project_id", help="Your Cloud project ID.", required=True)
+    parser.add_argument(
+        "--location",
+        help="The location to start this job in.",
+        default="us-central1",
+    )
+    parser.add_argument(
+        "--input_uri",
+        help="Uri of the video in the Cloud Storage bucket.",
+        required=True,
+    )
+    parser.add_argument(
+        "--output_uri",
+        help="Uri of the video output folder in the Cloud Storage bucket. Must end in '/'.",
+        required=True,
+    )
+    parser.add_argument(
+        "--preset",
+        help="The preset template (for example, 'preset/web-hd').",
+        default="preset/web-hd",
+    )
+    args = parser.parse_args()
+    create_job_from_preset_batch_mode(
+        args.project_id,
+        args.location,
+        args.input_uri,
+        args.output_uri,
+        args.preset,
+    )

video/transcoder/create_job_from_template.py

@@ -30,15 +30,25 @@
 )
 
 
-def create_job_from_template(project_id, location, input_uri, output_uri, template_id):
+def create_job_from_template(
+    project_id: str,
+    location: str,
+    input_uri: str,
+    output_uri: str,
+    template_id: str,
+) -> transcoder_v1.types.resources.Job:
     """Creates a job based on a job template.
 
     Args:
         project_id: The GCP project ID.
         location: The location to start the job in.
         input_uri: Uri of the video in the Cloud Storage bucket.
         output_uri: Uri of the video output folder in the Cloud Storage bucket.
-        template_id: The user-defined template ID."""
+        template_id: The user-defined template ID.
+
+    Returns:
+        The job resource.
+    """
 
     client = TranscoderServiceClient()
 

video/transcoder/create_job_template.py

@@ -30,13 +30,21 @@
 )
 
 
-def create_job_template(project_id, location, template_id):
+def create_job_template(
+    project_id: str,
+    location: str,
+    template_id: str,
+) -> transcoder_v1.types.resources.JobTemplate:
     """Creates a job template.
 
     Args:
         project_id: The GCP project ID.
         location: The location to store this template in.
-        template_id: The user-defined template ID."""
+        template_id: The user-defined template ID.
+
+    Returns:
+        The job template resource.
+    """
 
     client = TranscoderServiceClient()
 

video/transcoder/create_job_with_animated_overlay.py

@@ -32,16 +32,24 @@
 
 
 def create_job_with_animated_overlay(
-    project_id, location, input_uri, overlay_image_uri, output_uri
-):
+    project_id: str,
+    location: str,
+    input_uri: str,
+    overlay_image_uri: str,
+    output_uri: str,
+) -> transcoder_v1.types.resources.Job:
     """Creates a job based on an ad-hoc job configuration that includes an animated image overlay.
 
     Args:
         project_id: The GCP project ID.
         location: The location to start the job in.
         input_uri: Uri of the video in the Cloud Storage bucket.
         overlay_image_uri: Uri of the image for the overlay in the Cloud Storage bucket.
-        output_uri: Uri of the video output folder in the Cloud Storage bucket."""
+        output_uri: Uri of the video output folder in the Cloud Storage bucket.
+
+    Returns:
+        The job resource.
+    """
 
     client = TranscoderServiceClient()
 

video/transcoder/create_job_with_concatenated_inputs.py

@@ -35,16 +35,16 @@
 
 
 def create_job_with_concatenated_inputs(
-    project_id,
-    location,
-    input1_uri,
-    start_time_input1,
-    end_time_input1,
-    input2_uri,
-    start_time_input2,
-    end_time_input2,
-    output_uri,
-):
+    project_id: str,
+    location: str,
+    input1_uri: str,
+    start_time_input1: str,
+    end_time_input1: str,
+    input2_uri: str,
+    start_time_input2: str,
+    end_time_input2: str,
+    output_uri: str,
+) -> transcoder_v1.types.resources.Job:
     """Creates a job based on an ad-hoc job configuration that concatenates two input videos.
 
     Args:
@@ -61,7 +61,11 @@ def create_job_with_concatenated_inputs(
         end_time_input2 (str): End time, in fractional seconds ending in 's'
           (e.g., '15s'), relative to the second input video timeline.
         output_uri (str): Uri of the video output folder in the Cloud Storage
-          bucket."""
+          bucket.
+
+    Returns:
+        The job resource.
+    """
 
     s1 = duration.Duration()
     s1.FromJsonString(start_time_input1)

video/transcoder/create_job_with_embedded_captions.py

@@ -32,12 +32,12 @@
 
 
 def create_job_with_embedded_captions(
-    project_id,
-    location,
-    input_video_uri,
-    input_captions_uri,
-    output_uri,
-):
+    project_id: str,
+    location: str,
+    input_video_uri: str,
+    input_captions_uri: str,
+    output_uri: str,
+) -> transcoder_v1.types.resources.Job:
     """Creates a job based on an ad-hoc job configuration that embeds closed captions in the output video.
 
     Args:
@@ -48,7 +48,11 @@ def create_job_with_embedded_captions(
         input_captions_uri (str): Uri of the input captions file in the Cloud
           Storage bucket.
         output_uri (str): Uri of the video output folder in the Cloud Storage
-          bucket."""
+          bucket.
+
+    Returns:
+        The job resource.
+    """
 
     client = TranscoderServiceClient()
 

video/transcoder/create_job_with_periodic_images_spritesheet.py

@@ -32,15 +32,22 @@
 
 
 def create_job_with_periodic_images_spritesheet(
-    project_id, location, input_uri, output_uri
-):
+    project_id: str,
+    location: str,
+    input_uri: str,
+    output_uri: str,
+) -> transcoder_v1.types.resources.Job:
     """Creates a job based on an ad-hoc job configuration that generates two spritesheets.
 
     Args:
         project_id: The GCP project ID.
         location: The location to start the job in.
         input_uri: Uri of the video in the Cloud Storage bucket.
-        output_uri: Uri of the video output folder in the Cloud Storage bucket."""
+        output_uri: Uri of the video output folder in the Cloud Storage bucket.
+
+    Returns:
+        The job resource.
+    """
 
     client = TranscoderServiceClient()
 

video/transcoder/create_job_with_set_number_images_spritesheet.py

@@ -31,15 +31,22 @@
 
 
 def create_job_with_set_number_images_spritesheet(
-    project_id, location, input_uri, output_uri
-):
+    project_id: str,
+    location: str,
+    input_uri: str,
+    output_uri: str,
+) -> transcoder_v1.types.resources.Job:
     """Creates a job based on an ad-hoc job configuration that generates two spritesheets.
 
     Args:
         project_id: The GCP project ID.
         location: The location to start the job in.
         input_uri: Uri of the video in the Cloud Storage bucket.
-        output_uri: Uri of the video output folder in the Cloud Storage bucket."""
+        output_uri: Uri of the video output folder in the Cloud Storage bucket.
+
+    Returns:
+        The job resource.
+    """
 
     client = TranscoderServiceClient()