improve documentation

Author: mr-c

schema_salad/avro/schema.py

@@ -95,6 +95,7 @@ class Schema:
     """Base class for all Schema classes."""
 
     def __init__(self, atype: str, other_props: PropsType | None = None) -> None:
+        """Avro Schema initializer."""
         # Ensure valid ctor args
         if not isinstance(atype, str):
             raise SchemaParseException(
@@ -119,9 +120,11 @@ def props(self) -> PropsType:
 
     # utility functions to manipulate properties dict
     def get_prop(self, key: str) -> PropType | None:
+        """Retrieve a property from the Schema."""
         return self._props.get(key)
 
     def set_prop(self, key: str, value: PropType | None) -> None:
+        """Set a Schema property."""
         self._props[key] = value
 
 
@@ -169,6 +172,7 @@ def validate(val: str | None, name: str) -> None:
 
     @property
     def fullname(self) -> str | None:
+        """Retrieve the computed full name."""
         return self._full
 
     def get_space(self) -> str | None:
@@ -185,10 +189,12 @@ class Names:
     """Track name set and default namespace during parsing."""
 
     def __init__(self, default_namespace: str | None = None) -> None:
+        """Create a namespace tracker."""
         self.names: dict[str, NamedSchema] = {}
         self.default_namespace = default_namespace
 
     def has_name(self, name_attr: str, space_attr: str | None) -> bool:
+        """Test if the given namespace is stored."""
         test = Name(name_attr, space_attr, self.default_namespace).fullname
         return test in self.names
 
@@ -318,13 +324,16 @@ def __init__(
     # read-only properties
     @property
     def default(self) -> Any | None:
+        """Return the default value, if any."""
         return self.get_prop("default")
 
     # utility functions to manipulate properties dict
     def get_prop(self, key: str) -> PropType | None:
+        """Retrieve a property from the Field."""
         return self._props.get(key)
 
     def set_prop(self, key: str, value: PropType | None) -> None:
+        """Set a Field property."""
         self._props[key] = value
 
 
@@ -335,6 +344,7 @@ class PrimitiveSchema(Schema):
     """Valid primitive types are in PRIMITIVE_TYPES."""
 
     def __init__(self, atype: str, other_props: PropsType | None = None) -> None:
+        """Create a PrimitiveSchema."""
         # Ensure valid ctor args
         if atype not in PRIMITIVE_TYPES:
             raise AvroException(f"{atype} is not a valid primitive type.")

schema_salad/cpp_codegen.py

@@ -1,7 +1,7 @@
 """
 C++17 code generator for a given Schema Salad definition.
 
-Currently only supports emiting YAML from the C++ objects, not yet parsing
+Currently only supports emitting YAML from the C++ objects, not yet parsing
 YAML into C++ objects.
 
 The generated code requires the libyaml-cpp library & headers
@@ -489,7 +489,7 @@ def writeDefinition(self, target: IO[str], ind: str, common_namespace: str) -> N
 
 # !TODO way to many functions, most of these shouldn't exists
 def isPrimitiveType(v: Any) -> bool:
-    """Check if v is a primitve type."""
+    """Check if v is a primitive type."""
     if not isinstance(v, str):
         return False
     return v in ["null", "boolean", "int", "long", "float", "double", "string"]
@@ -680,6 +680,7 @@ def convertTypeToCpp(self, type_declaration: list[Any] | dict[str, Any] | str) -
         return safenamespacename(namespace) + "::" + safename(classname)
 
     def epilogue(self, root_loader: TypeDef | None) -> None:
+        """Trigger to generate the epilouge code."""
         # find common namespace
 
         common_namespace = os.path.commonprefix(

schema_salad/exceptions.py

@@ -65,6 +65,7 @@ def as_warning(self) -> "SchemaSaladException":
         return self
 
     def with_sourceline(self, sl: SourceLine | None) -> "SchemaSaladException":
+        """Use the provided SourceLine to set the causal location."""
         if sl and sl.file():
             self.file = sl.file()
             self.start = sl.start()

schema_salad/java_codegen.py

@@ -32,7 +32,7 @@ def _ensure_directory_and_write(path: Path, contents: str) -> None:
         f.write(contents)
 
 
-def doc_to_doc_string(doc: str | None, indent_level: int = 0) -> str:
+def _doc_to_doc_string(doc: str | None, indent_level: int = 0) -> str:
     lead = " " + "  " * indent_level + "* " * indent_level
     if doc:
         doc_str = f"{lead}<BLOCKQUOTE>\n"
@@ -185,9 +185,9 @@ def begin_class(
         if not abstract:
             implemented_by = "This interface is implemented by {{@link {}Impl}}<BR>"
             interface_doc_str += implemented_by.format(cls)
-        interface_doc_str += doc_to_doc_string(doc)
+        interface_doc_str += _doc_to_doc_string(doc)
         class_doc_str = f"* Auto-generated class implementation for <I>{classname}</I><BR>"
-        class_doc_str += doc_to_doc_string(doc)
+        class_doc_str += _doc_to_doc_string(doc)
         target = self.main_src_dir / f"{cls}.java"
         with open(target, "w") as f:
             _logger.info("Writing file: %s", target)
@@ -682,7 +682,7 @@ def declare_field(
 {field_doc_str}
    */
 """.format(
-            fieldname=fieldname, field_doc_str=doc_to_doc_string(doc, indent_level=1)
+            fieldname=fieldname, field_doc_str=_doc_to_doc_string(doc, indent_level=1)
         )
         target = self.main_src_dir / f"{self.current_class}.java"
         with open(target, "a") as f:
@@ -849,6 +849,7 @@ def idmap_loader(
         )
 
     def typedsl_loader(self, inner: TypeDef, ref_scope: int | None) -> TypeDef:
+        """Construct the TypeDef for the given DSL loader."""
         instance_type = inner.instance_type or "Object"
         return self.declare_type(
             TypeDef(

schema_salad/ref_resolver.py

@@ -285,7 +285,7 @@ def add_namespaces(self, ns: dict[str, str]) -> None:
         self.vocab.update(ns)
 
     def add_schemas(self, ns: list[str] | str, base_url: str) -> None:
-        """Fetch exernal schemas and add them to the graph."""
+        """Fetch external schemas and add them to the graph."""
         if self.skip_schemas:
             return
         for sch in aslist(ns):
@@ -1102,6 +1102,7 @@ def validate_link(
         return link
 
     def getid(self, d: Any) -> str | None:
+        """Use our identifiers to extract the first match from the document."""
         if isinstance(d, MutableMapping):
             for i in self.identifiers:
                 if i in d:

schema_salad/schema.py

@@ -646,7 +646,7 @@ def extend_and_specialize(items: list[dict[str, Any]], loader: Loader) -> list[d
                 #       because we have unit tests that rely on the order that
                 #       fields are written. Codegen output changes as well.
                 #       We are relying on the insertion order preserving
-                #       property of python dicts (i.e. relyig on Py3.5+).
+                #       property of Python dicts (i.e. relying on Py3.5+).
 
                 # First pass adding the exfields.
                 for sn_exfield, exfield in sns_exfields.items():

schema_salad/sourceline.py

@@ -6,7 +6,7 @@
 import ruamel.yaml
 from ruamel.yaml.comments import CommentedBase, CommentedMap, CommentedSeq
 
-lineno_re = re.compile("^(.*?:[0-9]+:[0-9]+: )(( *)(.*))")
+lineno_re = re.compile(r"^(.*?:[0-9]+:[0-9]+: )(( *)(.*))")
 
 
 def _add_lc_filename(r: ruamel.yaml.comments.CommentedBase, source: AnyStr) -> None:
@@ -32,6 +32,7 @@ def add_lc_filename(r: ruamel.yaml.comments.CommentedBase, source: str) -> None:
 
 
 def reflow_all(text: str, maxline: int | None = None) -> str:
+    """Reflow text respecting a common prefix with line & col info."""
     if maxline is None:
         maxline = int(os.environ.get("COLUMNS", "100"))
     maxno = 0
@@ -59,6 +60,7 @@ def reflow_all(text: str, maxline: int | None = None) -> str:
 
 
 def reflow(text: str, maxline: int, shift: str | None = "") -> str:
+    """Reflow a single line of text."""
     maxline = max(maxline, 20)
     if len(text) > maxline:
         sp = text.rfind(" ", 0, maxline)
@@ -120,6 +122,7 @@ def strip_duplicated_lineno(text: str) -> str:
 
 
 def strip_dup_lineno(text: str, maxline: int | None = None) -> str:
+    """Strip duplicated line numbers."""
     if maxline is None:
         maxline = int(os.environ.get("COLUMNS", "100"))
     pre: str | None = None
@@ -163,6 +166,16 @@ def cmap(
     lc: list[int] | None = None,
     fn: str | None = None,
 ) -> int | float | str | CommentedMap | CommentedSeq | None:
+    """
+    Apply line+column & filename data through to the provided data.
+
+    :param d: Target datastructure: number and strings will be passed through
+              unchanged. Non-Commented container types with be transformed into
+              the relevant Commented container types.
+    :param lc: Line & Column information to be applied.
+    :param fn: The Filename to store.
+    :returns: The (transformed) datastructure.
+    """
     if lc is None:
         lc = [0, 0, 0, 0]
     if fn is None:
@@ -241,6 +254,7 @@ def __exit__(
         raise self.makeError(str(exc_value)) from exc_value
 
     def file(self) -> str | None:
+        """Return the embedded filename."""
         if hasattr(self.item, "lc") and hasattr(self.item.lc, "filename"):
             return str(self.item.lc.filename)
         return None