Boilerplate reduction: Notebook template (#1204)

* Reduced notebook boilerplate

* Fixed lint issues

* Added unique suffix note

* Added unique string processor and moved tests to own folder

* Fixed broken link

* Added message about updating links

* Fixed typo

* Added missing import

* Added back useful instructions

* Addressed comments

* Removed matching engine

* Fixed comments

.cloud-build/execute_changed_notebooks_helper.py

@@ -38,7 +38,7 @@ from utils import NotebookProcessors, util
 
 # A buffer so that workers finish before the orchestrating job
 WORKER_TIMEOUT_BUFFER_IN_SECONDS: int = 60 * 60
-PYTHON_VERSION = "3.9" # Set default python version
+PYTHON_VERSION = "3.9"  # Set default python version
 
 
 def format_timedelta(delta: datetime.timedelta) -> str:
@@ -102,6 +102,7 @@ def _process_notebook(
             "VPC_NETWORK": variable_vpc_network,
         },
     )
+    unique_strings_preprocessor = NotebookProcessors.UniqueStringsPreprocessor()
 
     # Use no-execute preprocessor
     (
@@ -127,13 +128,15 @@ def _get_notebook_python_version(notebook_path: str) -> str:
     src = file.read()
     nb_json = json.loads(src)
 
-    #Iterate over the cells in the ipynb
-    for cell in nb_json['cells']:
-        if cell['cell_type'] == 'markdown':
-            markdown = str.join('', cell['source'])
+    # Iterate over the cells in the ipynb
+    for cell in nb_json["cells"]:
+        if cell["cell_type"] == "markdown":
+            markdown = str.join("", cell["source"])
 
             # Look for the python version specification pattern
-            re_match = re.search('python version = (\d\.\d)', markdown, flags=re.IGNORECASE)
+            re_match = re.search(
+                "python version = (\d\.\d)", markdown, flags=re.IGNORECASE
+            )
             if re_match:
                 # get the version number
                 python_version = re_match.group(1)
@@ -201,7 +204,9 @@ def process_and_execute_notebook(
     operation = None
     try:
         # Get the python version for running the notebook if specified
-        notebook_exec_python_version = _get_notebook_python_version(notebook_path=notebook)
+        notebook_exec_python_version = _get_notebook_python_version(
+            notebook_path=notebook
+        )
         print(f"Running notebook with python {notebook_exec_python_version}")
 
         # Pre-process notebook by substituting variable names
@@ -230,7 +235,7 @@ def process_and_execute_notebook(
             private_pool_id=private_pool_id,
             private_pool_region=variable_region,
             timeout_in_seconds=timeout_in_seconds,
-            python_version=notebook_exec_python_version
+            python_version=notebook_exec_python_version,
         )
 
         operation_metadata = BuildOperationMetadata(mapping=operation.metadata)
@@ -443,7 +448,7 @@ def process_and_execute_notebooks(
                         result.log_url,
                         result.output_uri,
                         result.output_uri_web,
-                        result.logs_bucket
+                        result.logs_bucket,
                     ]
                     for result in results_sorted
                 ],
@@ -454,34 +459,34 @@ def process_and_execute_notebooks(
                     "log_url",
                     "output_uri",
                     "output_uri_web",
-                    "logs_bucket"
+                    "logs_bucket",
                 ],
             )
         )
 
         if len(notebooks) == 1:
-          print("="*100)
-          print("The notebook execution build log:\n")
-          print("="*100)
+            print("=" * 100)
+            print("The notebook execution build log:\n")
+            print("=" * 100)
 
-          build_id = results_sorted[0].build_id
-          logs_bucket_name = (results_sorted[0].logs_bucket).removeprefix("gs://")
-          log_file_name = f"log-{build_id}.txt"
+            build_id = results_sorted[0].build_id
+            logs_bucket_name = (results_sorted[0].logs_bucket).removeprefix("gs://")
+            log_file_name = f"log-{build_id}.txt"
 
