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

wexample_filestate_python/option/add_future_annotations_option.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class AddFutureAnnotationsOption(AbstractPythonFileContentOption):
+    def applicable_on_empty_content_file(self) -> bool:
+        return False
+
+    def get_description(self) -> str:
+        return "Add `from __future__ import annotations` at the proper location (after shebang/encoding and module docstring)."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Add `from __future__ import annotations` if not already present."""
+        src = target.get_local_file().read()
+
+        # Fast path: already present
+        if "from __future__ import annotations" in src:
+            return src
+
+        import ast
+        import re
+
+        lines = src.splitlines(keepends=True)
+
+        # Detect shebang and encoding cookie positions
+        idx = 0
+        if lines and lines[0].startswith("#!"):
+            idx = 1
+        # Encoding cookie can be on first or second line (after shebang)
+        enc_re = re.compile(r"^#.*coding[:=]\s*([-_.a-zA-Z0-9]+)")
+        for i in range(idx, min(idx + 2, len(lines))):
+            if enc_re.match(lines[i]):
+                idx = i + 1
+
+        # Parse to find module docstring span
+        try:
+            tree = ast.parse(src)
+        except SyntaxError:
+            # If parsing fails, be conservative: insert after header block
+            insert_at = idx
+        else:
+            body = getattr(tree, "body", [])
+            if (
+                body
+                and isinstance(body[0], ast.Expr)
+                and isinstance(getattr(body[0], "value", None), ast.Constant)
+                and isinstance(body[0].value.value, str)
+            ):
+                # Module docstring present; insert after its end_lineno
+                doc_end = getattr(body[0], "end_lineno", body[0].lineno)  # 1-based
+                insert_at = max(idx, doc_end)  # line number where next stmt starts
+            else:
+                insert_at = idx
+
+        # lines is 0-based; insert_at is 1-based line count from AST
+        insert_index = max(0, min(len(lines), insert_at))
+
+        # Ensure there is a newline after the inserted import if needed
+        future_line = "from __future__ import annotations\n"
+
+        # Avoid inserting duplicate blank lines: if previous line is not blank and not newline, keep
+        # If there are existing future imports right after docstring, we can insert alongside them; no special handling needed
+        lines.insert(insert_index, future_line)
+        # If there isn't a blank line after the future import and next line is not blank, add one for readability
+        j = insert_index + 1
+        if j < len(lines):
+            if lines[j].strip() != "":
+                lines.insert(j, "\n")
+
+        return "".join(lines)

wexample_filestate_python/option/add_return_types_option.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class AddReturnTypesOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Add simple return type annotations (None/bool/str/int/float) when trivially inferable."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Add return type annotations for functions lacking them when trivially inferable.
+
+        Phase 1: annotate -> None, -> bool, -> str, -> int, -> float when all return
+        statements in a function agree on one of these literal types."""
+        import libcst as cst
+
+        src = target.get_local_file().read()
+
+        # We implement type inference and rewriting using LibCST to ensure
+        # robust, formatting-preserving edits. We extend inference to:
+        # - simple literals (None, bool, str, int, float)
+        # - simple class instantiation returns (MyClass() or via a variable assigned once)
+        def _infer_literal_type(expr: cst.BaseExpression) -> str | None:
+            if isinstance(expr, cst.Name):
+                if expr.value in ("True", "False"):
+                    return "bool"
+                if expr.value == "None":
+                    return "None"
+                return None
+            if isinstance(expr, cst.SimpleString):
+                return "str"
+            if isinstance(expr, cst.Integer):
+                return "int"
+            if isinstance(expr, cst.Float):
+                return "float"
+            return None
+
+        class _ReturnCollector(cst.CSTVisitor):
+            def __init__(self) -> None:
+                self.returns: list[cst.Return] = []
+
+            # Do not descend into nested scopes that could have their own returns
+            def visit_FunctionDef(self, node: cst.FunctionDef) -> bool:  # type: ignore[override]
+                return False
+
+            def visit_AsyncFunctionDef(self, node: cst.AsyncFunctionDef) -> bool:  # type: ignore[override]
+                return False
+
+            def visit_Lambda(self, node: cst.Lambda) -> bool:  # type: ignore[override]
+                return False
+
+            def visit_ClassDef(self, node: cst.ClassDef) -> bool:  # type: ignore[override]
+                return False
+
+            def visit_Return(self, node: cst.Return) -> None:  # type: ignore[override]
+                self.returns.append(node)
+
+        class _KnownTypesCollector(cst.CSTVisitor):
+            """Collect known simple type names from class defs and from-imports.
+
+            We stay conservative: only names directly available in the module namespace
+            (class definitions and `from x import Name [as Alias]`).
+            """
+
+            def __init__(self) -> None:
+                self.known: set[str] = set()
+
+            def visit_ClassDef(self, node: cst.ClassDef) -> None:  # type: ignore[override]
+                # Record class name as a potential return type
+                self.known.add(node.name.value)
+
+            def visit_ImportFrom(self, node: cst.ImportFrom) -> None:  # type: ignore[override]
+                # from pkg import A as B -> record B (or A if no alias)
+                for n in node.names:
+                    if isinstance(n, cst.ImportAlias):
+                        asname = n.asname.name.value if n.asname else None
+                        name = n.name.value if isinstance(n.name, cst.Name) else None
+                        if name:
+                            self.known.add(asname or name)
+
+        class _FunctionAssignCollector(cst.CSTVisitor):
+            """Collect simple var -> class-call assignments in a function body.
+
+            Only records the first simple assignment `x = MyClass(...)` where x is a Name
+            and call target resolves to a known type. If a variable is assigned multiple
+            times to different types, it is discarded.
+            """
+
+            def __init__(self, known_types: set[str]) -> None:
+                self.known_types = known_types
+                self.var_type: dict[str, str] = {}
+                self.discarded: set[str] = set()
+
+            def _infer_call_type(self, call: cst.Call) -> str | None:
+                func = call.func
+                if isinstance(func, cst.Name):
+                    # Only keep conservative matches: known type names
+                    if func.value in self.known_types and func.value[:1].isupper():
+                        return func.value
+                elif isinstance(func, cst.Attribute):
+                    # module.MyClass(...) -> infer MyClass if it's a known type
+                    if isinstance(func.attr, cst.Name):
+                        attr_name = func.attr.value
+                        if attr_name in self.known_types and attr_name[:1].isupper():
+                            return attr_name
+                return None
+
+            def _record_assignment(
+                self, target: cst.BaseExpression, value: cst.BaseExpression
+            ) -> None:
+                if not isinstance(target, cst.Name):
+                    return
+                var = target.value
+                if var in self.discarded:
+                    return
+                if not isinstance(value, cst.Call):
+                    return
+                rtype = self._infer_call_type(value)
+                if rtype is None:
+                    return
+                existing = self.var_type.get(var)
+                if existing is None:
+                    self.var_type[var] = rtype
+                elif existing != rtype:
+                    # conflicting assignments -> discard
+                    self.discarded.add(var)
+                    self.var_type.pop(var, None)
+
+            # Stop at nested scopes
+            def visit_FunctionDef(self, node: cst.FunctionDef) -> bool:  # type: ignore[override]
+                return False
+
+            def visit_AsyncFunctionDef(self, node: cst.AsyncFunctionDef) -> bool:  # type: ignore[override]
+                return False
+
+            def visit_ClassDef(self, node: cst.ClassDef) -> bool:  # type: ignore[override]
+                return False
+
+            def visit_Lambda(self, node: cst.Lambda) -> bool:  # type: ignore[override]
+                return False
+
+            def visit_Assign(self, node: cst.Assign) -> None:  # type: ignore[override]
+                # Handle simple form: a = Call(...)
+                if len(node.targets) != 1:
+                    return
+                target = node.targets[0].target
+                self._record_assignment(target, node.value)
+
+        class AddReturnTypesTransformer(cst.CSTTransformer):
+            def __init__(self, known_types: set[str]) -> None:
+                super().__init__()
+                self.known_types = known_types
+
+            def _infer_return_expr_type(
+                self, expr: cst.BaseExpression, var_types: dict[str, str]
+            ) -> str | None:
+                # Literal simple types
+                lit = _infer_literal_type(expr)
+                if lit is not None:
+                    return lit
+
+                # Call to a known class
+                if isinstance(expr, cst.Call):
+                    func = expr.func
+                    if (
+                        isinstance(func, cst.Name)
+                        and func.value in self.known_types
+                        and func.value[:1].isupper()
+                    ):
+                        return func.value
+                    if isinstance(func, cst.Attribute) and isinstance(
+                        func.attr, cst.Name
+                    ):
+                        attr_name = func.attr.value
+                        if attr_name in self.known_types and attr_name[:1].isupper():
+                            return attr_name
+                    return None
+
+                # Variable referring to a previously inferred var type
+                if isinstance(expr, cst.Name):
+                    return var_types.get(expr.value)
+
+                return None
+
+            def _infer_for_function(self, func_node: cst.BaseFunctionDef) -> str | None:
+                # Collect returns in the function body (non-nested)
+                collector = _ReturnCollector()
+                # Visit only the immediate body of the function
+                if isinstance(func_node, cst.FunctionDef):
+                    func_node.body.visit(collector)
+                elif isinstance(func_node, cst.AsyncFunctionDef):
+                    func_node.body.visit(collector)
+                else:
+                    return None
+                # If no return statements -> None
+                if not collector.returns:
+                    return "None"
+
+                # Build a simple assignment map within the function
+                fac = _FunctionAssignCollector(self.known_types)
+                if isinstance(func_node, cst.FunctionDef):
+                    func_node.body.visit(fac)
+                elif isinstance(func_node, cst.AsyncFunctionDef):
+                    func_node.body.visit(fac)
+
+                kinds: set[str] = set()
+                for r in collector.returns:
+                    if r.value is None:
+                        kinds.add("None")
+                        continue
+                    inferred = self._infer_return_expr_type(r.value, fac.var_type)
+                    if inferred is None:
+                        return None
+                    kinds.add(inferred)
+
+                if len(kinds) == 1:
+                    return next(iter(kinds))
+                return None
+
+            def leave_FunctionDef(
+                self,
+                original_node: cst.FunctionDef,
+                updated_node: cst.FunctionDef,
+            ) -> cst.FunctionDef:
+                if updated_node.returns is None:
+                    rtype = self._infer_for_function(original_node)
+                    if rtype is not None:
+                        return updated_node.with_changes(
+                            returns=cst.Annotation(annotation=cst.Name(rtype))
+                        )
+                return updated_node
+
+            def leave_AsyncFunctionDef(
+                self,
+                original_node: cst.AsyncFunctionDef,
+                updated_node: cst.AsyncFunctionDef,
+            ) -> cst.AsyncFunctionDef:
+                if updated_node.returns is None:
+                    rtype = self._infer_for_function(original_node)
+                    if rtype is not None:
+                        return updated_node.with_changes(
+                            returns=cst.Annotation(annotation=cst.Name(rtype))
+                        )
+                return updated_node
+
+        try:
+            module = cst.parse_module(src)
+        except Exception:
+            # If parsing fails for any reason, return the original source unchanged
+            return src
+
+        # Collect known simple type names from the module
+        ktc = _KnownTypesCollector()
+        module.visit(ktc)
+
+        new_module = module.visit(AddReturnTypesTransformer(ktc.known))
+        return new_module.code

