filestate_python

Version: 9.1.0

wexample-filestate-python extends wexample-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
• Quickstart
• Tests
• Architecture
• Integration in the Suite
• Dependencies
• Versioning & Compatibility Policy
• License
• About us
• Known Limitations & Roadmap
• Status & Compatibility
• Useful Links
• Migration Notes

Installation

pip install wexample-filestate-python

Requires Python >=3.10.

Quickstart

Install the package:

pip install wexample-filestate-python

This package adds a python option to 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():

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:

.venv/bin/python -m pip install pytest pytest-cov

Basic Usage

Run all tests with coverage:

.venv/bin/python -m pytest --cov --cov-report=html

Common Commands

# 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:

.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 for the complete package ecosystem.

Dependencies

• attrs: >=23.1.0
• autoflake:
• black:
• cattrs: >=23.1.0
• flynt:
• isort:
• libcst:
• packaging:
• ruff:
• tomli:
• wexample-api: >=6.8.0
• wexample-filestate: >=17.3.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 file for details.

Free to use in both personal and commercial projects.

About us

Wexample 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 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
• 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

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.