wexample-filestate-python 0.0.40__tar.gz → 0.0.41__tar.gz

{wexample_filestate_python-0.0.40 → wexample_filestate_python-0.0.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-filestate-python
-Version: 0.0.40
+Version: 0.0.41
 Summary: Helpers for Python.
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -9,17 +9,9 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Project-URL: homepage, https://github.com/wexample/python-filestate-python
 Requires-Python: >=3.10
-Requires-Dist: autoflake
-Requires-Dist: black
-Requires-Dist: flynt
-Requires-Dist: isort
-Requires-Dist: networkx
-Requires-Dist: packaging
 Requires-Dist: pydantic<3,>=2
-Requires-Dist: python-dotenv
-Requires-Dist: pyupgrade
-Requires-Dist: tomlkit
-Requires-Dist: wexample-filestate-git==0.0.38
+Requires-Dist: wexample-filestate==0.0.51
+Requires-Dist: wexample-helpers-api==0.0.32
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Description-Content-Type: text/markdown
@@ -28,7 +20,7 @@ Description-Content-Type: text/markdown
 
 Helpers for Python.
 
-Version: 0.0.40
+Version: 0.0.41
 
 ## Requirements
 
@@ -36,17 +28,8 @@ Version: 0.0.40
 
 ## Dependencies
 
-- autoflake
-- black
-- flynt
-- isort
-- networkx
-- packaging
 - pydantic>=2,<3
-- python-dotenv
-- pyupgrade
-- tomlkit
-- wexample-filestate-git==0.0.38
+- wexample-filestate==0.0.51
 
 ## Installation
 

{wexample_filestate_python-0.0.40 → wexample_filestate_python-0.0.41}/README.md

@@ -2,7 +2,7 @@
 
 Helpers for Python.
 
-Version: 0.0.40
+Version: 0.0.41
 
 ## Requirements
 
@@ -10,17 +10,8 @@ Version: 0.0.40
 
 ## Dependencies
 
-- autoflake
-- black
-- flynt
-- isort
-- networkx
-- packaging
 - pydantic>=2,<3
-- python-dotenv
-- pyupgrade
-- tomlkit
-- wexample-filestate-git==0.0.38
+- wexample-filestate==0.0.51
 
 ## Installation
 

{wexample_filestate_python-0.0.40 → wexample_filestate_python-0.0.41}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-filestate-python"
-version = "0.0.40"
+version = "0.0.41"
 description = "Helpers for Python."
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -18,17 +18,9 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "autoflake",
-    "black",
-    "flynt",
-    "isort",
-    "networkx",
-    "packaging",
     "pydantic>=2,<3",
-    "python-dotenv",
-    "pyupgrade",
-    "tomlkit",
-    "wexample-filestate-git==0.0.38",
+    "wexample-filestate==0.0.51",
+    "wexample-helpers-api==0.0.32",
 ]
 
 [project.readme]
