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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-filestate-python
-Version: 8.0.0
+Version: 8.1.0
 Summary: Helpers for Python.
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -18,8 +18,8 @@ Requires-Dist: isort
 Requires-Dist: libcst
 Requires-Dist: packaging
 Requires-Dist: tomli
-Requires-Dist: wexample-api>=6.5.0
-Requires-Dist: wexample-filestate>=13.0.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"
@@ -27,7 +27,7 @@ Description-Content-Type: text/markdown
 
 # filestate_python
 
-Version: 8.0.0
+Version: 8.1.0
 
 Helpers for Python.
 
@@ -116,8 +116,8 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 - libcst: 
 - packaging: 
 - tomli: 
-- wexample-api: >=6.5.0
-- wexample-filestate: >=13.0.0
+- wexample-api: >=6.6.0
+- wexample-filestate: >=14.0.0
 
 ## Versioning & Compatibility Policy
 

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

@@ -1,6 +1,6 @@
 # filestate_python
 
-Version: 8.0.0
+Version: 8.1.0
 
 Helpers for Python.
 
@@ -89,8 +89,8 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 - libcst: 
 - packaging: 
 - tomli: 
-- wexample-api: >=6.5.0
-- wexample-filestate: >=13.0.0
+- wexample-api: >=6.6.0
+- wexample-filestate: >=14.0.0
 
 ## Versioning & Compatibility Policy
 

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

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-filestate-python"
-version = "8.0.0"
+version = "8.1.0"
 description = "Helpers for Python."
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -27,8 +27,8 @@ dependencies = [
     "libcst",
     "packaging",
     "tomli",
-    "wexample-api>=6.5.0",
-    "wexample-filestate>=13.0.0",
+    "wexample-api>=6.6.0",
+    "wexample-filestate>=14.0.0",
 ]
 
 [project.readme]

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-8.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/option/python/sort_imports_option.py

@@ -12,11 +12,16 @@ if TYPE_CHECKING:
 
 
 @lru_cache(maxsize=1)
-def _isort_black_config() -> Config:
-    """Return a cached isort Config for the 'black' profile."""
+def _isort_setup() -> tuple:
+    """Return cached (code_fn, Config) for isort with the 'black' profile.
+
+    Both objects are imported and constructed once; subsequent calls hit
+    the LRU cache, eliminating per-file import overhead for isort.code.
+    """
+    from isort import code as _code
     from isort.settings import Config
 
-    return Config(profile="black")
+    return _code, Config(profile="black")
 
 
 @base_class
@@ -26,7 +31,6 @@ class SortImportsOption(AbstractPythonFileContentOption):
 
     def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
         """Sort Python imports using isort."""
-        from isort import code
-
+        _code, _config = _isort_setup()
         src = target.get_local_file().read()
-        return code(src, config=_isort_black_config())
+        return _code(src, config=_config)

