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

wexample_filestate_python/common/pipy_gateway.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+from wexample_helpers_api.common.abstract_gateway import AbstractGateway
+
+
+@base_class
+class PipyGateway(AbstractGateway):
+    base_url: str | None = public_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/config_option/mixin/with_stdout_wrapping_mixin.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+
+class WithStdoutWrappingMixin:
+    @classmethod
+    def _execute_and_wrap_stdout(cls, callback):
+        """Execute a callback and wrap any stdout/stderr output with additional newlines.
+
+        This ensures that output from external tools doesn't interfere with progress indicators
+        by adding a newline after any captured output.
+
+        Args:
+            callback: Function to execute that may produce stdout/stderr output
+
+        Returns:
+            The return value of the callback function
+        """
+        import io
+        import sys
+
+        old_stdout = sys.stdout
+        old_stderr = sys.stderr
+        captured_stdout = io.StringIO()
+        captured_stderr = io.StringIO()
+        sys.stdout = captured_stdout
+        sys.stderr = captured_stderr
+
+        try:
+            result = callback()
+        finally:
+            sys.stdout = old_stdout
+            sys.stderr = old_stderr
+
+            stdout_content = captured_stdout.getvalue()
+            stderr_content = captured_stderr.getvalue()
+
+            if stdout_content.strip():
+                sys.stdout.write(stdout_content.rstrip())
+                sys.stdout.write("\n")
+                sys.stdout.write("\n")
+            if stderr_content.strip():
+                sys.stderr.write(stderr_content.rstrip())
+                sys.stderr.write("\n")
+                sys.stderr.write("\n")
+
+        return result

