Added docstrings

Author: GlassOfWhiskey

schema_salad/metaschema.py

@@ -11,6 +11,7 @@
 from typing import ClassVar
 
 from schema_salad.runtime import (
+    Saveable,
     file_uri,
     parse_errors,
     prefix_url,
@@ -24,23 +25,24 @@
     from typing_extensions import Self
 
 import copy
-
 from collections.abc import MutableSequence, Sequence, MutableMapping
 from io import StringIO
 from itertools import chain
-from typing import Any, Final, cast, Generic, TypeVar
+from typing import Any, Final, cast, Generic
 from urllib.parse import urldefrag, urlsplit, urlunsplit
 
 from ruamel.yaml.comments import CommentedMap
 
 from schema_salad.exceptions import ValidationException, SchemaSaladException
-from schema_salad.runtime import LoadingOptions, convert_typing, extract_type, Saveable
+from schema_salad.runtime import (
+    LoadingOptions,
+    convert_typing,
+    extract_type,
+    SaveableType,
+)
 from schema_salad.sourceline import SourceLine, add_lc_filename
 from schema_salad.utils import yaml_no_ts  # requires schema-salad v8.2+
 
-S = TypeVar("S", bound=Saveable)
-
-
 _vocab: Final[dict[str, str]] = {}
 _rvocab: Final[dict[str, str]] = {}
 
@@ -285,10 +287,10 @@ def load(
         return self.inner.load(r, baseuri, loadingOptions, docRoot, lc=lc)
 
 
-class _RecordLoader(_Loader, Generic[S]):
+class _RecordLoader(_Loader, Generic[SaveableType]):
     def __init__(
         self,
-        classtype: type[S],
+        classtype: type[SaveableType],
         container: str | None = None,
         no_link_check: bool | None = None,
     ) -> None:
@@ -303,7 +305,7 @@ def load(
         loadingOptions: LoadingOptions,
         docRoot: str | None = None,
         lc: Any | None = None,
-    ) -> S:
+    ) -> SaveableType:
         if not isinstance(doc, MutableMapping):
             raise ValidationException(
                 f"Value is a {convert_typing(extract_type(type(doc)))}, "

schema_salad/python_codegen.py

@@ -139,6 +139,7 @@ def prologue(self) -> None:
 from typing import ClassVar
 
 from schema_salad.runtime import (
+    Saveable,
     file_uri,
     parse_errors,
     prefix_url,
@@ -152,8 +153,10 @@ def prologue(self) -> None:
     from typing_extensions import Self
 """)
 
-        for parent in self.parents_map.values():
-            self.out.write(f"import {parent}\n")
+        if self.parents_map:
+            self.out.write("\n")
+            for parent in self.parents_map.values():
+                self.out.write(f"import {parent}\n")
 
         python_codegen_support: Final = (
             files("schema_salad").joinpath("python_codegen_support.py").read_text("UTF-8")
@@ -625,9 +628,9 @@ def declare_field(
                 """
 {spc}            vocab = _vocab | loadingOptions.vocab
 {spc}            if {safename} not in (cls.__name__, vocab.get(cls.__name__)):
-{spc}               raise ValidationException(f"tried `{{cls.__name__}}` but")
+{spc}                raise ValidationException(f"tried `{{cls.__name__}}` but")
 {spc}        except ValidationException as e:
-{spc}               raise e
+{spc}            raise e
 """.format(
                     safename=self.safe_name(name),
                     spc=spc,

schema_salad/python_codegen_support.py

@@ -3,23 +3,24 @@
 from __future__ import annotations
 
 import copy
-
 from collections.abc import MutableSequence, Sequence, MutableMapping
 from io import StringIO
 from itertools import chain
-from typing import Any, Final, cast, Generic, TypeVar
+from typing import Any, Final, cast, Generic
 from urllib.parse import urldefrag, urlsplit, urlunsplit
 
 from ruamel.yaml.comments import CommentedMap
 
 from schema_salad.exceptions import ValidationException, SchemaSaladException
-from schema_salad.runtime import LoadingOptions, convert_typing, extract_type, Saveable
+from schema_salad.runtime import (
+    LoadingOptions,
+    convert_typing,
+    extract_type,
+    SaveableType,
+)
 from schema_salad.sourceline import SourceLine, add_lc_filename
 from schema_salad.utils import yaml_no_ts  # requires schema-salad v8.2+
 
-S = TypeVar("S", bound=Saveable)
-
-
 _vocab: Final[dict[str, str]] = {}
 _rvocab: Final[dict[str, str]] = {}
 
@@ -264,10 +265,10 @@ def load(
         return self.inner.load(r, baseuri, loadingOptions, docRoot, lc=lc)
 
 
-class _RecordLoader(_Loader, Generic[S]):
+class _RecordLoader(_Loader, Generic[SaveableType]):
     def __init__(
         self,
-        classtype: type[S],
+        classtype: type[SaveableType],
         container: str | None = None,
         no_link_check: bool | None = None,
     ) -> None:
@@ -282,7 +283,7 @@ def load(
         loadingOptions: LoadingOptions,
         docRoot: str | None = None,
         lc: Any | None = None,
-    ) -> S:
+    ) -> SaveableType:
         if not isinstance(doc, MutableMapping):
             raise ValidationException(
                 f"Value is a {convert_typing(extract_type(type(doc)))}, "

schema_salad/runtime.py

@@ -1,7 +1,8 @@
 """
 Shared code for parsers generated by the Python codegen.
 
-See :option:`--codegen=python` & :py:mod:`python_codegen`."""
+See :option:`--codegen=python` & :py:mod:`python_codegen`.
+"""
 
 from __future__ import annotations
 
@@ -13,7 +14,7 @@
 import xml.sax  # nosec
 from abc import ABCMeta, abstractmethod
 from collections.abc import MutableMapping, MutableSequence
-from typing import Any, Final, TypeAlias, cast
+from typing import Any, Final, TypeAlias, cast, TypeVar
 from urllib.parse import quote, urlparse, urlsplit
 from urllib.request import pathname2url
 
@@ -30,11 +31,12 @@
 
 _logger: Final = logging.getLogger("salad")
 
-
 IdxType: TypeAlias = MutableMapping[str, tuple[Any, "LoadingOptions"]]
 
 
 class LoadingOptions:
+    """Class that holds the state of loading a SALAD document."""
+
     idx: Final[IdxType]
     fileuri: Final[str | None]
     baseuri: Final[str]
@@ -210,6 +212,7 @@ def save(
         """Convert this object to a JSON/YAML friendly dictionary."""
 
 
+SaveableType = TypeVar("SaveableType", bound="Saveable")
 save_type: TypeAlias = (
     None | MutableMapping[str, Any] | MutableSequence[Any] | int | float | bool | str
 )
@@ -280,6 +283,7 @@ def save(
     base_url: str = "",
     relative_uris: bool = True,
 ) -> save_type:
+    """Convert an object to a JSON/YAML friendly dictionary."""
     if isinstance(val, Saveable):
         return val.save(top=top, base_url=base_url, relative_uris=relative_uris)
     if isinstance(val, MutableSequence):