wexample-filestate-python 0.0.48__py3-none-any.whl

wexample_filestate_python/utils/python_constants_utils.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+import libcst as cst
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+FLAG_NAME = "python-constant-sort"
+
+
+def find_flagged_constant_blocks(
+    module: cst.Module, src: str
+) -> list[tuple[int, int, list[cst.SimpleStatementLine]]]:
+    """Find blocks of contiguous UPPER_CASE assignments following the filestate flag.
+
+    A block starts at the first assignment statement that has the flag in its leading
+    comments; it continues with subsequent contiguous constant assignments until a
+    blank line or a non-constant statement is found.
+
+    Returns list of tuples (start_index, end_index_exclusive, nodes_in_block)
+    where indices refer to module.body positions.
+    """
+    blocks: list[tuple[int, int, list[cst.SimpleStatementLine]]] = []
+
+    i = 0
+    body = module.body
+    n = len(body)
+    while i < n:
+        stmt = body[i]
+        if isinstance(stmt, cst.SimpleStatementLine):
+            has_flag = _stmt_has_flag(stmt, src) or _prev_line_has_flag(list(body), i)
+            if has_flag and _get_simple_assignment_name(stmt) is not None:
+                # Start a block at i
+                j = i
+                nodes: list[cst.SimpleStatementLine] = []
+                while j < n:
+                    s = body[j]
+                    if isinstance(s, cst.SimpleStatementLine):
+                        if j != i:
+                            # Stop the block ONLY if there is a blank line separation
+                            # (an EmptyLine without a comment) among leading_lines.
+                            if any(el.comment is None for el in s.leading_lines):
+                                break
+                        name = _get_simple_assignment_name(s)
+                        if name is None:
+                            break
+                        nodes.append(s)
+                        j += 1
+                        continue
+                    # Stop at any other node
+                    break
+                if nodes:
+                    blocks.append((i, j, nodes))
+                    i = j
+                    continue
+        i += 1
+
+    return blocks
+
+
+# -------- Class-level support --------
+def find_flagged_constant_blocks_in_class(
+    classdef: cst.ClassDef, src: str
+) -> list[tuple[int, int, list[cst.SimpleStatementLine]]]:
+    """Find flagged constant blocks within a class body.
+
+    Returns list of tuples (start_index, end_index_exclusive, nodes_in_block)
+    where indices refer to classdef.body.body positions.
+    """
+    blocks: list[tuple[int, int, list[cst.SimpleStatementLine]]] = []
+    body_list = list(classdef.body.body)
+    n = len(body_list)
+    i = 0
+    while i < n:
+        item = body_list[i]
+        if isinstance(item, cst.SimpleStatementLine):
+            has_flag = _stmt_has_flag(item, src) or _prev_line_has_flag(body_list, i)
+            if has_flag and _get_simple_assignment_name(item) is not None:
+                j = i
+                nodes: list[cst.SimpleStatementLine] = []
+                while j < n:
+                    s = body_list[j]
+                    if isinstance(s, cst.SimpleStatementLine):
+                        if j != i:
+                            # Stop the block ONLY on a blank line (no comment) among leading_lines.
+                            if any(el.comment is None for el in s.leading_lines):
+                                break
+                        name = _get_simple_assignment_name(s)
+                        if name is None:
+                            break
+                        nodes.append(s)
+                        j += 1
+                        continue
+                    break
+                if nodes:
+                    blocks.append((i, j, nodes))
+                    i = j
+                    continue
+        i += 1
+    return blocks
+
+
+def reorder_flagged_constants(module: cst.Module, src: str) -> cst.Module:
+    blocks = find_flagged_constant_blocks(module, src)
+    if not blocks:
+        return module
+
+    new_body = list(module.body)
+
+    # Process blocks from last to first to keep indices stable
+    for start, end, nodes in reversed(blocks):
+        sorted_nodes = sort_constants_block(nodes)
+        # If unchanged, skip
+        if all(a is b for a, b in zip(nodes, sorted_nodes)):
+            continue
+        # Replace slice
+        new_body[start:end] = sorted_nodes
+
+    return module.with_changes(body=new_body)
+
+
+def reorder_flagged_constants_everywhere(module: cst.Module, src: str) -> cst.Module:
+    """Reorder flagged constant blocks at module level and within class bodies."""
+    first = reorder_flagged_constants(module, src)
+    second = reorder_flagged_constants_in_classes(first, src)
+    return second
+
+
+def reorder_flagged_constants_in_classes(module: cst.Module, src: str) -> cst.Module:
+    """Reorder flagged constant blocks inside all class definitions in the module."""
+    changed = False
+    new_module_body = list(module.body)
+
+    for idx, node in enumerate(new_module_body):
+        if isinstance(node, cst.ClassDef):
+            class_body_list = list(node.body.body)
+            blocks = find_flagged_constant_blocks_in_class(node, src)
+            if not blocks:
+                continue
+            # Apply from last to first within the class body
+            for start, end, nodes in reversed(blocks):
+                sorted_nodes = sort_constants_block(nodes)
+                if all(a is b for a, b in zip(nodes, sorted_nodes)):
+                    continue
+                class_body_list[start:end] = sorted_nodes
+                changed = True
+            if changed:
+                new_class_body = node.body.with_changes(body=class_body_list)
+                new_module_body[idx] = node.with_changes(body=new_class_body)
+
+    if not changed:
+        return module
+    return module.with_changes(body=new_module_body)
+
+
+def sort_constants_block(
+    nodes: list[cst.SimpleStatementLine],
+) -> list[cst.SimpleStatementLine]:
+    """Return a new list of nodes sorted by variable name (case-insensitive).
+
+    Preserve the flag comment by attaching it to the first node of the
+    sorted block (even if a different node becomes first after sorting),
+    and clear leading_lines of subsequent nodes to avoid extra blank lines.
+    """
+    from wexample_filestate.helpers.flag import flag_exists
+
+    # Preserve the entire leading_lines per node; additionally, capture the flag
+    # comment lines from whichever node currently holds them so we can keep the flag
+    # on the first node after sorting.
+    original_leadings = [n.leading_lines for n in nodes]
+
+    # Collect flag lines from any node (typically the first) to attach to new first
+    def _flag_lines(ll: Sequence[cst.EmptyLine]) -> list[cst.EmptyLine]:
+        return [
+            el
+            for el in ll
+            if el.comment is not None and flag_exists(FLAG_NAME, el.comment.value)
+        ]
+
+    collected_flag_lines: list[cst.EmptyLine] = []
+    for ll in original_leadings:
+        fl = _flag_lines(ll)
+        if fl:
+            collected_flag_lines = fl
+            break
+
+    pairs: list[tuple[str, cst.SimpleStatementLine]] = []
+    for node in nodes:
+        name = _get_simple_assignment_name(node)
+        if name is None:
+            # Shouldn't happen given precondition
+            continue
+        pairs.append((name, node))
+
+    # If already sorted, return original (no changes)
+    sorted_pairs = sorted(pairs, key=lambda p: p[0].lower())
+    if [n for _, n in sorted_pairs] == [n for _, n in pairs]:
+        return nodes
+
+    # Build new nodes preserving each node's original leading_lines, but move the
+    # flag comment lines to the new first node (removing them from others).
+    sorted_nodes: list[cst.SimpleStatementLine] = []
+
+    # Capture blank lines that precede the flag comment from the first node
+    first_node_blank_lines: list[cst.EmptyLine] = []
+    if original_leadings:
+        for el in original_leadings[0]:
+            if el.comment is None:
+                first_node_blank_lines.append(el)
+            elif flag_exists(FLAG_NAME, el.comment.value):
+                # Stop before the flag comment
+                break
+
+    # Pre-clean each node's leading_lines by removing any flag lines to avoid duplicates
+    # and removing blank lines (except for the first node's leading blanks before flag)
+    cleaned_leadings = []
+    for idx_ll, ll in enumerate(original_leadings):
+        cleaned = [
+            el
+            for el in ll
+            if not (el.comment is not None and flag_exists(FLAG_NAME, el.comment.value))
+            and el.comment is not None  # Remove blank lines (EmptyLine with no comment)
+        ]
+        cleaned_leadings.append(cleaned)
+
+    for idx, (_, node) in enumerate(sorted_pairs):
+        # Determine the original index of this node in 'nodes' list
+        original_index = next((i for i, (_, n) in enumerate(pairs) if n is node), None)
+        leading = (
+            cleaned_leadings[original_index]
+            if original_index is not None
+            else node.leading_lines
+        )
+
+        # For the first node, add blank lines before flag, then flag lines
+        if idx == 0:
+            leading = first_node_blank_lines + collected_flag_lines + list(leading)
+
+        sorted_nodes.append(node.with_changes(leading_lines=leading))
+    return sorted_nodes
+
+
+def _get_simple_assignment_name(stmt: cst.SimpleStatementLine) -> str | None:
+    if len(stmt.body) != 1:
+        return None
+    small = stmt.body[0]
+    if isinstance(small, cst.Assign):
+        if len(small.targets) != 1:
+            return None
+        target = small.targets[0].target
+        if isinstance(target, cst.Name) and _is_upper_name(target.value):
+            return target.value
+        return None
+    if isinstance(small, cst.AnnAssign):
+        target = small.target
+        if isinstance(target, cst.Name) and _is_upper_name(target.value):
+            return target.value
+        return None
+    return None
+
+
+def _is_blank_line(stmt: cst.CSTNode) -> bool:
+    # In Module.body, blank lines are represented as EmptyLine nodes
+    return isinstance(stmt, cst.EmptyLine)
+
+
+def _is_upper_name(name: str) -> bool:
+    return name.isupper()
+
+
+def _prev_line_has_flag(body_list: list[cst.CSTNode], index: int) -> bool:
+    """Return True if the previous sibling is an EmptyLine whose comment contains the flag."""
+    from wexample_filestate.helpers.flag import flag_exists
+
+    if index - 1 < 0:
+        return False
+    prev = body_list[index - 1]
+    if isinstance(prev, cst.EmptyLine) and prev.comment is not None:
+        return flag_exists(FLAG_NAME, prev.comment.value)
+    return False
+
+
+def _stmt_has_flag(stmt: cst.SimpleStatementLine, src: str) -> bool:
+    """Detect if a simple statement line is preceded by the filestate flag.
+
+    We look into leading_lines comments, else fallback to searching raw src segment
+    of the statement's leading trivia.
+    """
+    from wexample_filestate.helpers.flag import flag_exists
+
+    # Check libcst leading_lines comments
+    for el in stmt.leading_lines:
+        if el.comment is not None:
+            comment_text = el.comment.value  # includes '#'
+            if flag_exists(FLAG_NAME, comment_text):
+                return True
+    # Do NOT fallback to scanning the entire file universally; detection via
+    # previous sibling EmptyLine is handled by the callers.
+    return False

