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

wexample_filestate_python/utils/python_iterable_utils.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+FLAG_NAME = "python-iterable-sort"
+
+
+def reorder_flagged_iterables(src: str) -> str:
+    """Sort items of flagged iterable blocks (typically list literals) alphabetically.
+
+    - Looks for lines with '# filestate: python-iterable-sort'.
+    - Sorts the contiguous following element lines until a blank line or closing bracket.
+    - Preserves comments: a contiguous block of comment lines is attached to the
+      item immediately below it and moves with that item.
+    - Preserves indentation and commas; compares using a case-insensitive key on
+      the item line's stripped content.
+    - If already sorted, returns original src unchanged.
+    """
+    lines = src.splitlines()
+    if not lines:
+        return src
+
+    flag_lines = _find_flag_line_indices(src)
+    if not flag_lines:
+        return src
+
+    changed = False
+
+    def split_into_groups(block_lines: list[str]) -> list[list[str]]:
+        groups: list[list[str]] = []
+        pending_comments: list[str] = []
+        for ln in block_lines:
+            if ln.lstrip().startswith("#"):
+                pending_comments.append(ln)
+                continue
+            # item line
+            group = pending_comments + [ln]
+            groups.append(group)
+            pending_comments = []
+        # Any trailing comments without item are ignored for sorting and left in place
+        # (shouldn't occur in expected usage). If present, attach to last group to preserve.
+        if pending_comments:
+            if groups:
+                groups[-1].extend(pending_comments)
+            else:
+                groups.append(pending_comments)
+        return groups
+
+    def group_key(g: list[str]) -> str:
+        # Use the first non-comment line in group as key
+        for ln in g:
+            if not ln.lstrip().startswith("#"):
+                # Remove trailing comma for comparison but don't modify actual text
+                item = ln.strip()
+                if item.endswith(","):
+                    item = item[:-1]
+                return item.lower()
+        return ""  # fallback
+
+    for flag_idx in reversed(flag_lines):
+        start, end = _collect_iterable_block(lines, flag_idx)
+        if start >= end:
+            continue
+        block = lines[start:end]
+
+        groups = split_into_groups(block)
+        # Build current order keys for no-op detection
+        current_keys = [group_key(g) for g in groups]
+        sorted_groups = sorted(groups, key=group_key)
+        sorted_keys = [group_key(g) for g in sorted_groups]
+
+        if sorted_keys == current_keys:
+            continue
+
+        # Flatten groups back to lines
+        new_block: list[str] = []
+        for g in sorted_groups:
+            new_block.extend(g)
+
+        lines[start:end] = new_block
+        changed = True
+
+    return "\n".join(lines) if changed else src
+
+
+def _collect_iterable_block(lines: list[str], flag_idx: int) -> tuple[int, int]:
+    """Given the index of the flag line, collect the contiguous item block range.
+
+    Returns (start_idx, end_idx_exclusive) of lines to sort. We start at the next
+    non-empty, non-comment line after the flag, and stop before the first blank
+    line or the closing bracket ']' at the same or lesser indentation level.
+    """
+    n = len(lines)
+    # Determine base indentation from the flag line
+    flag_line = lines[flag_idx]
+    base_indent = len(flag_line) - len(flag_line.lstrip(" \t"))
+
+    # Start scanning after the flag line
+    i = flag_idx + 1
+    # Skip immediate blank/comment lines (though the example shows none)
+    while i < n and (lines[i].strip() == "" or lines[i].lstrip().startswith("#")):
+        i += 1
+    start = i
+
+    # Scan until blank line or closing bracket ']' at indentation <= base
+    while i < n:
+        stripped = lines[i].strip()
+        # Stop at blank separator line
+        if stripped == "":
+            break
+        # Stop when list ends
+        curr_indent = len(lines[i]) - len(lines[i].lstrip(" \t"))
+        if stripped.startswith("]") and curr_indent <= base_indent:
+            break
+        # Stop if we encounter a trailing comment-only line
+        if lines[i].lstrip().startswith("#"):
+            break
+        i += 1
+
+    end = i
+    return start, end
+
+
+def _find_flag_line_indices(src: str) -> list[int]:
+    """Return line indices where the iterable sort flag appears."""
+    from wexample_filestate.helpers.flag import flag_exists
+
+    lines = src.splitlines()
+    indices: list[int] = []
+    for i, line in enumerate(lines):
+        if flag_exists(FLAG_NAME, line):
+            indices.append(i)
+    return indices

