wexample-filestate-python 6.4.6__tar.gz → 6.7.0__tar.gz

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-filestate-python
-Version: 6.4.6
+Version: 6.7.0
 Summary: Helpers for Python.
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -20,7 +20,7 @@ Requires-Dist: packaging
 Requires-Dist: pyupgrade
 Requires-Dist: tomli
 Requires-Dist: wexample-api>=6.1.0
-Requires-Dist: wexample-filestate>=7.4.0
+Requires-Dist: wexample-filestate>=11.1.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -28,7 +28,7 @@ Description-Content-Type: text/markdown
 
 # filestate_python
 
-Version: 6.4.6
+Version: 6.7.0
 
 Helpers for Python.
 
@@ -119,7 +119,136 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 - pyupgrade: 
 - tomli: 
 - wexample-api: >=6.1.0
-- wexample-filestate: >=7.4.0
+- wexample-filestate: >=11.1.0
+
+## Versioning & Compatibility Policy
+
+Wexample packages follow **Semantic Versioning** (SemVer):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+Free to use in both personal and commercial projects.
+
+## Integration in the Suite
+
+This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+# About us
+
+[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
+
+This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.
+
+Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
+
+# filestate_python
+
+Version: 6.5.0
+
+Helpers for Python.
+
+## Table of Contents
+
+- [Tests](#tests)
+- [Suite Integration](#suite-integration)
+- [Dependencies](#dependencies)
+- [Versioning](#versioning)
+- [License](#license)
+- [Suite Integration](#suite-integration)
+- [Suite Signature](#suite-signature)
+- [Introduction](#introduction)
+- [Roadmap](#roadmap)
+- [Status Compatibility](#status-compatibility)
+- [Useful Links](#useful-links)
+- [Migration Notes](#migration-notes)
+
+## Tests
+
+This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
+
+### Installation
+
+First, install the required testing dependencies:
+```bash
+.venv/bin/python -m pip install pytest pytest-cov
+```
+
+### Basic Usage
+
+Run all tests with coverage:
+```bash
+.venv/bin/python -m pytest --cov --cov-report=html
+```
+
+### Common Commands
+```bash
+# Run tests with coverage for a specific module
+.venv/bin/python -m pytest --cov=your_module
+
+# Show which lines are not covered
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
+
+# Generate an HTML coverage report
+.venv/bin/python -m pytest --cov=your_module --cov-report=html
+
+# Combine terminal and HTML reports
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
+
+# Run specific test file with coverage
+.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
+```
+
+### Viewing HTML Reports
+
+After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
+
+### Coverage Threshold
+
+To enforce a minimum coverage percentage:
+```bash
+.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
+```
+
+This will cause the test suite to fail if coverage drops below 80%.
+
+## Integration in the Suite
+
+This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+## Dependencies
+
+- attrs: >=23.1.0
+- autoflake: 
+- black: 
+- cattrs: >=23.1.0
+- flynt: 
+- isort: 
+- libcst: 
+- packaging: 
+- pyupgrade: 
+- tomli: 
+- wexample-api: >=6.1.0
+- wexample-filestate: >=9.0.0
 
 ## Versioning & Compatibility Policy
 
@@ -342,3 +471,33 @@ See the [project roadmap](https://github.com/wexample/python-filestate_python/is
 When upgrading between major versions, refer to the migration guides in the documentation.
 
 Breaking changes are clearly documented with upgrade paths and examples.
+
+## Known Limitations & Roadmap
+
+Current limitations and planned features are tracked in the GitHub issues.
+
+See the [project roadmap](https://github.com/wexample/python-filestate_python/issues) for upcoming features and improvements.
+
+## Status & Compatibility
+
+**Maturity**: Production-ready
+
+**Python Support**: >=3.10
+
+**OS Support**: Linux, macOS, Windows
+
+**Status**: Actively maintained
+
+## Useful Links
+
+- **Homepage**: https://github.com/wexample/python-filestate-python
+- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
+- **Issue Tracker**: https://github.com/wexample/python-filestate-python/issues
+- **Discussions**: https://github.com/wexample/python-filestate-python/discussions
+- **PyPI**: [pypi.org/project/filestate_python](https://pypi.org/project/filestate_python/)
+
+## Migration Notes
+
+When upgrading between major versions, refer to the migration guides in the documentation.
+
+Breaking changes are clearly documented with upgrade paths and examples.

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/README.md

@@ -1,6 +1,6 @@
 # filestate_python
 
-Version: 6.4.6
+Version: 6.7.0
 
 Helpers for Python.
 
@@ -91,7 +91,136 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 - pyupgrade: 
 - tomli: 
 - wexample-api: >=6.1.0
-- wexample-filestate: >=7.4.0
+- wexample-filestate: >=11.1.0
+
+## Versioning & Compatibility Policy
+
+Wexample packages follow **Semantic Versioning** (SemVer):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+Free to use in both personal and commercial projects.
+
+## Integration in the Suite
+
+This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+# About us
+
+[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
+
+This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.
+
+Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
+
+# filestate_python
+
+Version: 6.5.0
+
+Helpers for Python.
+
+## Table of Contents
+
+- [Tests](#tests)
+- [Suite Integration](#suite-integration)
+- [Dependencies](#dependencies)
+- [Versioning](#versioning)
+- [License](#license)
+- [Suite Integration](#suite-integration)
+- [Suite Signature](#suite-signature)
+- [Introduction](#introduction)
+- [Roadmap](#roadmap)
+- [Status Compatibility](#status-compatibility)
+- [Useful Links](#useful-links)
+- [Migration Notes](#migration-notes)
+
+## Tests
+
+This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
+
+### Installation
+
+First, install the required testing dependencies:
+```bash
+.venv/bin/python -m pip install pytest pytest-cov
+```
+
+### Basic Usage
+
+Run all tests with coverage:
+```bash
+.venv/bin/python -m pytest --cov --cov-report=html
+```
+
+### Common Commands
+```bash
+# Run tests with coverage for a specific module
+.venv/bin/python -m pytest --cov=your_module
+
+# Show which lines are not covered
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
+
+# Generate an HTML coverage report
+.venv/bin/python -m pytest --cov=your_module --cov-report=html
+
+# Combine terminal and HTML reports
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
+
+# Run specific test file with coverage
+.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
+```
+
+### Viewing HTML Reports
+
+After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
+
+### Coverage Threshold
+
+To enforce a minimum coverage percentage:
+```bash
+.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
+```
+
+This will cause the test suite to fail if coverage drops below 80%.
+
+## Integration in the Suite
+
+This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+## Dependencies
+
+- attrs: >=23.1.0
+- autoflake: 
+- black: 
+- cattrs: >=23.1.0
+- flynt: 
+- isort: 
+- libcst: 
+- packaging: 
+- pyupgrade: 
+- tomli: 
+- wexample-api: >=6.1.0
+- wexample-filestate: >=9.0.0
 
 ## Versioning & Compatibility Policy
 
@@ -314,3 +443,33 @@ See the [project roadmap](https://github.com/wexample/python-filestate_python/is
 When upgrading between major versions, refer to the migration guides in the documentation.
 
 Breaking changes are clearly documented with upgrade paths and examples.
+
+## Known Limitations & Roadmap
+
+Current limitations and planned features are tracked in the GitHub issues.
+
+See the [project roadmap](https://github.com/wexample/python-filestate_python/issues) for upcoming features and improvements.
+
+## Status & Compatibility
+
+**Maturity**: Production-ready
+
+**Python Support**: >=3.10
+
+**OS Support**: Linux, macOS, Windows
+
+**Status**: Actively maintained
+
+## Useful Links
+
+- **Homepage**: https://github.com/wexample/python-filestate-python
+- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
+- **Issue Tracker**: https://github.com/wexample/python-filestate-python/issues
+- **Discussions**: https://github.com/wexample/python-filestate-python/discussions
+- **PyPI**: [pypi.org/project/filestate_python](https://pypi.org/project/filestate_python/)
+
+## Migration Notes
+
+When upgrading between major versions, refer to the migration guides in the documentation.
+
+Breaking changes are clearly documented with upgrade paths and examples.

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-filestate-python"
-version = "6.4.6"
+version = "6.7.0"
 description = "Helpers for Python."
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -29,7 +29,7 @@ dependencies = [
     "pyupgrade",
     "tomli",
     "wexample-api>=6.1.0",
-    "wexample-filestate>=7.4.0",
+    "wexample-filestate>=11.1.0",
 ]
 
 [project.readme]

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/add_return_types_option.py

@@ -22,7 +22,14 @@ class AddReturnTypesOption(AbstractPythonFileContentOption):
         statements in a function agree on one of these literal types."""
         import libcst as cst
 
-        src = target.get_local_file().read()
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
+
+        try:
+            src, module = get_python_source_and_module(target)
+        except Exception:
+            return target.get_local_file().read()
 
         # We implement type inference and rewriting using LibCST to ensure
         # robust, formatting-preserving edits. We extend inference to:
@@ -251,12 +258,6 @@ class AddReturnTypesOption(AbstractPythonFileContentOption):
                         )
                 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)

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/fix_attrs_option.py

@@ -24,14 +24,14 @@ class FixAttrsOption(AbstractPythonFileContentOption):
         - Ensure @attrs.define always uses kw_only=True
         - Ensure @attr.s always uses kw_only=True
         """
-        import libcst as cst
-
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_attrs_utils import (
             fix_attrs_kw_only,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         modified = fix_attrs_kw_only(module)
         return modified.code

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/fix_blank_lines_option.py

@@ -34,14 +34,14 @@ class FixBlankLinesOption(AbstractPythonFileContentOption):
 
         Note: Module-level spacing (between classes/functions/imports) is handled by Black.
         """
-        import libcst as cst
-
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_blank_lines_utils import (
             fix_function_blank_lines,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         modified = fix_function_blank_lines(module)
         return modified.code

wexample_filestate_python-6.7.0/src/wexample_filestate_python/option/python/format_option.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from wexample_filestate.option.mixin.with_batch_option_mixin import (
+    WithBatchOptionMixin,
+)
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class FormatOption(WithBatchOptionMixin, AbstractPythonFileContentOption):
+    _line_length: ClassVar[int] = 88
+
+    def get_description(self) -> str:
+        return "Format the Python file content using Black."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        cache = self._get_or_build_batch_cache(target)
+        path_key = str(target.get_path())
+        if path_key in cache:
+            return cache[path_key]
+        return target.read_text()
+
+    def _run_batch_on_paths(
+        self,
+        reference_target: TargetFileOrDirectoryType,
+        paths: list[Path],
+    ) -> None:
+        # Black is loaded lazily here. Thread-safety: dry_run()/apply() always
+        # call _prepare_options() before parallel inspection, which runs this
+        # method in the main thread first — so by the time worker threads run,
+        # the module is fully loaded and there is no concurrent first-import
+        # race on its lazy attribute table.
+        import black
+
+        mode = black.Mode(line_length=self._line_length)
+        for path in paths:
+            src = path.read_text()
+            try:
+                formatted = black.format_file_contents(src, fast=False, mode=mode)
+                if formatted != src:
+                    path.write_text(formatted)
+            except black.NothingChanged:
+                pass
+        return None

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/order_class_attributes_option.py

@@ -21,14 +21,14 @@ class OrderClassAttributesOption(AbstractPythonFileContentOption):
         Special include __slots__, __match_args__, and inner class Config. Operates on
         contiguous attribute blocks and preserves comments attached to each attribute.
         """
-        import libcst as cst
-
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_class_attributes_utils import (
             ensure_order_class_attributes_in_module,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         modified = ensure_order_class_attributes_in_module(module)
         return modified.code

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/order_class_docstring_option.py

@@ -23,14 +23,14 @@ class OrderClassDocstringOption(AbstractPythonFileContentOption):
         decorators and the class header). Normalizes to double quotes. Avoids
         whitespace-only diffs when already correct.
         """
-        import libcst as cst
-
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_class_docstring_utils import (
             ensure_all_classes_docstring_first,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         modified = ensure_all_classes_docstring_first(module)
         return modified.code

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/order_class_methods_option.py

@@ -24,14 +24,14 @@ class OrderClassMethodsOption(AbstractPythonFileContentOption):
         - Properties grouped by base name (getter/setter/deleter together), groups A–Z
         - Instance methods: public A–Z, then private/protected A–Z
         """
-        import libcst as cst
-
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_class_methods_utils import (
             ensure_order_class_methods_in_module,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         modified = ensure_order_class_methods_in_module(module)
         return modified.code

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/order_constants_option.py

@@ -22,14 +22,14 @@ class OrderConstantsOption(AbstractPythonFileContentOption):
         A block is a contiguous sequence of simple UPPER_CASE assignments (no blank line between).
         Non-flagged constants and other contexts are ignored.
         """
-        import libcst as cst
-
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_constants_utils import (
             reorder_flagged_constants_everywhere,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         modified = reorder_flagged_constants_everywhere(module, src)
         return modified.code

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/order_main_guard_option.py

@@ -21,16 +21,16 @@ class OrderMainGuardOption(AbstractPythonFileContentOption):
         Moves any top-level main-guard blocks to be the last non-empty statement in the
         module (before trailing blank lines), preserving content and spacing as much as possible.
         """
-        import libcst as cst
-
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_main_guard_utils import (
             find_main_guard_blocks,
             is_main_guard_at_end,
             move_main_guard_to_end,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         # No main guard present => nothing to do
         if not find_main_guard_blocks(module):

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/order_module_docstring_option.py

@@ -23,14 +23,16 @@ class OrderModuleDocstringOption(AbstractPythonFileContentOption):
         """
         import libcst as cst
 
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_docstring_utils import (
             find_module_docstring,
             is_module_docstring_at_top,
             move_docstring_to_top,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         # Check if there's a docstring and if it needs to be moved
         docstring_node, position = find_module_docstring(module)

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/order_module_functions_option.py

@@ -21,15 +21,15 @@ class OrderModuleFunctionsOption(AbstractPythonFileContentOption):
         - Keeps @overload groups attached to their implementation.
         - Preserves spacing/comments by keeping each group's first function's leading_lines.
         """
-        import libcst as cst
-
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_functions_utils import (
             module_functions_sorted_before_classes,
             reorder_module_functions,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         # Quick no-op detection: if there are no functions, or functions already sorted
         # and placed before classes, the transformation may be a noop.

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/order_module_metadata_option.py

@@ -23,16 +23,16 @@ class OrderModuleMetadataOption(AbstractPythonFileContentOption):
 
         Placement: after imports and `if TYPE_CHECKING:` blocks, before other module-level code.
         """
-        import libcst as cst
-
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_module_metadata_utils import (
             find_module_metadata_statements,
             group_and_sort_module_metadata,
             target_index_for_module_metadata,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         found = find_module_metadata_statements(module)
         if not found:

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/order_type_checking_block_option.py

@@ -22,16 +22,16 @@ class OrderTypeCheckingBlockOption(AbstractPythonFileContentOption):
         after the last regular import section (or after `from __future__ import ...`
         if no regular imports exist). Keeps spacing minimal and preserves content.
         """
-        import libcst as cst
-
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.python_type_checking_utils import (
             find_type_checking_blocks,
             move_type_checking_blocks_after_imports,
             target_index_for_type_checking,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         blocks = find_type_checking_blocks(module)
         if not blocks:

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/relocate_imports_option.py

@@ -35,6 +35,9 @@ class RelocateImportsOption(AbstractPythonFileContentOption):
 
         import libcst as cst
 
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
         from wexample_filestate_python.utils.relocate_imports.python_import_rewriter import (
             PythonImportRewriter,
         )
@@ -51,8 +54,7 @@ class RelocateImportsOption(AbstractPythonFileContentOption):
             PythonUsageCollector,
         )
 
-        src = target.get_local_file().read()
-        module = cst.parse_module(src)
+        src, module = get_python_source_and_module(target)
 
         # Index current imports using shared utility
         idx = PythonParserImportIndex()

wexample_filestate_python-6.7.0/src/wexample_filestate_python/option/python/remove_unused_option.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class RemoveUnusedOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Remove unused imports from the Python file using autoflake."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Remove unused Python imports using autoflake's in-process API.
+
+        Previously shelled out to `autoflake --stdout` per file, costing ~80ms
+        of subprocess + Python startup overhead each call (≈20s on a 268-file
+        project).
+        """
+        from autoflake import fix_code
+
+        src = target.get_local_file().read()
+        try:
+            return fix_code(
+                src,
+                remove_all_unused_imports=True,
+                remove_unused_variables=True,
+                expand_star_imports=True,
+                remove_duplicate_keys=True,
+            )
+        except Exception as e:
+            target.io.error(f"Autoflake error: {e}\n\n")
+            return src

{wexample_filestate_python-6.4.6 → wexample_filestate_python-6.7.0}/src/wexample_filestate_python/option/python/unquote_annotations_option.py

@@ -21,7 +21,11 @@ class UnquoteAnnotationsOption(AbstractPythonFileContentOption):
 
         import libcst as cst
 
-        src = target.get_local_file().read()
+        from wexample_filestate_python.utils.cst_cache import (
+            get_python_source_and_module,
+        )
+
+        src, module = get_python_source_and_module(target)
 
         class _Unquoter(cst.CSTTransformer):
             @staticmethod
@@ -80,6 +84,5 @@ class UnquoteAnnotationsOption(AbstractPythonFileContentOption):
                         return updated_node.with_changes(annotation=expr)
                 return updated_node
 
-        module = cst.parse_module(src)
         new_mod = module.visit(_Unquoter())
         return new_mod.code

wexample_filestate_python-6.7.0/src/wexample_filestate_python/utils/cst_cache.py

@@ -0,0 +1,37 @@
+"""Per-target libcst parse cache.
+
+Within a single rectification scan, a Python file's disk content does not
+change — yet historically each option parsed the libcst module independently,
+multiplying the parse cost by the number of content options (~15). This
+helper caches the `(src, module)` pair on the target item so all options on
+the same file share a single parse.
+
+The cache is naturally invalidated between rectification passes (a new
+workdir means new target instances).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import libcst as cst
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+_CACHE_ATTR = "_cst_cache"
+
+
+def get_python_source_and_module(
+    target: TargetFileOrDirectoryType,
+) -> tuple[str, cst.Module]:
+    cached = getattr(target, _CACHE_ATTR, None)
+    if cached is not None:
+        return cached
+
+    import libcst as cst
+
+    src = target.get_local_file().read()
+    module = cst.parse_module(src)
+    setattr(target, _CACHE_ATTR, (src, module))
+    return src, module

wexample_filestate_python-6.4.6/src/wexample_filestate_python/option/python/format_option.py

@@ -1,34 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, ClassVar
-
-from wexample_helpers.decorator.base_class import base_class
-
-from .abstract_python_file_content_option import AbstractPythonFileContentOption
-
-if TYPE_CHECKING:
-    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
-
-
-@base_class
-class FormatOption(AbstractPythonFileContentOption):
-    # Use ClassVar to avoid Pydantic treating it as a model field/private attr
-    _line_length: ClassVar[int] = 88
-
-    def get_description(self) -> str:
-        return "Format the Python file content using Black."
-
-    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
-        """Format Python files using Black."""
-        import black
-
-        src = target.get_local_file().read()
-        mode = black.Mode(line_length=self._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

wexample_filestate_python-6.4.6/src/wexample_filestate_python/option/python/remove_unused_option.py

@@ -1,45 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from wexample_helpers.decorator.base_class import base_class
-
-from .abstract_python_file_content_option import AbstractPythonFileContentOption
-
-if TYPE_CHECKING:
-    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
-
-
-@base_class
-class RemoveUnusedOption(AbstractPythonFileContentOption):
-    def get_description(self) -> str:
-        return "Remove unused imports from the Python file using autoflake."
-
-    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
-        """Remove unused Python imports using autoflake."""
-        from wexample_helpers.helpers.shell import shell_run
-        from wexample_helpers.helpers.system import system_get_venv_bin_path
-
-        result = shell_run(
-            cmd=[
-                f"{system_get_venv_bin_path()}/autoflake",
-                "--stdout",
-                "--remove-all-unused-imports",
-                "--remove-unused-variables",
-                "--expand-star-imports",
-                "--remove-duplicate-keys",
-                str(target.get_path()),
-            ],
-        )
-
-        if result.returncode != 0:
-            # Double line return is important to keep message visible event last line is erased by parent process.
-            target.io.error(f"Autoflake error: {result.stderr}\n\n")
-            return target.get_local_file().read()  # Return original content on error
-
-        modified_content = result.stdout
-
-        if not modified_content.strip():
-            return target.get_local_file().read()  # Return original content if empty
-
-        return modified_content