wexample_filestate_python/config_value/python_config_value.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wexample_config.config_value.config_value import ConfigValue
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+
+@base_class
+class PythonConfigValue(ConfigValue):
+    add_future_annotations: bool | None = public_field(
+        default=None,
+        description="Add `from __future__ import annotations`",
+    )
+    add_return_types: bool | None = public_field(
+        default=None,
+        description="Add return type annotations",
+    )
+    fix_attrs: bool | None = public_field(
+        default=None,
+        description="Fix attrs usage (ensure kw_only=True, etc.)",
+    )
+    fix_blank_lines: bool | None = public_field(
+        default=None,
+        description="Fix blank lines in Python files",
+    )
+    format: bool | None = public_field(
+        default=None,
+        description="Format Python code",
+    )
+    fstringify: bool | None = public_field(
+        default=None,
+        description="Convert string formatting to f-strings",
+    )
+    modernize_typing: bool | None = public_field(
+        default=None,
+        description="Modernize typing annotations",
+    )
+    order_class_attributes: bool | None = public_field(
+        default=None,
+        description="Sort class attributes: special first, then public A–Z, then private/protected A–Z",
+    )
+    order_class_docstring: bool | None = public_field(
+        default=None,
+        description="Ensure class docstring is first statement after header/decorators",
+    )
+    order_class_methods: bool | None = public_field(
+        default=None,
+        description="Order class methods (dunders sequence, class/staticmethods, properties, instances)",
+    )
+    order_constants: bool | None = public_field(
+        default=None,
+        description="Sort flagged UPPER_CASE constant blocks at module level",
+    )
+    order_iterable_items: bool | None = public_field(
+        default=None,
+        description="Sort items inside flagged iterable literals (lists/dicts)",
+    )
+    order_main_guard: bool | None = public_field(
+        default=None,
+        description="Ensure if __name__ == '__main__' block is at the very end",
+    )
+    order_module_docstring: bool | None = public_field(
+        default=None,
+        description="Order module docstring to be at the top of the file",
+    )
+    order_module_functions: bool | None = public_field(
+        default=None,
+        description="Order module-level functions (public A–Z, then private)",
+    )
+    order_module_metadata: bool | None = public_field(
+        default=None,
+        description="Group and sort module metadata at module level",
+    )
+    order_spacing: bool | None = public_field(
+        default=None,
+        description="Normalize blank lines between program structures (spacing rules)",
+    )
+    order_type_checking_block: bool | None = public_field(
+        default=None,
+        description="Move TYPE_CHECKING blocks to after regular imports",
+    )
+    raw: Any = public_field(
+        default=None, description="Disabled raw value for this config."
+    )
+    relocate_imports: bool | None = public_field(
+        default=None,
+        description="Relocate imports by usage (runtime-in-method, class property types, type-only)",
+    )
+    remove_unused: bool | None = public_field(
+        default=None,
+        description="Remove unused imports",
+    )
+    sort_imports: bool | None = public_field(
+        default=None,
+        description="Sort imports",
+    )
+    unquote_annotations: bool | None = public_field(
+        default=None,
+        description="Unquote annotations (remove string annotations)",
+    )
+
+    def to_option_raw_value(self) -> Any:
+        from wexample_filestate_python.config_option.add_future_annotations_config_option import (
+            AddFutureAnnotationsConfigOption,
+        )
+        from wexample_filestate_python.config_option.add_return_types_config_option import (
+            AddReturnTypesConfigOption,
+        )
+        from wexample_filestate_python.config_option.fix_attrs_config_option import (
+            FixAttrsConfigOption,
+        )
+        from wexample_filestate_python.config_option.fix_blank_lines_config_option import (
+            FixBlankLinesConfigOption,
+        )
+        from wexample_filestate_python.config_option.format_config_option import (
+            FormatConfigOption,
+        )
+        from wexample_filestate_python.config_option.fstringify_config_option import (
+            FstringifyConfigOption,
+        )
+        from wexample_filestate_python.config_option.modernize_typing_config_option import (
+            ModernizeTypingConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_class_attributes_config_option import (
+            OrderClassAttributesConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_class_docstring_config_option import (
+            OrderClassDocstringConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_class_methods_config_option import (
+            OrderClassMethodsConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_constants_config_option import (
+            OrderConstantsConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_iterable_items_config_option import (
+            OrderIterableItemsConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_main_guard_config_option import (
+            OrderMainGuardConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_module_docstring_config_option import (
+            OrderModuleDocstringConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_module_functions_config_option import (
+            OrderModuleFunctionsConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_module_metadata_config_option import (
+            OrderModuleMetadataConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_spacing_config_option import (
+            OrderSpacingConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_type_checking_block_config_option import (
+            OrderTypeCheckingBlockConfigOption,
+        )
+        from wexample_filestate_python.config_option.relocate_imports_config_option import (
+            RelocateImportsConfigOption,
+        )
+        from wexample_filestate_python.config_option.remove_unused_config_option import (
+            RemoveUnusedConfigOption,
+        )
+        from wexample_filestate_python.config_option.sort_imports_config_option import (
+            SortImportsConfigOption,
+        )
+        from wexample_filestate_python.config_option.unquote_annotations_config_option import (
+            UnquoteAnnotationsConfigOption,
+        )
+
+        return {
+            AddFutureAnnotationsConfigOption.get_name(): self.add_future_annotations,
+            AddReturnTypesConfigOption.get_name(): self.add_return_types,
+            FixAttrsConfigOption.get_name(): self.fix_attrs,
+            FixBlankLinesConfigOption.get_name(): self.fix_blank_lines,
+            FormatConfigOption.get_name(): self.format,
+            FstringifyConfigOption.get_name(): self.fstringify,
+            ModernizeTypingConfigOption.get_name(): self.modernize_typing,
+            OrderClassAttributesConfigOption.get_name(): self.order_class_attributes,
+            OrderClassDocstringConfigOption.get_name(): self.order_class_docstring,
+            OrderClassMethodsConfigOption.get_name(): self.order_class_methods,
+            OrderConstantsConfigOption.get_name(): self.order_constants,
+            OrderIterableItemsConfigOption.get_name(): self.order_iterable_items,
+            OrderMainGuardConfigOption.get_name(): self.order_main_guard,
+            OrderModuleDocstringConfigOption.get_name(): self.order_module_docstring,
+            OrderModuleFunctionsConfigOption.get_name(): self.order_module_functions,
+            OrderModuleMetadataConfigOption.get_name(): self.order_module_metadata,
+            OrderSpacingConfigOption.get_name(): self.order_spacing,
+            OrderTypeCheckingBlockConfigOption.get_name(): self.order_type_checking_block,
+            RelocateImportsConfigOption.get_name(): self.relocate_imports,
+            RemoveUnusedConfigOption.get_name(): self.remove_unused,
+            SortImportsConfigOption.get_name(): self.sort_imports,
+            UnquoteAnnotationsConfigOption.get_name(): self.unquote_annotations,
+        }

wexample_filestate_python/const/name_pattern.py

@@ -0,0 +1,4 @@
+from __future__ import annotations
+
+# filestate: python-constant-sort
+NAME_PATTERN_PYTHON_NOT_PYCACHE = "^(?!__pycache__$).+$"

wexample_filestate_python/const/python_file.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+PYTHON_FILE_PYTEST_COVERAGE_JSON: Path = Path("coverage.json")

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/helpers/package.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING
+
+import tomli
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def package_get_dependencies(root_dir: str | Path) -> dict[str, set[str]]:
+    """
+    Get dependencies between packages in a directory.
+    """
+    from pathlib import Path
+
+    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_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_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()
+
+
+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 {}

wexample_filestate_python/helpers/toml.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tomlkit.items import Array
+
+
+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.
+    """
+    from tomlkit import array
+
+    arr = tbl.get(key) if isinstance(tbl, dict) else None
+    if arr is None:
+        arr = array()
+        tbl[key] = arr
+        return arr, True
+    return arr, False
+
+
+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).
+    """
+    from tomlkit.items import Array
+
+    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_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.
+    """
+    from tomlkit import table
+
+    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 = table()
+            current[key] = tbl
+            changed = True
+        current = tbl
+    return current, changed
+
+
+def toml_get_string_value(item: Any) -> str:
+    """Return the string content of a tomlkit String or generic item as str."""
+    from tomlkit.items import String
+
+    if isinstance(item, String):
+        return item.value
+    return str(item)
+
+
+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.
+    """
+    from tomlkit import array
+
+    arr = array(values)
+    arr.multiline(True)
+    tbl[key] = arr
+    return arr
+
+
+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.
+    """
+    from tomlkit.items import Array, String
+
+    # 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

wexample_filestate_python/option/abstract_python_file_content_option.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from wexample_config.config_option.abstract_config_option import AbstractConfigOption
+from wexample_filestate.option.mixin.option_mixin import OptionMixin
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class AbstractPythonFileContentOption(OptionMixin, AbstractConfigOption):
+    @staticmethod
+    def get_raw_value_allowed_type() -> Any:
+        return bool
+
+    def create_required_operation(
+        self, target: TargetFileOrDirectoryType
+    ) -> AbstractOperation | None:
+        from wexample_filestate.operation.file_write_operation import FileWriteOperation
+
+        """Create FileWriteOperation if add_future_annotations is enabled and needed."""
+        # Get current content
+        current_content = target.get_local_file().read()
+
+        # Apply add_future_annotations transformation
+        new_content = self._apply_content_change(target=target)
+
+        # If content changed, create FileWriteOperation
+        if new_content != current_content:
+            return FileWriteOperation(
+                option=self,
+                target=target,
+                content=new_content,
+                description=self.get_description(),
+            )
+
+        return None
+
+    @abstract_method
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> None:
+        pass