-          log_contents = util.download_blob_into_memory(
-            bucket_name=logs_bucket_name,
-            blob_name=log_file_name,
-            download_as_text=True
+            log_contents = util.download_blob_into_memory(
+                bucket_name=logs_bucket_name,
+                blob_name=log_file_name,
+                download_as_text=True,
             )
 
-          # Remove extra steps from the log
-          match = re.search("starting Step #4", log_contents, flags=re.IGNORECASE)
+            # Remove extra steps from the log
+            match = re.search("starting Step #4", log_contents, flags=re.IGNORECASE)
 
-          if match is not None:
-            match_index = match.span()[0]
-            print(log_contents[match_index:])
-          else:
-            print(log_contents)
+            if match is not None:
+                match_index = match.span()[0]
+                print(log_contents[match_index:])
+            else:
+                print(log_contents)
 
         print("\n=== END RESULTS===\n")
 

.cloud-build/test_notebook_vm.txt

@@ -2,5 +2,4 @@ notebooks/official/vizier/gapic-vizier-multi-objective-optimization.ipynb
 notebooks/official/pipelines/lightweight_functions_component_io_kfp.ipynb
 notebooks/official/ml_metadata/sdk-metric-parameter-tracking-for-locally-trained-models.ipynb
 notebooks/official/custom/custom-tabular-bq-managed-dataset.ipynb
-notebooks/official/matching_engine/sdk_matching_engine_for_indexing.ipynb
 .cloud-build/tests/python_version_test.ipynb

.cloud-build/utils/NotebookProcessors.py

@@ -14,6 +14,8 @@
 # limitations under the License.
 
 from typing import Dict
+import random
+import string
 
 from nbconvert.preprocessors import Preprocessor
 
@@ -63,3 +65,30 @@ class UpdateVariablesPreprocessor(Preprocessor):
             executable_cells.append(cell)
         notebook.cells = executable_cells
         return notebook, resources
+
+
+# Generate a uuid of a specifed length
+def generate_uuid(length: int = 8) -> str:
+    return "".join(random.choices(string.ascii_lowercase + string.digits, k=length))
+
+
+class UniqueStringsPreprocessor(Preprocessor):
+    # A preprocessor that replaces strings that end with "-unique" with a uuid.
+
+    @staticmethod
+    def update_unique_strings(content: str):
+        # Replace strings that end with "-unique" with a uuid.
+
+        return content.replace('-unique"', f'-{generate_uuid()}"')
+
+    def preprocess(self, notebook, resources=None):
+        executable_cells = []
+        for cell in notebook.cells:
+            if cell.cell_type == "code":
+                cell.source = self.update_unique_strings(
+                    content=cell.source,
+                )
+
+            executable_cells.append(cell)
+        notebook.cells = executable_cells
+        return notebook, resources

.cloud-build/utils/UpdateNotebookVariables.py

@@ -40,65 +40,3 @@ def get_updated_value(content: str, variable_name: str, variable_value: str) ->
         content,
         flags=re.M,
     )
-
-
-def test_update_value():
-    new_content = get_updated_value(
-        content='asdf\nPROJECT_ID = "[your-project-id]" #@param {type:"string"} \nasdf',
-        variable_name="PROJECT_ID",
-        variable_value="sample-project",
-    )
-    assert (
-        new_content
-        == 'asdf\nPROJECT_ID = "sample-project" #@param {type:"string"} \nasdf'
-    )
-
-
-def test_update_value_single_quotes():
-    new_content = get_updated_value(
-        content="PROJECT_ID = '[your-project-id]'",
-        variable_name="PROJECT_ID",
-        variable_value="sample-project",
-    )
-    assert new_content == "PROJECT_ID = 'sample-project'"
-
-
-def test_update_value_avoidance():
-    new_content = get_updated_value(
-        content="PROJECT_ID = shell_output[0] ",
-        variable_name="PROJECT_ID",
-        variable_value="sample-project",
-    )
-    assert new_content == "PROJECT_ID = shell_output[0] "
-
-
-def test_region():
-    new_content = get_updated_value(
-        content='REGION = "[your-region]"  # @param {type:"string"}',
-        variable_name="REGION",
-        variable_value="us-central1",
-    )
-    assert new_content == 'REGION = "us-central1"  # @param {type:"string"}'
-
-
-def test_region_equal_equals_ignore():
-    # Tests that == is ignored
-    new_content = get_updated_value(
-        content='REGION == "[your-region]"  # @param {type:"string"}',
-        variable_name="REGION",
-        variable_value="us-central1",
-    )
-    assert new_content == 'REGION == "[your-region]"  # @param {type:"string"}'
-
-
-def test_service_account():
-    # Tests that == is ignored
-    new_content = get_updated_value(
-        content='SERVICE_ACCOUNT = "[your-service-account]"  # @param {type:"string"}',
-        variable_name="SERVICE_ACCOUNT",
-        variable_value="12345-compute@developer.gserviceaccount.com",
-    )
-    assert (
-        new_content
-        == 'SERVICE_ACCOUNT = "12345-compute@developer.gserviceaccount.com"  # @param {type:"string"}'
-    )

