linting

Author: gvwilson

docs/Makefile

@@ -21,6 +21,14 @@ examples:
 	@mkdir -p tmp
 	${RUN} bin/example_pages.py --indir _posts/plotly_js --outdir tmp/javascript --verbose 1
 
+## format: reformat Python code
+format:
+	@ruff format bin
+
+## lint: check code and project
+lint:
+	@ruff check bin
+
 ## reference: build reference documentation in ./tmp
 reference:
 	@rm -rf tmp

docs/bin/example_pages.py

@@ -7,10 +7,10 @@
 from pathlib import Path
 import re
 
-from utils import _log, _str
+from utils import _log
 
 
-HTML_TAG_RE = re.compile(r'<[^>]*>')
+HTML_TAG_RE = re.compile(r"<[^>]*>")
 SUITE_RE = re.compile(r'where:"suite","(.+?)"')
 
 
@@ -57,10 +57,10 @@ def _make_html(examples):
 
         accum.append('  <div class="row">\n')
         accum.append(_make_html_text(path, header, content))
-        accum.append('  </div>\n')
+        accum.append("  </div>\n")
 
-        accum.append('    </div>\n')
-        accum.append('</div>\n\n')
+        accum.append("    </div>\n")
+        accum.append("</div>\n\n")
 
     return "".join(accum)
 
@@ -73,13 +73,15 @@ def _make_html(examples):
     </div>
 """
 
+
 def _make_html_name(path, header):
     """Make example name block."""
     name = header["name"] if header["name"] else ""
     _log(not name, f"{path} does not have name")
     name = _strip_html(name.replace(" ", "-").replace(",", "").lower())
     return HTML_NAME.format(name=name)
 
+
 HTML_TEXT = """\
   <div class="{columns} columns">
     {markdown_content}
@@ -100,11 +102,14 @@ def _make_html_name(path, header):
       </blockquote>
 """
 
+
 def _make_html_text(path, header, content):
     """Make text of example."""
     columns = "twelve" if "horizontal" in header.get("arrangement", "") else "six"
     markdown_content = markdown(header.get("markdown_content", ""))
-    page_content = HTML_TEXT_PAGE_CONTENT.format(text=escape(content)) if content else ""
+    page_content = (
+        HTML_TEXT_PAGE_CONTENT.format(text=escape(content)) if content else ""
+    )
     description = header.get("description", "")
     description = HTML_TEXT_DESCRIPTION.format(text=description) if description else ""
     return HTML_TEXT.format(
@@ -121,7 +126,9 @@ def _parse_args():
     parser.add_argument("--indir", type=Path, help="Input directory")
     parser.add_argument("--schema", type=Path, help="Path to plot schema JSON file")
     parser.add_argument("--outdir", type=Path, help="Output directory")
-    parser.add_argument("--verbose", type=int, default=0, help="Integer verbosity level")
+    parser.add_argument(
+        "--verbose", type=int, default=0, help="Integer verbosity level"
+    )
     return parser.parse_args()
 
 
@@ -131,10 +138,13 @@ def _process(args, path, record, example_files):
         return
 
     examples = [
-        (p, r) for p, r in example_files.items()
+        (p, r)
+        for p, r in example_files.items()
         if r["header"].get("suite", None) == suite
     ]
-    examples.sort(key=lambda pair: (example_files[pair[0]]["header"]["order"], str(pair[0])))
+    examples.sort(
+        key=lambda pair: (example_files[pair[0]]["header"]["order"], str(pair[0]))
+    )
 
     section = record["header"]["permalink"].strip("/").split("/")[-1]
     _log(args.verbose > 0, f"...{section}: {len(examples)}")

docs/bin/reference_pages.py

@@ -28,7 +28,7 @@
 """
 
 PLOT_SCHEMA_REPLACEMENTS = (
-    ('*', '"'),
+    ("*", '"'),
     ("{array}", "array"),
     ("{arrays}", "arrays"),
     ("{object}", "object"),
@@ -49,8 +49,7 @@
     "magic_underscores",
     "role",
     "stream",
-    "transforms"
-    "uid",
+    "transformsuid",
 }
 
 SKIP_MUSTMATCH = {
@@ -70,12 +69,14 @@
     "yaxis",
 }
 
-ANNOTATION = " ".join([
-    "<br>An annotation is a text element that can be placed anywhere in the plot.",
-    "It can be positioned with respect to relative coordinates in the plot",
-    "or with respect to the actual data coordinates of the graph.",
-    "Annotations can be shown with or without an arrow.",
-])
+ANNOTATION = " ".join(
+    [
+        "<br>An annotation is a text element that can be placed anywhere in the plot.",
+        "It can be positioned with respect to relative coordinates in the plot",
+        "or with respect to the actual data coordinates of the graph.",
+        "Annotations can be shown with or without an arrow.",
+    ]
+)
 
 
 def main():