@@ -51,7 +43,7 @@ distribution = true
 
 [tool.pdm.build]
 includes = [
-    "src/wexample_filestate_python/py.typed",
+    "src/wexample_filestate_python/*",
 ]
 package-dir = "src"
 packages = [

wexample_filestate_python-0.0.41/src/wexample_filestate_python/common/pipy_gateway.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pydantic import Field
+from wexample_helpers_api.common.abstract_gateway import AbstractGateway
+
+
+class PipyGateway(AbstractGateway):
+    base_url: str | None = Field(
+        default="https://pypi.org/", description="Base Pipy API URL"
+    )
+
+    def package_release_exists(self, package_name: str, version: str) -> bool:
+        response = self.make_request(f"pypi/{package_name}/json")
+        # Package exists
+        if response.status_code == 200:
+            return bool(response.json().get("releases", {}).get(version))
+
+        return False

wexample_filestate_python-0.0.41/src/wexample_filestate_python/config_option/python_config_option.py

@@ -0,0 +1,20 @@
+from typing import Any, ClassVar
+
+from wexample_config.config_option.abstract_config_option import AbstractConfigOption
+
+
+class PythonConfigOption(AbstractConfigOption):
+    OPTION_NAME_FORMAT: ClassVar[str] = "format"
+    OPTION_NAME_SORT_IMPORTS: ClassVar[str] = "sort_imports"
+    OPTION_NAME_ADD_RETURN_TYPES: ClassVar[str] = "add_return_types"
+    OPTION_NAME_MODERNIZE_TYPING: ClassVar[str] = "modernize_typing"
+    OPTION_NAME_FSTRINGIFY: ClassVar[str] = "fstringify"
+    OPTION_NAME_REMOVE_UNUSED: ClassVar[str] = "remove_unused"
+    # New preferred option name to add `from __future__ import annotations`
+    OPTION_NAME_ADD_FUTURE_ANNOTATIONS: ClassVar[str] = "add_future_annotations"
+    # New policy: unquote annotations (remove string annotations)
+    OPTION_NAME_UNQUOTE_ANNOTATIONS: ClassVar[str] = "unquote_annotations"
+
+    @staticmethod
+    def get_raw_value_allowed_type() -> Any:
+        return list[str]

wexample_filestate_python-0.0.41/src/wexample_filestate_python/const/name_pattern.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+NAME_PATTERN_PYTHON_NOT_PYCACHE = "^(?!__pycache__$).+$"

wexample_filestate_python-0.0.41/src/wexample_filestate_python/file/python_file.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+from wexample_filestate.item.item_target_file import ItemTargetFile
+
+
+class PythonFile(ItemTargetFile):
+    EXTENSION_ENV: ClassVar[str] = "py"
+
+    def _expected_file_name_extension(self) -> str | None:
+        return PythonFile.EXTENSION_ENV

wexample_filestate_python-0.0.41/src/wexample_filestate_python/helpers/package.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import tomli
+
+
+def package_parse_setup(path: Path) -> dict:
+    """
+    Parse a setup.py file to extract metadata.
+    """
+    with open(path) as f:
+        content = f.read()
+
+    tree = ast.parse(content)
+    for node in ast.walk(tree):
+        if (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Name)
+            and node.func.id == "setup"
+        ):
+            result = {}
+            for kw in node.keywords:
+                if isinstance(kw.value, ast.Str):
+                    result[kw.arg] = kw.value.s
+                elif isinstance(kw.value, ast.List):
+                    result[kw.arg] = [
+                        elt.s for elt in kw.value.elts if isinstance(elt, ast.Str)
+                    ]
+            return result
+    return {}
+
+
+def package_parse_toml(path: Path) -> dict:
+    """
+    Parse a pyproject.toml file to extract metadata.
+    """
+    try:
+        with open(path, "rb") as f:
+            data = tomli.load(f)
+            if "project" in data:
+                project_data = data["project"]
+                return {
+                    "name": project_data.get("name"),
+                    "install_requires": project_data.get("dependencies", []),
+                }
+    except Exception as e:
+        print(f"Error parsing {path}: {e}")
+    return {}
+
+
+def package_get_info(package_dir: Path) -> tuple[str, set[str]] | None:
+    """
+    Get package name and its dependencies from setup.py or pyproject.toml.
+    """
+    # Try pyproject.toml first
+    toml_path = package_dir / "pyproject.toml"
+    if toml_path.exists():
+        metadata = package_parse_toml(toml_path)
+    else:
+        # Fallback to setup.py
+        setup_py_path = package_dir / "setup.py"
+        if setup_py_path.exists():
+            metadata = package_parse_setup(setup_py_path)
+        else:
+            return None
+
+    name = metadata.get("name")
+    if not name:
+        return None
+
+    deps = metadata.get("install_requires", [])
+    return name, set(deps)
+
+
+def package_get_dependencies(root_dir: str | Path) -> dict[str, set[str]]:
+    """
+    Get dependencies between packages in a directory.
+    """
+    packages_root = Path(root_dir)
+    if not packages_root.exists() or not packages_root.is_dir():
+        raise ValueError(f"Error: {packages_root} does not exist or is not a directory")
+
+    dependencies = {}
+
+    # First pass: collect all local packages
+    for package_dir in packages_root.iterdir():
+        if not package_dir.is_dir():
+            continue
+
+        package_info = package_get_info(package_dir)
+        if package_info:
+            name, _ = package_info
+            dependencies[name] = set()
+
+    # Second pass: analyze dependencies
+    for package_dir in packages_root.iterdir():
+        if not package_dir.is_dir():
+            continue
+
+        package_info = package_get_info(package_dir)
+        if package_info:
+            name, deps = package_info
+            if name in dependencies:
+                # Only keep dependencies that are local packages
+                dependencies[name] = {dep for dep in deps if dep in dependencies}
+
+    return dependencies
+
+
+def package_list_sorted(root_dir: str | Path) -> list[str]:
+    """
+    Get a list of package names sorted by dependency order.
+    """
+    from wexample_filestate.helpers.dependencies import dependencies_sort
+
+    dependencies = package_get_dependencies(root_dir)
+    if not dependencies:
+        return []
+
+    # Convert dependencies dict to list for sorting
+    packages = list(dependencies.keys())
+
+    def get_deps(pkg: str) -> set[str]:
+        return dependencies[pkg]
+
+    return dependencies_sort(packages, get_deps)
+
+
+def package_normalize_name(val: str) -> str:
+    import re as _re
+
+    # strip extras, versions, markers
+    base = _re.split(r"[\s<>=!~;\[]", val, maxsplit=1)[0]
+    return base.strip().lower()