wexample_filestate_python/utils/python_main_guard_utils.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import libcst as cst
+
+
+def find_main_guard_blocks(module: cst.Module) -> list[tuple[int, cst.If]]:
+    """Return list of (index, IfNode) for all top-level __main__ guard blocks."""
+    res: list[tuple[int, cst.If]] = []
+    for i, stmt in enumerate(module.body):
+        if is_main_guard_if(stmt):
+            res.append((i, stmt))
+    return res
+
+
+def is_main_guard_at_end(module: cst.Module) -> bool:
+    blocks = find_main_guard_blocks(module)
+    if not blocks:
+        return True
+    last_index = blocks[-1][0]
+    # Consider "at the end" if it's the last non-empty node (ignoring trailing blank lines)
+    # Find last non-empty node index
+    last_non_empty = -1
+    for i in range(len(module.body) - 1, -1, -1):
+        if not isinstance(module.body[i], cst.EmptyLine):
+            last_non_empty = i
+            break
+    return last_index == last_non_empty
+
+
+def is_main_guard_if(node: cst.CSTNode) -> bool:
+    return isinstance(node, cst.If) and _is_name_eq_main(node.test)
+
+
+def move_main_guard_to_end(module: cst.Module) -> cst.Module:
+    blocks = find_main_guard_blocks(module)
+    if not blocks:
+        return module
+
+    new_body = list(module.body)
+
+    # Remove all blocks first (from highest index to lowest)
+    removed: list[cst.If] = []
+    for idx, node in sorted(blocks, key=lambda t: t[0], reverse=True):
+        removed.append(new_body.pop(idx))
+    removed.reverse()  # preserve original order
+
+    # Strip leading_lines of the first moved guard only if it would create extra blank lines at end
+    # In practice, we keep existing leading_lines to minimize diffs.
+    # Append guards at the end (before trailing EmptyLines, if any)
+    # Find insertion point: just before trailing EmptyLines
+    insert_at = len(new_body)
+    while insert_at > 0 and isinstance(new_body[insert_at - 1], cst.EmptyLine):
+        insert_at -= 1
+
+    for offset, node in enumerate(removed):
+        new_body.insert(insert_at + offset, node)
+
+    return module.with_changes(body=new_body)
+
+
+def _is_name_eq_main(test: cst.BaseExpression) -> bool:
+    # Match patterns: __name__ == "__main__" or '__main__'
+    if not isinstance(test, cst.Comparison):
+        return False
+    # Expect a single comparator with Eq
+    if len(test.comparisons) != 1:
+        return False
+    comp = test.comparisons[0]
+    if not isinstance(comp.operator, cst.Equal):
+        return False
+    # Left should be Name("__name__") (optionally with parentheses tolerated by CST?)
+    left_ok = isinstance(test.left, cst.Name) and test.left.value == "__name__"
+    if not left_ok:
+        return False
+    # Right should be SimpleString of __main__
+    right = comp.comparator
+    if isinstance(right, cst.SimpleString):
+        s = right.evaluated_value  # libcst provides unescaped python value
+        return s == "__main__"
+    return False

