feat: Implement the extensions RFC 0002

README.md

@@ -23,13 +23,13 @@ This library requires:
 
 ## Versioning
 
-This package's version follows [Semantic Versioning 2.0](https://semver.org/), but is still considered to be in its 
+This package's version follows [Semantic Versioning 2.0](https://semver.org/), but is still considered to be in its
 initial development, thus backwards incompatible versions are denoted by minor version bumps. To help illustrate how
 versions will increment during this initial development stage, they are described below:
 
-1. The MAJOR version is currently 0, indicating initial development. 
-2. The MINOR version is currently incremented when backwards incompatible changes are introduced to the public API. 
-3. The PATCH version is currently incremented when bug fixes or backwards compatible changes are introduced to the public API. 
+1. The MAJOR version is currently 0, indicating initial development.
+2. The MINOR version is currently incremented when backwards incompatible changes are introduced to the public API.
+3. The PATCH version is currently incremented when bug fixes or backwards compatible changes are introduced to the public API.
 
 ## Contributing
 
@@ -303,7 +303,7 @@ For example, if you would like to verify your download of the wheel for version
 3) Save the following contents to a file called `openjobdescription-pgp.asc`:
     ```
     -----BEGIN PGP PUBLIC KEY BLOCK-----
-    
+
     mQINBGXGjx0BEACdChrQ/nch2aYGJ4fxHNQwlPE42jeHECqTdlc1V/mug+7qN7Pc
     C4NQk4t68Y72WX/NG49gRfpAxPlSeNt18c3vJ9/sWTukmonWYGK0jQGnDWjuVgFT
     XtvJAAQBFilQXN8h779Th2lEuD4bQX+mGB7l60Xvh7vIehE3C4Srbp6KJXskPLPo
@@ -350,36 +350,36 @@ For example, if you would like to verify your download of the wheel for version
     gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc.
     This is free software: you are free to change and redistribute it.
     There is NO WARRANTY, to the extent permitted by law.
-    
-    
+
+
     pub  4096R/BCC40987  created: 2024-02-09  expires: 2026-02-08  usage: SCEA
                          trust: unknown       validity: unknown
     [ unknown] (1). Open Job Description <[email protected]>
-    
+
     gpg> trust
     pub  4096R/BCC40987  created: 2024-02-09  expires: 2026-02-08  usage: SCEA
                          trust: unknown       validity: unknown
     [ unknown] (1). Open Job Description <[email protected]>
-    
+
     Please decide how far you trust this user to correctly verify other users' keys
     (by looking at passports, checking fingerprints from different sources, etc.)
-    
+
       1 = I don't know or won't say
       2 = I do NOT trust
       3 = I trust marginally
       4 = I trust fully
       5 = I trust ultimately
       m = back to the main menu
-    
+
     Your decision? 5
     Do you really want to set this key to ultimate trust? (y/N) y
-    
+
     pub  4096R/BCC40987  created: 2024-02-09  expires: 2026-02-08  usage: SCEA
                          trust: ultimate      validity: unknown
     [ unknown] (1). Open Job Description <[email protected]>
     Please note that the shown key validity is not necessarily correct
     unless you restart the program.
-    
+
     gpg> quit
     ```
 
@@ -391,11 +391,11 @@ For example, if you would like to verify your download of the wheel for version
 
 ## Security
 
-We take all security reports seriously. When we receive such reports, we will 
-investigate and subsequently address any potential vulnerabilities as quickly 
-as possible. If you discover a potential security issue in this project, please 
+We take all security reports seriously. When we receive such reports, we will
+investigate and subsequently address any potential vulnerabilities as quickly
+as possible. If you discover a potential security issue in this project, please
 notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/)
-or directly via email to [AWS Security]([email protected]). Please do not 
+or directly via email to [AWS Security]([email protected]). Please do not
 create a public GitHub issue in this project.
 
 ## License

src/openjd/model/_parse.py

@@ -4,6 +4,7 @@
 from dataclasses import is_dataclass
 from decimal import Decimal
 from enum import Enum
+from collections.abc import Iterable
 from typing import Any, ClassVar, Optional, Type, TypeVar, Union, cast
 
 import yaml
@@ -44,9 +45,14 @@ class PydanticDataclass:
 T = TypeVar("T", bound=OpenJDModel)
 
 
-def _parse_model(*, model: Type[T], obj: Any) -> T:
+def _parse_model(*, model: Type[T], obj: Any, context: Any = None) -> T:
+    if context is None:
+        context = model.model_parsing_context_type()
     if is_dataclass(model):
-        return cast(T, cast(PydanticDataclass, model).__pydantic_model__.model_validate(obj))
+        return cast(
+            T,
+            cast(PydanticDataclass, model).__pydantic_model__.model_validate(obj, context=context),
+        )
     else:
         prevalidator_error: Optional[PydanticValidationError] = None
         if hasattr(model, "_root_template_prevalidator"):
