Rename implementation_name to python_implementation

docs/api/stacks/venvstacks.stacks.RuntimeSpec.rst

@@ -14,7 +14,7 @@ venvstacks.stacks.RuntimeSpec
       ~RuntimeSpec.env_name
       ~RuntimeSpec.kind
       ~RuntimeSpec.py_version
-      ~RuntimeSpec.implementation_name
+      ~RuntimeSpec.python_implementation
       ~RuntimeSpec.name
       ~RuntimeSpec.versioned
       ~RuntimeSpec.requirements

docs/changelog.d/20241111_104113_ncoghlan_add_stack_format_docs.rst

@@ -2,6 +2,6 @@ Added
 -----
 
 - Added documentation for the :ref:`stack-specification-format` (added in :issue:`78`).
-- Added ``implementation_name`` to the published layer metadata (added in :issue:`78`).
+- Added ``python_implementation`` to the published layer metadata (added in :issue:`78`).
 - Added ``bound_to_implementation`` to the published layer metadata (added in :issue:`78`).
 

docs/changelog.d/20241112_134636_ncoghlan_discourage_at_symbol_in_layer_names.rst

@@ -2,6 +2,6 @@ Changed
 -------
 
 - Updated docs to actively discourage using ``@`` in layers names (part of :issue:`78`).
-- Renamed ``fully_versioned_name`` runtime layer specification field to ``implementation_name`` (part of :issue:`78`).
+- Renamed ``fully_versioned_name`` runtime layer specification field to ``python_implementation`` (part of :issue:`78`).
 - Simplified ``runtime_name`` in layer metadata to always refer to the runtime install target (part of :issue:`78`).
 

docs/file-formats.rst

@@ -139,7 +139,10 @@ Runtime layer specification fields
 
 Runtime layer specifications must contain the following additional field:
 
-* ``implementation_name`` (:toml:`string`): the :pypi:`pbs-installer` name
+* ``python_implementation`` (:toml:`string`): the :pypi:`pbs-installer` name
+  of the Python runtime to be installed as the base runtime for this layer
+  (and any upper layers that depend on this layer).
+* ``implementation_version`` (:toml:`string`): the :pypi:`pbs-installer` name
   of the Python runtime to be installed as the base runtime for this layer
   (and any upper layers that depend on this layer).
 
@@ -151,9 +154,9 @@ Framework layer specifications must contain the following additional field:
 
 * ``runtime`` (:toml:`string`): the name of the runtime layer that this framework layer uses.
 
-The ``install_target`` and ``implementation_name`` attributes of the specified
-are runtime are respectively recorded in the ``runtime_name`` 
-and ``implementation_name`` fields of the layer output metadata.
+The ``install_target`` and ``python_implementation`` attributes of the specified
+runtime are respectively recorded in the ``runtime_name`` 
+and ``python_implementation`` fields of the layer output metadata.
 
 ``bound_to_implementation`` is an additional boolean field in the frame layer
 output metadata that indicates how tightly coupled the framework layer is
@@ -189,7 +192,7 @@ Application layer specifications must contain the following additional field:
 The ``runtime`` dependency for application layers is not specified directly. Instead, all
 of the declared framework dependencies *must* depend on the same runtime layer, and that
 base runtime also becomes the base runtime for the application layer using those frameworks.
-``runtime_name``, ``implementation_name``, and ``bound_to_implementation`` in the layer
+``runtime_name``, ``python_implementation``, and ``bound_to_implementation`` in the layer
 output metadata are set to the same values as they are for the underlying frameworks.
 
 
@@ -241,7 +244,7 @@ when used in a loaded stack specification:
 
 * ``build_requirements``: no longer has any effect (rendered non-functional before
   :ref:`0.1.0rc1 <changelog-0.1.0rc1>`, warning emitted from :ref:`0.2.0 <changelog-0.2.0>`)
-* ``fully_versioned_name``: renamed to ``implementation_name`` in :ref:`0.2.0 <changelog-0.2.0>`
+* ``fully_versioned_name``: renamed to ``python_implementation`` in :ref:`0.2.0 <changelog-0.2.0>`
 
 
 .. _layer-requirements:
@@ -307,12 +310,12 @@ layer archives or locally exporting layer environments:
 
     # Fields that are populated after the layer metadata has initially been defined
     # "runtime_name" is set to the underlying runtime's deployed environment name
