Fix flake8 linting errors

docs/source/conf.py

@@ -39,7 +39,10 @@
     "pipx": ("https://pypa.github.io/pipx/%s", None),
     "pypi": ("https://pypi.org/%s", None),
     "repos-blob": ("https://github.com/OpenMPDK/Spex/blob/main/%s", None),
-    "repos-actions": ("https://github.com/OpenMPDK/Spex/actions/workflows/example.yml%s", None)
+    "repos-actions": (
+        "https://github.com/OpenMPDK/Spex/actions/workflows/example.yml%s",
+        None,
+    ),
 }
 
 # -- Optins for HTML output -------------------------------------------------

pyproject.toml

@@ -61,6 +61,9 @@ exclude = [
     "docs/",
     ".venv/"
 ]
+per-file-ignores = [
+    "src/spex/htmlspec/docx/__init__.py:F401"
+]
 
 
 [tool.isort]

src/spex/htmlspec/docx/styles.py

@@ -39,7 +39,8 @@ def __init_alias_dct(style_doc: _Element, style_type: str) -> Dict[str, str]:
     @lru_cache(maxsize=60)
     def __get_style(self, style_id: str) -> Optional[RunProperties]:
         # get entry
-        # if w:basedOn exists, resolv (using same fn, causing caching), return merge(<basedOn>, <this>)
+        # if w:basedOn exists, resolv (using same fn, causing caching),
+        # return merge(<basedOn>, <this>)
         style = Xpath.elem_first_req(
             self._style_doc,
             f"./w:style[@w:type = '{self._style_type}'][@w:styleId = '{style_id}']",

src/spex/htmlspec/docx/tablewrap.py

@@ -63,9 +63,11 @@ def tc_vmerge(tc: _Element) -> VMerge:
                 vmerge = tc_vmerge(tc)
                 if vmerge is VMerge.MERGED:
                     lcell = matrix[-1][cndx]
-                    assert (
-                        grid_span == lcell.colspan
-                    ), f"cell has grid_span {grid_span}, but parent has {lcell.colspan} - breaks assumption of rectangular-only merges"
+                    assert grid_span == lcell.colspan, (
+                        f"cell has grid_span {grid_span}, but parent has "
+                        f"{lcell.colspan} - breaks assumption of "
+                        "rectangular-only merges"
+                    )
                     # update bottom value to mark
                     lcell.bottom = rndx
                 else:

src/spex/htmlspec/docx/tags.py

@@ -25,7 +25,10 @@
 
 
 def _expand(tag: str) -> str:
-    """Expand tag such as `w:tbl` into the absolute format used by lxml etree.Element.tag."""
+    """
+    Expand tag such as `w:tbl` into the absolute
+    format used by lxml etree.Element.tag.
+    """
     ns, tagname = tag.split(":")
     return f"{{{_nsmap[ns]}}}{tagname}"
 

src/spex/htmlspec/parser.py

@@ -234,7 +234,8 @@ def _parse_table(self, stream: Stream[_Element]) -> Optional[Table]:
                     and shd_fill is not None
                     and (shd_fill[0:2] == shd_fill[2:4] == shd_fill[4:6])
                 ):
