Validate template variables and improve defaults (frequenz-floss#95)

- Add some basic variable validation
- Improve defaults built with `name` (fixes frequenz-floss#79)
- Make sure name is converted to an identifier for files

Author: llucax

cookiecutter/cookiecutter.json

@@ -24,6 +24,7 @@
 	"default_codeowners": "(like @some-org/some-team; defaults to a team based on the repo type)",
 	"_extensions": [
 		"jinja2_time.TimeExtension",
+		"local_extensions.as_identifier",
 		"local_extensions.default_codeowners",
 		"local_extensions.github_repo_name",
 		"local_extensions.introduction",

cookiecutter/hooks/post_gen_project.py

@@ -474,9 +474,10 @@ def finish_lib_setup() -> None:
       - `lib`: `src/frequenz/{name}`
       - `rest`: `src/frequenz/{type}/{name}`
     """
+    name = cookiecutter.name.lower().replace("-", "_")
     recursive_overwrite_move(
-        _pathlib.Path(f"src/frequenz/{cookiecutter.type}/{cookiecutter.name}"),
-        _pathlib.Path(f"src/frequenz/{cookiecutter.name}"),
+        _pathlib.Path(f"src/frequenz/{cookiecutter.type}/{name}"),
+        _pathlib.Path(f"src/frequenz/{name}"),
     )
     _pathlib.Path(f"src/frequenz/{cookiecutter.type}").rmdir()
 

cookiecutter/hooks/pre_gen_project.py

@@ -0,0 +1,80 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Cookiecutter pre-generation hooks.
+
+This module contains the pre-generation hooks for the cookiecutter template. It
+validates the cookiecutter variables and prints an error message and exits with a
+non-zero exit code if any of them are invalid.
+"""
+
+import collections
+import json
+import re
+import sys
+from typing import Any
+
+NAME_REGEX = re.compile(r"^[a-zA-Z][_a-zA-Z0-9]+(-[_a-zA-Z][_a-zA-Z0-9]+)*$")
+PYTHON_PACKAGE_REGEX = re.compile(r"^[a-zA-Z][_a-zA-Z0-9]+(\.[_a-zA-Z][_a-zA-Z0-9]+)*$")
+PYPI_PACKAGE_REGEX = NAME_REGEX
+
+
+def to_named_tuple(dictionary: dict[Any, Any], /) -> Any:
+    """Convert a dictionary to a named tuple.
+
+    Args:
+        dictionary: The dictionary to convert.
+
+    Returns:
+        The named tuple with the same keys and values as the dictionary.
+    """
+    filtered = {k: v for k, v in dictionary.items() if not k.startswith("_")}
+    return collections.namedtuple("Cookiecutter", filtered.keys())(*filtered.values())
+
+
+cookiecutter = to_named_tuple(json.loads(r"""{{cookiecutter | tojson}}"""))
+
+
+def main() -> None:
+    """Validate the cookiecutter variables.
+
+    This function validates the cookiecutter variables and prints an error message and
+    exits with a non-zero exit code if any of them are invalid.
+    """
+    errors: dict[str, list[str]] = {}
+
+    def add_error(key: str, message: str) -> None:
+        """Add an error to the error dictionary.
+
+        Args:
+            key: The key of the error.
+            message: The error message.
+        """
+        errors.setdefault(key, []).append(message)
+
+    if not NAME_REGEX.match(cookiecutter.name):
+        add_error("name", f"Invalid project name (must match {NAME_REGEX.pattern})")
+
+    if not PYTHON_PACKAGE_REGEX.match(cookiecutter.python_package):
+        add_error(
+            "python_package",
+            f"Invalid package name (must match {PYTHON_PACKAGE_REGEX.pattern})",
+        )
+
+    if not PYPI_PACKAGE_REGEX.match(cookiecutter.pypi_package_name):
+        add_error(
+            "pypi_package_name",
+            f"Invalid package name (must match {PYPI_PACKAGE_REGEX.pattern})",
+        )
+
+    if errors:
+        print("The following errors were found:", file=sys.stderr)
+        for key, messages in errors.items():
+            print(f"  {key}:", file=sys.stderr)
+            for message in messages:
+                print(f"    - {message}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

cookiecutter/local_extensions.py

@@ -24,6 +24,11 @@ def _build_identifier(repo_type: str, name: str, separator: str) -> str:
     Returns:
         The built identifier.
     """
+    if separator == ".":
+        name = name.replace("-", "_")
+    if separator == "-":
+        name = name.replace("_", "-")
+    name = name.lower()
     middle = f"{repo_type}{separator}" if repo_type != "lib" else ""
     return f"frequenz{separator}{middle}{name}"
 
@@ -42,6 +47,19 @@ def _get_from_json(key: str) -> str:
 
 
 # Ignoring because cookiecutter simple_filter decorator is not typed.
+@_simple_filter  # type: ignore[misc]
+def as_identifier(name: str) -> str:
+    """Convert a name to a valid identifier.
+
+    Args:
+        name: The name to convert.
+
+    Returns:
+        The converted identifier.
+    """
+    return name.lower().replace("-", "_")
+
+
 @_simple_filter  # type: ignore[misc]
 def python_package(cookiecutter: dict[str, str]) -> str:
     """Generate the Python package (import) depending on the repository type.
@@ -93,7 +111,7 @@ def title(cookiecutter: dict[str, str]) -> str:
     Returns:
         The default site name.
     """
-    name = cookiecutter["name"].capitalize()
+    name = cookiecutter["name"].replace("_", " ").replace("-", " ").title()
     match cookiecutter["type"]:
         case "actor":
             return f"Frequenz {name} Actor"

cookiecutter/variable-reference.md

@@ -2,7 +2,9 @@
 
 * `name`: The name of the project. This will be used to build defaults for
   other inputs, such as `title`, `python_package`, etc. It should be one word,
-  using only alphanumeric characters (and starting with a letter).
+  using only alphanumeric characters (and starting with a letter). It can
+  include also `_` and `-` which will be handled differently when building
+  other variables from it (replaced by spaces in titles for example).
 
 * `description`: A short description of the project. It will be used as the
   description in the `README.md`, `pyproject.toml`, `mkdocs.yml`, etc.

cookiecutter/{{cookiecutter.github_repo_name}}/.github/labeler.yml

@@ -10,10 +10,10 @@
 # For example:
 #
 # "part:module":
-#   - "src/frequenz/{{cookiecutter.type}}/{{cookiecutter.name}}/module/**"
+#   - "src/frequenz/{{cookiecutter.type}}/{{cookiecutter.name | as_identifier}}/module/**"
 #
 # "part:other":
-#   - "src/frequenz/{{cookiecutter.type}}/{{cookiecutter.name}}/other/**"
+#   - "src/frequenz/{{cookiecutter.type}}/{{cookiecutter.name | as_identifier}}/other/**"
 #
 # # For excluding some files (in this example, label "part:complicated"
 # # everything inside src/ with a .py suffix, except for src/__init__.py)

cookiecutter/{{cookiecutter.github_repo_name}}/proto/frequenz/api/{{cookiecutter.name}}/{{cookiecutter.name}}.proto renamed to cookiecutter/{{cookiecutter.github_repo_name}}/proto/frequenz/api/{{cookiecutter.name | as_identifier}}/{{cookiecutter.name | as_identifier}}.proto

@@ -12,7 +12,7 @@
 
 syntax = "proto3";
 
-package frequenz.api.{{cookiecutter.name}}.{{cookiecutter.name}};
+package frequenz.api.{{cookiecutter.name | as_identifier}}.{{cookiecutter.name | as_identifier}};
 
 // An example message.
 //

cookiecutter/{{cookiecutter.github_repo_name}}/src/frequenz/{{cookiecutter.type}}/{{cookiecutter.name}}/__init__.py renamed to cookiecutter/{{cookiecutter.github_repo_name}}/src/frequenz/{{cookiecutter.type}}/{{cookiecutter.name | as_identifier}}/__init__.py

@@ -1,42 +1,42 @@
 # License: {{cookiecutter.license}}
 # Copyright © {% now 'utc', '%Y' %} {{cookiecutter.author_name}}
 
-"""Tests for the {{cookiecutter.name}} package."""
+"""Tests for the {{cookiecutter.python_package}} package."""
 
 {%- if cookiecutter.type == "api" %}
 
 
 def test_package_import() -> None:
     """Test that the package can be imported."""
     # pylint: disable=import-outside-toplevel
-    from frequenz.api import {{cookiecutter.name}}
+    from frequenz.api import {{cookiecutter.name | as_identifier}}
 
-    assert {{cookiecutter.name}} is not None
+    assert {{cookiecutter.name | as_identifier}} is not None
 
 
 def test_module_import_components() -> None:
     """Test that the modules can be imported."""
     # pylint: disable=import-outside-toplevel
-    from frequenz.api.{{cookiecutter.name}} import {{cookiecutter.name}}_pb2
+    from frequenz.api.{{cookiecutter.name | as_identifier}} import {{cookiecutter.name | as_identifier}}_pb2
 
-    assert {{cookiecutter.name}}_pb2 is not None
+    assert {{cookiecutter.name | as_identifier}}_pb2 is not None
 
     # pylint: disable=import-outside-toplevel
-    from frequenz.api.{{cookiecutter.name}} import {{cookiecutter.name}}_pb2_grpc
+    from frequenz.api.{{cookiecutter.name | as_identifier}} import {{cookiecutter.name | as_identifier}}_pb2_grpc
 
-    assert {{cookiecutter.name}}_pb2_grpc is not None
+    assert {{cookiecutter.name | as_identifier}}_pb2_grpc is not None
 {%- else %}
 import pytest
 
 from {{cookiecutter.python_package}} import delete_me
 
 
-def test_{{cookiecutter.name}}_succeeds() -> None:  # TODO(cookiecutter): Remove
+def test_{{cookiecutter.name | as_identifier}}_succeeds() -> None:  # TODO(cookiecutter): Remove
     """Test that the delete_me function succeeds."""
     assert delete_me() is True
 
 
-def test_{{cookiecutter.name}}_fails() -> None:  # TODO(cookiecutter): Remove
+def test_{{cookiecutter.name | as_identifier}}_fails() -> None:  # TODO(cookiecutter): Remove
     """Test that the delete_me function fails."""
     with pytest.raises(RuntimeError, match="This function should be removed!"):
         delete_me(blow_up=True)