wexample_filestate_python-0.0.41/src/wexample_filestate_python/helpers/toml.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import Any
+
+from tomlkit import array as _tk_array
+from tomlkit import table as _tk_table
+from tomlkit.items import Array, String
+
+
+def toml_sort_string_array(arr: Any) -> bool:
+    """
+    Sort a tomlkit Array of String items in-place (case-insensitive) while
+    preserving the existing multiline/style flags.
+
+    Returns True if the array was changed.
+    """
+    # Validate array type
+    if not isinstance(arr, Array):
+        return False
+
+    items = list(arr)
+    if not items or not all(isinstance(i, String) for i in items):
+        return False
+
+    values = [i.value for i in items]
+    sorted_items = [
+        x
+        for _, x in sorted(zip([v.lower() for v in values], items), key=lambda t: t[0])
+    ]
+
+    if items == sorted_items:
+        return False
+
+    multiline_flag = getattr(arr, "multiline", None)
+    # Clear and re-append to preserve tomlkit item identity
+    while len(arr):
+        arr.pop()
+    for item in sorted_items:
+        arr.append(item)
+    if multiline_flag is not None:
+        arr.multiline(multiline_flag)
+    return True
+
+
+def toml_ensure_table(doc: Any, path: list[str]) -> tuple[Any, bool]:
+    """
+    Ensure a nested TOML table exists and return (table, changed).
+    Path example: ["tool", "pdm", "build"]. Uses tomlkit.table() for missing parts.
+    """
+    if not isinstance(path, list) or not path:
+        raise ValueError("path must be a non-empty list of keys")
+
+    changed = False
+    current = doc
+    for key in path:
+        tbl = current.get(key) if isinstance(current, dict) else None
+        if not tbl or not isinstance(tbl, dict):
+            tbl = _tk_table()
+            current[key] = tbl
+            changed = True
+        current = tbl
+    return current, changed
+
+
+def toml_ensure_array(tbl: Any, key: str) -> tuple[Any, bool]:
+    """
+    Ensure an array exists at tbl[key] and return (array, changed).
+    Uses tomlkit.array() for creation.
+    """
+    arr = tbl.get(key) if isinstance(tbl, dict) else None
+    if arr is None:
+        arr = _tk_array()
+        tbl[key] = arr
+        return arr, True
+    return arr, False
+
+
+def toml_get_string_value(item: Any) -> str:
+    """Return the string content of a tomlkit String or generic item as str."""
+    if isinstance(item, String):
+        return item.value
+    return str(item)
+
+
+def toml_ensure_array_multiline(tbl: Any, key: str) -> tuple[Array, bool]:
+    """
+    Ensure an array exists at tbl[key] and force multiline formatting.
+    Returns (array, changed_created).
+    """
+    arr, changed = toml_ensure_array(tbl, key)
+    # Force multiline for readability when dumping
+    if isinstance(arr, Array):
+        arr.multiline(True)
+    return arr, changed
+
+
+def toml_set_array_multiline(tbl: Any, key: str, values: list[Any]) -> Array:
+    """
+    Replace tbl[key] with a tomlkit array built from values and set multiline(True).
+    Returns the created Array instance.
+    """
+    arr = _tk_array(values)
+    arr.multiline(True)
+    tbl[key] = arr
+    return arr