wexample_filestate_python/utils/python_module_metadata_utils.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import libcst as cst
+
+# Common, recognized module metadata names
+METADATA_NAMES: tuple[str, ...] = (
+    "__all__",
+    "__version__",
+    "__author__",
+    "__email__",
+    "__license__",
+    "__copyright__",
+    "__title__",
+    "__description__",
+)
+
+
+def find_module_metadata_statements(
+    module: cst.Module,
+) -> list[tuple[int, cst.SimpleStatementLine, str]]:
+    """Find all module-level metadata assignments.
+
+    Returns list of tuples: (index_in_body, node, metadata_name)
+    """
+    results: list[tuple[int, cst.SimpleStatementLine, str]] = []
+    for i, stmt in enumerate(module.body):
+        name = _get_assignment_target_name(stmt)
+        if name is not None:
+            assert isinstance(stmt, cst.SimpleStatementLine)
+            results.append((i, stmt, name))
+    return results
+
+
+def group_and_sort_module_metadata(module: cst.Module) -> cst.Module:
+    """Group and sort module metadata assignments by variable name (A–Z).
+
+    - Collect all recognized metadata assignments at module level
+    - Remove them from their current positions
+    - Sort them case-insensitively by the metadata name
+    - Insert them as a contiguous block at the target index
+    - Avoid introducing extra blank lines by clearing leading_lines
+    """
+    found = find_module_metadata_statements(module)
+    if not found:
+        return module
+
+    # Determine insertion index before we mutate the body
+    insert_at = target_index_for_module_metadata(module)
+
+    # Remove from body (reverse order) and collect nodes with cleaned leading lines
+    to_remove_indices = sorted([i for i, _, _ in found], reverse=True)
+    new_body: list[cst.CSTNode] = list(module.body)
+    moved: list[tuple[str, cst.SimpleStatementLine]] = []
+
+    for idx in to_remove_indices:
+        node = new_body.pop(idx)
+        assert isinstance(node, cst.SimpleStatementLine)
+        name = _get_assignment_target_name(node)
+        if name is None:
+            # Should not happen; skip
+            continue
+        moved.append((name, node.with_changes(leading_lines=[])))
+
+    # Sort moved by name case-insensitively, '_' after letters rule not needed here
+    moved.sort(key=lambda t: t[0].lower())
+
+    # Adjust insertion index after removals that occurred before it
+    num_removed_before = sum(1 for idx in to_remove_indices if idx < insert_at)
+    adjusted_insert = insert_at - num_removed_before
+
+    # Insert in order
+    for offset, (_, node) in enumerate(moved):
+        new_body.insert(adjusted_insert + offset, node)
+
+    return module.with_changes(body=new_body)
+
+
+def target_index_for_module_metadata(module: cst.Module) -> int:
+    """Compute target index to insert grouped module metadata.
+
+    According to file-level ordering:
+    - after imports
+    - after TYPE_CHECKING block
+    - then module metadata
+
+    So we insert after the last TYPE_CHECKING block if present, else after last regular
+    import if present, else after last __future__ import, else after docstring, else 0.
+    """
+    from wexample_filestate_python.utils.python_type_checking_utils import (
+        _is_future_import,
+        _is_regular_import,
+        find_type_checking_blocks,
+    )
+
+    last_type_checking = -1
+    for idx, _if in find_type_checking_blocks(module):
+        last_type_checking = max(last_type_checking, idx)
+
+    last_regular_import = -1
+    last_future_import = -1
+    for i, stmt in enumerate(module.body):
+        if _is_regular_import(stmt):
+            last_regular_import = i
+        elif _is_future_import(stmt):
+            last_future_import = i
+
+    if last_type_checking != -1:
+        return last_type_checking + 1
+    if last_regular_import != -1:
+        return last_regular_import + 1
+    if last_future_import != -1:
+        return last_future_import + 1
+    if module.has_docstring:
+        return 1
+    return 0
+
+
+def _get_assignment_target_name(stmt: cst.CSTNode) -> str | None:
+    """Return the variable name if this statement is an assignment to a metadata name.
+
+    Only supports simple module-level assignments like `__version__ = ...` or
+    annotated assignment `__version__: str = ...`. Ignores destructuring or multiple targets.
+    """
+    if not isinstance(stmt, cst.SimpleStatementLine):
+        return None
+
+    if len(stmt.body) != 1:
+        return None
+
+    small = stmt.body[0]
+
+    if isinstance(small, cst.Assign):
+        # Only allow single target
+        if len(small.targets) != 1:
+            return None
+        target = small.targets[0].target
+        if isinstance(target, cst.Name) and target.value in METADATA_NAMES:
+            return target.value
+        return None
+
+    if isinstance(small, cst.AnnAssign):
+        target = small.target
+        if isinstance(target, cst.Name) and target.value in METADATA_NAMES:
+            return target.value
+        return None
+
+    return None

