Update or add "docstrings"

Signed-off-by: Tobias Wolf <wolf@b1-systems.de>

Author: NotTheEvilOne

src/gardenlinux/apt/__init__.py

@@ -1,5 +1,9 @@
 # -*- coding: utf-8 -*-
 
+"""
+APT module
+"""
+
 from .debsource import Debsrc, DebsrcFile
 
-__all__ = ["Parser"]
+__all__ = ["Debsrc", "DebsrcFile"]

src/gardenlinux/apt/debsource.py

@@ -1,27 +1,63 @@
 # -*- coding: utf-8 -*-
-# SPDX-License-Identifier: MIT
 
-# Based on code from glvd https://github.com/gardenlinux/glvd/blob/7ca2ff54e01da5e9eae61d1cd565eaf75f3c62ce/src/glvd/data/debsrc.py#L1
-
-from __future__ import annotations
+"""
+deb sources
+"""
 
 import re
 from typing import TextIO
 
 
 class Debsrc:
+    """
+    Class to reflect deb sources.
+
+    :author:     Garden Linux Maintainers
+    :copyright:  Copyright 2024 SAP SE
+    :package:    gardenlinux
+    :subpackage: apt
+    :since:      0.7.0
+    :license:    https://www.apache.org/licenses/LICENSE-2.0
+                 Apache License, Version 2.0
+    """
+
     def __init__(self, deb_source, deb_version):
-        self.deb_source = deb_source
-        self.deb_version = deb_version
+        """
+        Constructor __init__(Debsrc)
+
+        :param deb_source:  Source name
+        :param deb_version: Source version
 
-    deb_source: str
-    deb_version: str
+        :since: 0.7.0
+        """
+
+        self.deb_source: str = deb_source
+        self.deb_version: str = deb_version
 
     def __repr__(self) -> str:
+        """
+        python.org: Called by the repr() built-in function to compute the "official" string representation of an object.
+
+        :return: (str) String representation
+        :since:  0.7.0
+        """
+
         return f"{self.deb_source} {self.deb_version}"
 
 
 class DebsrcFile(dict[str, Debsrc]):
