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

wexample_filestate_python/utils/python_class_attributes_utils.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import libcst as cst
+
+# Special attribute names and inner classes to prioritize
+SPECIAL_ATTR_NAMES = {"__slots__", "__match_args__"}
+SPECIAL_INNER_CLASS_NAMES = {"Config"}
+
+
+def ensure_order_class_attributes_in_module(module: cst.Module) -> cst.Module:
+    changed = False
+    new_body = list(module.body)
+    for idx, node in enumerate(new_body):
+        if isinstance(node, cst.ClassDef):
+            updated = reorder_class_attributes(node)
+            if updated is not node:
+                new_body[idx] = updated
+                changed = True
+    if not changed:
+        return module
+    return module.with_changes(body=new_body)
+
+
+def find_attribute_blocks_in_class(
+    classdef: cst.ClassDef,
+) -> list[tuple[int, int, list[cst.CSTNode]]]:
+    """Find contiguous blocks of class attributes within the class body.
+
+    A block starts at an attribute statement and continues through subsequent
+    attribute statements; it stops when hitting a blank separator (empty line without
+    comment) or a non-attribute node (e.g., def, @decorated def, etc.).
+    Inline and preceding comment lines are considered attached to the following node.
+
+    Returns list of (start_index, end_index_exclusive, nodes)
+    where indices refer to classdef.body.body positions.
+    """
+    body_list = list(classdef.body.body)
+    n = len(body_list)
+    blocks: list[tuple[int, int, list[cst.CSTNode]]] = []
+    i = 0
+    while i < n:
+        node = body_list[i]
+        if _is_attribute_statement(node):
+            # Start a block
+            j = i
+            nodes: list[cst.CSTNode] = []
+            while j < n:
+                cur = body_list[j]
+                if _is_attribute_statement(cur):
+                    # If not the first, ensure there is no blank separator before cur
+                    if j != i:
+                        # Stop if there is a blank separator among leading_lines (for simple statements)
+                        if isinstance(cur, cst.SimpleStatementLine):
+                            if any(el.comment is None for el in cur.leading_lines):
+                                break
+                        # For ClassDef, presence of a preceding blank line is represented
+                        # by a separate EmptyLine node; if previous sibling is a blank separator, stop.
+                        prev = body_list[j - 1]
+                        if _is_blank_separator(prev):
+                            break
+                    nodes.append(cur)
+                    j += 1
+                    continue
+                # Stop on first non-attribute node
+                break
+            if nodes:
+                blocks.append((i, j, nodes))
+                i = j
+                continue
+        i += 1
+    return blocks
+
+
+def reorder_attribute_block(
+    nodes: list[cst.CSTNode], *, dataclass_mode: bool = False
+) -> list[cst.CSTNode]:
+    """Reorder one attribute block by categories, preserving per-node leading comments.
+
+    Order:
+      1) Special (__slots__, __match_args__, inner class Config)
+      2) Public A–Z
+      3) Private/protected A–Z
+    """
+
+    def cat(node: cst.CSTNode) -> tuple:
+        name = _attr_name(node) or ""
+        if _is_special_attribute(node):
+            # Category 0: special always first
+            return (0, _sort_key(name), False)
+        if dataclass_mode:
+            # In dataclass mode, prioritize fields without defaults (required),
+            # then fields with defaults/default_factory; non-field attributes come after.
+            if _is_dataclass_field(node):
+                if _dataclass_field_has_default(node):
+                    # Category 2: defaulted fields
+                    return (2, _sort_key(name), False)
+                # Category 1: required fields
+                return (1, _sort_key(name), False)
+            # Non-field attributes: keep public before private after fields
+            if _is_public(name):
+                return (3, _sort_key(name), False)
+            return (4, _sort_key(name), False)
+        # Default (non-dataclass) ordering: public, then private
+        if _is_public(name):
+            # Category 1
+            return (1, _sort_key(name), False)
+        # Category 2 (private/protected)
+        return (2, _sort_key(name), False)
+
+    original = list(nodes)
+    sorted_nodes = sorted(nodes, key=cat)
+
+    # If unchanged order, return original to avoid diffs
+    if sorted_nodes == original:
+        return original
+
+    # Normalize leading_lines: only the first node keeps its leading_lines,
+    # others should have minimal leading_lines (preserve comments but remove blank lines).
+    out: list[cst.CSTNode] = []
+    for idx, node in enumerate(sorted_nodes):
+        if idx == 0:
+            # First node: keep its leading_lines as-is
+            out.append(node)
+        else:
+            # Subsequent nodes: strip blank leading_lines, keep only comment lines
+            if isinstance(node, cst.SimpleStatementLine):
+                # Filter leading_lines to keep only comment lines
+                comment_lines = [
+                    line for line in node.leading_lines if line.comment is not None
+                ]
+                out.append(node.with_changes(leading_lines=comment_lines))
+            else:
+                # For ClassDef or other nodes, just append as-is
+                # (blank separators are handled by EmptyLine nodes between body items)
+                out.append(node)
+    return out
+
+
+def reorder_class_attributes(classdef: cst.ClassDef) -> cst.ClassDef:
+    blocks = find_attribute_blocks_in_class(classdef)
+    if not blocks:
+        return classdef
+
+    changed = False
+    body_list = list(classdef.body.body)
+    dc_mode = _is_dataclass(classdef)
+    for start, end, nodes in reversed(blocks):
+        new_nodes = reorder_attribute_block(nodes, dataclass_mode=dc_mode)
+        if new_nodes != nodes:
+            body_list[start:end] = new_nodes
+            changed = True
+    if not changed:
+        return classdef
+    return classdef.with_changes(body=classdef.body.with_changes(body=body_list))
+
+
+def _attr_name(node: cst.CSTNode) -> str | None:
+    if isinstance(node, cst.SimpleStatementLine) and len(node.body) == 1:
+        small = node.body[0]
+        if isinstance(small, cst.Assign):
+            tgt = small.targets[0].target
+            if isinstance(tgt, cst.Name):
+                return tgt.value
+        if isinstance(small, cst.AnnAssign):
+            tgt = small.target
+            if isinstance(tgt, cst.Name):
+                return tgt.value
+    if isinstance(node, cst.ClassDef):
+        return node.name.value
+    return None
+
+
+def _dataclass_field_has_default(node: cst.CSTNode) -> bool:
+    """Return True if the dataclass field has a default value or default_factory.
+
+    We treat any AnnAssign with a non-None value as having a default.
+    This includes calls like field(default=..., default_factory=...).
+    """
+    if not _is_dataclass_field(node):
+        return False
+    assert isinstance(node, cst.SimpleStatementLine)
+    small = node.body[0]
+    assert isinstance(small, cst.AnnAssign)
+    return small.value is not None
+
+
+def _is_attribute_statement(node: cst.CSTNode) -> bool:
+    """Return True if node is a class-level attribute we should order.
+
+    We consider:
+      - Simple single-target Name assignments (Assign/AnnAssign) whose target name is NOT UPPER_CASE
+      - Inner class definitions (e.g., Config) as attributes for ordering
+
+    Uppercase names are ignored here (treated as constants in another operation).
+    """
+    if isinstance(node, cst.SimpleStatementLine) and len(node.body) == 1:
+        small = node.body[0]
+        if isinstance(small, cst.Assign):
+            # Only simple single-target Name assignments
+            if len(small.targets) != 1:
+                return False
+            target = small.targets[0].target
+            if isinstance(target, cst.Name):
+                # Ignore UPPER_CASE constants
+                if target.value.isupper():
+                    return False
+                return True
+            return False
+        if isinstance(small, cst.AnnAssign):
+            target = small.target
+            if isinstance(target, cst.Name):
+                if target.value.isupper():
+                    return False
+                return True
+            return False
+    # Pydantic / config style inner classes are considered attributes for ordering
+    if isinstance(node, cst.ClassDef) and isinstance(node.name, cst.Name):
+        return True
+    return False
+
+
+def _is_blank_separator(node: cst.CSTNode) -> bool:
+    # A blank separator is an EmptyLine without a comment
+    return isinstance(node, cst.EmptyLine) and node.comment is None
+
+
+def _is_comment_line(node: cst.CSTNode) -> bool:
+    return isinstance(node, cst.EmptyLine) and node.comment is not None
+
+
+def _is_dataclass(classdef: cst.ClassDef) -> bool:
+    """Detect if class has a @dataclass decorator (dataclass or dataclasses.dataclass)."""
+    for dec in classdef.decorators:
+        try:
+            expr = dec.decorator
+            if isinstance(expr, cst.Name) and expr.value == "dataclass":
+                return True
+            if isinstance(expr, cst.Attribute) and isinstance(expr.attr, cst.Name):
+                if expr.attr.value == "dataclass":
+                    return True
+        except Exception:
+            continue
+    return False
+
+
+def _is_dataclass_field(node: cst.CSTNode) -> bool:
+    """Dataclass fields are typically annotated assignments (AnnAssign) with non-UPPER names."""
+    if isinstance(node, cst.SimpleStatementLine) and len(node.body) == 1:
+        small = node.body[0]
+        if isinstance(small, cst.AnnAssign):
+            tgt = small.target
+            if isinstance(tgt, cst.Name) and not tgt.value.isupper():
+                return True
+    return False
+
+
+def _is_public(name: str) -> bool:
+    return not name.startswith("_")
+
+
+def _is_special_attribute(node: cst.CSTNode) -> bool:
+    name = _attr_name(node)
+    if name is None:
+        return False
+    if name in SPECIAL_ATTR_NAMES:
+        return True
+    if isinstance(node, cst.ClassDef) and name in SPECIAL_INNER_CLASS_NAMES:
+        return True
+    return False
+
+
+def _sort_key(name: str) -> tuple:
+    # Case-insensitive A-Z; ensure '_' sorts after letters
+    # We achieve this by key: (name without leading '_', is_private)
+    return (name.lstrip("_").lower(), name.startswith("_"))

