Improve gardenlinux.oci docstrings

Signed-off-by: Tobias Wolf <[email protected]>

Author: NotTheEvilOne

.github/actions/features_parse/action.yml

@@ -11,7 +11,7 @@ outputs:
 runs:
   using: composite
   steps:
-    - uses: gardenlinux/python-gardenlinux-lib/.github/actions/[email protected].0
+    - uses: gardenlinux/python-gardenlinux-lib/.github/actions/[email protected].2
     - id: result
       shell: bash
       run: |

.github/actions/flavors_parse/action.yml

@@ -13,7 +13,7 @@ outputs:
 runs:
   using: composite
   steps:
-    - uses: gardenlinux/python-gardenlinux-lib/.github/actions/[email protected].0
+    - uses: gardenlinux/python-gardenlinux-lib/.github/actions/[email protected].2
     - id: matrix
       shell: bash
       run: |

.github/actions/setup/action.yml

@@ -3,7 +3,7 @@ description: Installs the given GardenLinux Python library
 inputs:
     version:
         description: GardenLinux Python library version
-        default: "0.7.0"
+        default: "0.7.2"
 runs:
     using: composite
     steps:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "gardenlinux"
-version = "0.7.0"
+version = "0.7.2"
 description = "Contains tools to work with the features directory of gardenlinux, for example deducting dependencies from feature sets or validating cnames"
 authors = ["Garden Linux Maintainers <[email protected]>"]
 license = "Apache-2.0"

src/gardenlinux/oci/container.py

@@ -39,7 +39,7 @@ class Container(Registry):
     :author:     Garden Linux Maintainers
     :copyright:  Copyright 2024 SAP SE
     :package:    gardenlinux
-    :subpackage: flavors
+    :subpackage: oci
     :since:      0.7.0
     :license:    https://www.apache.org/licenses/LICENSE-2.0
                  Apache License, Version 2.0
