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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-filestate-python
-Version: 0.0.40
+Version: 0.0.43
 Summary: Helpers for Python.
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -9,17 +9,10 @@ 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: attrs>=23.1.0
+Requires-Dist: cattrs>=23.1.0
+Requires-Dist: wexample-filestate==0.0.53
+Requires-Dist: wexample-helpers-api==0.0.34
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Description-Content-Type: text/markdown
@@ -28,7 +21,7 @@ Description-Content-Type: text/markdown
 
 Helpers for Python.
 
-Version: 0.0.40
+Version: 0.0.42
 
 ## Requirements
 
@@ -36,17 +29,10 @@ Version: 0.0.40
 
 ## Dependencies
 
-- autoflake
-- black
-- flynt
-- isort
-- networkx
-- packaging
-- pydantic>=2,<3
-- python-dotenv
-- pyupgrade
-- tomlkit
-- wexample-filestate-git==0.0.38
+- attrs>=23.1.0
+- cattrs>=23.1.0
+- wexample-filestate==0.0.52
+- wexample-helpers-api==0.0.33
 
 ## Installation
 

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

@@ -2,7 +2,7 @@
 
 Helpers for Python.
 
-Version: 0.0.40
+Version: 0.0.42
 
 ## Requirements
 
@@ -10,17 +10,10 @@ Version: 0.0.40
 
 ## Dependencies
 
-- autoflake
-- black
-- flynt
-- isort
-- networkx
-- packaging
-- pydantic>=2,<3
-- python-dotenv
-- pyupgrade
-- tomlkit
-- wexample-filestate-git==0.0.38
+- attrs>=23.1.0
+- cattrs>=23.1.0
+- wexample-filestate==0.0.52
+- wexample-helpers-api==0.0.33
 
 ## Installation
 

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

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-filestate-python"
-version = "0.0.40"
+version = "0.0.43"
 description = "Helpers for Python."
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -18,17 +18,10 @@ 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",
+    "attrs>=23.1.0",
+    "cattrs>=23.1.0",
+    "wexample-filestate==0.0.53",
+    "wexample-helpers-api==0.0.34",
 ]
 
 [project.readme]