wexample_filestate_python/utils/python_class_docstring_utils.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import libcst as cst
+
+
+def ensure_all_classes_docstring_first(module: cst.Module) -> cst.Module:
+    """For each class in the module, ensure its docstring (if present) is first."""
+    changed = False
+    new_body = list(module.body)
+
+    for i, node in enumerate(new_body):
+        if isinstance(node, cst.ClassDef):
+            if not is_class_docstring_first(node):
+                updated = move_class_docstring_to_top(node)
+                if updated is not node:
+                    new_body[i] = updated
+                    changed = True
+    if not changed:
+        return module
+    return module.with_changes(body=new_body)
+
+
+def find_class_docstring_nodes(
+    classdef: cst.ClassDef,
+) -> tuple[cst.SimpleStatementLine | None, int]:
+    """Return (docstring_node, index) inside class body if present, else (None, -1).
+
+    According to Python conventions, a class docstring is a first statement that's a
+    string literal expression. We detect any top-level string literal in the class body.
+    """
+    body_elems = list(classdef.body.body)
+    for i, elem in enumerate(body_elems):
+        if isinstance(elem, cst.SimpleStatementLine) and len(elem.body) == 1:
+            small = elem.body[0]
+            if isinstance(small, cst.Expr) and isinstance(
+                small.value, cst.SimpleString
+            ):
+                return elem, i
+        # If we hit a non-simple line before finding a docstring, there's no docstring
+        if not isinstance(elem, cst.SimpleStatementLine):
+            break
+    return None, -1
+
+
+def is_class_docstring_first(classdef: cst.ClassDef) -> bool:
+    node, idx = find_class_docstring_nodes(classdef)
+    # Docstring is considered first if at index 0
+    return node is not None and idx == 0
+
+
+def move_class_docstring_to_top(classdef: cst.ClassDef) -> cst.ClassDef:
+    """Move existing class docstring to be the first statement in the class body.
+
+    Also normalizes quotes to double quotes and removes leading blank lines for the docstring.
+    """
+    doc, idx = find_class_docstring_nodes(classdef)
+    if doc is None or idx == 0:
+        return classdef
+
+    normalized = normalize_docstring_quotes_stmt(doc).with_changes(leading_lines=[])
+
+    body_list = list(classdef.body.body)
+    body_list.pop(idx)
+    body_list.insert(0, normalized)
+    new_suite = classdef.body.with_changes(body=body_list)
+    return classdef.with_changes(body=new_suite)
+
+
+def normalize_docstring_quotes_stmt(
+    stmt: cst.SimpleStatementLine,
+) -> cst.SimpleStatementLine:
+    """Normalize class docstring quotes to double quotes, similar to module behavior."""
+    if not (isinstance(stmt, cst.SimpleStatementLine) and len(stmt.body) == 1):
+        return stmt
+    small = stmt.body[0]
+    if not (isinstance(small, cst.Expr) and isinstance(small.value, cst.SimpleString)):
+        return stmt
+    q = small.value.quote
+    if q.startswith('"""') or q.startswith('"'):
+        return stmt
+    # Convert starting quote to double
+    new_quote = '"""' if q.startswith("'''") else '"'
+    new_value = small.value.with_changes(quote=new_quote)
+    new_small = small.with_changes(value=new_value)
+    return stmt.with_changes(body=[new_small])