wexample_filestate_python/utils/python_docstring_utils.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import libcst as cst
+
+if TYPE_CHECKING:
+    pass
+
+
+def find_module_docstring(
+    module: cst.Module,
+) -> tuple[cst.SimpleStatementLine | None, int]:
+    """Find the module docstring in a CST module.
+
+    Args:
+        module: The CST module to search
+
+    Returns:
+        A tuple of (docstring_node, position) where position is the index
+        in module.body. Returns (None, -1) if no docstring found.
+    """
+    for i, stmt in enumerate(module.body):
+        # Skip comments and blank lines at the start
+        if isinstance(stmt, (cst.SimpleStatementLine)):
+            if len(stmt.body) == 1 and isinstance(stmt.body[0], cst.Expr):
+                expr = stmt.body[0]
+                if isinstance(expr.value, cst.SimpleString):
+                    # This is a string literal at module level - likely a docstring
+                    return stmt, i
+        elif not isinstance(stmt, cst.SimpleStatementLine):
+            # Hit a non-simple statement (like import, class, def) - no docstring
+            break
+
+    return None, -1
+
+
+def is_module_docstring_at_top(module: cst.Module) -> bool:
+    """Check if the module docstring is already at the top position.
+
+    Args:
+        module: The CST module to check
+
+    Returns:
+        True if docstring is at position 0, False otherwise
+    """
+    docstring_node, position = find_module_docstring(module)
+    return docstring_node is not None and position == 0
+
+
+def move_docstring_to_top(module: cst.Module) -> cst.Module:
+    """Move the module docstring to the top of the file.
+
+    Args:
+        module: The CST module to modify
+
+    Returns:
+        Modified module with docstring at the top
+    """
+    docstring_node, position = find_module_docstring(module)
+
+    if docstring_node is None or position == 0:
+        # No docstring or already at top
+        return module
+
+    # Normalize quotes in the docstring
+    normalized_docstring = normalize_docstring_quotes(docstring_node)
+
+    # Remove docstring from current position
+    new_body = list(module.body)
+    new_body.pop(position)
+
+    # Insert at the beginning with no leading whitespace
+    # Ensure the docstring has no leading newlines
+    clean_docstring = normalized_docstring.with_changes(leading_lines=[])
+
+    new_body.insert(0, clean_docstring)
+
+    return module.with_changes(body=new_body)
+
+
+def normalize_docstring_quotes(
+    docstring_node: cst.SimpleStatementLine,
+) -> cst.SimpleStatementLine:
+    """Convert single quotes to double quotes in docstring nodes.
+
+    Args:
+        docstring_node: A CST node containing a docstring statement
+
+    Returns:
+        The same node with normalized double quotes
+    """
+    if not isinstance(docstring_node.body[0], cst.Expr):
+        return docstring_node
+
+    expr = docstring_node.body[0]
+    if not isinstance(expr.value, cst.SimpleString):
+        return docstring_node
+
+    string_value = expr.value
+    quote = string_value.quote
+
+    # Convert single quotes to double quotes
+    if quote.startswith("'''"):
+        new_quote = '"""'
+    elif quote.startswith("'"):
+        new_quote = '"'
+    else:
+        # Already using double quotes
+        return docstring_node
+
+    # Create new string with double quotes
+    new_string = string_value.with_changes(quote=new_quote)
+    new_expr = expr.with_changes(value=new_string)
+    new_body = [new_expr] + list(docstring_node.body[1:])
+
+    return docstring_node.with_changes(body=new_body)