@@ -55,7 +61,7 @@ def _parse_model(*, model: Type[T], obj: Any) -> T:
             except PydanticValidationError as exc:
                 prevalidator_error = exc
         try:
-            result = cast(T, cast(BaseModel, model).model_validate(obj))
+            result = cast(T, cast(BaseModel, model).model_validate(obj, context=context))
         except PydanticValidationError as exc:
             if prevalidator_error is not None:
                 errors = list[InitErrorDetails]()
@@ -74,9 +80,15 @@ def _parse_model(*, model: Type[T], obj: Any) -> T:
         return result
 
 
-def parse_model(*, model: Type[T], obj: Any) -> T:
+def parse_model(
+    *, model: Type[T], obj: Any, supported_extensions: Optional[Iterable[str]] = None
+) -> T:
     try:
-        return _parse_model(model=model, obj=obj)
+        return _parse_model(
+            model=model,
+            obj=obj,
+            context=model.model_parsing_context_type(supported_extensions=supported_extensions),
+        )
     except PydanticValidationError as exc:
         errors: list[ErrorDetails] = exc.errors()
         raise DecodeValidationError(pydantic_validationerrors_to_str(model, errors))
@@ -141,12 +153,22 @@ def decimal_to_str(data: Union[dict[str, Any], list[Any]]) -> None:
     return as_dict
 
 
-def decode_job_template(*, template: dict[str, Any]) -> JobTemplate:
+def decode_job_template(
+    *, template: dict[str, Any], supported_extensions: Optional[Iterable[str]] = None
+) -> JobTemplate:
     """Given a dictionary containing a Job Template, this will decode the template, run validation checks on it,
     and then return the decoded template.
 
+    This function places no restriction on the version of the specification. The caller
+    can inspect the `specificationVersion` property of the returned object to validate this.
+
+    By default, no extensions are supported. The caller can opt in to specific extensions,
+    by providing them as a list.
+
     Args:
         template (dict[str, Any]): A Job Template as a dictionary object.
+        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:
         JobTemplate: The decoded job template.
@@ -189,7 +211,9 @@ def decode_job_template(*, template: dict[str, Any]) -> JobTemplate:
         )
 
     if schema_version == TemplateSpecificationVersion.JOBTEMPLATE_v2023_09:
-        return parse_model(model=JobTemplate_2023_09, obj=template)
+        return parse_model(
+            model=JobTemplate_2023_09, obj=template, supported_extensions=supported_extensions
+        )
     else:
         raise NotImplementedError(
             f"Template decode for schema {schema_version.value} is not yet implemented."
@@ -203,12 +227,22 @@ def decode_template(*, template: dict[str, Any]) -> JobTemplate:
     return decode_job_template(template=template)
 
 
-def decode_environment_template(*, template: dict[str, Any]) -> EnvironmentTemplate:
+def decode_environment_template(
+    *, template: dict[str, Any], supported_extensions: Optional[Iterable[str]] = None
+) -> EnvironmentTemplate:
     """Given a dictionary containing an Environment Template, this will decode the template, run validation checks on it,
     and then return the decoded template.
 
+    This function places no restriction on the version of the specification. The caller
+    can inspect the `specificationVersion` property of the returned object to validate this.
+
+    By default, no extensions are supported. The caller can opt in to specific extensions,
+    by providing them as a list.
+
     Args:
         template (dict[str, Any]): An Environment Template as a dictionary object.
+        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:
         EnvironmentTemplate: The decoded environment template.
@@ -246,7 +280,11 @@ def decode_environment_template(*, template: dict[str, Any]) -> EnvironmentTempl
         )
 
     if schema_version == TemplateSpecificationVersion.ENVIRONMENT_v2023_09:
-        return parse_model(model=EnvironmentTemplate_2023_09, obj=template)
+        return parse_model(
+            model=EnvironmentTemplate_2023_09,
+            obj=template,
+            supported_extensions=supported_extensions,
+        )
     else:
         raise NotImplementedError(
             f"Template decode for schema {schema_version.value} is not yet implemented."

src/openjd/model/_types.py

@@ -274,6 +274,10 @@ class OpenJDModel(BaseModel):
     # The specific schema revision that the model implements.
     revision: ClassVar[SpecificationRevision]
 
+    # The model parsing context required by this model. Each revision of
+    # the specification defines this, and it must be default-constructible.
+    model_parsing_context_type: ClassVar[Type]
+
     # ----
     # Metadata used for defining template variables for use in FormatStrings
 

src/openjd/model/v2023_09/__init__.py

@@ -57,6 +57,7 @@
     JobStringParameterDefinition,
     JobTemplate,
     JobTemplateName,
+    ModelParsingContext,
     ParameterStringValue,
     PathTaskParameterDefinition,
     RangeExpressionTaskParameterDefinition,
@@ -136,6 +137,7 @@
     "JobStringParameterDefinition",
     "JobTemplate",
     "JobTemplateName",
+    "ModelParsingContext",
     "ParameterStringValue",
     "PathTaskParameterDefinition",
     "RangeExpressionTaskParameterDefinition",