.cloud-build/utils/tests/test_preprocessors.py

@@ -0,0 +1,14 @@
+from utils import NotebookProcessors
+
+
+def test_update_value():
+    # Test that the content was updated
+    preprocessor = NotebookProcessors.UniqueStringsPreprocessor()
+
+    content = 'PROJECT_ID = "your-project-id-unique"'
+
+    new_content = preprocessor.update_unique_strings(content)
+
+    assert new_content != content
+    assert new_content.startswith('PROJECT_ID = "your-project-id-')
+    assert new_content.endswith('"')

.cloud-build/utils/tests/test_update_notebook_variables.py

@@ -0,0 +1,63 @@
+from utils import UpdateNotebookVariables
+
+
+def test_update_value():
+    new_content = UpdateNotebookVariables.get_updated_value(
+        content='asdf\nPROJECT_ID = "[your-project-id]" #@param {type:"string"} \nasdf',
+        variable_name="PROJECT_ID",
+        variable_value="sample-project",
+    )
+    assert (
+        new_content
+        == 'asdf\nPROJECT_ID = "sample-project" #@param {type:"string"} \nasdf'
+    )
+
+
+def test_update_value_single_quotes():
+    new_content = UpdateNotebookVariables.get_updated_value(
+        content="PROJECT_ID = '[your-project-id]'",
+        variable_name="PROJECT_ID",
+        variable_value="sample-project",
+    )
+    assert new_content == "PROJECT_ID = 'sample-project'"
+
+
+def test_update_value_avoidance():
+    new_content = UpdateNotebookVariables.get_updated_value(
+        content="PROJECT_ID = shell_output[0] ",
+        variable_name="PROJECT_ID",
+        variable_value="sample-project",
+    )
+    assert new_content == "PROJECT_ID = shell_output[0] "
+
+
+def test_region():
+    new_content = UpdateNotebookVariables.get_updated_value(
+        content='REGION = "[your-region]"  # @param {type:"string"}',
+        variable_name="REGION",
+        variable_value="us-central1",
+    )
+    assert new_content == 'REGION = "us-central1"  # @param {type:"string"}'
+
+
+def test_region_equal_equals_ignore():
+    # Tests that == is ignored
+    new_content = UpdateNotebookVariables.get_updated_value(
+        content='REGION == "[your-region]"  # @param {type:"string"}',
+        variable_name="REGION",
+        variable_value="us-central1",
+    )
+    assert new_content == 'REGION == "[your-region]"  # @param {type:"string"}'
+
+
+def test_service_account():
+    # Tests that == is ignored
+    new_content = UpdateNotebookVariables.get_updated_value(
+        content='SERVICE_ACCOUNT = "[your-service-account]"  # @param {type:"string"}',
+        variable_name="SERVICE_ACCOUNT",
+        variable_value="12345-compute@developer.gserviceaccount.com",
+    )
+    assert (
+        new_content
+        == 'SERVICE_ACCOUNT = "12345-compute@developer.gserviceaccount.com"  # @param {type:"string"}'
+    )