@@ -93,23 +94,37 @@ def main():
             continue
         title = m.group(1)
 
-        if (m := INCLUDE_TRACE_RE.search(src_content)):
-            if _log(m.group(1) != title, f"title {title} != include title {m.group(1)} in {src_path}"):
+        if m := INCLUDE_TRACE_RE.search(src_content):
+            if _log(
+                m.group(1) != title,
+                f"title {title} != include title {m.group(1)} in {src_path}",
+            ):
                 continue
             trace_name = m.group(2)
             trace_data = schema["traces"].get(trace_name, None)
-            if _log(trace_data is None, f"trace '{trace_name}' not found in {args.schema}"):
+            if _log(
+                trace_data is None, f"trace '{trace_name}' not found in {args.schema}"
+            ):
                 continue
             html = _reference_trace(args, schema, src_path, trace_name, trace_data)
 
-        elif (m := INCLUDE_BLOCK_RE.search(src_content)):
+        elif m := INCLUDE_BLOCK_RE.search(src_content):
             parent_link = m.group(1)
             block = m.group(2)
             parent_path = m.group(3)
             mustmatch = m.group(4)
             accum = []
             attributes = schema["layout"]["layoutAttributes"]
-            _reference_block(args, src_path, accum, attributes, parent_link, parent_path, block, mustmatch)
+            _reference_block(
+                args,
+                src_path,
+                accum,
+                attributes,
+                parent_link,
+                parent_path,
+                block,
+                mustmatch,
+            )
             html = _replace_special("".join([_str(a) for a in accum]))
 
         else:
@@ -144,15 +159,21 @@ def _get(value, key, default=None):
 
 def _parse_args():
     """Parse command-line arguments."""
-    parser = argparse.ArgumentParser(description="Generate HTML reference documentation")
+    parser = argparse.ArgumentParser(
+        description="Generate HTML reference documentation"
+    )
     parser.add_argument("inputs", nargs="+", type=Path, help="Input Jekyll files")
     parser.add_argument("--schema", type=Path, help="Path to plot schema JSON file")
     parser.add_argument("--outdir", type=Path, help="Output directory")
-    parser.add_argument("--verbose", type=int, default=0, help="Integer verbosity level")
+    parser.add_argument(
+        "--verbose", type=int, default=0, help="Integer verbosity level"
+    )
     return parser.parse_args()
 
 
-def _reference_block(args, src_path, accum, attributes, parent_link, parent_path, block, mustmatch=None):
+def _reference_block(
+    args, src_path, accum, attributes, parent_link, parent_path, block, mustmatch=None
+):
     """Generate HTML documentation for a trace's attributes."""
     accum.append("<ul>\n")
     for key, value in attributes.items():