-    # "implementation_name" is set to the underlying runtime's implementation name
+    # "python_implementation" is set to the underlying runtime's implementation name
     # "bound_to_implementation" means that the layered environment includes
     # copies of some files from the runtime implementation, and hence will
     # need updating even for runtime maintenance releases
     runtime_name: NotRequired[str]
-    implementation_name: NotRequired[str]
+    python_implementation: NotRequired[str]
     bound_to_implementation: NotRequired[bool]
 
     # Extra fields only defined for framework and application environments

docs/overview.rst

@@ -52,7 +52,7 @@ all running in a controlled Python 3.11 base runtime:
 
    [[runtimes]]
    name = "cpython-3.11"
-   implementation_name = "[email protected]"
+   python_implementation = "[email protected]"
    requirements = [
        "numpy",
    ]

src/venvstacks/stacks.py

@@ -469,14 +469,14 @@ class RuntimeSpec(LayerSpecBase):
 
     kind = LayerVariants.RUNTIME
     category = LayerCategories.RUNTIMES
-    implementation_name: str = field(repr=False)
+    python_implementation: str = field(repr=False)
 
     @property
     def py_version(self) -> str:
         """Extract just the Python version string from the base runtime identifier."""
-        # implementation_name should be of the form "[email protected]"
+        # python_implementation should be of the form "[email protected]"
         # (this may need adjusting if runtimes other than CPython are ever used...)
-        return self.implementation_name.partition("@")[2]
+        return self.python_implementation.partition("@")[2]
 
 
 @dataclass
@@ -519,13 +519,13 @@ class LayerSpecMetadata(TypedDict):
     locked_at: str                 # ISO formatted date/time value
 
     # Fields that are populated after the layer metadata has initially been defined
-    # "runtime_name" is set to the underlying runtime's deployed environment name
-    # "implementation_name" is set to the underlying runtime's implementation name
+    # "runtime_layer" is set to the underlying runtime's deployed environment name
+    # "python_implementation" is set to the underlying runtime's implementation name
     # "bound_to_implementation" means that the layered environment includes
     # copies of some files from the runtime implementation, and hence will
     # need updating even for runtime maintenance releases
-    runtime_name: NotRequired[str]
-    implementation_name: NotRequired[str]
+    runtime_layer: NotRequired[str]
+    python_implementation: NotRequired[str]
     bound_to_implementation: NotRequired[bool]
 
     # Extra fields only defined for framework and application environments
@@ -1514,7 +1514,7 @@ def _remove_pip(self) -> subprocess.CompletedProcess[str] | None:
         return self._run_pip(pip_args)
 
     def _create_new_environment(self, *, lock_only: bool = False) -> None:
-        python_runtime = self.env_spec.implementation_name
+        python_runtime = self.env_spec.python_implementation
         install_path = _pdm_python_install(self.build_path, python_runtime)
         if install_path is None:
             self._fail_build(f"Failed to install {python_runtime}")
@@ -1533,8 +1533,8 @@ def _create_new_environment(self, *, lock_only: bool = False) -> None:
     def _update_output_metadata(self, metadata: LayerSpecMetadata) -> None:
         super()._update_output_metadata(metadata)
         # This *is* a runtime layer, so it needs to be updated on maintenance releases
-        metadata["runtime_name"] = self.install_target
-        metadata["implementation_name"] = self.env_spec.implementation_name
+        metadata["runtime_layer"] = self.install_target
+        metadata["python_implementation"] = self.env_spec.python_implementation
         metadata["bound_to_implementation"] = True
 
     def create_build_environment(self, *, clean: bool = False) -> None:
@@ -1674,8 +1674,8 @@ def _update_output_metadata(self, metadata: LayerSpecMetadata) -> None:
         # Windows copies the main Python binary and support libary, so always needs updates
         runtime = self.base_runtime
         assert runtime is not None
-        metadata["runtime_name"] = runtime.install_target
-        metadata["implementation_name"] = runtime.env_spec.implementation_name
+        metadata["runtime_layer"] = runtime.install_target
+        metadata["python_implementation"] = runtime.env_spec.python_implementation
         metadata["bound_to_implementation"] = bool(_WINDOWS_BUILD)
 
 