@@ -50,9 +43,6 @@ dev = [
 distribution = true
 
 [tool.pdm.build]
-includes = [
-    "src/wexample_filestate_python/py.typed",
-]
 package-dir = "src"
 packages = [
     { include = "wexample_filestate_python", from = "src" },

wexample_filestate_python-0.0.43/src/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_api.common.abstract_gateway import AbstractGateway
+from wexample_helpers.decorator.base_class import base_class
+
+
+@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-0.0.43/src/wexample_filestate_python/config_option/python_config_option.py

@@ -0,0 +1,49 @@
+from typing import Any, ClassVar
+
+from wexample_config.config_option.abstract_config_option import AbstractConfigOption
+
+
+class PythonConfigOption(AbstractConfigOption):
+    # filestate: python-constant-sort
+    # New preferred option name to add `from __future__ import annotations`
+    OPTION_NAME_ADD_FUTURE_ANNOTATIONS: ClassVar[str] = "add_future_annotations"
+    OPTION_NAME_ADD_RETURN_TYPES: ClassVar[str] = "add_return_types"
+    # Fix attrs usage (ensure kw_only=True, etc.)
+    OPTION_NAME_FIX_ATTRS: ClassVar[str] = "fix_attrs"
+    # Fix blank lines in Python files (after signatures, docstrings, etc.)
+    OPTION_NAME_FIX_BLANK_LINES: ClassVar[str] = "fix_blank_lines"
+    OPTION_NAME_FORMAT: ClassVar[str] = "format"
+    OPTION_NAME_FSTRINGIFY: ClassVar[str] = "fstringify"
+    OPTION_NAME_MODERNIZE_TYPING: ClassVar[str] = "modernize_typing"
+    # Sort class attributes: special first, then public A–Z, then private/protected A–Z
+    OPTION_NAME_ORDER_CLASS_ATTRIBUTES: ClassVar[str] = "order_class_attributes"
+    # Ensure class docstring is first statement after header/decorators
+    OPTION_NAME_ORDER_CLASS_DOCSTRING: ClassVar[str] = "order_class_docstring"
+    # Order class methods (dunders sequence, class/staticmethods, properties, instances)
+    OPTION_NAME_ORDER_CLASS_METHODS: ClassVar[str] = "order_class_methods"
+    # Sort flagged UPPER_CASE constant blocks at module level
+    OPTION_NAME_ORDER_CONSTANTS: ClassVar[str] = "order_constants"
+    # Sort items inside flagged iterable literals (lists/dicts)
+    OPTION_NAME_ORDER_ITERABLE_ITEMS: ClassVar[str] = "order_iterable_items"
+    # Ensure if __name__ == "__main__" block is at the very end
+    OPTION_NAME_ORDER_MAIN_GUARD: ClassVar[str] = "order_main_guard"
+    # Order module docstring to be at the top of the file
+    OPTION_NAME_ORDER_MODULE_DOCSTRING: ClassVar[str] = "order_module_docstring"
+    # Order module-level functions (public A–Z, then private)
+    OPTION_NAME_ORDER_MODULE_FUNCTIONS: ClassVar[str] = "order_module_functions"
+    # Group and sort module metadata at module level
+    OPTION_NAME_ORDER_MODULE_METADATA: ClassVar[str] = "order_module_metadata"
+    # Normalize blank lines between program structures (spacing rules)
+    OPTION_NAME_ORDER_SPACING: ClassVar[str] = "order_spacing"
+    # Move TYPE_CHECKING blocks to after regular imports
+    OPTION_NAME_ORDER_TYPE_CHECKING_BLOCK: ClassVar[str] = "order_type_checking_block"
+    # Relocate imports by usage (runtime-in-method, class property types, type-only)
+    OPTION_NAME_RELOCATE_IMPORTS: ClassVar[str] = "relocate_imports"
+    OPTION_NAME_REMOVE_UNUSED: ClassVar[str] = "remove_unused"
+    OPTION_NAME_SORT_IMPORTS: ClassVar[str] = "sort_imports"
+    # 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.43/src/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-0.0.43/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.43/src/wexample_filestate_python/helpers/package.py

@@ -0,0 +1,141 @@
+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_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()
+
+
+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-0.0.43/src/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-0.0.43/src/wexample_filestate_python/operation/abstract_python_file_operation.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_filestate.operation.abstract_existing_file_operation import (
+    AbstractExistingFileOperation,
+)
+
+if TYPE_CHECKING:
+    from wexample_config.config_option.abstract_config_option import (
+        AbstractConfigOption,
+    )
+    from wexample_filestate.enum.scopes import Scope
+
+
+class AbstractPythonFileOperation(AbstractExistingFileOperation):
+    @classmethod
+    def get_option_name(cls) -> str:
+        raise NotImplementedError
+
+    @classmethod
+    def get_scope(cls) -> Scope:
+        from wexample_filestate.enum.scopes import Scope
+
+        return Scope.CONTENT
+
+    @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():
+                print(stdout_content.rstrip())
+                print()
+            if stderr_content.strip():
+                print(stderr_content.rstrip(), file=sys.stderr)
+                print(file=sys.stderr)
+
+        return result
+
+    def applicable_for_option(self, option: AbstractConfigOption) -> bool:
+        """Generic applicability for Python file transforms controlled by a single option name."""
+        from wexample_filestate_python.config_option.python_config_option import (
+            PythonConfigOption,
+        )
+
+        # 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.43/src/wexample_filestate_python/operation/python_add_future_annotations_operation.py

@@ -0,0 +1,105 @@
+from typing import TYPE_CHECKING
+
+from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+from .abstract_python_file_operation import AbstractPythonFileOperation
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+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
+
+    @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)
+
+    def describe_after(self) -> str:
+        return "`from __future__ import annotations` has been added in the correct position."
+
+    def describe_before(self) -> str:
+        return "The file may be missing `from __future__ import annotations` at the module top."
+
+    def description(self) -> str:
+        return "Add `from __future__ import annotations` at the proper location (after shebang/encoding and module docstring)."