@@ -401,7 +401,7 @@ def push_manifest_and_artifacts(
                     cleanup_blob = True
 
                 manifest.append_layer(layer)
-                layer_dict = layer.to_dict()
+                layer_dict = layer.dict
 
                 self._logger.debug(f"Layer: {layer_dict}")
 

src/gardenlinux/oci/index.py

@@ -7,7 +7,25 @@
 
 
 class Index(dict):
+    """
+    OCI image index
+
+    :author:     Garden Linux Maintainers
+    :copyright:  Copyright 2024 SAP SE
+    :package:    gardenlinux
+    :subpackage: oci
+    :since:      0.7.0
+    :license:    https://www.apache.org/licenses/LICENSE-2.0
+                 Apache License, Version 2.0
+    """
+
     def __init__(self, *args, **kwargs):
+        """
+        Constructor __init__(Index)
+
+        :since: 0.7.0
+        """
+
         dict.__init__(self)
 
         self.update(deepcopy(EmptyIndex))
@@ -16,10 +34,24 @@ def __init__(self, *args, **kwargs):
 
     @property
     def json(self):
+        """
+        Returns the OCI image index as a JSON
+
+        :return: (bytes) OCI image index as JSON
+        :since:  0.7.0
+        """
+
         return json.dumps(self).encode("utf-8")
 
     @property
     def manifests_as_dict(self):
+        """
+        Returns the OCI image manifests of the index
+
+        :return: (dict) OCI image manifests with CNAME or digest as key
+        :since:  0.7.0
+        """
+
         manifests = {}
 
         for manifest in self["manifests"]:
@@ -33,6 +65,14 @@ def manifests_as_dict(self):
         return manifests
 
     def append_manifest(self, manifest):
+        """
+        Appends the given OCI image manifest to the index
+
+        :param manifest: OCI image manifest
+
+        :since: 0.7.0
+        """
+
         if not isinstance(manifest, dict):
             raise RuntimeError("Unexpected manifest type given")
 

src/gardenlinux/oci/layer.py

@@ -13,12 +13,34 @@
 
 
 class Layer(_Layer, Mapping):
+    """
+    OCI image layer
+
+    :author:     Garden Linux Maintainers
+    :copyright:  Copyright 2024 SAP SE
+    :package:    gardenlinux
+    :subpackage: oci
+    :since:      0.7.0
+    :license:    https://www.apache.org/licenses/LICENSE-2.0
+                 Apache License, Version 2.0
+    """
+
     def __init__(
         self,
         blob_path: PathLike | str,
         media_type: Optional[str] = None,
         is_dir: bool = False,
     ):
+        """
+        Constructor __init__(Index)
+
+        :param blob_path: The path of the blob for the layer
+        :param media_type: Media type for the blob (optional)
+        :param is_dir: Is the blob a directory?
+
+        :since: 0.7.0
+        """
+
         if not isinstance(blob_path, PathLike):
             blob_path = Path(blob_path)
 
@@ -28,11 +50,26 @@ def __init__(
             ANNOTATION_TITLE: blob_path.name,
         }
 
+    @property
+    def dict(self):
+        """
+        Return a dictionary representation of the layer
+
+        :return: (dict) OCI manifest layer metadata dictionary
+        :since:  0.7.2
+        """
+        layer = _Layer.to_dict(self)
+        layer["annotations"] = self._annotations
+
+        return layer
+
     def __delitem__(self, key):
         """
         python.org: Called to implement deletion of self[key].
 
         :param key: Mapping key
+
+        :since: 0.7.0
         """
 
         if key == "annotations":
@@ -49,6 +86,7 @@ def __getitem__(self, key):
         :param key: Mapping key
 
         :return: (mixed) Mapping key value
+        :since:  0.7.0
         """
 
         if key == "annotations":
@@ -63,6 +101,7 @@ def __iter__(self):
         python.org: Return an iterator object.
 
         :return: (object) Iterator object
+        :since:  0.7.0
         """
 
         iter(_SUPPORTED_MAPPING_KEYS)
@@ -71,7 +110,8 @@ def __len__(self):
         """
         python.org: Called to implement the built-in function len().
 
-        :return: (int) Number of database instance attributes
+        :return: (int) Number of attributes
+        :since:  0.7.0
         """
 
         return len(_SUPPORTED_MAPPING_KEYS)
@@ -82,6 +122,8 @@ def __setitem__(self, key, value):
 
         :param key: Mapping key
         :param value: self[key] value
+
+        :since: 0.7.0
         """
 
         if key == "annotations":
@@ -91,21 +133,16 @@ def __setitem__(self, key, value):
             f"'{self.__class__.__name__}' object is not subscriptable except for keys: {_SUPPORTED_MAPPING_KEYS}"
         )
 
-    def to_dict(self):
-        """
-        Return a dictionary representation of the layer
-        """
-        layer = _Layer.to_dict(self)
-        layer["annotations"] = self._annotations
-
-        return layer
-
     @staticmethod
     def generate_metadata_from_file_name(file_name: PathLike | str, arch: str) -> dict:
         """
-        :param str file_name: file_name of the blob
-        :param str arch: the arch of the target image
-        :return: dict of oci layer metadata for a given layer file
+        Generates OCI manifest layer metadata for the given file path and name.
+
+        :param file_name: File path and name of the target layer
+        :param arch: The arch of the target image
+
+        :return: (dict) OCI manifest layer metadata dictionary
+        :since:  0.7.0
         """
 
         if not isinstance(file_name, PathLike):
@@ -122,8 +159,12 @@ def generate_metadata_from_file_name(file_name: PathLike | str, arch: str) -> di
     @staticmethod
     def lookup_media_type_for_file_name(file_name: str) -> str:
         """
-        :param str file_name: file_name of the target layer
-        :return: mediatype
+        Looks up the media type based on file extension.
+
+        :param file_name: File path and name of the target layer
+
+        :return: (str) Media type
+        :since:  0.7.0
         """
 
         if not isinstance(file_name, PathLike):