wexample_filestate_python/utils/python_functions_utils.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import libcst as cst
+
+
+def collect_module_function_groups(
+    module: cst.Module,
+) -> list[tuple[int, FunctionGroup]]:
+    """Collect top-level functions into groups, preserving overload sequences.
+
+    A group is formed by consecutive FunctionDef nodes with the same name when
+    the first N-1 have @overload and the last is the implementation (may or may not
+    have @overload in stub-only modules). If there are multiple consecutive
+    @overload for a name but no implementation following, they still form a group.
+    """
+    groups: list[tuple[int, FunctionGroup]] = []
+    i = 0
+    body = module.body
+    n = len(body)
+    while i < n:
+        node = body[i]
+        if isinstance(node, cst.FunctionDef):
+            name = _func_name(node)
+            j = i + 1
+            collected: list[cst.FunctionDef] = [node]
+            # collect further overloads of the same name that are directly consecutive
+            while j < n:
+                next_node = body[j]
+                if (
+                    isinstance(next_node, cst.FunctionDef)
+                    and _func_name(next_node) == name
+                ):
+                    collected.append(next_node)
+                    j += 1
+                    continue
+                break
+            groups.append((i, FunctionGroup(name=name, nodes=tuple(collected))))
+            i = j
+            continue
+        i += 1
+    return groups
+
+
+def module_functions_sorted_before_classes(module: cst.Module) -> bool:
+    """Check if all function groups appear before the first class in the module."""
+    first_class_index = None
+    for idx, node in enumerate(module.body):
+        if isinstance(node, cst.ClassDef):
+            first_class_index = idx
+            break
+    if first_class_index is None:
+        return True
+    # Find first function index
+    for idx, node in enumerate(module.body):
+        if isinstance(node, cst.FunctionDef):
+            return idx < first_class_index
+    return True
+
+
+def reorder_module_functions(module: cst.Module) -> cst.Module:
+    """Reorder module-level functions: group, sort (public then private), and place before classes.
+
+    Keeps overload groups intact and preserves each group's leading_lines on its first function.
+    """
+    groups_with_idx = collect_module_function_groups(module)
+    if not groups_with_idx:
+        return module
+
+    # Extract groups in original order
+    groups = [g for _, g in groups_with_idx]
+
+    # If there is only functions and no classes or their order already correct and sorted, skip?
+    # We'll compute a new ordering and compare.
+    sorted_groups = sort_function_groups(groups)
+
+    # Remove all function nodes from body
+    remove_indices = []
+    for idx, g in groups_with_idx:
+        remove_indices.extend(range(idx, idx + len(g.nodes)))
+    remove_indices = sorted(set(remove_indices))
+
+    new_body: list[cst.CSTNode] = []
+    for idx, node in enumerate(module.body):
+        if idx in remove_indices:
+            continue
+        new_body.append(node)
+
+    # Determine insertion index using an anchor strategy:
+    # - Find the index of the FIRST function definition in the original module
+    # - Reinsert the whole (sorted) functions block at that original position
+    #   (adjusted for removals). This avoids moving unrelated code like type
+    #   aliases or sys.path mutations and preserves the developer's chosen
+    #   placement of the function block.
+    def _is_main_guard(node: cst.CSTNode) -> bool:
+        if not isinstance(node, cst.If):
+            return False
+        test = node.test
+        # Match patterns like: if __name__ == "__main__":
+        if isinstance(test, cst.Comparison):
+            left = test.left
+            comps = test.comparisons
+            if (
+                len(comps) == 1
+                and isinstance(left, cst.Name)
+                and left.value == "__name__"
+            ):
+                comp = comps[0]
+                # operator should be ==
+                if isinstance(comp.operator, cst.Equal):
+                    right = comp.comparator
+                    if isinstance(right, cst.SimpleString):
+                        val = (
+                            right.evaluated_value
+                            if hasattr(right, "evaluated_value")
+                            else right.value.strip("\"'")
+                        )
+                        return val == "__main__" or right.value.strip() in (
+                            "'__main__'",
+                            '"__main__"',
+                        )
+        return False
+
+    # Anchor = index of first function in original body
+    first_func_index: int | None = None
+    for idx, node in enumerate(module.body):
+        if isinstance(node, cst.FunctionDef):
+            first_func_index = idx
+            break
+
+    if first_func_index is None:
+        # No functions at module level
+        return module
+
+    # Adjust anchor for removed nodes
+    removed_before_anchor = sum(1 for i in remove_indices if i < first_func_index)
+    insert_at = first_func_index - removed_before_anchor
+
+    # Keep __main__ guard last: if we somehow would insert after it, clamp to its position
+    for idx, node in enumerate(new_body):
+        if _is_main_guard(node) and insert_at > idx:
+            insert_at = idx
+            break
+
+    # Ensure functions come before the first class if any
+    first_class_index = None
+    for idx, node in enumerate(new_body):
+        if isinstance(node, cst.ClassDef):
+            first_class_index = idx
+            break
+    if first_class_index is not None and insert_at > first_class_index:
+        insert_at = first_class_index
+
+    # Build function nodes preserving each group's comments/spacing on first element
+    rebuilt_functions: list[cst.CSTNode] = []
+    for g in sorted_groups:
+        # Preserve leading_lines of the original first node in the group
+        original_first_leading = g.nodes[0].leading_lines
+        for k, fn in enumerate(g.nodes):
+            if k == 0:
+                rebuilt_functions.append(
+                    fn.with_changes(leading_lines=original_first_leading)
+                )
+            else:
+                rebuilt_functions.append(fn.with_changes(leading_lines=[]))
+
+    # Insert functions as a contiguous block
+    new_body[insert_at:insert_at] = rebuilt_functions
+
+    return module.with_changes(body=new_body)
+
+
+def sort_function_groups(groups: list[FunctionGroup]) -> list[FunctionGroup]:
+    """Sort groups by public (A–Z) then private (_*), each alphabetically case-insensitive."""
+    public = [g for g in groups if not _is_private_name(g.name)]
+    private = [g for g in groups if _is_private_name(g.name)]
+    public.sort(key=lambda g: g.name.lower())
+    private.sort(key=lambda g: g.name.lower())
+    return public + private
+
+
+def _func_name(fn: cst.FunctionDef) -> str:
+    return fn.name.value
+
+
+def _has_overload_decorator(fn: cst.FunctionDef) -> bool:
+    if fn.decorators:
+        return any(_is_overload_decorator(d) for d in fn.decorators)
+    return False
+
+
+def _is_overload_decorator(dec: cst.Decorator) -> bool:
+    expr = dec.decorator
+    # @overload
+    if isinstance(expr, cst.Name) and expr.value == "overload":
+        return True
+    # @typing.overload
+    if isinstance(expr, cst.Attribute):
+        if isinstance(expr.attr, cst.Name) and expr.attr.value == "overload":
+            return True
+    return False
+
+
+def _is_private_name(name: str) -> bool:
+    return name.startswith("_")
+
+
+@dataclass(frozen=True)
+class FunctionGroup:
+    name: str
+    nodes: tuple[cst.FunctionDef, ...]