wexample_filestate_python/option/fix_attrs_option.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class FixAttrsOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return (
+            "Ensure attrs decorators (@attrs.define, @attr.s) always use kw_only=True."
+        )
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Fix attrs usage in Python files according to standardized rules.
+
+        Current rules:
+        - Ensure @attrs.define always uses kw_only=True
+        - Ensure @attr.s always uses kw_only=True
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_attrs_utils import (
+            fix_attrs_kw_only,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        modified = fix_attrs_kw_only(module)
+        return modified.code

wexample_filestate_python/option/fix_blank_lines_option.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class FixBlankLinesOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Remove blank lines immediately after function/method signatures, class definitions, and between signatures and docstrings."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Fix blank lines in Python files according to standardized rules.
+
+        Current rules:
+        - Remove blank lines immediately after function/method signatures
+        - Remove blank lines immediately after class definitions (except after docstrings)
+        - Ensure no blank lines between signature and docstring
+        - Ensure no blank lines between docstring and first code line (functions only)
+        - Normalize double blank lines inside function/class bodies to maximum 1 blank line
+        - Class properties: no blank lines between properties except UPPERCASE to lowercase transition
+        - Class properties: blank line before first method after properties section
+        - Dataclass properties: blank line between required and optional properties
+        - Module level: 0 blank lines before module docstring
+        - Module level: 1 blank line after module docstring (if present)
+        - Module level: 0 blank lines before first statement (if no docstring)
+        - Compatible with Black: allows blank line after class docstring
+
+        Note: Module-level spacing (between classes/functions/imports) is handled by Black.
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_blank_lines_utils import (
+            fix_function_blank_lines,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        modified = fix_function_blank_lines(module)
+        return modified.code

wexample_filestate_python/option/format_option.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class FormatOption(AbstractPythonFileContentOption):
+    # Use ClassVar to avoid Pydantic treating it as a model field/private attr
+    _line_length: ClassVar[int] = 88
+
+    def get_description(self) -> str:
+        return "Format the Python file content using Black."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Format Python files using Black."""
+        import black
+
+        src = target.get_local_file().read()
+        mode = black.Mode(line_length=self._line_length)
+
+        try:
+            formatted = black.format_file_contents(src, fast=False, mode=mode)
+            return formatted
+        except black.NothingChanged:
+            return src
+        except Exception as e:
+            raise e

wexample_filestate_python/option/fstringify_option.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from wexample_filestate_python.config_option.mixin.with_stdout_wrapping_mixin import (
+    WithStdoutWrappingMixin,
+)
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class FstringifyOption(WithStdoutWrappingMixin, AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Convert old-style string formatting to f-strings using flynt."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Convert string formatting to f-strings using flynt."""
+        from flynt.api import fstringify_code
+        from flynt.state import State
+
+        src = target.get_local_file().read()
+        state = State(aggressive=False, multiline=False, len_limit=120)
+
+        def _execute_fstringify():
+            return fstringify_code(src, state=state)
+
+        result = self._execute_and_wrap_stdout(_execute_fstringify)
+        return result.content

wexample_filestate_python/option/modernize_typing_option.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class ModernizeTypingOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Modernize typing syntax (PEP 585/604) using pyupgrade for Python 3.12."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Modernize typing syntax (PEP 585/604) to Python 3.12 style."""
+        from pyupgrade._main import Settings, _fix_plugins
+
+        src = target.get_local_file().read()
+        settings = Settings(min_version=(3, 12))
+        updated = _fix_plugins(src, settings=settings)
+        return updated

wexample_filestate_python/option/order_class_attributes_option.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class OrderClassAttributesOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Sort class attribute blocks with special names prioritized, preserving comments and spacing."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Sort class attributes: special first, then public A–Z, then private/protected A–Z.
+
+        Special include __slots__, __match_args__, and inner class Config. Operates on
+        contiguous attribute blocks and preserves comments attached to each attribute.
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_class_attributes_utils import (
+            ensure_order_class_attributes_in_module,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        modified = ensure_order_class_attributes_in_module(module)
+        return modified.code

wexample_filestate_python/option/order_class_docstring_option.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class OrderClassDocstringOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Ensure class docstrings are at the top of each class body, preserving headers and decorators."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Ensure each class keeps header/decorators and has its docstring at the top.
+
+        For every class definition in the module, if a class-level docstring exists but
+        is not the first statement in the class suite, move it to the top (after
+        decorators and the class header). Normalizes to double quotes. Avoids
+        whitespace-only diffs when already correct.
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_class_docstring_utils import (
+            ensure_all_classes_docstring_first,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        modified = ensure_all_classes_docstring_first(module)
+        return modified.code

wexample_filestate_python/option/order_class_methods_option.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class OrderClassMethodsOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Order class methods and properties according to standardized rules."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Order class methods according to rules 13–17.
+
+        - Special dunder methods in logical groups
+        - Classmethods: public A–Z, then private A–Z
+        - Staticmethods: public A–Z, then private A–Z
+        - Properties grouped by base name (getter/setter/deleter together), groups A–Z
+        - Instance methods: public A–Z, then private/protected A–Z
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_class_methods_utils import (
+            ensure_order_class_methods_in_module,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        modified = ensure_order_class_methods_in_module(module)
+        return modified.code

wexample_filestate_python/option/order_constants_option.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class OrderConstantsOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Sort contiguous UPPER_CASE constant blocks marked with '# filestate: python-constant-sort' alphabetically at module level."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Sort flagged constant blocks (UPPER_CASE) alphabetically A–Z at module level.
+
+        Only blocks marked by the inline flag '# filestate: python-constant-sort' are considered.
+        A block is a contiguous sequence of simple UPPER_CASE assignments (no blank line between).
+        Non-flagged constants and other contexts are ignored.
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_constants_utils import (
+            reorder_flagged_constants_everywhere,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        modified = reorder_flagged_constants_everywhere(module, src)
+        return modified.code