wexample_filestate_python-0.0.41/src/wexample_filestate_python/operation/abstract_python_file_operation.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_config.config_option.abstract_config_option import AbstractConfigOption
+from wexample_filestate.enum.scopes import Scope
+from wexample_filestate.operation.abstract_existing_file_operation import (
+    AbstractExistingFileOperation,
+)
+from wexample_filestate_python.config_option.python_config_option import (
+    PythonConfigOption,
+)
+
+if TYPE_CHECKING:
+    pass
+
+
+class AbstractPythonFileOperation(AbstractExistingFileOperation):
+    @classmethod
+    def get_scope(cls) -> Scope:
+        return Scope.CONTENT
+
+    @classmethod
+    def get_option_name(cls) -> str:
+        raise NotImplementedError
+
+    def applicable_for_option(self, option: AbstractConfigOption) -> bool:
+        """Generic applicability for Python file transforms controlled by a single option name."""
+        # Option type
+        if not isinstance(option, PythonConfigOption):
+            return False
+
+        # Option value must contain our specific option name
+        value = option.get_value()
+        if value is None or not value.has_item_in_list(self.get_option_name()):
+            return False
+
+        # Delegate change detection to the base helper
+        return self.source_need_change(self.target)

wexample_filestate_python-0.0.41/src/wexample_filestate_python/operation/python_add_future_annotations_operation.py

@@ -0,0 +1,101 @@
+from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+from .abstract_python_file_operation import AbstractPythonFileOperation
+
+
+class PythonAddFutureAnnotationsOperation(AbstractPythonFileOperation):
+    """Ensure `from __future__ import annotations` is present at module top.
+
+    Triggered by: {"python": ["add_future_annotations"]}
+
+    Note: This operation historically removed __future__ imports; we repurpose it
+    to add the annotations future consistently across the codebase, per new policy.
+    """
+
+    @classmethod
+    def get_option_name(cls) -> str:
+        from wexample_filestate_python.config_option.python_config_option import (
+            PythonConfigOption,
+        )
+
+        return PythonConfigOption.OPTION_NAME_ADD_FUTURE_ANNOTATIONS
+
+    def describe_before(self) -> str:
+        return "The file may be missing `from __future__ import annotations` at the module top."
+
+    def describe_after(self) -> str:
+        return "`from __future__ import annotations` has been added in the correct position."
+
+    def description(self) -> str:
+        return "Add `from __future__ import annotations` at the proper location (after shebang/encoding and module docstring)."
+
+    @classmethod
+    def preview_source_change(cls, target: TargetFileOrDirectoryType) -> str | None:
+        """Return source with a `from __future__ import annotations` inserted
+        in the correct place if it is not already present.
+
+        Rules:
+        - Keep shebang on first line intact.
+        - Keep encoding cookie (PEP 263) within first two lines intact.
+        - If module docstring exists, insert after the docstring statement.
+        - Otherwise, insert after shebang/encoding header block.
+        - If the future import already exists anywhere, return the original source.
+        """
+        src = cls._read_current_str_or_fail(target)
+
+        # 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-0.0.41/src/wexample_filestate_python/operation/python_add_return_types_operation.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+from .abstract_python_file_operation import AbstractPythonFileOperation
+
+
+class PythonAddReturnTypesOperation(AbstractPythonFileOperation):
+    """Annotate return types 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.
+
+    Triggered by config: { "python": ["add_return_types"] }.
+    """
+
+    @classmethod
+    def get_option_name(cls) -> str:
+        from wexample_filestate_python.config_option.python_config_option import (
+            PythonConfigOption,
+        )
+
+        return PythonConfigOption.OPTION_NAME_ADD_RETURN_TYPES
+
+    @classmethod
+    def preview_source_change(cls, target: TargetFileOrDirectoryType) -> str | None:
+        """Add a return annotation to def lines where a simple literal type is inferable.
+
+        Logic is inlined here (previously in helpers.source.source_annotate_simple_returns).
+        """
+        import libcst as cst
+
+        src = cls._read_current_str_or_fail(target)
+
+        # 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
+
+    def describe_before(self) -> str:
+        return "Some Python functions are missing obvious return type annotations."
+
+    def describe_after(self) -> str:
+        return "Functions have been annotated with simple return types where obvious."
+
+    def description(self) -> str:
+        return "Add simple return type annotations (None/bool/str/int/float) when trivially inferable."

