fix: Clarify comments and extend tests for PR feedback

Signed-off-by: Mark Wiebe <[email protected]>

Author: mwiebe

src/openjd/model/_parse.py

@@ -167,7 +167,7 @@ def decode_job_template(
 
     Args:
         template (dict[str, Any]): A Job Template as a dictionary object.
-        supported_extensions (list[str]): A list of extension names to support. This list is intersected
+        supported_extensions (Optional[Iterable[str]]): A list of extension names to support. This list is intersected
             with the extensions names supported by the implementation before processing.
 
     Returns:
@@ -241,7 +241,7 @@ def decode_environment_template(
 
     Args:
         template (dict[str, Any]): An Environment Template as a dictionary object.
-        supported_extensions (list[str]): A list of extension names to support. This list is intersected
+        supported_extensions (Optional[Iterable[str]]): A list of extension names to support. This list is intersected
             with the extensions names supported by the implementation before processing.
 
     Returns:

src/openjd/model/v2023_09/_model.py

@@ -62,9 +62,15 @@ class ModelParsingContext:
     """
 
     extensions: set[str]
-    """Initially, is the set of supported extension names. When the 'extensions'
-    field of the template is processed, this becomes the set of extensions that
-    the the template requested."""
+    """When parsing a top-level model instance, this is the set of supported extension names.
+    The 'extensions' field is second in the list of model properties for both the job template
+    and environment template, and when that field is processed it becomes the set of extensions
+    that the template requested.
+
+    When fields of a model that depend on an extension are processed, its validators should
+    check whether the needed extension is included in the context and adjust its parsing
+    as written in the specification.
+    """
 
     def __init__(self, *, supported_extensions: Optional[Iterable[str]] = None) -> None:
         self.extensions = set(supported_extensions or [])
@@ -2450,7 +2456,8 @@ def _permitted_extension_names(
     ) -> Optional[ExtensionNameList]:
         context = cast(ModelParsingContext, info.context)
         if value is not None:
-            # Before processing the extensions field, context.extensions is the list of supported extensions.
+            # Before processing the extensions field, context.extensions is the list of supported extensions
+            # that were requested in the call of the parse_job_template function.
             # Take the intersection of the input supported extensions with what is implemented
             # in this list, as the implementation needs to support an extension for it to be supported.
             supported_extensions = context.extensions.intersection(cls.supported_extension_names())

test/openjd/model/test_parse.py

@@ -196,6 +196,13 @@ class MockExtensionName(str, Enum):
     SUPPORTED_NAME = "SUPPORTED_NAME"
 
 
+class MockExtensionNameWithTwoNames(str, Enum):
+    """A mock enum with only SUPPORTED_NAME for testing."""
+
+    SUPPORTED_NAME = "SUPPORTED_NAME"
+    ANOTHER_SUPPORTED_NAME = "ANOTHER_SUPPORTED_NAME"
+
+
 @pytest.mark.parametrize(
     "template,template_type,decode_function",
     [
@@ -262,6 +269,12 @@ def test_template_extensions_list(template, template_type, decode_function) -> N
             in str(excinfo.value)
         )
 
+        # Extension names cannot be repeated
+        template["extensions"] = ["SUPPORTED_NAME", "SUPPORTED_NAME"]
+        with pytest.raises(DecodeValidationError) as excinfo:
+            decode_function(template=template)
+        assert "Duplicate values for extension name are not allowed." in str(excinfo.value)
+
         # When the request list includes an unsupported extension name
         template["extensions"] = ["SUPPORTED_NAME"]
         with pytest.raises(DecodeValidationError) as excinfo:
@@ -279,3 +292,10 @@ def test_template_extensions_list(template, template_type, decode_function) -> N
             f"1 validation errors for {template_type}\nextensions:\n\tUnsupported extension names: UNSUPPORTED_NAME"
             in str(excinfo.value)
         )
+
+    # For this test, there are two different extension names supported
+    with patch.object(openjd.model.v2023_09._model, "ExtensionName", MockExtensionNameWithTwoNames):
+        # When the requested extension name is in the supported list
+        template["extensions"] = ["ANOTHER_SUPPORTED_NAME"]
+        model = decode_function(template=template, supported_extensions=["ANOTHER_SUPPORTED_NAME"])
+        assert model.extensions == ["ANOTHER_SUPPORTED_NAME"]