chore: configured snippet generates empty sample function (#1525)

* chore: configured snippet generates empty sample function

Author: dizcology

packages/gapic-generator/gapic/configurable_snippetgen/configured_snippet.py

@@ -17,23 +17,23 @@
 import inflection
 import libcst
 
+from gapic.configurable_snippetgen import libcst_utils
 from gapic.configurable_snippetgen import snippet_config_language_pb2
 from gapic.schema import api
 
 
-def _make_empty_module() -> libcst.Module:
-    return libcst.Module(body=[])
-
-
-@dataclasses.dataclass(frozen=True)
+@dataclasses.dataclass
 class ConfiguredSnippet:
     api_schema: api.API
     config: snippet_config_language_pb2.SnippetConfig
     api_version: str
     is_sync: bool
-    _module: libcst.Module = dataclasses.field(
-        default_factory=_make_empty_module, init=False
-    )
+
+    def __post_init__(self):
+        self._module: libcst.Module = libcst_utils.empty_module()
+        self._sample_function_def: libcst.FunctionDef = libcst_utils.base_function_def(
+            function_name=self.sample_function_name, is_sync=self.is_sync
+        )
 
     @property
     def code(self) -> str:
@@ -78,3 +78,26 @@ def filename(self) -> str:
         config_id = self.config.metadata.config_id
         sync_or_async = "sync" if self.is_sync else "async"
         return f"{module_name}_{self.api_version}_generated_{service_name}_{snake_case_rpc_name}_{config_id}_{sync_or_async}.py"
+
+    def _build_sample_function(self) -> None:
+        # TODO: https://github.com/googleapis/gapic-generator-python/issues/1536, add return type.
+        # TODO: https://github.com/googleapis/gapic-generator-python/issues/1537, add sample function parameters.
+        # TODO: https://github.com/googleapis/gapic-generator-python/issues/1538, add docstring.
+        # TODO: https://github.com/googleapis/gapic-generator-python/issues/1539, add sample function body.
+        pass
+
+    def _add_sample_function(self) -> None:
+        self._module = self._module.with_changes(
+            body=[self._sample_function_def])
+
+    def generate(self) -> None:
+        """Generates the snippet.
+
+        This is the main entrypoint of a ConfiguredSnippet instance, calling
+        other methods to update self._module.
+        """
+        self._build_sample_function()
+        self._add_sample_function()
+        # TODO: https://github.com/googleapis/gapic-generator-python/issues/1535, add imports.
+        # TODO: https://github.com/googleapis/gapic-generator-python/issues/1534, add region tag.
+        # TODO: https://github.com/googleapis/gapic-generator-python/issues/1533, add header.

packages/gapic-generator/gapic/configurable_snippetgen/libcst_utils.py

@@ -0,0 +1,36 @@
+# 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 libcst
+
+from gapic.configurable_snippetgen import snippet_config_language_pb2
+
+
+def empty_module() -> libcst.Module:
+    return libcst.Module(body=[])
+
+
+def base_function_def(function_name: str, is_sync: bool) -> libcst.FunctionDef:
+    """Returns a FunctionDef node with a placeholder docstring."""
+    params = libcst.Parameters(params=[])
+    body = libcst.IndentedBlock(body=[libcst.parse_statement('""')])
+    asynchronous = None if is_sync else libcst.Asynchronous()
+    function_def = libcst.FunctionDef(
+        name=libcst.Name(value=function_name),
+        params=params,
+        body=body,
+        asynchronous=asynchronous,
+    )
+
+    return function_def

packages/gapic-generator/tests/unit/configurable_snippetgen/test_configured_snippet.py

@@ -26,13 +26,11 @@
 
 
 CURRENT_DIRECTORY = Path(__file__).parent.absolute()
-SPEECH_V1_REQUEST_PATH = (CURRENT_DIRECTORY /
-    "resources" / "speech" / "request.desc")
+SPEECH_V1_REQUEST_PATH = CURRENT_DIRECTORY / \
+    "resources" / "speech" / "request.desc"
 CONFIG_JSON_PATH = (
-    CURRENT_DIRECTORY /
-    "resources" /
-    "speech" /
-    "speech_createCustomClass.json")
+    CURRENT_DIRECTORY / "resources" / "speech" / "speech_createCustomClass.json"
+)
 
 
 def _load_api_schema(request_path: Path) -> api.API:
@@ -79,16 +77,13 @@ def _make_configured_snippet(
 @pytest.fixture
 def snippet():
     return _make_configured_snippet(
-        SPEECH_V1_REQUEST_PATH,
-        CONFIG_JSON_PATH,
-        api_version="v1",
-        is_sync=True)
+        SPEECH_V1_REQUEST_PATH, CONFIG_JSON_PATH, api_version="v1", is_sync=True
+    )
 
 
 def test_region_tag(snippet):
     assert (
-        snippet.region_tag
-        == "speech_v1_config_Adaptation_CreateCustomClass_Basic_sync"
+        snippet.region_tag == "speech_v1_config_Adaptation_CreateCustomClass_Basic_sync"
     )
 
 
@@ -97,13 +92,19 @@ def test_sample_function_name(snippet):
 
 
 def test_filename(snippet):
-    assert snippet.filename == "speech_v1_generated_Adaptation_create_custom_class_Basic_sync.py"
+    assert (
+        snippet.filename
+        == "speech_v1_generated_Adaptation_create_custom_class_Basic_sync.py"
+    )
 
 
 def test_code(snippet):
+    snippet.generate()
+
     # https://github.com/googleapis/gapic-generator-python/issues/1522
     # Placeholder code.  We will gradually add to the ConfiguredSnippet class
     # until the generated code is the same as that of the golden file.
-    expected_code = "\n"
-
+    expected_code = """def sample_create_custom_class_Basic():
+    \"\"
+"""
     assert snippet.code == expected_code

packages/gapic-generator/tests/unit/configurable_snippetgen/test_libcst_utils.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+# 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 libcst
+import pytest
+
+from gapic.configurable_snippetgen import libcst_utils
+
+
+def _assert_code_equal(node: libcst.CSTNode, code: str) -> str:
+    assert libcst.Module(body=[node]).code == code
+
+
+@pytest.mark.parametrize(
+    "is_sync,expected_code",
+    [
+        (True, 'def some_function():\n    ""\n'),
+        (False, 'async def some_function():\n    ""\n'),
+    ],
+)
+def test_base_function_def(is_sync, expected_code):
+    node = libcst_utils.base_function_def("some_function", is_sync)
+
+    expected_node = libcst.parse_statement(expected_code)
+
+    # Whenever possible we try to control the shape of the nodes,
+    # because we will be manipulating them during snippet generation.
+    assert node.deep_equals(expected_node), (node, expected_node)
+
+    # Sometimes it is more convenient to just verify the code.
+    _assert_code_equal(node, expected_code)

packages/gapic-generator/tests/unit/configurable_snippetgen/test_resources.py

@@ -23,8 +23,8 @@
 
 
 CURRENT_DIRECTORY = Path(__file__).parent.absolute()
-SPEECH_V1_REQUEST_PATH = (CURRENT_DIRECTORY /
-    "resources" / "speech" / "request.desc")
+SPEECH_V1_REQUEST_PATH = CURRENT_DIRECTORY / \
+    "resources" / "speech" / "request.desc"
 
 
 def test_request():