wexample_filestate_python/utils/python_type_checking_utils.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import libcst as cst
+
+
+def find_type_checking_blocks(module: cst.Module) -> list[tuple[int, cst.If]]:
+    """Return list of (index, IfNode) for all top-level `if TYPE_CHECKING:` blocks."""
+    results: list[tuple[int, cst.If]] = []
+    for i, stmt in enumerate(module.body):
+        if isinstance(stmt, cst.If) and _is_type_checking_test(stmt.test):
+            results.append((i, stmt))
+    return results
+
+
+def move_type_checking_blocks_after_imports(module: cst.Module) -> cst.Module:
+    """Move all `if TYPE_CHECKING:` blocks to just after regular imports.
+    Preserves the order of the blocks and removes extra leading blank lines.
+    """
+    blocks = find_type_checking_blocks(module)
+    if not blocks:
+        return module
+
+    # Determine target position before removal to avoid index shifts
+    insert_at = target_index_for_type_checking(module)
+
+    # Remove blocks from body (from highest index to lowest to keep indices valid)
+    remove_indices = sorted((i for i, _ in blocks), reverse=True)
+    new_body = list(module.body)
+    moved_blocks: list[cst.If] = []
+    for idx in remove_indices:
+        node = new_body.pop(idx)
+        assert isinstance(node, cst.If)
+        # Strip leading lines to avoid introducing blank lines
+        moved_blocks.append(node.with_changes(leading_lines=[]))
+
+    # We removed in reverse; preserve original relative order by reversing back
+    moved_blocks.reverse()
+
+    # Adjust insert_at for prior removals that occurred before it
+    num_removed_before = sum(1 for idx in remove_indices if idx < insert_at)
+    adjusted_insert = insert_at - num_removed_before
+
+    for offset, block in enumerate(moved_blocks):
+        new_body.insert(adjusted_insert + offset, block)
+
+    return module.with_changes(body=new_body)
+
+
+def target_index_for_type_checking(module: cst.Module) -> int:
+    """Compute target insertion index for TYPE_CHECKING blocks.
+    After last regular import if any; otherwise after last __future__ import;
+    otherwise after module docstring if present; else position 0.
+    """
+    last_regular_import = -1
+    last_future_import = -1
+
+    for i, stmt in enumerate(module.body):
+        if _is_regular_import(stmt):
+            last_regular_import = i
+        elif _is_future_import(stmt):
+            last_future_import = i
+        else:
+            # stop scanning when hitting first non-import after having passed imports?
+            # We still record all to get the last occurrence.
+            pass
+
+    if last_regular_import != -1:
+        return last_regular_import + 1
+    if last_future_import != -1:
+        return last_future_import + 1
+
+    # Module docstring at index 0?
+    if module.has_docstring:
+        return 1
+
+    return 0
+
+
+def _is_future_import(stmt: cst.CSTNode) -> bool:
+    if isinstance(stmt, cst.SimpleStatementLine):
+        for small in stmt.body:
+            if isinstance(small, cst.ImportFrom):
+                # from __future__ import ...
+                mod = small.module
+                if isinstance(mod, cst.Name) and mod.value == "__future__":
+                    return True
+    return False
+
+
+def _is_regular_import(stmt: cst.CSTNode) -> bool:
+    if isinstance(stmt, cst.SimpleStatementLine):
+        for small in stmt.body:
+            if isinstance(small, (cst.Import, cst.ImportFrom)):
+                # Exclude __future__
+                if isinstance(small, cst.ImportFrom):
+                    mod = small.module
+                    if isinstance(mod, cst.Name) and mod.value == "__future__":
+                        return False
+                return True
+    return False
+
+
+def _is_type_checking_test(test: cst.BaseExpression) -> bool:
+    # TYPE_CHECKING
+    if isinstance(test, cst.Name) and test.value == "TYPE_CHECKING":
+        return True
+    # typing.TYPE_CHECKING
+    if isinstance(test, cst.Attribute):
+        if isinstance(test.attr, cst.Name) and test.attr.value == "TYPE_CHECKING":
+            # Optional: enforce base name 'typing'
+            if isinstance(test.value, cst.Name) and test.value.value == "typing":
+                return True
+    return False

wexample_filestate_python/utils/relocate_imports/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .python_parser_import_index import PythonParserImportIndex
+
+__all__ = [
+    "PythonParserImportIndex",
+]