@@ -1848,7 +1848,7 @@ def _update_legacy_fields(
         return modified
 
     _RUNTIME_LEGACY_CONVERSIONS: ClassVar[Mapping[str, str | None]] = {
-        "fully_versioned_name": "implementation_name",
+        "fully_versioned_name": "python_implementation",
         "build_requirements": None,
     }
     _FRAMEWORK_LEGACY_CONVERSIONS: ClassVar[Mapping[str, str | None]] = {

tests/minimal_project/venvstacks.toml

@@ -6,7 +6,7 @@
 
 [[runtimes]]
 name = "cpython-3.11"
-implementation_name = "[email protected]"
+python_implementation = "[email protected]"
 requirements = []
 
 [[frameworks]]

tests/sample_project/expected_manifests/linux_x86_64/env_metadata/app-scipy-client.json

@@ -8,7 +8,7 @@
   "archive_name": "app-scipy-client.tar.xz",
   "archive_size": 3008,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "app-scipy-client",
   "layer_name": "app-scipy-client",
   "lock_version": 1,

tests/sample_project/expected_manifests/linux_x86_64/env_metadata/app-scipy-import.json

@@ -8,7 +8,7 @@
   "archive_name": "[email protected]",
   "archive_size": 2920,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "app-scipy-import@1",
   "layer_name": "app-scipy-import",
   "lock_version": 1,

tests/sample_project/expected_manifests/linux_x86_64/env_metadata/app-sklearn-import.json

@@ -8,7 +8,7 @@
   "archive_name": "app-sklearn-import.tar.xz",
   "archive_size": 2920,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "app-sklearn-import",
   "layer_name": "app-sklearn-import",
   "lock_version": 1,

tests/sample_project/expected_manifests/linux_x86_64/env_metadata/cpython-3.11.json

@@ -6,7 +6,7 @@
   "archive_name": "cpython-3.11.tar.xz",
   "archive_size": 29723308,
   "bound_to_implementation": true,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "cpython-3.11",
   "layer_name": "cpython-3.11",
   "lock_version": 1,

tests/sample_project/expected_manifests/linux_x86_64/env_metadata/cpython-3.12.json

@@ -6,7 +6,7 @@
   "archive_name": "cpython-3.12.tar.xz",
   "archive_size": 42683536,
   "bound_to_implementation": true,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "cpython-3.12",
   "layer_name": "cpython-3.12",
   "lock_version": 1,

tests/sample_project/expected_manifests/linux_x86_64/env_metadata/framework-http-client.json

@@ -6,7 +6,7 @@
   "archive_name": "framework-http-client.tar.xz",
   "archive_size": 364152,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "framework-http-client",
   "layer_name": "framework-http-client",
   "lock_version": 1,

tests/sample_project/expected_manifests/linux_x86_64/env_metadata/framework-scipy.json

@@ -6,7 +6,7 @@
   "archive_name": "[email protected]",
   "archive_size": 23956060,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "framework-scipy@1",
   "layer_name": "framework-scipy",
   "lock_version": 1,

tests/sample_project/expected_manifests/linux_x86_64/env_metadata/framework-sklearn.json

@@ -6,7 +6,7 @@
   "archive_name": "framework-sklearn.tar.xz",
   "archive_size": 30371692,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "framework-sklearn",
   "layer_name": "framework-sklearn",
   "lock_version": 1,

tests/sample_project/expected_manifests/linux_x86_64/venvstacks.json

@@ -11,7 +11,7 @@
         "archive_name": "[email protected]",
         "archive_size": 2920,
         "bound_to_implementation": false,
-        "implementation_name": "[email protected]",
+        "python_implementation": "[email protected]",
         "install_target": "app-scipy-import@1",
         "layer_name": "app-scipy-import",
         "lock_version": 1,
@@ -33,7 +33,7 @@
         "archive_name": "app-scipy-client.tar.xz",
         "archive_size": 3008,
         "bound_to_implementation": false,
-        "implementation_name": "[email protected]",
+        "python_implementation": "[email protected]",
         "install_target": "app-scipy-client",
         "layer_name": "app-scipy-client",
         "lock_version": 1,
@@ -56,7 +56,7 @@
         "archive_name": "app-sklearn-import.tar.xz",
         "archive_size": 2920,
         "bound_to_implementation": false,
-        "implementation_name": "[email protected]",
+        "python_implementation": "[email protected]",
         "install_target": "app-sklearn-import",
         "layer_name": "app-sklearn-import",
         "lock_version": 1,
@@ -78,7 +78,7 @@
         "archive_name": "[email protected]",
         "archive_size": 23956060,
         "bound_to_implementation": false,
-        "implementation_name": "[email protected]",
+        "python_implementation": "[email protected]",
         "install_target": "framework-scipy@1",
         "layer_name": "framework-scipy",
         "lock_version": 1,
@@ -95,7 +95,7 @@
         "archive_name": "framework-sklearn.tar.xz",
         "archive_size": 30371692,
         "bound_to_implementation": false,
-        "implementation_name": "[email protected]",
+        "python_implementation": "[email protected]",
         "install_target": "framework-sklearn",
         "layer_name": "framework-sklearn",
         "lock_version": 1,
@@ -112,7 +112,7 @@
         "archive_name": "framework-http-client.tar.xz",
         "archive_size": 364152,
         "bound_to_implementation": false,
-        "implementation_name": "[email protected]",
+        "python_implementation": "[email protected]",
         "install_target": "framework-http-client",
         "layer_name": "framework-http-client",
         "lock_version": 1,
@@ -131,7 +131,7 @@
         "archive_name": "cpython-3.11.tar.xz",
         "archive_size": 29723308,
         "bound_to_implementation": true,
-        "implementation_name": "[email protected]",
+        "python_implementation": "[email protected]",
         "install_target": "cpython-3.11",
         "layer_name": "cpython-3.11",
         "lock_version": 1,
@@ -148,7 +148,7 @@
         "archive_name": "cpython-3.12.tar.xz",
         "archive_size": 42683536,
         "bound_to_implementation": true,
-        "implementation_name": "[email protected]",
+        "python_implementation": "[email protected]",
         "install_target": "cpython-3.12",
         "layer_name": "cpython-3.12",
         "lock_version": 1,

tests/sample_project/expected_manifests/macosx_arm64/env_metadata/app-scipy-client.json

@@ -8,7 +8,7 @@
   "archive_name": "app-scipy-client.tar.xz",
   "archive_size": 2984,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "app-scipy-client",
   "layer_name": "app-scipy-client",
   "lock_version": 1,

tests/sample_project/expected_manifests/macosx_arm64/env_metadata/app-scipy-import.json

@@ -8,7 +8,7 @@
   "archive_name": "[email protected]",
   "archive_size": 2900,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "app-scipy-import@1",
   "layer_name": "app-scipy-import",
   "lock_version": 1,

tests/sample_project/expected_manifests/macosx_arm64/env_metadata/cpython-3.11.json

@@ -6,7 +6,7 @@
   "archive_name": "cpython-3.11.tar.xz",
   "archive_size": 14963240,
   "bound_to_implementation": true,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "cpython-3.11",
   "layer_name": "cpython-3.11",
   "lock_version": 1,

tests/sample_project/expected_manifests/macosx_arm64/env_metadata/cpython-3.12.json

@@ -6,7 +6,7 @@
   "archive_name": "cpython-3.12.tar.xz",
   "archive_size": 13596100,
   "bound_to_implementation": true,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "cpython-3.12",
   "layer_name": "cpython-3.12",
   "lock_version": 1,

tests/sample_project/expected_manifests/macosx_arm64/env_metadata/framework-http-client.json

@@ -6,7 +6,7 @@
   "archive_name": "framework-http-client.tar.xz",
   "archive_size": 364232,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "framework-http-client",
   "layer_name": "framework-http-client",
   "lock_version": 1,

tests/sample_project/expected_manifests/macosx_arm64/env_metadata/framework-scipy.json

@@ -6,7 +6,7 @@
   "archive_name": "[email protected]",
   "archive_size": 15076180,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "framework-scipy@1",
   "layer_name": "framework-scipy",
   "lock_version": 1,

tests/sample_project/expected_manifests/macosx_arm64/env_metadata/framework-sklearn.json

@@ -6,7 +6,7 @@
   "archive_name": "framework-sklearn.tar.xz",
   "archive_size": 20688076,
   "bound_to_implementation": false,
-  "implementation_name": "[email protected]",
+  "python_implementation": "[email protected]",
   "install_target": "framework-sklearn",
   "layer_name": "framework-sklearn",
   "lock_version": 1,