wexample_filestate_python/utils/python_class_methods_utils.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import libcst as cst
+
+# Dunder ordering groups per guideline
+DUnderGroups: list[list[str]] = [
+    ["__new__", "__init__"],
+    ["__repr__", "__str__"],
+    ["__lt__", "__le__", "__eq__", "__ne__", "__gt__", "__ge__", "__hash__"],
+    ["__bool__"],
+    ["__getattribute__", "__getattr__", "__setattr__", "__delattr__"],
+    ["__len__", "__iter__", "__getitem__", "__setitem__", "__delitem__"],
+    ["__call__"],
+    ["__enter__", "__exit__", "__aenter__", "__aexit__"],
+    ["__await__", "__aiter__", "__anext__"],
+    ["__get__", "__set__", "__delete__", "__getstate__", "__setstate__"],
+]
+
+# Build a lookup map: name -> (group_index, index_within_group)
+_DUNDER_ORDER: dict[str, tuple[int, int]] = {}
+for gi, group in enumerate(DUnderGroups):
+    for si, name in enumerate(group):
+        _DUNDER_ORDER[name] = (gi, si)
+
+
+def ensure_order_class_methods_in_module(module: cst.Module) -> cst.Module:
+    changed = False
+    new_body = list(module.body)
+    for idx, node in enumerate(new_body):
+        if isinstance(node, cst.ClassDef):
+            updated = reorder_class_methods(node)
+            if updated is not node:
+                new_body[idx] = updated
+                changed = True
+    if not changed:
+        return module
+    return module.with_changes(body=new_body)
+
+
+def reorder_class_methods(classdef: cst.ClassDef) -> cst.ClassDef:
+    """Reorder methods and properties in the class body according to rules 13-17.
+
+    - Dunder methods ordered in logical groups
+    - Classmethods sorted public A–Z then private A–Z
+    - Staticmethods sorted public A–Z then private A–Z
+    - Properties grouped by base name (getter, setter, deleter together), groups A–Z
+    - Instance methods sorted public A–Z then private/protected A–Z
+
+    Non-method nodes (attributes, inner classes, etc.) retain their relative positions; the
+    collection of methods/properties is reordered as a single subsequence in place of the
+    original methods/properties (stable placement among non-method nodes).
+    """
+    body_list = list(classdef.body.body)
+
+    # Collect method nodes and their indices
+    method_indices: list[int] = []
+    method_nodes: list[cst.FunctionDef] = []
+    for idx, node in enumerate(body_list):
+        if _is_method_node(node):
+            method_indices.append(idx)
+            method_nodes.append(node)
+
+    if not method_nodes:
+        return classdef
+
+    # Classify
+    dunders: list[dict] = []
+    classmethods: list[dict] = []
+    staticmethods: list[dict] = []
+    properties: list[dict] = []
+    instances: list[dict] = []
+
+    for f in method_nodes:
+        kind, meta = _classify_method(f)
+        if kind == "dunder":
+            dunders.append(meta)
+        elif kind == "classmethod":
+            classmethods.append(meta)
+        elif kind == "staticmethod":
+            staticmethods.append(meta)
+        elif kind == "property":
+            properties.append(meta)
+        else:
+            instances.append(meta)
+
+    # Order dunders by (group, within) then keep unknown dunders after known, alpha by name
+    known = [m for m in dunders if m["order"][0] != 999]
+    unknown = [m for m in dunders if m["order"][0] == 999]
+    known_sorted = sorted(known, key=lambda m: (m["order"][0], m["order"][1]))
+    unknown_sorted = sorted(unknown, key=lambda m: _sort_key_alpha(m["name"]))
+    dunder_ordered = [m["node"] for m in known_sorted + unknown_sorted]
+
+    # Sort classmethods/staticmethods and instances: public first then private
+    def sort_by_visibility(items: list[dict]) -> list[cst.FunctionDef]:
+        pub = [i for i in items if not _is_private(i["name"])]
+        priv = [i for i in items if _is_private(i["name"])]
+        pub_sorted = [
+            i["node"] for i in sorted(pub, key=lambda x: _sort_key_alpha(x["name"]))
+        ]
+        priv_sorted = [
+            i["node"] for i in sorted(priv, key=lambda x: _sort_key_alpha(x["name"]))
+        ]
+        return pub_sorted + priv_sorted
+
+    classmethods_ordered = sort_by_visibility(classmethods)
+    staticmethods_ordered = sort_by_visibility(staticmethods)
+    instances_ordered = sort_by_visibility(instances)
+
+    # Group properties by base name, order getter, setter, deleter within group
+    prop_groups: dict[str, dict[str, cst.FunctionDef | None]] = {}
+    for m in properties:
+        base = m["base"]
+        kind = m["kind"]
+        node = m["node"]
+        g = prop_groups.setdefault(
+            base, {"getter": None, "setter": None, "deleter": None}
+        )
+        g[kind] = node
+
+    def prop_group_to_nodes(base: str, g: dict[str, cst.FunctionDef | None]):
+        order = []
+        if g.get("getter") is not None:
+            order.append(g["getter"])  # type: ignore
+        if g.get("setter") is not None:
+            order.append(g["setter"])  # type: ignore
+        if g.get("deleter") is not None:
+            order.append(g["deleter"])  # type: ignore
+        return order
+
+    props_ordered: list[cst.FunctionDef] = []
+    for base in sorted(prop_groups.keys(), key=lambda n: n.lower()):
+        props_ordered.extend(prop_group_to_nodes(base, prop_groups[base]))
+
+    # Final ordered list: dunder -> classmethods -> staticmethods -> properties -> instances
+    ordered_methods: list[cst.FunctionDef] = (
+        dunder_ordered
+        + classmethods_ordered
+        + staticmethods_ordered
+        + props_ordered
+        + instances_ordered
+    )
+
+    # If order unchanged, return original
+    if ordered_methods == method_nodes:
+        return classdef
+
+    # Reconstruct body: replace the method nodes subsequence positions with ordered ones,
+    # keeping non-method nodes in place.
+    new_body = list(body_list)
+    for pos, new_node in zip(method_indices, ordered_methods):
+        new_body[pos] = new_node
+
+    new_suite = classdef.body.with_changes(body=new_body)
+    return classdef.with_changes(body=new_suite)
+
+
+def _classify_method(func: cst.FunctionDef) -> tuple[str, dict]:
+    """Classify a FunctionDef into one of: dunder, classmethod, staticmethod, property, instance.
+    Returns (kind, meta) where meta provides extra info like name, dunder order, property base/kind.
+    """
+    name = func.name.value
+    # Properties first (they may also have classmethod/staticmethod in theory, ignore that)
+    base, pkind = _property_kind(func)
+    if base is not None:
+        return "property", {"base": base, "kind": pkind, "node": func}
+    # Classmethod / staticmethod
+    if _has_decorator(func, "classmethod"):
+        return "classmethod", {"name": name, "node": func}
+    if _has_decorator(func, "staticmethod"):
+        return "staticmethod", {"name": name, "node": func}
+    # Dunder methods
+    if _is_dunder(name):
+        order = _DUNDER_ORDER.get(name, (999, 999))
+        return "dunder", {"name": name, "order": order, "node": func}
+    # Instance method
+    return "instance", {"name": name, "node": func}
+
+
+def _has_decorator(func: cst.FunctionDef, decorator_name: str) -> bool:
+    for dec in func.decorators:
+        expr = dec.decorator
+        # @decorator
+        if isinstance(expr, cst.Name) and expr.value == decorator_name:
+            return True
+        # @module.decorator
+        if (
+            isinstance(expr, cst.Attribute)
+            and isinstance(expr.attr, cst.Name)
+            and expr.attr.value == decorator_name
+        ):
+            return True
+    return False
+
+
+def _is_dunder(name: str) -> bool:
+    return name.startswith("__") and name.endswith("__")
+
+
+def _is_method_node(node: cst.CSTNode) -> bool:
+    return isinstance(node, cst.FunctionDef)
+
+
+def _is_private(name: str) -> bool:
+    return name.startswith("_") and not _is_dunder(name)
+
+
+def _property_kind(func: cst.FunctionDef) -> tuple[str | None, str | None]:
+    """Return (base_name, kind) where kind in {getter, setter, deleter} or (None, None).
+    For setters/deleters, decorator is like @<name>.setter or @<name>.deleter.
+    """
+    # Getter: @property on a function whose name is the property name
+    if _has_decorator(func, "property"):
+        return func.name.value, "getter"
+    # Setter/deleter: look for Attribute decorator <name>.setter / <name>.deleter
+    for dec in func.decorators:
+        expr = dec.decorator
+        if isinstance(expr, cst.Attribute) and isinstance(expr.attr, cst.Name):
+            if expr.attr.value in {"setter", "deleter"}:
+                # base name is left side of the attribute if it's a Name
+                base = expr.value
+                if isinstance(base, cst.Name):
+                    return base.value, (
+                        "setter" if expr.attr.value == "setter" else "deleter"
+                    )
+    return None, None
+
+
+def _sort_key_alpha(name: str) -> tuple:
+    # Case-insensitive, underscore after letters
+    return (name.lstrip("_").lower(), name.startswith("_"))