{wexample_filestate_python-8.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/option/python_option.py

@@ -14,6 +14,12 @@ from wexample_helpers.decorator.base_class import base_class
 if TYPE_CHECKING:
     from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
 
+# Module-level caches (safe per the @base_class note below; only instance-level
+# annotations become attrs fields, not plain module variables).
+_SCOPES: list[Scope] = [Scope.CONTENT]
+_RAW_VALUE_ALLOWED_TYPE: Any = None
+_ALLOWED_OPTIONS: list[type[AbstractConfigOption]] | None = None
+
 
 @base_class
 class PythonOption(OptionMixin, AbstractNestedConfigOption):
@@ -23,15 +29,18 @@ class PythonOption(OptionMixin, AbstractNestedConfigOption):
     # module-level constants or `functools.cache` on methods if needed.
     @classmethod
     def get_scopes(cls) -> list[Scope]:
-        return [Scope.CONTENT]
+        return _SCOPES
 
     @staticmethod
     def get_raw_value_allowed_type() -> Any:
-        from wexample_filestate_python.config_value.python_config_value import (
-            PythonConfigValue,
-        )
+        global _RAW_VALUE_ALLOWED_TYPE
+        if _RAW_VALUE_ALLOWED_TYPE is None:
+            from wexample_filestate_python.config_value.python_config_value import (
+                PythonConfigValue,
+            )
 
-        return Union[list[str], dict, PythonConfigValue]
+            _RAW_VALUE_ALLOWED_TYPE = Union[list[str], dict, PythonConfigValue]
+        return _RAW_VALUE_ALLOWED_TYPE
 
     def create_required_operation(
         self, target: TargetFileOrDirectoryType, scopes: set[Scope]
@@ -39,6 +48,10 @@ class PythonOption(OptionMixin, AbstractNestedConfigOption):
         return self._create_child_required_operation(target=target, scopes=scopes)
 
     def get_allowed_options(self) -> list[type[AbstractConfigOption]]:
+        global _ALLOWED_OPTIONS
+        if _ALLOWED_OPTIONS is not None:
+            return _ALLOWED_OPTIONS
+
         # Import all the config options for each Python operation
         from wexample_filestate_python.option.python.add_future_annotations_option import (
             AddFutureAnnotationsOption,
@@ -105,7 +118,7 @@ class PythonOption(OptionMixin, AbstractNestedConfigOption):
             UnquoteAnnotationsOption,
         )
 
-        return [
+        _ALLOWED_OPTIONS = [
             # filestate: python-iterable-sort
             AddFutureAnnotationsOption,
             AddReturnTypesOption,
@@ -130,10 +143,11 @@ class PythonOption(OptionMixin, AbstractNestedConfigOption):
             SortImportsOption,
             UnquoteAnnotationsOption,
         ]
+        return _ALLOWED_OPTIONS
 
     def set_value(self, raw_value: Any) -> None:
         # Convert list form to dict form for consistency
         if isinstance(raw_value, list):
-            raw_value = {option_name: True for option_name in raw_value}
+            raw_value = dict.fromkeys(raw_value, True)
 
         super().set_value(raw_value=raw_value)

{wexample_filestate_python-8.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/options_provider/python_options_provider.py

@@ -13,15 +13,14 @@ if TYPE_CHECKING:
 
 
 class PythonOptionsProvider(AbstractOptionsProvider):
-    # Do NOT cache the returned list in a `cls._options_cache` class attribute.
-    # The cache is inherited via MRO, so a write from the base shadows what
-    # subclasses should return. Roadmap the optim instead.
     @classmethod
     def get_options(cls) -> list[type[AbstractConfigOption]]:
-        from wexample_filestate_python.option.python_option import (
-            PythonOption,
-        )
+        # Use `cls.__dict__` (not `hasattr`) so each class in the hierarchy
+        # maintains its own cache without the MRO inheritance side-effect.
+        if "_options_cache" not in cls.__dict__:
+            from wexample_filestate_python.option.python_option import (
+                PythonOption,
+            )
 
-        return [
-            PythonOption,
-        ]
+            cls._options_cache: list[type[AbstractConfigOption]] = [PythonOption]
+        return cls._options_cache

{wexample_filestate_python-8.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/utils/python_attrs_utils.py

@@ -33,11 +33,7 @@ def _is_attrs_decorator(decorator: cst.Decorator) -> bool:
         base_decorator.value, cst.Name
     ):
         module_name = base_decorator.value.value
-        attr_name = (
-            base_decorator.attr.value
-            if isinstance(base_decorator.attr, cst.Name)
-            else None
-        )
+        attr_name = base_decorator.attr.value
         return (module_name == "attrs" and attr_name in ("define", "frozen")) or (
             module_name == "attr" and attr_name == "s"
         )

{wexample_filestate_python-8.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/utils/python_blank_lines_utils.py

@@ -190,6 +190,8 @@ def _is_class_property(node: cst.CSTNode) -> bool:
 
 def _is_dataclass(class_node: cst.ClassDef) -> bool:
     """Check if a class has @dataclass decorator."""
+    if not class_node.decorators:
+        return False
     for decorator in class_node.decorators:
         dec = decorator.decorator
         if isinstance(dec, cst.Name) and dec.value == "dataclass":
@@ -214,8 +216,7 @@ def _is_lowercase_property(node: cst.CSTNode) -> bool:
     if _is_class_property(node):
         assign = node.body[0]
         target = assign.targets[0].target
-        if isinstance(target, cst.Name):
-            return target.value.islower()
+        return target.value.islower()  # _is_class_property already ensures cst.Name
     return False
 
 
@@ -264,8 +265,7 @@ def _is_uppercase_property(node: cst.CSTNode) -> bool:
     if _is_class_property(node):
         assign = node.body[0]
         target = assign.targets[0].target
-        if isinstance(target, cst.Name):
-            return target.value.isupper()
+        return target.value.isupper()  # _is_class_property already ensures cst.Name
     return False
 
 

{wexample_filestate_python-8.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/utils/python_class_methods_utils.py

@@ -92,7 +92,7 @@ def reorder_class_methods(classdef: cst.ClassDef) -> cst.ClassDef:
     for m in dunders:
         (unknown if m["order"][0] == 999 else known).append(m)
     dunder_ordered = [m["node"] for m in sorted(known, key=lambda m: m["order"])]
-    dunder_ordered += [m["node"] for m in sorted(unknown, key=lambda m: _sort_key_alpha(m["name"]))]
+    dunder_ordered += [m["node"] for m in sorted(unknown, key=_KEY_BY_NAME)]
 
     # Sort classmethods/staticmethods and instances: public first then private
     classmethods_ordered = _sort_by_visibility(classmethods)
@@ -188,6 +188,11 @@ def _is_dunder(name: str) -> bool:
 def _is_private(name: str) -> bool:
     return name.startswith("_") and not (name.startswith("__") and name.endswith("__"))
 
+# Hoisted sort-key; avoids creating a new lambda/closure object on every
+# call to _sort_by_visibility and reorder_class_methods.
+def _KEY_BY_NAME(m: dict) -> tuple:
+    return _sort_key_alpha(m["name"])
+
 
 def _prop_group_to_nodes(g: dict[str, cst.FunctionDef | None]) -> list[cst.FunctionDef]:
     return [g[k] for k in _PROP_KINDS if g[k] is not None]  # type: ignore
@@ -199,11 +204,12 @@ def _sort_by_visibility(items: list[dict]) -> list[cst.FunctionDef]:
     priv: list[dict] = []
     for i in items:
         (priv if _is_private(i["name"]) else pub).append(i)
-    pub_sorted = [i["node"] for i in sorted(pub, key=lambda x: _sort_key_alpha(x["name"]))]
-    priv_sorted = [i["node"] for i in sorted(priv, key=lambda x: _sort_key_alpha(x["name"]))]
+    pub_sorted = [i["node"] for i in sorted(pub, key=_KEY_BY_NAME)]
+    priv_sorted = [i["node"] for i in sorted(priv, key=_KEY_BY_NAME)]
     return pub_sorted + priv_sorted
 
 
 def _sort_key_alpha(name: str) -> tuple:
-    # Case-insensitive, underscore after letters
-    return (name.lstrip("_").lower(), name.startswith("_"))
+    # Case-insensitive, underscore after letters.
+    # name[0] == "_" avoids method-dispatch overhead; safe for non-empty identifiers.
+    return (name.lstrip("_").lower(), name[0] == "_")

{wexample_filestate_python-8.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/utils/python_functions_utils.py

@@ -152,15 +152,9 @@ def reorder_module_functions(module: cst.Module) -> cst.Module:
     # Build function nodes preserving each group's comments/spacing on first element
     rebuilt_functions: list[cst.CSTNode] = []
     for g in sorted_groups:
-        # Preserve leading_lines of the original first node in the group
-        original_first_leading = g.nodes[0].leading_lines
-        for k, fn in enumerate(g.nodes):
-            if k == 0:
-                rebuilt_functions.append(
-                    fn.with_changes(leading_lines=original_first_leading)
-                )
-            else:
-                rebuilt_functions.append(fn.with_changes(leading_lines=[]))
+        # First node keeps its original leading_lines (no-op with_changes avoided)
+        rebuilt_functions.append(g.nodes[0])
+        rebuilt_functions.extend(fn.with_changes(leading_lines=[]) for fn in g.nodes[1:])
 
     # Insert functions as a contiguous block
     new_body[insert_at:insert_at] = rebuilt_functions

{wexample_filestate_python-8.0.0 → wexample_filestate_python-8.1.0}/src/wexample_filestate_python/utils/python_iterable_utils.py

@@ -35,9 +35,10 @@ def reorder_flagged_iterables(src: str) -> str:
         groups = _split_into_groups(block)
         # Compute keys once; reuse for both no-op check and sort order
         keys = [_group_key(g) for g in groups]
-        sorted_keys = sorted(keys)
 
-        if sorted_keys == keys:
+        # O(n) pairwise check instead of O(n log n) sorted(); short-circuits on first
+        # out-of-order pair so the already-sorted case is also fast.
+        if len(keys) < 2 or all(keys[i] <= keys[i + 1] for i in range(len(keys) - 1)):
             continue
 
         order = sorted(range(len(groups)), key=lambda i: keys[i])
@@ -110,9 +111,9 @@ def _split_into_groups(block_lines: list[str]) -> list[list[str]]:
         if ln.lstrip().startswith("#"):
             pending_comments.append(ln)
             continue
-        # item line
-        group = pending_comments + [ln]
-        groups.append(group)
+        # item line: append in-place to avoid pending_comments + [ln] allocation
+        pending_comments.append(ln)
+        groups.append(pending_comments)
         pending_comments = []
     # Any trailing comments without item are ignored for sorting and left in place
     # (shouldn't occur in expected usage). If present, attach to last group to preserve.

wexample_filestate_python-8.1.0/tests/unit/helpers/test_package.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+def test_package_get_dependencies() -> None:
+    pass
+
+def test_package_get_info() -> None:
+    pass
+
+def test_package_normalize_name() -> None:
+    pass
+
+def test_package_parse_setup() -> None:
+    pass
+
+def test_package_parse_toml() -> None:
+    pass

wexample_filestate_python-8.1.0/tests/unit/helpers/test_toml.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+def test_toml_ensure_array() -> None:
+    pass
+
+def test_toml_ensure_array_multiline() -> None:
+    pass
+
+def test_toml_ensure_table() -> None:
+    pass
+
+def test_toml_get_string_value() -> None:
+    pass
+
+def test_toml_set_array_multiline() -> None:
+    pass
+
+def test_toml_sort_string_array() -> None:
+    pass