wexample-filestate-python 7.0.0__tar.gz → 8.1.0__tar.gz

{wexample_filestate_python-7.0.0 → wexample_filestate_python-8.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-filestate-python
-Version: 7.0.0
+Version: 8.1.0
 Summary: Helpers for Python.
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -17,10 +17,9 @@ Requires-Dist: flynt
 Requires-Dist: isort
 Requires-Dist: libcst
 Requires-Dist: packaging
-Requires-Dist: pyupgrade
 Requires-Dist: tomli
-Requires-Dist: wexample-api>=6.4.0
-Requires-Dist: wexample-filestate>=12.2.0
+Requires-Dist: wexample-api>=6.6.0
+Requires-Dist: wexample-filestate>=14.0.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -28,7 +27,7 @@ Description-Content-Type: text/markdown
 
 # filestate_python
 
-Version: 7.0.0
+Version: 8.1.0
 
 Helpers for Python.
 
@@ -116,10 +115,9 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 - isort: 
 - libcst: 
 - packaging: 
-- pyupgrade: 
 - tomli: 
-- wexample-api: >=6.4.0
-- wexample-filestate: >=12.2.0
+- wexample-api: >=6.6.0
+- wexample-filestate: >=14.0.0
 
 ## Versioning & Compatibility Policy
 

{wexample_filestate_python-7.0.0 → wexample_filestate_python-8.1.0}/README.md

@@ -1,6 +1,6 @@
 # filestate_python
 
-Version: 7.0.0
+Version: 8.1.0
 
 Helpers for Python.
 
@@ -88,10 +88,9 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 - isort: 
 - libcst: 
 - packaging: 
-- pyupgrade: 
 - tomli: 
-- wexample-api: >=6.4.0
-- wexample-filestate: >=12.2.0
+- wexample-api: >=6.6.0
+- wexample-filestate: >=14.0.0
 
 ## Versioning & Compatibility Policy
 

{wexample_filestate_python-7.0.0 → wexample_filestate_python-8.1.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-filestate-python"
-version = "7.0.0"
+version = "8.1.0"
 description = "Helpers for Python."
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -26,10 +26,9 @@ dependencies = [
     "isort",
     "libcst",
     "packaging",
-    "pyupgrade",
     "tomli",
-    "wexample-api>=6.4.0",
-    "wexample-filestate>=12.2.0",
+    "wexample-api>=6.6.0",
+    "wexample-filestate>=14.0.0",
 ]
 
 [project.readme]

{wexample_filestate_python-7.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/config_option/mixin/with_stdout_wrapping_mixin.py

@@ -1,5 +1,8 @@
 from __future__ import annotations
 
+import io
+import sys
+
 
 class WithStdoutWrappingMixin:
     @classmethod
@@ -15,9 +18,6 @@ class WithStdoutWrappingMixin:
         Returns:
             The return value of the callback function
         """
-        import io
-        import sys
-
         old_stdout = sys.stdout
         old_stderr = sys.stderr
         captured_stdout = io.StringIO()
@@ -34,9 +34,9 @@ class WithStdoutWrappingMixin:
             stdout_content = captured_stdout.getvalue()
             stderr_content = captured_stderr.getvalue()
 
-            if stdout_content.strip():
+            if stdout_content and stdout_content.strip():
                 sys.stdout.write(stdout_content.rstrip() + "\n\n")
-            if stderr_content.strip():
+            if stderr_content and stderr_content.strip():
                 sys.stderr.write(stderr_content.rstrip() + "\n\n")
 
         return result

wexample_filestate_python-8.1.0/src/wexample_filestate_python/config_value/python_config_value.py

@@ -0,0 +1,210 @@
+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
+
+# Cached mapping: option-name → self attribute name.
+# Built once on first call to to_option_raw_value() so the 22 deferred
+# imports and get_name() class-method calls are paid only once per process.
+_OPTION_NAME_TO_ATTR: dict[str, str] | None = None
+
+
+def _build_option_name_to_attr() -> dict[str, str]:
+    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(): "add_future_annotations",
+        AddReturnTypesConfigOption.get_name(): "add_return_types",
+        FixAttrsConfigOption.get_name(): "fix_attrs",
+        FixBlankLinesConfigOption.get_name(): "fix_blank_lines",
+        FormatConfigOption.get_name(): "format",
+        FstringifyConfigOption.get_name(): "fstringify",
+        ModernizeTypingConfigOption.get_name(): "modernize_typing",
+        OrderClassAttributesConfigOption.get_name(): "order_class_attributes",
+        OrderClassDocstringConfigOption.get_name(): "order_class_docstring",
+        OrderClassMethodsConfigOption.get_name(): "order_class_methods",
+        OrderConstantsConfigOption.get_name(): "order_constants",
+        OrderIterableItemsConfigOption.get_name(): "order_iterable_items",
+        OrderMainGuardConfigOption.get_name(): "order_main_guard",
+        OrderModuleDocstringConfigOption.get_name(): "order_module_docstring",
+        OrderModuleFunctionsConfigOption.get_name(): "order_module_functions",
+        OrderModuleMetadataConfigOption.get_name(): "order_module_metadata",
+        OrderSpacingConfigOption.get_name(): "order_spacing",
+        OrderTypeCheckingBlockConfigOption.get_name(): "order_type_checking_block",
+        RelocateImportsConfigOption.get_name(): "relocate_imports",
+        RemoveUnusedConfigOption.get_name(): "remove_unused",
+        SortImportsConfigOption.get_name(): "sort_imports",
+        UnquoteAnnotationsConfigOption.get_name(): "unquote_annotations",
+    }
+
+
+@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:
+        global _OPTION_NAME_TO_ATTR
+        if _OPTION_NAME_TO_ATTR is None:
+            _OPTION_NAME_TO_ATTR = _build_option_name_to_attr()
+        return {
+            name: getattr(self, attr)
+            for name, attr in _OPTION_NAME_TO_ATTR.items()
+        }

{wexample_filestate_python-7.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/file/python_file.py

@@ -9,4 +9,4 @@ class PythonFile(ItemTargetFile):
     EXTENSION_ENV: ClassVar[str] = "py"
 
     def _expected_file_name_extension(self) -> str | None:
-        return PythonFile.EXTENSION_ENV
+        return self.EXTENSION_ENV

wexample_filestate_python-8.1.0/src/wexample_filestate_python/file/python_test_stub_file.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from wexample_helpers.decorator.base_class import base_class
+
+from wexample_filestate_python.file.python_file import PythonFile
+
+
+def _is_skippable_class(class_name: str, class_node) -> bool:
+    import libcst as cst
+
+    if class_name.startswith("Abstract"):
+        return True
+    for decorator in class_node.decorators:
+        expr = decorator.decorator
+        if isinstance(expr, cst.Name) and expr.value in (
+            "abstract_class",
+            "abstractmethod",
+        ):
+            return True
+        if isinstance(expr, cst.Call) and isinstance(expr.func, cst.Name):
+            if expr.func.value == "abstract_class":
+                return True
+    return False
+
+
+def _public_function_names(module) -> list[str]:
+    import libcst as cst
+
+    return [
+        node.name.value
+        for node in module.body
+        if isinstance(node, cst.FunctionDef) and not node.name.value.startswith("_")
+    ]
+
+
+def _public_method_names(class_node) -> list[str]:
+    import libcst as cst
+
+    statements = getattr(class_node.body, "body", ())
+    return [
+        stmt.name.value
+        for stmt in statements
+        if isinstance(stmt, cst.FunctionDef) and not stmt.name.value.startswith("_")
+    ]
+
+
+def _render_stub(primary_module_name: str, module) -> str:
+    import libcst as cst
+
+    lines: list[str] = [
+        "from __future__ import annotations",
+        "",
+    ]
+
+    classes_emitted = False
+    for node in module.body:
+        if isinstance(node, cst.ClassDef):
+            class_name = node.name.value
+            if _is_skippable_class(class_name, node):
+                continue
+            methods = _public_method_names(node)
+            if not methods:
+                continue
+            lines.append(f"class Test{class_name}:")
+            for method_name in methods:
+                lines.extend([
+                    f"    def test_{method_name}(self) -> None:",
+                    "        pass",
+                    "",
+                ])
+            classes_emitted = True
+
+    func_names = _public_function_names(module)
+    if func_names:
+        if classes_emitted:
+            lines.append("")
+        for func_name in func_names:
+            lines.extend([
+                f"def test_{func_name}() -> None:",
+                "    pass",
+                "",
+            ])
+
+    if not classes_emitted and not func_names:
+        # No public surface — emit a placeholder so the file is valid pytest
+        # and the human knows the stub generator ran but found nothing.
+        lines.append(f"# Auto-generated stub for {primary_module_name}.py.")
+        lines.append(
+            "# No public functions/classes detected — add tests manually."
+        )
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+@base_class
+class PythonTestStubFile(PythonFile):
+    """A pytest stub generated as a sidecar of a Python module.
+
+    When used in a `sidecar_of` declaration as the `cls`, this class is
+    instantiated for each missing test file the framework needs to create.
+    `build_default_content()` is the hook `SidecarOfOption` wires into the
+    standard `default_content` flow — it reads the primary module via the
+    shared `cst_cache`, enumerates its public top-level functions and the
+    public methods of each top-level class, and emits a minimal pytest
+    skeleton (one `test_*` per public callable, wrapped in a
+    `TestPascalCase` class when the primary has classes).
+
+    Intentionally minimal:
+      - Generates `pass` bodies so the human fills them in.
+      - Skips private callables (`_*`) and dunders.
+      - Skips classes that look abstract (decorated `@abstract_class` or
+        prefixed `Abstract`) — they don't need direct tests.
+    """
+
+    def build_default_content(self) -> str:
+        primary = self.get_sidecar_primary()
+        primary_path = primary.get_path()
+
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
+
+        _, module = get_python_source_and_module(primary)
+        return _render_stub(
+            primary_module_name=primary_path.stem,
+            module=module,
+        )

{wexample_filestate_python-7.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/helpers/package.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import ast
+import re
 from typing import TYPE_CHECKING
 
 import tomli
@@ -19,32 +20,21 @@ def package_get_dependencies(root_dir: str | Path) -> dict[str, set[str]]:
     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 = {}
-    all_entries = list(packages_root.iterdir())
-
-    # First pass: collect all local packages
-    for package_dir in all_entries:
-        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 all_entries:
-        if not package_dir.is_dir():
-            continue
+    # Filter to directories once; avoids repeated is_dir() calls in two passes.
+    all_dirs = [e for e in packages_root.iterdir() if e.is_dir()]
 
+    # Single pass: collect all local package infos (name → raw deps).
+    pkg_infos: dict[str, set[str]] = {}
+    for package_dir in all_dirs:
         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}
+            pkg_infos[name] = deps
+
+    local_names: set[str] = set(pkg_infos)  # O(1) membership for filtering
 
-    return dependencies
+    # Keep only deps that resolve to a local package (set intersection).
+    return {name: deps & local_names for name, deps in pkg_infos.items()}
 
 
 def package_get_info(package_dir: Path) -> tuple[str, set[str]] | None:
@@ -72,10 +62,8 @@ def package_get_info(package_dir: Path) -> tuple[str, set[str]] | None:
 
 
 def package_normalize_name(val: str) -> str:
-    import re as _re
-
     # strip extras, versions, markers
-    base = _re.split(r"[\s<>=!~;\[]", val, maxsplit=1)[0]
+    base = re.split(r"[\s<>=!~;\[]", val, maxsplit=1)[0]
     return base.strip().lower()
 
 

{wexample_filestate_python-7.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/helpers/toml.py

@@ -96,11 +96,12 @@ def toml_sort_string_array(arr: Any) -> bool:
     if not items or not all(isinstance(i, String) for i in items):
         return False
 
-    sorted_items = sorted(items, key=lambda i: i.value.lower())
-
-    if items == sorted_items:
+    keys = [i.value.lower() for i in items]
+    sorted_keys = sorted(keys)
+    if keys == sorted_keys:
         return False
 
+    sorted_items = sorted(items, key=lambda i: i.value.lower())
     multiline_flag = arr._multiline
     # Clear and re-append to preserve tomlkit item identity
     while arr:

{wexample_filestate_python-7.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/option/python/add_future_annotations_option.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import ast
+import re
 from typing import TYPE_CHECKING
 
 from wexample_helpers.decorator.base_class import base_class
@@ -9,6 +11,10 @@ from .abstract_python_file_content_option import AbstractPythonFileContentOption
 if TYPE_CHECKING:
     from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
 
+# PEP 263 encoding cookie matcher. Compiled once at import time, reused
+# across every file the rectifier touches.
+_ENCODING_COOKIE_RE = re.compile(r"^#.*coding[:=]\s*([-_.a-zA-Z0-9]+)")
+
 
 @base_class
 class AddFutureAnnotationsOption(AbstractPythonFileContentOption):
@@ -23,9 +29,6 @@ class AddFutureAnnotationsOption(AbstractPythonFileContentOption):
         if "from __future__ import annotations" in src:
             return src
 
-        import ast
-        import re
-
         lines = src.splitlines(keepends=True)
 
         # Detect shebang and encoding cookie positions
@@ -33,9 +36,8 @@ class AddFutureAnnotationsOption(AbstractPythonFileContentOption):
         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]):
+            if _ENCODING_COOKIE_RE.match(lines[i]):
                 idx = i + 1
 
         # Parse to find module docstring span
@@ -45,11 +47,11 @@ class AddFutureAnnotationsOption(AbstractPythonFileContentOption):
             # If parsing fails, be conservative: insert after header block
             insert_at = idx
         else:
-            body = getattr(tree, "body", [])
+            body = tree.body
             if (
                 body
                 and isinstance(body[0], ast.Expr)
-                and isinstance(getattr(body[0], "value", None), ast.Constant)
+                and isinstance(body[0].value, ast.Constant)
                 and isinstance(body[0].value.value, str)
             ):
                 # Module docstring present; insert after its end_lineno
@@ -59,7 +61,7 @@ class AddFutureAnnotationsOption(AbstractPythonFileContentOption):
                 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))
+        insert_index = min(len(lines), insert_at)
 
         # Ensure there is a newline after the inserted import if needed
         future_line = "from __future__ import annotations\n"