+    """
+    Class to represent deb sources loaded and parsed as dict.
+
+    :author:     Garden Linux Maintainers
+    :copyright:  Copyright 2024 SAP SE
+    :package:    gardenlinux
+    :subpackage: apt
+    :since:      0.7.0
+    :license:    https://www.apache.org/licenses/LICENSE-2.0
+                 Apache License, Version 2.0
+    """
+
     __re = re.compile(
         r"""
         ^(?:
@@ -43,18 +79,16 @@ class DebsrcFile(dict[str, Debsrc]):
         re.VERBOSE,
     )
 
-    def _read_source(self, source: str, version: str) -> None:
-        self[source] = Debsrc(
-            deb_source=source,
-            deb_version=version,
-        )
-
     def read(self, f: TextIO) -> None:
-        current_source = current_version = None
+        """
+        Read and parse the given TextIO data to extract deb sources.
+
+        :param f: TextIO data to parse
 
-        def finish():
-            if current_source and current_version:
-                self._read_source(current_source, current_version)
+        :since: 0.7.0
+        """
+
+        current_source = current_version = None
 
         for line in f.readlines():
             if match := self.__re.match(line):
@@ -70,4 +104,17 @@ def finish():
             else:
                 raise RuntimeError(f"Unable to read line: {line}")
 
-        finish()
+        if current_source and current_version:
+            self._set_source(current_source, current_version)
+
+    def _set_source(self, source: str, version: str) -> None:
+        """
+        Sets the dict value based on the given source key.
+
+        :since: 0.7.0
+        """
+
+        self[source] = Debsrc(
+            deb_source=source,
+            deb_version=version,
+        )

src/gardenlinux/apt/package_repo_info.py

@@ -1,55 +1,110 @@
 # -*- coding: utf-8 -*-
 
+"""
+APT repositories
+"""
+
 from apt_repo import APTRepository
 from typing import Optional
 
 
 class GardenLinuxRepo(APTRepository):
+    """
+    Class to reflect APT based GardenLinux repositories.
+
+    :author:     Garden Linux Maintainers
+    :copyright:  Copyright 2024 SAP SE
+    :package:    gardenlinux
+    :subpackage: apt
+    :since:      0.7.0
+    :license:    https://www.apache.org/licenses/LICENSE-2.0
+                 Apache License, Version 2.0
+    """
+
     def __init__(
         self,
         dist: str,
         url: Optional[str] = "http://packages.gardenlinux.io/gardenlinux",
         components: Optional[list[str]] = ["main"],
-    ) -> None:
+    ):
+        """
+        Constructor __init__(GardenLinuxRepo)
+
+        :param dist:       Repository dist
+        :param url:        Repository url
+        :param components: Repository components provided
+
+        :since: 0.7.0
+        """
+
         self.components = components
         self.url = url
         self.dist = dist
         self.repo = APTRepository(self.url, self.dist, self.components)
 
     def get_package_version_by_name(self, name: str) -> list[tuple[str, str]]:
         """
-        :param str name: name of package to find
-        :returns: packages matching the input name
+        Returns the package version matching the given name.
+
+        :param name: name of package to find
+
+        :return: (list) Packages matching the input name
+        :since: 0.7.0
         """
+
         return [
             (package.package, package.version)
             for package in self.repo.get_packages_by_name(name)
         ]
 
-    def get_packages_versions(self):
+    def get_packages_versions(self) -> list[tuple[str, str]]:
         """
         Returns list of (package, version) tuples
+
+        :return: (list) Packages versions
+        :since: 0.7.0
         """
+
         return [(p.package, p.version) for p in self.repo.packages]
 
 
-def compare_gardenlinux_repo_version(version_a: str, version_b: str):
+def compare_gardenlinux_repo_version(
+    version_a: str, version_b: str
+) -> list[tuple[str, str, str]]:
     """
-    :param str version_a: Version of first Garden Linux repo
-    :param str version_b: Version of first Garden Linux repo
+    Compares differences between repository versions given.
 
     Example: print(compare_gardenlinux_repo_version("1443.2", "1443.1"))
+
+    :param version_a: Version of first Garden Linux repo
+    :param version_b: Version of first Garden Linux repo
+
+    :return: (list) Differences between repo a and repo b
+    :since:  0.7.0
     """
+
     return compare_repo(GardenLinuxRepo(version_a), GardenLinuxRepo(version_b))
 
 
 def compare_repo(
     a: GardenLinuxRepo, b: GardenLinuxRepo, available_in_both: Optional[bool] = False
-):
+) -> list[tuple[str, str, str]]:
     """
-    :param a GardenLinuxRepo: first repo to compare
-    :param b GardenLinuxRepo: second repo to compare
-    :returns: differences between repo a and repo b
+    Compares differences between repositories given.
+
+    Example:
+    gl_repo = GardenLinuxRepo("today")
+    gl_repo_1592 = GardenLinuxRepo("1592.0")
+    deb_testing = GardenLinuxRepo("testing", "https://deb.debian.org/debian/")
+    print(compare_repo(gl_repo, gl_repo_1592, available_in_both=True))
+    print(compare_repo(gl_repo, deb_testing, available_in_both=False))
+
+    :param a GardenLinuxRepo: First repo to compare
+    :param b GardenLinuxRepo: Second repo to compare
+    :param available_in_both: Compare packages available in both repos only
+
+    :return: (list) Differences between repo a and repo b
+    :since:  0.7.0
     """
 
     packages_a = dict(a.get_packages_versions())
@@ -69,15 +124,3 @@ def compare_repo(
         )
         or (name not in packages_b or name not in packages_a)
     ]
-
-
-# EXAMPLE USAGE.
-# print(compare_gardenlinux_repo_version("1443.2", "1443.1"))
-
-# gl_repo = GardenLinuxRepo("today")
-# gl_repo_1592 = GardenLinuxRepo("1592.0")
-# deb_testing = GardenLinuxRepo("testing", "https://deb.debian.org/debian/")
-# print(compare_repo(gl_repo, gl_repo_1592, available_in_both=True))
-# print(compare_repo(gl_repo, deb_testing, available_in_both=True))
-# # print(gl_repo.get_packages_versions())
-# print(gl_repo.get_package_version_by_name("wget"))

src/gardenlinux/features/__init__.py

@@ -1,5 +1,9 @@
 # -*- coding: utf-8 -*-
 
+"""
+Features module
+"""
+
 from .cname import CName
 from .parser import Parser