-                    # heuristic: specs uses various greytone colors to mark table headers
+                    # heuristic: specs uses various greytone colors
+                    # to mark table headers
                     tag = "th"
 
                 tcell = TableCell(

src/spex/jsonspec/document.py

@@ -88,7 +88,7 @@ def tbl_normalize_mappings(self) -> Dict[str, str]:
 
     @property
     def extractors(self) -> List[Type["FigureExtractor"]]:
-        """Return list of Figure extractors to try applying to figures found in document.
+        """Return list of Figure extractors to try applying to figures found in document
 
         Note:
             Each extractor's `can_apply` function is called in turn to determine if

src/spex/jsonspec/extractors/figure.py

@@ -133,23 +133,26 @@ def can_apply(cls, tbl_col_hdrs: List[str]) -> bool:
 
     @staticmethod
     def content_column_hdrs() -> List[str]:
-        """Return prioritized list of column headers where extractor should extract the row's content.
+        """Return prioritized list of column headers where extractor should
+        extract the row's content.
 
-        The content row is where the extractor will extract a brief (short documentation string)
-        for the row and any sub-tables, if present.
-        Also, if there is no dedicated column for row names, these too will be extracted from this column.
+        The content row is where the extractor will extract a brief (short
+        documentation string) for the row and any sub-tables, if present.
+        Also, if there is no dedicated column for row names, these too will be
+        extracted from this column.
 
         Note:
             First match found in figure's actual table headers is used.
 
-            This is intended to be overridden for specialized extractors where the content
-            column is using a non-standard heading.
+            This is intended to be overridden for specialized extractors where
+            the content column is using a non-standard heading.
         """
         return ["description"]
 
     @staticmethod
     def label_column_hdrs() -> List[str]:
-        """Return prioritized list of column headers where extractor should extract the row's name.
+        """Return prioritized list of column headers where extractor should
+        extract the row's name.
 
         Note:
             First match found in figure's actual table headers is used.

src/spex/jsonspec/extractors/skiptable.py

@@ -12,7 +12,8 @@ class SkipTable(FigureExtractor):
     @classmethod
     def can_apply(cls, tbl_col_hdrs: List[str]) -> bool:
         raise RuntimeError(
-            "Don't add Skiptable to `extractors`, implied if no extractor can be applied."
+            "Don't add Skiptable to `extractors`, implied if no extractor can be"
+            "applied."
         )
 
     def __call__(self) -> Iterator[Entity]:

src/spex/jsonspec/extractors/structtable.py

@@ -32,10 +32,11 @@ class StructTableExtractor(FigureExtractor, ABC):
     @staticmethod
     @abstractmethod
     def range_column_hdrs() -> List[str]:
-        """Return prioritized list of column headers where extractor should extract the row's range.
+        """Return prioritized list of column headers where extractor should
+        extract the row's range.
 
-        The value row is where the extractor will extract the row's range, equivalent to the field's
-        offset and width in a C struct.
+        The value row is where the extractor will extract the row's range,
+        equivalent to the field's offset and width in a C struct.
 
         Note:
             First match found in figure's actual table headers is used.
@@ -81,7 +82,8 @@ def row_err_handler(
         fields: List[StructField],
         err: Exception,
     ) -> Generator["Entity", None, RowErrPolicy]:
-        """hook called for unhandled errors from extracting a row's value and data fields.
+        """hook called for unhandled errors from extracting a row's value and
+        data fields.
 
         This hook is useful only for individual table overrides to catch special cases.
         """
@@ -150,8 +152,9 @@ def __call__(self) -> Iterator["Entity"]:
             yield from self.extract_data_subtbls(subtbl_ent, row_data)
             fields.append(sfield)
 
-        # bits tables have their rows in descending order, bytes tables show rows in ascending order
-        # this step ensures we are always processing fields sorted by their range in ascending order
+        # bits tables have their rows in descending order, bytes tables show
+        # rows in ascending order this step ensures we are always processing
+        # fields sorted by their range in ascending order
         fields = list(reversed(fields)) if self.type == "bits" else fields
 
         self.validate_fields(fields)
@@ -288,7 +291,8 @@ def _extract_label(self, row: Element, row_key: str, data: Element) -> str:
                     return lbl
                 txt_parts = txt.split(":", 1)
                 # generic naming strategy
-                # TODO: improve, replace certain words/sentences by certain abbreviations
+                # TODO: improve, replace certain words/sentences by certain
+                # abbreviations
                 #       namespace -> ns, pointer -> ptr
                 gen_name = "".join(w[0] for w in txt_parts[0].split()).lower()
                 self.add_issue(LintErr.LBL_IMPUTED, row_key=row_key)

src/spex/jsonspec/extractors/valuetable.py

@@ -106,10 +106,11 @@ def __call__(self) -> Iterator["Entity"]:
 
     @staticmethod
     def value_column_hdrs() -> List[str]:
-        """Return prioritized list of column headers where extractor should extract the row's value.
+        """Return prioritized list of column headers where extractor should
+        extract the row's value.
 
-        The value row is where the extractor will extract the row's value - loosely equivalent to
-        the enum value of the entry.
+        The value row is where the extractor will extract the row's value -
+        loosely equivalent to the enum value of the entry.
 
         Note:
             First match found in figure's actual table headers is used.
@@ -126,7 +127,8 @@ def row_err_handler(
         fields: List[ValueField],
         err: Exception,
     ) -> Generator["Entity", None, RowErrPolicy]:
-        """hook called for unhandled errors from extracting a row's value and data fields.
+        """hook called for unhandled errors from extracting a row's value and
+        data fields.
 
         This hook is useful only for individual table overrides to catch special cases.
         """
@@ -166,8 +168,10 @@ def val_elem(self, row: Element) -> Element:
         return Xpath.elem_first_req(row, f"./td[{self._col_ndx_value + 1}]")
 
     def val_clean(self, row: Element, val_cell: Element) -> Union[str, int]:
-        # TODO: read as number if possible, complain if not a hex value using the 'h' suffix
-        # TODO: there are also tables using b suffix, is there always a suffix or..?
+        # TODO: read as number if possible, complain if not a hex value using
+        # the 'h' suffix
+        # TODO: there are also tables using b suffix, is there
+        # always a suffix or..?
         return (
             "".join(
                 e.decode("utf-8") if isinstance(e, bytes) else e
@@ -181,7 +185,8 @@ def content_elem(self, row: Element) -> Element:
         return Xpath.elem_first_req(row, f"./td[{self._col_ndx_content + 1}]")
 
     def _extract_label_dedicated_col(self, row: Element, row_key: str) -> str:
-        # if we hit this, some document actually has a value table with a dedicated 'attribute' column
+        # if we hit this, some document actually has a value table with a
+        # dedicated 'attribute' column
         breakpoint()
         p1 = Xpath.elem_first_req(row, f"./td[{self._col_ndx_label + 1}]/p[1]")
         txt = XmlUtils.to_text(p1).lower()

src/spex/jsonspec/lint.py

@@ -12,7 +12,10 @@
 class Code(Enum):
     O1000 = "general error"
 
-    T1000 = "error parsing table - the table's columns implied it should be parsed but some quirk of the table caused the parser to fail"
+    T1000 = (
+        "error parsing table - the table's columns implied it should be parsed but "
+        "some quirk of the table caused the parser to fail"
+    )
     T1001 = "field overlaps with range of prior field"
     T1002 = "gap between this and the prior field"
     T1004 = "row order wrong, bits should be in desc order, bytes in asc order"
@@ -86,9 +89,10 @@ def __post_init__(self):
             self.err, LintErr
         ), f"invalid code, expected {LintErr}, got {type(self.err)}"
         if self.err.value.name[0] in ("R", "L", "V"):
-            assert (
-                self.row is not None
-            ), "R|L|V codes point to a row or label/value within the row, row field must be set"
+            assert self.row is not None, (
+                "R|L|V codes point to a row or label/value within the row, "
+                "row field must be set"
+            )
 
     def to_json(self) -> JSON:
         ret: Dict[str, JSON] = {

src/spex/parse.py

@@ -157,7 +157,10 @@ def parse_spec(
         ]
 
         if reported_lint_errs:
-            err_prefix = f"Encountered {len(reported_lint_errs)} linting errors during processing"
+            err_prefix = (
+                f"Encountered {len(reported_lint_errs)} "
+                "linting errors during processing"
+            )
             if p := w.path:
                 err_msg = f"see `{str(p)}`"
             else:

src/spex/xml.py

@@ -53,7 +53,8 @@ def elems(cls, e: XmlElem, query: str) -> List[Element]:
                 )
             else:
                 raise RuntimeError(
-                    f"query '{query}' did not return a list of Element, first element is {type(res[0])}"
+                    f"query '{query}' did not return a list of Element, "
+                    f"first element is {type(res[0])}"
                 )
         return cast(List[Element], res)
 
@@ -77,7 +78,8 @@ def attrs(cls, e: XmlElem, query: str) -> List[str]:
         assert isinstance(res, list)
         if len(res) > 0 and not isinstance(res[0], str):
             raise RuntimeError(
-                f"query should return a list of str elements for attr-queries, got {type(res[0])}, use `Xpath.elems` instead?"
+                "query should return a list of str elements for attr-queries, "
+                f"got {type(res[0])}, use `Xpath.elems` instead?"
             )
         return cast(List[str], res)