random docstring cleanups

Author: mr-c

schema_salad/__init__.py

@@ -1,4 +1,4 @@
-"""Salad is a schema language for describing JSON or YAML structured linked data documents"""
+"""Salad is a schema language for describing JSON or YAML structured linked data documents."""
 
 import logging
 import sys

schema_salad/avro/schema.py

@@ -422,15 +422,16 @@ def items(self) -> Schema:
 
 
 class UnionSchema(Schema):
-    """
-    names is a dictionary of schema objects
-    """
-
     def __init__(
         self,
         schemas: List[JsonDataType],
         names: Names,
     ) -> None:
+        """
+        Initialize a new UnionSchema.
+
+        :param names: a dictionary of schema objects
+        """
         # Ensure valid ctor args
         if names is None:
             raise SchemaParseException("Must provide Names.")
@@ -555,8 +556,9 @@ def get_other_props(
     all_props: PropsType, reserved_props: Tuple[str, ...]
 ) -> Optional[PropsType]:
     """
-    Retrieve the non-reserved properties from a dictionary of properties
-    @args reserved_props: The set of reserved properties to exclude
+    Retrieve the non-reserved properties from a dictionary of properties.
+
+    :param reserved_props: The set of reserved properties to exclude
     """
     if hasattr(all_props, "items") and callable(all_props.items):
         return {k: v for (k, v) in all_props.items() if k not in reserved_props}
@@ -567,7 +569,7 @@ def make_avsc_object(json_data: JsonDataType, names: Optional[Names] = None) ->
     """
     Build Avro Schema from data parsed out of JSON string.
 
-    @arg names: A Name object (tracks seen names and default space)
+    :param names: A Name object (tracks seen names and default space)
     """
     if names is None:
         names = Names()
@@ -651,7 +653,7 @@ def make_avsc_object(json_data: JsonDataType, names: Optional[Names] = None) ->
 
 
 def is_subtype(existing: PropType, new: PropType) -> bool:
-    """Checks if a new type specification is compatible with an existing type spec."""
+    """Check if a new type specification is compatible with an existing type spec."""
     if existing == new:
         return True
     if isinstance(existing, list) and (new in existing):

schema_salad/codegen.py

@@ -41,7 +41,6 @@ def codegen(
     parser_info: Optional[str] = None,
 ) -> None:
     """Generate classes with loaders for the given Schema Salad description."""
-
     j = schema.extend_and_specialize(i, loader)
 
     gen = None  # type: Optional[CodeGenBase]

schema_salad/dlang_codegen.py

@@ -35,7 +35,6 @@ def __init__(
 
     def prologue(self) -> None:
         """Trigger to generate the prolouge code."""
-
         module_comment = []
 
         if self.parser_info:
@@ -141,7 +140,7 @@ def to_doc_comment(self, doc: Union[None, str, List[str]]) -> str:
             for line in lines
         ]
 
-        doc_lines = "\n".join((f" * {line}" for line in lines))
+        doc_lines = "\n".join(f" * {line}" for line in lines)
 
         return f"""/**
 {doc_lines}
@@ -239,7 +238,7 @@ def parse_record_schema(self, stype: Dict[str, Any]) -> str:
         if "fields" in stype:
             for field in stype["fields"]:
                 field_decls.append(self.parse_record_field(field, classname))
-        decl_str = "\n".join((textwrap.indent(f"{d}", " " * 4) for d in field_decls))
+        decl_str = "\n".join(textwrap.indent(f"{d}", " " * 4) for d in field_decls)
 
         if stype.get("documentRoot", False):
             doc_root_annotation = "@documentRoot "

schema_salad/dotnet_codegen.py

@@ -971,7 +971,7 @@ def copy_utils_recursive(util_src: str, util_target: Path) -> None:
                 src = src_template.safe_substitute(template_args)
                 _ensure_directory_and_write(src_path, src)
 
-        for (util_src, util_target) in util_src_dirs.items():
+        for util_src, util_target in util_src_dirs.items():
             copy_utils_recursive(util_src, util_target)
 
     def secondaryfilesdsl_loader(self, inner: TypeDef) -> TypeDef:

schema_salad/exceptions.py

@@ -1,3 +1,4 @@
+"""Shared Exception classes."""
 from typing import List, Optional, Sequence, Tuple, Union
 
 from .sourceline import SourceLine, reflow_all, strip_duplicated_lineno
@@ -98,6 +99,7 @@ def summary(self, level: int = 0, with_bullet: bool = False) -> str:
         return f"{self.prefix()}{spaces}{bullet}{self.message}"
 
     def __str__(self) -> str:
+        """Convert to a string using :py:`pretty_str`."""
         return str(self.pretty_str())
 
     def pretty_str(self, level: int = 0) -> str:

schema_salad/java_codegen.py

@@ -902,7 +902,7 @@ def expand_resource_template_to(resource: str, path: Path) -> None:
             "main_utils": self.main_src_dir,
             "test_utils": self.test_src_dir,
         }
-        for (util_src, util_target) in util_src_dirs.items():
+        for util_src, util_target in util_src_dirs.items():
             for util in pkg_resources.resource_listdir(__name__, f"java/{util_src}"):
                 src_path = util_target / "utils" / util
                 src_template = template_from_resource(os.path.join(util_src, util))

schema_salad/main.py

@@ -266,7 +266,7 @@ def main(argsl: Optional[List[str]] = None) -> int:
         _logger.debug("Index is %s", list(metaschema_loader.idx.keys()))
         _logger.debug("Vocabulary is %s", list(metaschema_loader.vocab.keys()))
         return 1
-    except (RuntimeError) as e:
+    except RuntimeError as e:
         _logger.error(
             "Schema `%s` read error:\n%s",
             args.schema,

schema_salad/makedoc.py

@@ -243,9 +243,7 @@ def markdown_list_hook(markdown, text, state):
 
 
 def patch_fenced_code(original_markdown_text: str, modified_markdown_text: str) -> str:
-    """
-    Reverts fenced code fragments found in the modified contents back to their original definition.
-    """
+    """Reverts fenced code fragments found in the modified contents back to their original definition."""
     # Pattern inspired from 'mistune.block_parser.BlockParser.FENCED_CODE'.
     # However, instead of the initial ' {0,3}' part to match any indented fenced-code,
     # use any quantity of spaces, as long as they match at the end as well (using '\1').

schema_salad/metaschema.py

@@ -47,7 +47,6 @@
 
 
 class LoadingOptions:
-
     idx: IdxType
     fileuri: Optional[str]
     baseuri: str
@@ -73,7 +72,6 @@ def __init__(
         idx: Optional[IdxType] = None,
     ) -> None:
         """Create a LoadingOptions object."""
-
         self.original_doc = original_doc
 
         if idx is not None: