wexample-filestate-python 9.0.1__tar.gz → 9.0.3__tar.gz

wexample_filestate_python-9.0.3/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.1
+Name: wexample-filestate-python
+Version: 9.0.3
+Summary: Extends wexample-filestate with Python file options: format, sort imports, modernize typing, and reorder class members.
+Author-Email: weeger <contact@wexample.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+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: attrs>=23.1.0
+Requires-Dist: autoflake
+Requires-Dist: black
+Requires-Dist: cattrs>=23.1.0
+Requires-Dist: flynt
+Requires-Dist: isort
+Requires-Dist: libcst
+Requires-Dist: packaging
+Requires-Dist: tomli
+Requires-Dist: wexample-api>=6.8.0
+Requires-Dist: wexample-filestate>=17.1.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Description-Content-Type: text/markdown
+
+# filestate_python
+
+Version: 9.0.3
+
+`wexample-filestate-python` extends [wexample-filestate](https://github.com/wexample/python-filestate) with a `python` configuration option that applies up to 22 code-transformation sub-options to `.py` files — formatting with Black, import sorting with isort, unused-name removal with autoflake, f-string conversion with flynt, typing modernisation, and a range of structural ordering passes (class attributes, methods, docstrings, constants, iterables, and more) implemented with libcst. It is aimed at Python package authors who want source conventions declared once and enforced uniformly by the filestate engine, without maintaining separate linting scripts per project.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Tests](#tests)
+- [Architecture](#architecture)
+- [Integration in the Suite](#integration-in-the-suite)
+- [Dependencies](#dependencies)
+- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
+- [License](#license)
+- [About us](#about-us)
+- [Known Limitations & Roadmap](#known-limitations--roadmap)
+- [Status & Compatibility](#status--compatibility)
+- [Useful Links](#useful-links)
+- [Migration Notes](#migration-notes)
+
+## Installation
+
+```bash
+pip install wexample-filestate-python
+```
+
+Requires Python >=3.10.
+
+## Quickstart
+
+Install the package:
+
+```bash
+pip install wexample-filestate-python
+```
+
+This package adds a `python` option to [wexample-filestate](https://pypi.org/project/wexample-filestate/). That option drives Black, isort, autoflake, and the other tools declared in src/wexample_filestate_python/option/python_option.py against any `.py` files you describe in a config dict.
+
+Create a `FileStateManager` pointed at your project directory, pass `PythonOptionsProvider` so the `python` key is recognised, then call `apply()`:
+
+```python
+from wexample_filestate.utils.file_state_manager import FileStateManager
+from wexample_filestate_python.options_provider.python_options_provider import PythonOptionsProvider
+from wexample_prompt.common.io_manager import IoManager
+
+manager = FileStateManager.create_from_path(
+    path="/path/to/your/project",
+    config={
+        "children": [
+            {
+                "name": "my_module.py",
+                "python": ["format", "sort_imports", "remove_unused"],
+            }
+        ]
+    },
+    io=IoManager(),
+    options_providers=[PythonOptionsProvider],
+)
+manager.apply()
+```
+
+`apply()` inspects `my_module.py`, runs each requested rule in turn, and writes the result in place. If the file already satisfies every rule no write is performed.
+
+The `python` value accepts either a list of rule names (shown above) or a dict mapping names to `True`/`False`. Each name is the snake-case short form of a class in src/wexample_filestate_python/option/python_option.py: `format` → `FormatOption` (Black), `sort_imports` → `SortImportsOption` (isort), `remove_unused` → `RemoveUnusedOption` (autoflake), and so on. The complete list of available rules is `get_allowed_options()` in that same file.
+
+## 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%.
+
+## Architecture
+
+The package extends `wexample-filestate` with Python-specific file transformations. All source lives under `src/wexample_filestate_python/` and is organised into six named namespaces: `file/`, `option/`, `options_provider/`, `config_value/`, `utils/`, and `helper/`.
+
+### Registration
+
+src/wexample_filestate_python/options_provider/python_options_provider.py implements `AbstractOptionsProvider.get_options()` and returns `[PythonOption]`. The `wexample-filestate` engine calls `get_options()` on every registered provider at startup to discover the top-level options a plugin contributes.
+
+### Option tree
+
+src/wexample_filestate_python/option/python_option.py is an `AbstractNestedConfigOption` scoped to `Scope.CONTENT`. Its `get_allowed_options()` lists all 22 leaf options that a user can enable. `set_value()` normalises list input to dict form — `["format", "sort_imports"]` becomes `{"format": True, "sort_imports": True}` — before delegating to the parent. When the engine determines a file needs rectification, it calls `create_required_operation()`, which delegates to `_create_child_required_operation()` inherited from `AbstractNestedConfigOption`; that method iterates the enabled child options and collects the operations they declare.
+
+### Leaf options
+
+All content-transforming leaf options live under `option/python/` and extend src/wexample_filestate_python/option/python/abstract_python_file_content_option.py, itself an `AbstractFileContentOption` from `wexample-filestate`. The one method each option must implement is `_apply_content_change(target) -> str`, which receives the target file object and returns the transformed source text.
+
+The tools each option delegates to:
+
+- `FormatOption` — `black.format_file_contents()`; uses `WithBatchOptionMixin` to collect all target paths and pass them to Black in one call
+- `SortImportsOption` — `isort.code()` with the `"black"` profile; the `(code_fn, Config)` pair is constructed once via `@lru_cache(maxsize=1)`
+- `ModernizeTypingOption` — `ruff check --select=UP --fix` via subprocess; also uses `WithBatchOptionMixin`
+- `RemoveUnusedOption` — `autoflake.fix_code()` called in-process
+- `FstringifyOption` — `flynt.api.fstringify_code()`; wrapped by `WithStdoutWrappingMixin` to prevent flynt's stdout from corrupting progress indicators
+- `AddFutureAnnotationsOption` — uses `ast.parse()` to locate the docstring end, then inserts `from __future__ import annotations` at the correct line
+- `FixAttrsOption` — delegates to `python_attrs_utils.fix_attrs_kw_only()` through the CST cache
+- `RelocateImportsOption` — runs the five-class import relocation pipeline described below
+- All `Order*Option` classes — call the matching `utils/python_*_utils.py` function through the CST cache and return `modified.code`, or return the original `src` string unchanged when a tree identity check (`if modified is module`) confirms nothing moved
+
+`ClassNameMatchesFileNameOption` is the exception: it extends `OptionMixin` + `AbstractConfigOption` directly (not `AbstractFileContentOption`), declares `[Scope.NAME, Scope.CONTENT]`, and currently only reports mismatches rather than rewriting.
+
+src/wexample_filestate_python/config_option/mixin/with_stdout_wrapping_mixin.py provides `_execute_and_wrap_stdout(callback)`: it captures stdout and stderr during the call and re-emits them with a trailing double newline, preventing tool output from interfering with the parent process's progress display.
+
+### CST cache
+
+src/wexample_filestate_python/utils/cst_cache.py exposes `get_python_source_and_module(target) -> (str, cst.Module)`. On the first call for a given target it reads the file and calls `libcst.parse_module(src)`, then stores the pair as `target._cst_cache`. Every subsequent option on the same target hits the attribute directly, so the ~15 content options on a file share one parse. The cache is naturally invalidated between runs because each run produces new target instances.
+
+### Import relocation pipeline
+
+`RelocateImportsOption` coordinates five libcst classes in `utils/relocate_imports/`, applied in sequence on the same `cst.Module`:
+
+1. src/wexample_filestate_python/utils/relocate_imports/python_parser_import_index.py (`PythonParserImportIndex`, CSTVisitor) — builds `name_to_from: dict[str, (module, alias)]` for every non-`__future__` from-import in the file
+2. src/wexample_filestate_python/utils/relocate_imports/python_usage_collector.py (`PythonUsageCollector`, CSTVisitor) — classifies each imported name: **A** (used at runtime inside a function body), **B** (needed at class-definition time: base classes, class-body annotations), **C** (appears only in type annotations)
+3. src/wexample_filestate_python/utils/relocate_imports/python_runtime_symbol_collector.py (`PythonRuntimeSymbolCollector`, CSTVisitor) — conservative fallback; marks names appearing in any non-annotation expression at module level (e.g. `TerminalColor.RED` in a dict literal), so they are not mistakenly moved under `TYPE_CHECKING`
+4. src/wexample_filestate_python/utils/relocate_imports/python_import_rewriter.py (`PythonImportRewriter`, CSTTransformer) — removes module-level imports for A and C-only names; inserts `from typing import TYPE_CHECKING` and a `if TYPE_CHECKING:` block carrying the C-only imports; leaves B names at module level
+5. src/wexample_filestate_python/utils/relocate_imports/python_localize_runtime_imports.py (`PythonLocalizeRuntimeImports`, CSTTransformer) — injects `from <module> import Name` at the top of each function body that uses a category-A name, after any docstring
+
+The rewriter's output feeds directly into the localizer: `final_module = rewritten.visit(PythonLocalizeRuntimeImports(...))`.
+
+### Domain utils
+
+Each `python_*_utils.py` in `utils/` owns one transformation domain and exposes pure functions taking a `cst.Module` and returning a (possibly identical) `cst.Module`:
+
+- `python_class_methods_utils.py` — dunder grouping and method ordering within classes (dunders → classmethods → staticmethods → properties → instance methods, each bucket sorted A–Z with private after public)
+- `python_class_attributes_utils.py` — attribute ordering within classes
+- `python_blank_lines_utils.py` — removes leading blank lines after function/class signatures
+- `python_functions_utils.py` — collects module-level function groups, handling consecutive `@overload` sequences as a single unit
+- `python_attrs_utils.py` — ensures `@attrs.define` / `@attr.s` decorators carry `kw_only=True`
+- `python_iterable_utils.py` — sorts items inside flagged iterable literals
+- `python_constants_utils.py` — sorts flagged `UPPER_CASE` constant blocks at module level
+- `python_module_metadata_utils.py`, `python_class_docstring_utils.py`, `python_main_guard_utils.py`, `python_type_checking_utils.py`, `python_docstring_utils.py` — remaining structural ordering rules (metadata grouping, docstring placement, `if __name__ == "__main__":` position, `TYPE_CHECKING` block placement)
+
+### File types
+
+src/wexample_filestate_python/file/python_file.py sets `EXTENSION_ENV = "py"` so the inherited `_expected_file_name_extension()` enforces a `.py` extension on any declared file target.
+
+src/wexample_filestate_python/file/python_test_stub_file.py extends `PythonFile` and implements `build_default_content()`. When a test stub is absent, it reads the primary module through `get_python_source_and_module()`, walks the libcst tree for public top-level functions and public class methods (skipping `Abstract`-prefixed classes, `@abstract_class`-decorated classes, and any `_`-prefixed names), and emits a minimal pytest skeleton: one `test_<name>` per public callable, wrapped in a `TestFoo` class when the primary has classes.
+
+### Config value
+
+src/wexample_filestate_python/config_value/python_config_value.py (`PythonConfigValue`) is a `ConfigValue` with one `bool | None` field per option. It allows users to declare Python options in typed form rather than raw dict. Its `to_option_raw_value()` translates the struct back to the dict format that `PythonOption.set_value()` expects, using a lazily-built `option-name → field-name` map constructed on first call.
+
+### Helpers
+
+src/wexample_filestate_python/helper/package.py reads `pyproject.toml` (via `tomli`) or `setup.py` (via `ast.parse`) to extract a package's name and dependencies; `package_get_dependencies(root_dir)` walks a directory of packages and returns an inter-package dependency graph filtered to local packages only.
+
+src/wexample_filestate_python/helper/toml.py wraps `tomlkit` for creating and sorting arrays and tables while preserving TOML formatting: `toml_ensure_array_multiline`, `toml_sort_string_array`, `toml_ensure_table`, and related helpers.
+
+### Constants
+
+src/wexample_filestate_python/const/path.py — `PATH_DIR_SRC` and `PATH_DIR_TESTS` as `Path` constants.
+
+src/wexample_filestate_python/const/python_file.py — `PYTHON_FILE_EXTENSION = "py"` and `PYTHON_FILE_PYTEST_COVERAGE_JSON`.
+
+src/wexample_filestate_python/const/name_pattern.py — `NAME_PATTERN_PYTHON_NOT_PYCACHE`, a regex string that excludes `__pycache__` from directory matches.
+
+### PyPI gateway
+
+src/wexample_filestate_python/common/pipy_gateway.py wraps the PyPI JSON API via `AbstractGateway` from `wexample-api`. `package_release_exists(name, version) -> bool` hits `https://pypi.org/pypi/{name}/json` and checks whether the version key appears in `releases`.
+
+## 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: 
+- tomli: 
+- wexample-api: >=6.8.0
+- wexample-filestate: >=17.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.
+
+## 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.
+
+## 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/wexample-filestate-python](https://pypi.org/project/wexample-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-9.0.3/README.md

@@ -0,0 +1,282 @@
+# filestate_python
+
+Version: 9.0.3
+
+`wexample-filestate-python` extends [wexample-filestate](https://github.com/wexample/python-filestate) with a `python` configuration option that applies up to 22 code-transformation sub-options to `.py` files — formatting with Black, import sorting with isort, unused-name removal with autoflake, f-string conversion with flynt, typing modernisation, and a range of structural ordering passes (class attributes, methods, docstrings, constants, iterables, and more) implemented with libcst. It is aimed at Python package authors who want source conventions declared once and enforced uniformly by the filestate engine, without maintaining separate linting scripts per project.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Tests](#tests)
+- [Architecture](#architecture)
+- [Integration in the Suite](#integration-in-the-suite)
+- [Dependencies](#dependencies)
+- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
+- [License](#license)
+- [About us](#about-us)
+- [Known Limitations & Roadmap](#known-limitations--roadmap)
+- [Status & Compatibility](#status--compatibility)
+- [Useful Links](#useful-links)
+- [Migration Notes](#migration-notes)
+
+## Installation
+
+```bash
+pip install wexample-filestate-python
+```
+
+Requires Python >=3.10.
+
+## Quickstart
+
+Install the package:
+
+```bash
+pip install wexample-filestate-python
+```
+
+This package adds a `python` option to [wexample-filestate](https://pypi.org/project/wexample-filestate/). That option drives Black, isort, autoflake, and the other tools declared in src/wexample_filestate_python/option/python_option.py against any `.py` files you describe in a config dict.
+
+Create a `FileStateManager` pointed at your project directory, pass `PythonOptionsProvider` so the `python` key is recognised, then call `apply()`:
+
+```python
+from wexample_filestate.utils.file_state_manager import FileStateManager
+from wexample_filestate_python.options_provider.python_options_provider import PythonOptionsProvider
+from wexample_prompt.common.io_manager import IoManager
+
+manager = FileStateManager.create_from_path(
+    path="/path/to/your/project",
+    config={
+        "children": [
+            {
+                "name": "my_module.py",
+                "python": ["format", "sort_imports", "remove_unused"],
+            }
+        ]
+    },
+    io=IoManager(),
+    options_providers=[PythonOptionsProvider],
+)
+manager.apply()
+```
+
+`apply()` inspects `my_module.py`, runs each requested rule in turn, and writes the result in place. If the file already satisfies every rule no write is performed.
+
+The `python` value accepts either a list of rule names (shown above) or a dict mapping names to `True`/`False`. Each name is the snake-case short form of a class in src/wexample_filestate_python/option/python_option.py: `format` → `FormatOption` (Black), `sort_imports` → `SortImportsOption` (isort), `remove_unused` → `RemoveUnusedOption` (autoflake), and so on. The complete list of available rules is `get_allowed_options()` in that same file.
+
+## 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%.
+
+## Architecture
+
+The package extends `wexample-filestate` with Python-specific file transformations. All source lives under `src/wexample_filestate_python/` and is organised into six named namespaces: `file/`, `option/`, `options_provider/`, `config_value/`, `utils/`, and `helper/`.
+
+### Registration
+
+src/wexample_filestate_python/options_provider/python_options_provider.py implements `AbstractOptionsProvider.get_options()` and returns `[PythonOption]`. The `wexample-filestate` engine calls `get_options()` on every registered provider at startup to discover the top-level options a plugin contributes.
+
+### Option tree
+
+src/wexample_filestate_python/option/python_option.py is an `AbstractNestedConfigOption` scoped to `Scope.CONTENT`. Its `get_allowed_options()` lists all 22 leaf options that a user can enable. `set_value()` normalises list input to dict form — `["format", "sort_imports"]` becomes `{"format": True, "sort_imports": True}` — before delegating to the parent. When the engine determines a file needs rectification, it calls `create_required_operation()`, which delegates to `_create_child_required_operation()` inherited from `AbstractNestedConfigOption`; that method iterates the enabled child options and collects the operations they declare.
+
+### Leaf options
+
+All content-transforming leaf options live under `option/python/` and extend src/wexample_filestate_python/option/python/abstract_python_file_content_option.py, itself an `AbstractFileContentOption` from `wexample-filestate`. The one method each option must implement is `_apply_content_change(target) -> str`, which receives the target file object and returns the transformed source text.
+
+The tools each option delegates to:
+
+- `FormatOption` — `black.format_file_contents()`; uses `WithBatchOptionMixin` to collect all target paths and pass them to Black in one call
+- `SortImportsOption` — `isort.code()` with the `"black"` profile; the `(code_fn, Config)` pair is constructed once via `@lru_cache(maxsize=1)`
+- `ModernizeTypingOption` — `ruff check --select=UP --fix` via subprocess; also uses `WithBatchOptionMixin`
+- `RemoveUnusedOption` — `autoflake.fix_code()` called in-process
+- `FstringifyOption` — `flynt.api.fstringify_code()`; wrapped by `WithStdoutWrappingMixin` to prevent flynt's stdout from corrupting progress indicators
+- `AddFutureAnnotationsOption` — uses `ast.parse()` to locate the docstring end, then inserts `from __future__ import annotations` at the correct line
+- `FixAttrsOption` — delegates to `python_attrs_utils.fix_attrs_kw_only()` through the CST cache
+- `RelocateImportsOption` — runs the five-class import relocation pipeline described below
+- All `Order*Option` classes — call the matching `utils/python_*_utils.py` function through the CST cache and return `modified.code`, or return the original `src` string unchanged when a tree identity check (`if modified is module`) confirms nothing moved
+
+`ClassNameMatchesFileNameOption` is the exception: it extends `OptionMixin` + `AbstractConfigOption` directly (not `AbstractFileContentOption`), declares `[Scope.NAME, Scope.CONTENT]`, and currently only reports mismatches rather than rewriting.
+
+src/wexample_filestate_python/config_option/mixin/with_stdout_wrapping_mixin.py provides `_execute_and_wrap_stdout(callback)`: it captures stdout and stderr during the call and re-emits them with a trailing double newline, preventing tool output from interfering with the parent process's progress display.
+
+### CST cache
+
+src/wexample_filestate_python/utils/cst_cache.py exposes `get_python_source_and_module(target) -> (str, cst.Module)`. On the first call for a given target it reads the file and calls `libcst.parse_module(src)`, then stores the pair as `target._cst_cache`. Every subsequent option on the same target hits the attribute directly, so the ~15 content options on a file share one parse. The cache is naturally invalidated between runs because each run produces new target instances.
+
+### Import relocation pipeline
+
+`RelocateImportsOption` coordinates five libcst classes in `utils/relocate_imports/`, applied in sequence on the same `cst.Module`:
+
+1. src/wexample_filestate_python/utils/relocate_imports/python_parser_import_index.py (`PythonParserImportIndex`, CSTVisitor) — builds `name_to_from: dict[str, (module, alias)]` for every non-`__future__` from-import in the file
+2. src/wexample_filestate_python/utils/relocate_imports/python_usage_collector.py (`PythonUsageCollector`, CSTVisitor) — classifies each imported name: **A** (used at runtime inside a function body), **B** (needed at class-definition time: base classes, class-body annotations), **C** (appears only in type annotations)
+3. src/wexample_filestate_python/utils/relocate_imports/python_runtime_symbol_collector.py (`PythonRuntimeSymbolCollector`, CSTVisitor) — conservative fallback; marks names appearing in any non-annotation expression at module level (e.g. `TerminalColor.RED` in a dict literal), so they are not mistakenly moved under `TYPE_CHECKING`
+4. src/wexample_filestate_python/utils/relocate_imports/python_import_rewriter.py (`PythonImportRewriter`, CSTTransformer) — removes module-level imports for A and C-only names; inserts `from typing import TYPE_CHECKING` and a `if TYPE_CHECKING:` block carrying the C-only imports; leaves B names at module level
+5. src/wexample_filestate_python/utils/relocate_imports/python_localize_runtime_imports.py (`PythonLocalizeRuntimeImports`, CSTTransformer) — injects `from <module> import Name` at the top of each function body that uses a category-A name, after any docstring
+
+The rewriter's output feeds directly into the localizer: `final_module = rewritten.visit(PythonLocalizeRuntimeImports(...))`.
+
+### Domain utils
+
+Each `python_*_utils.py` in `utils/` owns one transformation domain and exposes pure functions taking a `cst.Module` and returning a (possibly identical) `cst.Module`:
+
+- `python_class_methods_utils.py` — dunder grouping and method ordering within classes (dunders → classmethods → staticmethods → properties → instance methods, each bucket sorted A–Z with private after public)
+- `python_class_attributes_utils.py` — attribute ordering within classes
+- `python_blank_lines_utils.py` — removes leading blank lines after function/class signatures
+- `python_functions_utils.py` — collects module-level function groups, handling consecutive `@overload` sequences as a single unit
+- `python_attrs_utils.py` — ensures `@attrs.define` / `@attr.s` decorators carry `kw_only=True`
+- `python_iterable_utils.py` — sorts items inside flagged iterable literals
+- `python_constants_utils.py` — sorts flagged `UPPER_CASE` constant blocks at module level
+- `python_module_metadata_utils.py`, `python_class_docstring_utils.py`, `python_main_guard_utils.py`, `python_type_checking_utils.py`, `python_docstring_utils.py` — remaining structural ordering rules (metadata grouping, docstring placement, `if __name__ == "__main__":` position, `TYPE_CHECKING` block placement)
+
+### File types
+
+src/wexample_filestate_python/file/python_file.py sets `EXTENSION_ENV = "py"` so the inherited `_expected_file_name_extension()` enforces a `.py` extension on any declared file target.
+
+src/wexample_filestate_python/file/python_test_stub_file.py extends `PythonFile` and implements `build_default_content()`. When a test stub is absent, it reads the primary module through `get_python_source_and_module()`, walks the libcst tree for public top-level functions and public class methods (skipping `Abstract`-prefixed classes, `@abstract_class`-decorated classes, and any `_`-prefixed names), and emits a minimal pytest skeleton: one `test_<name>` per public callable, wrapped in a `TestFoo` class when the primary has classes.
+
+### Config value
+
+src/wexample_filestate_python/config_value/python_config_value.py (`PythonConfigValue`) is a `ConfigValue` with one `bool | None` field per option. It allows users to declare Python options in typed form rather than raw dict. Its `to_option_raw_value()` translates the struct back to the dict format that `PythonOption.set_value()` expects, using a lazily-built `option-name → field-name` map constructed on first call.
+
+### Helpers
+
+src/wexample_filestate_python/helper/package.py reads `pyproject.toml` (via `tomli`) or `setup.py` (via `ast.parse`) to extract a package's name and dependencies; `package_get_dependencies(root_dir)` walks a directory of packages and returns an inter-package dependency graph filtered to local packages only.
+
+src/wexample_filestate_python/helper/toml.py wraps `tomlkit` for creating and sorting arrays and tables while preserving TOML formatting: `toml_ensure_array_multiline`, `toml_sort_string_array`, `toml_ensure_table`, and related helpers.
+
+### Constants
+
+src/wexample_filestate_python/const/path.py — `PATH_DIR_SRC` and `PATH_DIR_TESTS` as `Path` constants.
+
+src/wexample_filestate_python/const/python_file.py — `PYTHON_FILE_EXTENSION = "py"` and `PYTHON_FILE_PYTEST_COVERAGE_JSON`.
+
+src/wexample_filestate_python/const/name_pattern.py — `NAME_PATTERN_PYTHON_NOT_PYCACHE`, a regex string that excludes `__pycache__` from directory matches.
+
+### PyPI gateway
+
+src/wexample_filestate_python/common/pipy_gateway.py wraps the PyPI JSON API via `AbstractGateway` from `wexample-api`. `package_release_exists(name, version) -> bool` hits `https://pypi.org/pypi/{name}/json` and checks whether the version key appears in `releases`.
+
+## 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: 
+- tomli: 
+- wexample-api: >=6.8.0
+- wexample-filestate: >=17.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.
+
+## 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.
+
+## 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/wexample-filestate-python](https://pypi.org/project/wexample-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-9.0.1 → wexample_filestate_python-9.0.3}/pyproject.toml

@@ -6,8 +6,8 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-filestate-python"
-version = "9.0.1"
-description = "Helpers for Python."
+version = "9.0.3"
+description = "Extends wexample-filestate with Python file options: format, sort imports, modernize typing, and reorder class members."
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
 ]
@@ -28,7 +28,7 @@ dependencies = [
     "packaging",
     "tomli",
     "wexample-api>=6.8.0",
-    "wexample-filestate>=16.0.0",
+    "wexample-filestate>=17.1.0",
 ]
 
 [project.readme]