add/ update comments and doc strings

Author: notactuallyfinn

src/hermes/model/api.py

@@ -12,6 +12,7 @@
 from hermes.model.types.ld_container import PYTHONIZED_LD_CONTAINER
 from hermes.model.types.ld_context import ALL_CONTEXTS
 from hermes.model.types.pyld_util import bundled_loader
+
 from .context_manager import HermesContext
 from .error import HermesContextError
 
@@ -37,7 +38,9 @@ def __init__(
         Returns:
             None:
         """
+        # create context object
         ctx = ALL_CONTEXTS + [{**extra_vocabs}] if extra_vocabs is not None else ALL_CONTEXTS
+        # initialize underlying ld_dict
         super().__init__([ld_dict.from_dict(data, context=ctx).data_dict if data else {}], context=ctx)
 
     @classmethod
@@ -92,7 +95,9 @@ def write_to_cache(self: Self, ctx: HermesContext, target_dir: str) -> None:
         Returns:
             None:
         """
+        # open cache dir
         with ctx[target_dir] as cache:
+            # write expanded, context and compact version of self
             cache["codemeta"] = self.compact()
             cache["context"] = {"@context": self.full_context}
             cache["expanded"] = self.ld_value

src/hermes/model/context_manager.py

@@ -3,12 +3,13 @@
 # SPDX-License-Identifier: Apache-2.0
 
 # SPDX-FileContributor: Michael Meinel
+# SPDX-FileContributor: Michael Fritzsche
 
 import json
 import os.path
 from pathlib import Path
 from types import TracebackType
-from typing import Union
+from typing import Optional
 from typing_extensions import Self
 
 from .error import HermesContextError
@@ -42,11 +43,14 @@ def __enter__(self: Self) -> None:
         Returns:
             None:
         """
+        # check if the cache_dir exists
         if self._cache_dir.is_dir():
+            # load all files from the cache dir and cache the contents
             for filepath in self._cache_dir.glob('*'):
                 basename, _ = os.path.splitext(filepath.name)
                 self._cached_data[basename] = json.load(filepath.open('r'))
 
+        # return the cache object
         return self
 
     def __getitem__(self: Self, item: str) -> dict:
@@ -59,11 +63,14 @@ def __getitem__(self: Self, item: str) -> dict:
         Returns:
             dict: The JSON value in the given file.
         """
+        # check whether or not the given file was already loaded
         if item not in self._cached_data:
+            # construct the file path as well as load and cache the file
             filepath = self._cache_dir / f'{item}.json'
             if filepath.is_file():
                 self._cached_data[item] = json.load(filepath.open('r'))
 
+        # return the loaded json
         return self._cached_data[item]
 
     def __setitem__(self: Self, key: str, value: dict) -> None:
@@ -78,13 +85,14 @@ def __setitem__(self: Self, key: str, value: dict) -> None:
         Returns:
             None:
         """
+        # update the value of the cache
         self._cached_data[key] = value
 
     def __exit__(
         self: Self,
-        exc_type: Union[type[BaseException], None],
-        exc_val: Union[BaseException, None],
-        exc_tb: Union[TracebackType, None]
+        exc_type: Optional[type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType]
     ) -> None:
         """
         Updates the files from the cache.
@@ -98,9 +106,12 @@ def __exit__(
             None:
         """
         if exc_type is None:
+            # If the exit did not happen because of an exception:
+            # create the cache dir (if necessary) and write the cached json data
             self._cache_dir.mkdir(exist_ok=True, parents=True)
 
             for basename, data in self._cached_data.items():
+                # create complete file path and write the data
                 cachefile = self._cache_dir / f'{basename}.json'
                 json.dump(data, cachefile.open('w'))
 
@@ -158,10 +169,12 @@ def finalize_step(self: Self, step: str) -> None:
             ValueError: If no step can be removed.
             ValueError: If the given step is not the last one.
         """
+        # check if the given step was prepared last
         if len(self._current_step) < 1:
             raise ValueError("There is no step to end.")
         if self._current_step[-1] != step:
             raise ValueError(f"Cannot end step {step} while in {self._current_step[-1]}.")
+        # remove the last step (i.e. the given one)
         self._current_step.pop()
 
     def __getitem__(self: Self, source_name: str) -> HermesCache:
@@ -177,7 +190,9 @@ def __getitem__(self: Self, source_name: str) -> HermesCache:
         Raises:
             HermesContextError: If no step has been prepared (i.e. no current cache dir is set).
         """
+        # check if a step is prepared
         if len(self._current_step) < 1:
             raise HermesContextError("Prepare a step first.")
+        # build the dir of the cache and return the HermesCache for it
         subdir = self.cache_dir / self._current_step[-1] / source_name
         return HermesCache(subdir)

src/hermes/model/merge/container.py

@@ -7,16 +7,16 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Callable, Union
+from typing import TYPE_CHECKING, Any, Callable, Optional, Union
 from typing_extensions import Self
 
 from hermes.model.types import ld_container, ld_context, ld_dict, ld_list
 from hermes.model.types.ld_container import (
     BASIC_TYPE, EXPANDED_JSON_LD_VALUE, JSON_LD_CONTEXT_DICT, JSON_LD_VALUE, TIME_TYPE
 )
 from hermes.model.types.pyld_util import bundled_loader
-from .action import MergeError
 
+from .action import MergeError
 if TYPE_CHECKING:
     from .action import MergeAction
 
@@ -83,11 +83,11 @@ def __init__(
         self: "ld_merge_list",
         data: Union[list[str], list[dict[str, EXPANDED_JSON_LD_VALUE]]],
         *,
-        parent: Union[ld_container, None] = None,
-        key: Union[str, None] = None,
-        index: Union[int, None] = None,
-        context: Union[list[Union[str, JSON_LD_CONTEXT_DICT]], None] = None,
-        strategies: dict[Union[str, None], dict[Union[str, None], MergeAction]] = {}
+        parent: Optional[ld_container] = None,
+        key: Optional[str] = None,
+        index: Optional[int] = None,
+        context: Optional[list[Union[str, JSON_LD_CONTEXT_DICT]]] = None,
+        strategies: dict[Optional[str], dict[Optional[str], MergeAction]] = {}
     ) -> None:
         """
         Create a new ld_merge_list.
@@ -124,11 +124,11 @@ def __init__(
         self: Self,
         data: list[dict[str, EXPANDED_JSON_LD_VALUE]],
         *,
-        parent: Union[ld_dict, ld_list, None] = None,
-        key: Union[str, None] = None,
-        index: Union[int, None] = None,
-        context: Union[list[Union[str, JSON_LD_CONTEXT_DICT]], None] = None,
-        strategies: dict[Union[str, None], dict[Union[str, None], MergeAction]] = {}
+        parent: Optional[Union[ld_dict, ld_list]] = None,
+        key: Optional[str] = None,
+        index: Optional[int] = None,
+        context: Optional[list[Union[str, JSON_LD_CONTEXT_DICT]]] = None,
+        strategies: dict[Optional[str], dict[Optional[str], MergeAction]] = {}
     ) -> None:
         """
         Create a new instance of an ld_merge_dict. See also :meth:`ld_dict.__init__`.
@@ -199,7 +199,7 @@ def update(self: Self, other: ld_dict) -> None:
         # this works implicitly because ld_dict.update invokes self.__setitem__ which is overwritten by ld_merge_dict
         super().update(other)
 
-    def add_strategy(self: Self, strategy: dict[Union[str, None], dict[Union[str, None], MergeAction]]) -> None:
+    def add_strategy(self: Self, strategy: dict[Optional[str], dict[Optional[str], MergeAction]]) -> None:
         """
         Adds ``strategy`` to the ``self.strategies``.
 

src/hermes/model/types/ld_container.py

@@ -10,7 +10,7 @@
 from __future__ import annotations
 
 from datetime import date, datetime, time
-from typing import Any, TypeAlias, TYPE_CHECKING, Union
+from typing import Any, Optional, TypeAlias, TYPE_CHECKING, Union
 from typing_extensions import Self
 
 from .pyld_util import JsonLdProcessor, bundled_loader
@@ -70,10 +70,10 @@ def __init__(
         self: Self,
         data: EXPANDED_JSON_LD_VALUE,
         *,
-        parent: Union[ld_dict, ld_list, None] = None,
-        key: Union[str, None] = None,
-        index: Union[int, None] = None,
-        context: Union[list[Union[str, JSON_LD_CONTEXT_DICT]], None] = None,
+        parent: Optional[Union[ld_dict, ld_list]] = None,
+        key: Optional[str] = None,
+        index: Optional[int] = None,
+        context: Optional[list[Union[str, JSON_LD_CONTEXT_DICT]]] = None,
     ) -> None:
         """
         Create a new instance of an ld_container.
@@ -303,7 +303,7 @@ def __str__(self: Self) -> str:
         return str(self.to_python())
 
     def compact(
-        self: Self, context: Union[list[Union[JSON_LD_CONTEXT_DICT, str]], JSON_LD_CONTEXT_DICT, str, None] = None
+        self: Self, context: Optional[Union[list[Union[JSON_LD_CONTEXT_DICT, str]], JSON_LD_CONTEXT_DICT, str]] = None
     ) -> COMPACTED_JSON_LD_VALUE:
         """
         Returns the compacted version of the given ld_container using its context only if none was supplied.

src/hermes/model/types/ld_context.py

@@ -4,6 +4,7 @@
 
 # SPDX-FileContributor: Michael Meinel
 # SPDX-FileContributor: Stephan Druskat <stephan.druskat@dlr.de>
+# SPDX-FileContributor: Michael Fritzsche
 
 from typing import Union
 from typing_extensions import Self
@@ -69,7 +70,7 @@ class ContextPrefix:
         context dict[str | None, str]: The mapping of prefix its expanded IRI.
     """
 
-    def __init__(self: Self, vocabularies: list[str | dict]) -> None:
+    def __init__(self: Self, vocabularies: list[Union[str, dict]]) -> None:
         """
         If the list contains more than one string item, the last one will be used as the default vocabulary. If a prefix
         string is used more than once across all dictionaries in the list, the last item with this key will be included
@@ -86,10 +87,12 @@ def __init__(self: Self, vocabularies: list[str | dict]) -> None:
         self.vocabularies = vocabularies
         self.context = {}
 
+        # add every entry in the vocabulary to the context
         for vocab in self.vocabularies:
             if isinstance(vocab, str):
                 vocab = {None: vocab}
 
+            # add all prefix, base_iri pairs from vocab to context
             self.context.update(
                 {
                     prefix: base_iri
@@ -98,7 +101,7 @@ def __init__(self: Self, vocabularies: list[str | dict]) -> None:
                 }
             )
 
-    def __getitem__(self: Self, compressed_term: str | tuple) -> str:
+    def __getitem__(self: Self, compressed_term: Union[str, tuple]) -> str:
         """
         Gets the fully qualified IRI for a term from a vocabulary inside the initialized context.
         The vocabulary must have been added to the context at initialization.
@@ -121,7 +124,11 @@ def __getitem__(self: Self, compressed_term: str | tuple) -> str:
 
         Returns:
             str: The fully qualified IRI for the passed term
+
+        Raises:
+            HermesContextError: If the compressed term is '' or its prefix can't be expanded.
         """
+        # seperate the prefix from the term
         if not isinstance(compressed_term, str):
             prefix, term = compressed_term
         elif ":" in compressed_term:
@@ -133,11 +140,13 @@ def __getitem__(self: Self, compressed_term: str | tuple) -> str:
         else:
             raise HermesContextError(compressed_term)
 
+        # expand the prefix
         try:
             base_iri = self.context[prefix]
         except KeyError as ke:
             raise HermesContextError(prefix) from ke
 
+        # return the expanded term
         return base_iri + term
 
 

src/hermes/model/types/ld_dict.py

@@ -8,7 +8,7 @@
 from __future__ import annotations
 
 from collections.abc import Generator, Iterator, KeysView
-from typing import Any, Literal, Union, TYPE_CHECKING
+from typing import Any, Literal, Optional, Union, TYPE_CHECKING
 from typing_extensions import Self
 
 from .ld_container import (
@@ -41,10 +41,10 @@ def __init__(
         self: Self,
         data: list[dict[str, EXPANDED_JSON_LD_VALUE]],
         *,
-        parent: Union[ld_dict, ld_list, None] = None,
-        key: Union[str, None] = None,
-        index: Union[int, None] = None,
-        context: Union[list[Union[str, JSON_LD_CONTEXT_DICT]], None] = None
+        parent: Optional[Union[ld_dict, ld_list]] = None,
+        key: Optional[str] = None,
+        index: Optional[int] = None,
+        context: Optional[list[Union[str, JSON_LD_CONTEXT_DICT]]] = None
     ) -> None:
         """
         Create a new instance of an ld_dict.
@@ -133,7 +133,6 @@ def __contains__(self: Self, key: str) -> bool:
         """
         # expand the key and check if self contains a key, value pair with it
         full_iri = self.ld_proc.expand_iri(self.active_ctx, key)
-        # FIXME: is that good?
         return full_iri in self.data_dict
 
     def __eq__(
@@ -364,10 +363,10 @@ def from_dict(
         cls: type[Self],
         value: dict[str, PYTHONIZED_LD_CONTAINER],
         *,
-        parent: Union[ld_dict, ld_list, None] = None,
-        key: Union[str, None] = None,
-        context: Union[str, JSON_LD_CONTEXT_DICT, list[Union[str, JSON_LD_CONTEXT_DICT]], None] = None,
-        ld_type: Union[str, list[str], None] = None
+        parent: Optional[Union[ld_dict, ld_list]] = None,
+        key: Optional[str] = None,
+        context: Optional[Union[str, JSON_LD_CONTEXT_DICT, list[Union[str, JSON_LD_CONTEXT_DICT]]]] = None,
+        ld_type: Optional[Union[str, list[str]]] = None
     ) -> ld_dict:
         """
         Creates a ld_dict from the given dict with the given parent, key, context and ld_type.\n

src/hermes/model/types/ld_list.py

@@ -11,7 +11,7 @@
 
 from collections import deque
 from collections.abc import Generator, Hashable
-from typing import Any, Union, TYPE_CHECKING
+from typing import Any, Optional, Union, TYPE_CHECKING
 from typing_extensions import Self
 
 from .ld_container import (
@@ -42,10 +42,10 @@ def __init__(
         self: Self,
         data: EXPANDED_JSON_LD_VALUE,
         *,
-        parent: Union[ld_dict, ld_list, None] = None,
-        key: Union[str, None] = None,
-        index: Union[int, None] = None,
-        context: Union[list[Union[str, JSON_LD_CONTEXT_DICT]], None] = None,
+        parent: Optional[Union[ld_dict, ld_list]] = None,
+        key: Optional[str] = None,
+        index: Optional[int] = None,
+        context: Optional[list[Union[str, JSON_LD_CONTEXT_DICT]]] = None,
     ) -> None:
         """
         Create a new instance of an ld_list.
@@ -132,6 +132,9 @@ def __setitem__(
 
         Returns:
             None:
+
+        Raises:
+            TypeError: If a slice is not assigned an iterable.
         """
         if not isinstance(index, slice):
             # expand the value
@@ -582,9 +585,9 @@ def from_list(
         cls: type[Self],
         value: list[Union[JSON_LD_VALUE, BASIC_TYPE, TIME_TYPE]],
         *,
-        parent: Union[ld_dict, ld_list, None] = None,
-        key: Union[str, None] = None,
-        context: Union[str, JSON_LD_CONTEXT_DICT, list[Union[str, JSON_LD_CONTEXT_DICT]], None] = None,
+        parent: Optional[Union[ld_dict, ld_list]] = None,
+        key: Optional[str] = None,
+        context: Optional[Union[str, JSON_LD_CONTEXT_DICT, list[Union[str, JSON_LD_CONTEXT_DICT]]]] = None,
         container_type: str = "@set"
     ) -> ld_list:
         """