turn script into cli app

Author: rmorshea

requirements/pkg-deps.txt

@@ -6,4 +6,5 @@ fastjsonschema >=2.14.5
 requests >=2
 colorlog >=6
 asgiref >=3
-lxml >= 4
+lxml >=4
+typer >=8, <9

src/idom/__main__.py

@@ -0,0 +1,14 @@
+import click
+
+from idom import __version__
+from idom._console.update_html_usages import update_html_usages
+
+
+app = click.Group(
+    commands=[
+        update_html_usages,
+    ]
+)
+
+if __name__ == "__main__":
+    app()

src/idom/_console/__init__.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import ast
+import re
+from collections.abc import Sequence
+from glob import iglob
+from keyword import kwlist
+from pathlib import Path
+from textwrap import indent
+from tokenize import COMMENT as COMMENT_TOKEN
+from tokenize import generate_tokens
+from typing import Iterator
+
+import click
+
+from idom import html
+
+
+CAMEL_CASE_SUB_PATTERN = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+@click.command()
+@click.argument("patterns", nargs=-1)
+def update_html_usages(patterns: list[str]) -> None:
+    """Rewrite files matching the given glob patterns to the new html element API.
+
+    The old API required users to pass a dictionary of attributes to html element
+    constructor functions. For example:
+
+    >>> html.div({"className": "x"}, "y")
+    {"tagName": "div", "attributes": {"className": "x"}, "children": ["y"]}
+
+    The latest API though allows for attributes to be passed as snake_cased keyword
+    arguments instead. The above example would be rewritten as:
+
+    >>> html.div("y", class_name="x")
+    {"tagName": "div", "attributes": {"class_name": "x"}, "children": ["y"]}
+
+    All snake_case attributes are converted to camelCase by the client where necessary.
+
+    ----- Notes -----
+
+    While this command does it's best to preserve as much of the original code as
+    possible, there are inevitably some limitations in doing this. As a result, we
+    recommend running your code formatter like Black against your code after executing
+    this command.
+
+    Additionally, We are unable to perserve the location of comments that lie within any
+    rewritten code. This command will place the comments in the code it plans to rewrite
+    just above its changes. As such it requires manual intervention to put those
+    comments back in their original location.
+    """
+    for pat in patterns:
+        for file in map(Path, iglob(pat)):
+            result = generate_rewrite(file=file, source=file.read_text())
+            if result is not None:
+                file.write_text(result)
+
+
+def generate_rewrite(file: Path, source: str) -> None:
+    tree = ast.parse(source)
+
+    changed: list[Sequence[ast.AST]] = []
+    for parents, node in walk_with_parent(tree):
+        if isinstance(node, ast.Call):
+            func = node.func
+            match func:
+                case ast.Attribute():
+                    name = func.attr
+                case ast.Name(ctx=ast.Load()):
+                    name = func.id
+                case _:
+                    name = ""
+            if hasattr(html, name):
+                match node.args:
+                    case [ast.Dict(keys, values), *_]:
+                        new_kwargs = list(node.keywords)
+                        for k, v in zip(keys, values):
+                            if isinstance(k, ast.Constant) and isinstance(k.value, str):
+                                new_kwargs.append(
+                                    ast.keyword(arg=conv_attr_name(k.value), value=v)
+                                )
+                            else:
+                                new_kwargs = [ast.keyword(arg=None, value=node.args[0])]
+                                break
+                        node.args = node.args[1:]
+                        node.keywords = new_kwargs
+                        changed.append((node, *parents))
+                    case [
+                        ast.Call(
+                            func=ast.Name(id="dict", ctx=ast.Load()),
+                            args=args,
+                            keywords=kwargs,
+                        ),
+                        *_,
+                    ]:
+                        new_kwargs = [
+                            *[ast.keyword(arg=None, value=a) for a in args],
+                            *node.keywords,
+                        ]
+                        for kw in kwargs:
+                            if kw.arg is not None:
+                                new_kwargs.append(
+                                    ast.keyword(
+                                        arg=conv_attr_name(kw.arg), value=kw.value
+                                    )
+                                )
+                            else:
+                                new_kwargs.append(kw)
+                        node.args = node.args[1:]
+                        node.keywords = new_kwargs
+                        changed.append((node, *parents))
+
+                    case _:
+                        pass
+
+    if not changed:
+        return
+
+    ast.fix_missing_locations(tree)
+
+    lines = source.split("\n")
+
+    # find closest parent nodes that should be re-written
+    nodes_to_unparse: list[ast.AST] = []
+    for node_lineage in changed:
+        origin_node = node_lineage[0]
+        for i in range(len(node_lineage) - 1):
+            current_node, next_node = node_lineage[i : i + 2]
+            if (
+                not hasattr(next_node, "lineno")
+                or next_node.lineno < origin_node.lineno
+                or isinstance(next_node, (ast.ClassDef, ast.FunctionDef))
+            ):
+                nodes_to_unparse.append(current_node)
+                break
+        else:
+            raise RuntimeError("Failed to change code")
+
+    # check if an nodes to rewrite contain eachother, pick outermost nodes
+    current_outermost_node, *sorted_nodes_to_unparse = list(
+        sorted(nodes_to_unparse, key=lambda n: n.lineno)
+    )
+    outermost_nodes_to_unparse = [current_outermost_node]
+    for node in sorted_nodes_to_unparse:
+        if node.lineno > current_outermost_node.end_lineno:
+            current_outermost_node = node
+            outermost_nodes_to_unparse.append(node)
+
+    moved_comment_lines_from_end: list[int] = []
+    # now actually rewrite these nodes (in reverse to avoid changes earlier in file)
+    for node in reversed(outermost_nodes_to_unparse):
+        # make a best effort to preserve any comments that we're going to overwrite
+        comments = find_comments(lines[node.lineno - 1 : node.end_lineno])
+
+        # there may be some content just before and after the content we're re-writing
+        before_replacement = lines[node.lineno - 1][: node.col_offset].lstrip()
+
+        if node.end_lineno is not None and node.end_col_offset is not None:
+            after_replacement = lines[node.end_lineno - 1][
+                node.end_col_offset :
+            ].strip()
+        else:
+            after_replacement = ""
+
+        replacement = indent(
+            before_replacement
+            + "\n".join([*comments, ast.unparse(node)])
+            + after_replacement,
+            " " * (node.col_offset - len(before_replacement)),
+        )
+
+        if node.end_lineno:
+            lines[node.lineno - 1 : node.end_lineno] = [replacement]
+        else:
+            lines[node.lineno - 1] = replacement
+
+        if comments:
+            moved_comment_lines_from_end.append(len(lines) - node.lineno)
+
+    for lineno_from_end in sorted(list(set(moved_comment_lines_from_end))):
+        click.echo(f"Moved comments to {file}:{len(lines) - lineno_from_end}")
+
+    return "\n".join(lines)
+
+
+def find_comments(lines: list[str]) -> list[str]:
+    iter_lines = iter(lines)
+    return [
+        token
+        for token_type, token, _, _, _ in generate_tokens(lambda: next(iter_lines))
+        if token_type == COMMENT_TOKEN
+    ]
+
+
+def walk_with_parent(
+    node: ast.AST, parents: tuple[ast.AST, ...] = ()
+) -> Iterator[tuple[tuple[ast.AST, ...], ast.AST]]:
+    parents = (node,) + parents
+    for child in ast.iter_child_nodes(node):
+        yield parents, child
+        yield from walk_with_parent(child, parents)
+
+
+def conv_attr_name(name: str) -> str:
+    new_name = CAMEL_CASE_SUB_PATTERN.sub("_", name).replace("-", "_").lower()
+    return f"{new_name}_" if new_name in kwlist else new_name