@@ -168,7 +189,9 @@ def _reference_block(args, src_path, accum, attributes, parent_link, parent_path
         accum.append(f"    {key}\n")
         accum.append("</a>\n")
 
-        accum.append(f"<br><em>Parent:</em> <code>{parent_path.replace('-', '.')}</code>\n")
+        accum.append(
+            f"<br><em>Parent:</em> <code>{parent_path.replace('-', '.')}</code>\n"
+        )
 
         if (key == "type") and (block == "data"):
             accum.append("<br />\n")
@@ -183,13 +206,17 @@ def _reference_block(args, src_path, accum, attributes, parent_link, parent_path
         if _get(value, "items") and (_get(value, "valType") != "info_array"):
             _reference_block_array(src_path, accum, key, value)
         elif _get(value, "role") == "object":
-            accum.append('<br><em>Type:</em> {object} containing one or more of the keys listed below.\n')
+            accum.append(
+                "<br><em>Type:</em> {object} containing one or more of the keys listed below.\n"
+            )
 
         if _get(value, "description", "") != "":
             accum.append(f"<p>{escape(value.get('description'))}</p>\n")
 
         if _get(value, "role") == "object":
-            _reference_block_object(args, src_path, accum, parent_link, parent_path, key, value)
+            _reference_block_object(
+                args, src_path, accum, parent_link, parent_path, key, value
+            )
 
         accum.append("</li>\n")
     accum.append("</ul>\n")
@@ -201,11 +228,13 @@ def _reference_block_valtype(src_path, accum, key, value):
     inner = " " * 20
     accum.append("<br>\n")
 
-    if (_get(value, "valType") == "enumerated") or _get(_get(value, "valType"), "values"):
+    if (_get(value, "valType") == "enumerated") or _get(
+        _get(value, "valType"), "values"
+    ):
         accum.append(f"{outer}<em>Type:</em>\n")
         accum.append(f"{inner}{_get(value, 'valType')}")
         if _get(value, "arrayOk"):
-            accum.append(f" or array of { _get(value, 'valType')}s\n")
+            accum.append(f" or array of {_get(value, 'valType')}s\n")
         accum.append(f"{inner}, one of (\n")
         for i, sub_value in enumerate(_get(value, "values")):
             _comma(accum, i, "|")
@@ -217,7 +246,9 @@ def _reference_block_valtype(src_path, accum, key, value):
         if _get(value, "arrayOk"):
             accum.append(f" or array of {_get(value, 'valType')}s")
         if _get(value, "min") and _get(value, "max"):
-            accum.append(f" between or equal to {_get(value, 'min')} and {_get(value, 'max')}\n")
+            accum.append(
+                f" between or equal to {_get(value, 'min')} and {_get(value, 'max')}\n"
+            )
         elif _get(value, "min"):
             accum.append(f" greater than or equal to {_get(value, 'min')}\n")
         elif _get(value, "max"):
@@ -278,7 +309,7 @@ def _reference_block_valtype(src_path, accum, key, value):
             return
         accum.append(f"{inner}<em>Type:</em> string")
         if _get(value, "arrayOk"):
-            accum.append(f" or array of strings")
+            accum.append(" or array of strings")
 
     else:
         accum.append(f"{inner}<em>Type:</em> {_get(value, 'valType')}\n")
@@ -293,7 +324,6 @@ def _reference_block_valtype(src_path, accum, key, value):
 def _reference_block_dflt(src_path, accum, key, value):
     """Handle a default."""
     outer = " " * 16
-    inner = " " * 20
     if _get(value, "valType") == "flaglist":
         accum.append(
             f"{outer}<br><em>Default:</em> <code>*{_get(value, 'dflt')}*</code>\n"
@@ -307,9 +337,13 @@ def _reference_block_dflt(src_path, accum, key, value):
             accum.append(f"[{', '.join(temp)}]")
         elif _get(value, "valType") in {"info_array", "colorlist"}:
             accum.append(f"[{', '.join([_str(x) for x in _get(value, 'dflt')])}]")
-        elif (_get(value, "valType") in {"string", "color"}) or (_get(value, "dflt") == "auto"):
+        elif (_get(value, "valType") in {"string", "color"}) or (
+            _get(value, "dflt") == "auto"
+        ):
             accum.append(f"*{_get(value, 'dflt')}*")
-        elif (_get(value, "valType") == "enumerated") and (_get(value, "dflt") not in {"true", "false"}):
+        elif (_get(value, "valType") == "enumerated") and (
+            _get(value, "dflt") not in {"true", "false"}
+        ):
             accum.append(f"*{_get(value, 'dflt')}*")
         else:
             accum.append(_get(value, "dflt"))
@@ -327,19 +361,21 @@ def _reference_block_array(src_path, accum, key, value):
             accum.append(f"{inner}{ANNOTATION}\n")
 
 
-def _reference_block_object(args, src_path, accum, parent_link, parent_path, key, value):
+def _reference_block_object(
+    args, src_path, accum, parent_link, parent_path, key, value
+):
     """Handle an object with a recursive call."""
-    local_parent_link = f"{parent_link}-{key}"
-    local_parent_path = f"{parent_path}-{key}"
+    parent_path = f"{parent_path}-{key}"
     if _get(value, "items"):
         # This will break if there is ever more than one type of item in items,
         # but for now it's just "shape" and "annotation"
         for item_key, item_value in _get(value, "items").items():
             attributes = item_value
-            local_parent_link = f"{parent_link}-{key}-items-{item_key}"
     else:
         attributes = value
-    _reference_block(args, src_path, accum, attributes, parent_link, parent_path, "nested")
+    _reference_block(
+        args, src_path, accum, attributes, parent_link, parent_path, "nested"
+    )
 
 
 def _reference_trace(args, schema, src_path, trace_name, trace_data):
@@ -354,7 +390,9 @@ def _reference_trace(args, schema, src_path, trace_name, trace_data):
     parent_link = trace_name
     parent_path = f"data[type={trace_name}]"
     attributes = trace_data["attributes"]
-    _reference_block(args, src_path, accum, attributes, parent_link, parent_path, "data")
+    _reference_block(
+        args, src_path, accum, attributes, parent_link, parent_path, "data"
+    )
 
     return _replace_special("".join([_str(a) for a in accum]))
 
@@ -377,16 +415,5 @@ def _skip_mustmatch(key, mustmatch):
         return False
 
 
-def _str(val):
-    """Hacky string conversion."""
-    if isinstance(val, str):
-        return val
-    if isinstance(val, bool):
-        return str(val).lower()
-    if isinstance(val, int):
-        return str(val)
-    return str(val)
-
-
 if __name__ == "__main__":
     main()

pyproject.toml

@@ -5,5 +5,6 @@ version = "3.1.0"
 requires-python = ">=3.12"
 dependencies = [
     "markdown",
-    "python-frontmatter"
+    "python-frontmatter",
+    "ruff"
 ]