wexample_filestate_python-0.0.41/src/wexample_filestate_python/operation/python_format_operation.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+from .abstract_python_file_operation import AbstractPythonFileOperation
+
+
+class PythonFormatOperation(AbstractPythonFileOperation):
+    """Format Python files using Black.
+
+    Triggered by config: { "python": ["format"] }
+    """
+
+    # Use ClassVar to avoid Pydantic treating it as a model field/private attr
+    _line_length: ClassVar[int] = 88
+
+    @classmethod
+    def get_option_name(cls) -> str:
+        from wexample_filestate_python.config_option.python_config_option import (
+            PythonConfigOption,
+        )
+
+        return PythonConfigOption.OPTION_NAME_FORMAT
+
+    @classmethod
+    def preview_source_change(cls, target: TargetFileOrDirectoryType) -> str | None:
+        import black
+
+        src = cls._read_current_str_or_fail(target)
+        mode = black.Mode(line_length=cls._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
+
+    def describe_before(self) -> str:
+        return "The Python file is not formatted according to Black's rules."
+
+    def describe_after(self) -> str:
+        return "The Python file has been formatted with Black."
+
+    def description(self) -> str:
+        return "Format the Python file content using Black."

wexample_filestate_python-0.0.41/src/wexample_filestate_python/operation/python_fstringify_operation.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+from .abstract_python_file_operation import AbstractPythonFileOperation
+
+
+class PythonFStringifyOperation(AbstractPythonFileOperation):
+    """Convert string formatting to f-strings using flynt.
+
+    Triggered by: {"python": ["fstringify"]}
+    """
+
+    @classmethod
+    def get_option_name(cls) -> str:
+        from wexample_filestate_python.config_option.python_config_option import (
+            PythonConfigOption,
+        )
+
+        return PythonConfigOption.OPTION_NAME_FSTRINGIFY
+
+    @classmethod
+    def preview_source_change(cls, target: TargetFileOrDirectoryType) -> str | None:
+        from flynt.api import fstringify_code  # type: ignore
+        from flynt.state import State  # type: ignore
+
+        src = cls._read_current_str_or_fail(target)
+        state = State(aggressive=False, multiline=False, len_limit=120)
+        result = fstringify_code(src, state=state)
+
+        if result is None:
+            return src
+        return result.content
+
+    def describe_before(self) -> str:
+        return "The file uses legacy string formatting ('%'/format) that can be upgraded to f-strings."
+
+    def describe_after(self) -> str:
+        return "String formatting has been converted to modern f-strings."
+
+    def description(self) -> str:
+        return "Convert old-style string formatting to f-strings using flynt."

wexample_filestate_python-0.0.41/src/wexample_filestate_python/operation/python_modernize_typing_operation.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+from .abstract_python_file_operation import AbstractPythonFileOperation
+
+
+class PythonModernizeTypingOperation(AbstractPythonFileOperation):
+    """Modernize typing syntax (PEP 585/604) to Python 3.12 style.
+
+    Triggered by: {"python": ["modernize_typing"]}
+    """
+
+    @classmethod
+    def get_option_name(cls) -> str:
+        from wexample_filestate_python.config_option.python_config_option import (
+            PythonConfigOption,
+        )
+
+        return PythonConfigOption.OPTION_NAME_MODERNIZE_TYPING
+
+    @classmethod
+    def preview_source_change(cls, target: TargetFileOrDirectoryType) -> str | None:
+        from pyupgrade._main import Settings, _fix_plugins  # type: ignore
+
+        src = cls._read_current_str_or_fail(target)
+        settings = Settings(min_version=(3, 12))
+        updated = _fix_plugins(src, settings=settings)
+        # _fix_plugins returns a string; return as-is
+        return updated
+
+    def describe_before(self) -> str:
+        return (
+            "The file uses legacy typing syntax that can be modernized for Python 3.12."
+        )
+
+    def describe_after(self) -> str:
+        return "Typing syntax has been modernized to Python 3.12 style (PEP 585/604)."
+
+    def description(self) -> str:
+        return "Modernize typing syntax (PEP 585/604) using pyupgrade for Python 3.12."

wexample_filestate_python-0.0.41/src/wexample_filestate_python/operation/python_remove_unused_imports_operation.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+from .abstract_python_file_operation import AbstractPythonFileOperation
+
+
+class PythonRemoveUnusedOperation(AbstractPythonFileOperation):
+    """Remove unused Python imports using autoflake.
+
+    Triggered by config: { "python": ["remove_unused_imports"] }
+    """
+
+    @classmethod
+    def get_option_name(cls) -> str:
+        from wexample_filestate_python.config_option.python_config_option import (
+            PythonConfigOption,
+        )
+
+        return PythonConfigOption.OPTION_NAME_REMOVE_UNUSED
+
+    @classmethod
+    def preview_source_change(cls, target: TargetFileOrDirectoryType) -> str | None:
+        from autoflake import fix_code
+
+        src = cls._read_current_str_or_fail(target)
+        return fix_code(
+            src,
+            remove_all_unused_imports=True,
+            expand_star_imports=True,
+            remove_duplicate_keys=True,
+            remove_unused_variables=True,
+        )
+
+    def describe_before(self) -> str:
+        return "The Python file contains unused imports."
+
+    def describe_after(self) -> str:
+        return "Unused imports have been removed with autoflake."
+
+    def description(self) -> str:
+        return "Remove unused imports from the Python file using autoflake."

wexample_filestate_python-0.0.41/src/wexample_filestate_python/operation/python_sort_imports_operation.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+from .abstract_python_file_operation import AbstractPythonFileOperation
+
+
+class PythonSortImportsOperation(AbstractPythonFileOperation):
+    """Sort Python imports using isort.
+
+    Triggered by config: { "python": ["sort_imports"] }
+    """
+
+    @classmethod
+    def get_option_name(cls) -> str:
+        from wexample_filestate_python.config_option.python_config_option import (
+            PythonConfigOption,
+        )
+
+        return PythonConfigOption.OPTION_NAME_SORT_IMPORTS
+
+    @classmethod
+    def preview_source_change(cls, target: TargetFileOrDirectoryType) -> str | None:
+        from isort import code as isort_code
+        from isort.settings import Config
+
+        src = cls._read_current_str_or_fail(target)
+        config = Config(profile="black")
+        formatted = isort_code(src, config=config)
+        return formatted
+
+    def describe_before(self) -> str:
+        return "The Python file has unsorted or poorly grouped imports."
+
+    def describe_after(self) -> str:
+        return "The Python imports have been sorted and grouped by isort."
+
+    def description(self) -> str:
+        return "Sort and group Python imports using isort."

wexample_filestate_python-0.0.41/src/wexample_filestate_python/operation/python_unquote_annotations_operation.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+from .abstract_python_file_operation import AbstractPythonFileOperation
+
+
+class PythonUnquoteAnnotationsOperation(AbstractPythonFileOperation):
+    """Remove quotes around type annotations by turning stringized annotations back into expressions.
+
+    Triggered by config: { "python": ["unquote_annotations"] }
+    """
+
+    @classmethod
+    def get_option_name(cls) -> str:
+        from wexample_filestate_python.config_option.python_config_option import (
+            PythonConfigOption,
+        )
+
+        return PythonConfigOption.OPTION_NAME_UNQUOTE_ANNOTATIONS
+
+    @classmethod
+    def preview_source_change(cls, target: TargetFileOrDirectoryType) -> str | None:
+        import json
+
+        import libcst as cst
+
+        src = cls._read_current_str_or_fail(target)
+
+        class _Unquoter(cst.CSTTransformer):
+            @staticmethod
+            def _unquote_expr(s: cst.SimpleString) -> cst.BaseExpression | None:
+                try:
+                    code = json.loads(s.value)
+                except Exception:
+                    return None
+                try:
+                    return cst.parse_expression(code)
+                except Exception:
+                    return None
+
+            @staticmethod
+            def _process_annotation(
+                ann: cst.Annotation | None,
+            ) -> cst.Annotation | None:
+                if ann is None:
+                    return None
+                node = ann.annotation
+                if isinstance(node, cst.SimpleString):
+                    expr = _Unquoter._unquote_expr(node)
+                    if expr is not None:
+                        return cst.Annotation(annotation=expr)
+                return ann
+
+            def leave_Param(
+                self, original_node: cst.Param, updated_node: cst.Param
+            ) -> cst.Param:
+                return updated_node.with_changes(
+                    annotation=self._process_annotation(updated_node.annotation)
+                )
+
+            def leave_FunctionDef(
+                self, original_node: cst.FunctionDef, updated_node: cst.FunctionDef
+            ) -> cst.FunctionDef:
+                return updated_node.with_changes(
+                    returns=self._process_annotation(updated_node.returns)
+                )
+
+            def leave_AnnAssign(
+                self, original_node: cst.AnnAssign, updated_node: cst.AnnAssign
+            ) -> cst.AnnAssign:
+                return updated_node.with_changes(
+                    annotation=self._process_annotation(updated_node.annotation)
+                )
+
+            def leave_TypeAlias(
+                self, original_node: cst.TypeAlias, updated_node: cst.TypeAlias
+            ) -> cst.TypeAlias:
+                # Python 3.12 'type X = ...' syntax
+                ann = updated_node.annotation
+                if isinstance(ann, cst.SimpleString):
+                    expr = self._unquote_expr(ann)
+                    if expr is not None:
+                        return updated_node.with_changes(annotation=expr)
+                return updated_node
+
+        module = cst.parse_module(src)
+        new_mod = module.visit(_Unquoter())
+        return new_mod.code
+
+    def describe_before(self) -> str:
+        return "The Python file contains stringized (quoted) type annotations."
+
+    def describe_after(self) -> str:
+        return "Quoted type annotations have been converted back to expressions."
+
+    def description(self) -> str:
+        return "Unquote type annotations (arguments, returns, variables) using LibCST."

wexample_filestate_python-0.0.41/src/wexample_filestate_python/operations_provider/python_operations_provider.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_filestate.operations_provider.abstract_operations_provider import (
+    AbstractOperationsProvider,
+)
+
+if TYPE_CHECKING:
+    from wexample_filestate.operation.abstract_operation import AbstractOperation
+
+
+class PythonOperationsProvider(AbstractOperationsProvider):
+    @staticmethod
+    def get_operations() -> list[type[AbstractOperation]]:
+        from wexample_filestate_python.operation.python_add_future_annotations_operation import (
+            PythonAddFutureAnnotationsOperation,
+        )
+        from wexample_filestate_python.operation.python_add_return_types_operation import (
+            PythonAddReturnTypesOperation,
+        )
+        from wexample_filestate_python.operation.python_format_operation import (
+            PythonFormatOperation,
+        )
+        from wexample_filestate_python.operation.python_fstringify_operation import (
+            PythonFStringifyOperation,
+        )
+        from wexample_filestate_python.operation.python_modernize_typing_operation import (
+            PythonModernizeTypingOperation,
+        )
+        from wexample_filestate_python.operation.python_remove_unused_imports_operation import (
+            PythonRemoveUnusedOperation,
+        )
+        from wexample_filestate_python.operation.python_sort_imports_operation import (
+            PythonSortImportsOperation,
+        )
+        from wexample_filestate_python.operation.python_unquote_annotations_operation import (
+            PythonUnquoteAnnotationsOperation,
+        )
+
+        return [
+            PythonFormatOperation,
+            PythonSortImportsOperation,
+            PythonAddReturnTypesOperation,
+            PythonModernizeTypingOperation,
+            PythonFStringifyOperation,
+            PythonRemoveUnusedOperation,
+            PythonAddFutureAnnotationsOperation,
+            PythonUnquoteAnnotationsOperation,
+        ]

wexample_filestate_python-0.0.41/src/wexample_filestate_python/options_provider/python_options_provider.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_config.options_provider.abstract_options_provider import (
+    AbstractOptionsProvider,
+)
+from wexample_filestate_python.config_option.python_config_option import (
+    PythonConfigOption,
+)
+
+if TYPE_CHECKING:
+    from wexample_config.config_option.abstract_config_option import (
+        AbstractConfigOption,
+    )
+
+
+class PythonOptionsProvider(AbstractOptionsProvider):
+    @classmethod
+    def get_options(cls) -> list[type[AbstractConfigOption]]:
+        return [
+            PythonConfigOption,
+        ]