wexample-filestate-python 9.1.3__tar.gz → 9.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. wexample_filestate_python-9.2.0/PKG-INFO +121 -0
  2. wexample_filestate_python-9.2.0/README.md +93 -0
  3. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/pyproject.toml +2 -2
  4. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/file/__pycache__ → wexample_filestate_python-9.2.0/tests/helper}/__init__.py +0 -0
  5. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/helper/__pycache__ → wexample_filestate_python-9.2.0/tests/unit}/__init__.py +0 -0
  6. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/helper/python → wexample_filestate_python-9.2.0/tests/unit/helper}/__init__.py +0 -0
  7. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/option → wexample_filestate_python-9.2.0/tests/unit/utils}/__init__.py +0 -0
  8. wexample_filestate_python-9.1.3/PKG-INFO +0 -310
  9. wexample_filestate_python-9.1.3/README.md +0 -282
  10. wexample_filestate_python-9.1.3/src/wexample_filestate_python/option/python/__init__.py +0 -0
  11. wexample_filestate_python-9.1.3/src/wexample_filestate_python/options_provider/__init__.py +0 -0
  12. wexample_filestate_python-9.1.3/src/wexample_filestate_python/options_provider/__pycache__/__init__.py +0 -0
  13. wexample_filestate_python-9.1.3/src/wexample_filestate_python/utils/__init__.py +0 -0
  14. wexample_filestate_python-9.1.3/src/wexample_filestate_python/utils/__pycache__/__init__.py +0 -0
  15. wexample_filestate_python-9.1.3/src/wexample_filestate_python/utils/relocate_imports/__pycache__/__init__.py +0 -0
  16. wexample_filestate_python-9.1.3/tests/helper/__init__.py +0 -0
  17. wexample_filestate_python-9.1.3/tests/tests/__init__.py +0 -0
  18. wexample_filestate_python-9.1.3/tests/unit/__init__.py +0 -0
  19. wexample_filestate_python-9.1.3/tests/unit/helper/__init__.py +0 -0
  20. wexample_filestate_python-9.1.3/tests/unit/utils/__init__.py +0 -0
  21. wexample_filestate_python-9.1.3/tests/wexample_tests/__init__.py +0 -0
  22. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/__init__.py +0 -0
  23. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/__pycache__ → wexample_filestate_python-9.2.0/src/wexample_filestate_python/common}/__init__.py +0 -0
  24. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/common/pipy_gateway.py +0 -0
  25. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/common → wexample_filestate_python-9.2.0/src/wexample_filestate_python/config_option}/__init__.py +0 -0
  26. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/common/__pycache__ → wexample_filestate_python-9.2.0/src/wexample_filestate_python/config_option/mixin}/__init__.py +0 -0
  27. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/config_option/mixin/with_stdout_wrapping_mixin.py +0 -0
  28. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/config_option → wexample_filestate_python-9.2.0/src/wexample_filestate_python/config_value}/__init__.py +0 -0
  29. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/config_value/python_config_value.py +0 -0
  30. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/config_option/__pycache__ → wexample_filestate_python-9.2.0/src/wexample_filestate_python/const}/__init__.py +0 -0
  31. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/const/name_pattern.py +0 -0
  32. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/const/path.py +0 -0
  33. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/const/python_file.py +0 -0
  34. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/config_option/mixin → wexample_filestate_python-9.2.0/src/wexample_filestate_python/event}/__init__.py +0 -0
  35. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/config_option/mixin/__pycache__ → wexample_filestate_python-9.2.0/src/wexample_filestate_python/event/src}/__init__.py +0 -0
  36. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/config_value → wexample_filestate_python-9.2.0/src/wexample_filestate_python/event/src/wexample_event}/__init__.py +0 -0
  37. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/config_value/__pycache__ → wexample_filestate_python-9.2.0/src/wexample_filestate_python/file}/__init__.py +0 -0
  38. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/file/python_file.py +0 -0
  39. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/file/python_test_stub_file.py +0 -0
  40. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/const → wexample_filestate_python-9.2.0/src/wexample_filestate_python/helper}/__init__.py +0 -0
  41. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/helper/package.py +0 -0
  42. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/const/__pycache__ → wexample_filestate_python-9.2.0/src/wexample_filestate_python/helper/python}/__init__.py +0 -0
  43. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/helper/toml.py +0 -0
  44. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/event → wexample_filestate_python-9.2.0/src/wexample_filestate_python/option}/__init__.py +0 -0
  45. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/event/src → wexample_filestate_python-9.2.0/src/wexample_filestate_python/option/python}/__init__.py +0 -0
  46. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/abstract_python_file_content_option.py +0 -0
  47. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/add_future_annotations_option.py +0 -0
  48. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/add_return_types_option.py +0 -0
  49. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/class_name_matches_file_name_option.py +0 -0
  50. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/fix_attrs_option.py +0 -0
  51. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/fix_blank_lines_option.py +0 -0
  52. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/format_option.py +0 -0
  53. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/fstringify_option.py +0 -0
  54. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/modernize_typing_option.py +0 -0
  55. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/order_class_attributes_option.py +0 -0
  56. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/order_class_docstring_option.py +0 -0
  57. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/order_class_methods_option.py +0 -0
  58. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/order_constants_option.py +0 -0
  59. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/order_iterable_items_option.py +0 -0
  60. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/order_main_guard_option.py +0 -0
  61. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/order_module_docstring_option.py +0 -0
  62. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/order_module_functions_option.py +0 -0
  63. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/order_module_metadata_option.py +0 -0
  64. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/order_type_checking_block_option.py +0 -0
  65. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/relocate_imports_option.py +0 -0
  66. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/remove_unused_option.py +0 -0
  67. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/sort_imports_option.py +0 -0
  68. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python/unquote_annotations_option.py +0 -0
  69. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/option/python_option.py +0 -0
  70. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/event/src/wexample_event → wexample_filestate_python-9.2.0/src/wexample_filestate_python/options_provider}/__init__.py +0 -0
  71. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/options_provider/python_options_provider.py +0 -0
  72. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/py.typed +0 -0
  73. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/file → wexample_filestate_python-9.2.0/src/wexample_filestate_python/utils}/__init__.py +0 -0
  74. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/cst_cache.py +0 -0
  75. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_attrs_utils.py +0 -0
  76. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_blank_lines_utils.py +0 -0
  77. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_class_attributes_utils.py +0 -0
  78. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_class_docstring_utils.py +0 -0
  79. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_class_methods_utils.py +0 -0
  80. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_constants_utils.py +0 -0
  81. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_docstring_utils.py +0 -0
  82. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_functions_utils.py +0 -0
  83. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_iterable_utils.py +0 -0
  84. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_main_guard_utils.py +0 -0
  85. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_module_metadata_utils.py +0 -0
  86. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/python_type_checking_utils.py +0 -0
  87. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/relocate_imports/__init__.py +0 -0
  88. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/relocate_imports/python_import_rewriter.py +0 -0
  89. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/relocate_imports/python_localize_runtime_imports.py +0 -0
  90. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/relocate_imports/python_parser_import_index.py +0 -0
  91. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/relocate_imports/python_runtime_symbol_collector.py +0 -0
  92. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/src/wexample_filestate_python/utils/relocate_imports/python_usage_collector.py +0 -0
  93. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/tests/.gitkeep +0 -0
  94. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/tests/helper/test_package.py +0 -0
  95. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/tests/helper/test_toml.py +0 -0
  96. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/helper → wexample_filestate_python-9.2.0/tests/tests}/__init__.py +0 -0
  97. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/tests/unit/helper/test_package.py +0 -0
  98. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/tests/unit/helper/test_toml.py +0 -0
  99. {wexample_filestate_python-9.1.3 → wexample_filestate_python-9.2.0}/tests/unit/utils/test_python_iterable_utils.py +0 -0
  100. {wexample_filestate_python-9.1.3/src/wexample_filestate_python/option/__pycache__ → wexample_filestate_python-9.2.0/tests/wexample_tests}/__init__.py +0 -0
@@ -0,0 +1,121 @@
1
+ Metadata-Version: 2.1
2
+ Name: wexample-filestate-python
3
+ Version: 9.2.0
4
+ Summary: Extends wexample-filestate with Python file options: format, sort imports, modernize typing, and reorder class members.
5
+ Author-Email: weeger <contact@wexample.com>
6
+ License: MIT
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: License :: OSI Approved :: MIT License
9
+ Classifier: Operating System :: OS Independent
10
+ Project-URL: homepage, https://github.com/wexample/python-filestate-python
11
+ Requires-Python: >=3.10
12
+ Requires-Dist: attrs>=23.1.0
13
+ Requires-Dist: autoflake
14
+ Requires-Dist: black
15
+ Requires-Dist: cattrs>=23.1.0
16
+ Requires-Dist: flynt
17
+ Requires-Dist: isort
18
+ Requires-Dist: libcst
19
+ Requires-Dist: packaging
20
+ Requires-Dist: ruff
21
+ Requires-Dist: tomli
22
+ Requires-Dist: wexample-api>=6.8.0
23
+ Requires-Dist: wexample-filestate>=17.6.0
24
+ Provides-Extra: dev
25
+ Requires-Dist: pytest; extra == "dev"
26
+ Requires-Dist: pytest-cov; extra == "dev"
27
+ Description-Content-Type: text/markdown
28
+
29
+ # filestate_python
30
+
31
+ Version: 9.2.0
32
+
33
+ Extends wexample-filestate with Python file options: format, sort imports, modernize typing, and reorder class members.
34
+
35
+ ## Table of Contents
36
+
37
+ - [Install](#install)
38
+ - [Tests](#tests)
39
+ - [Roadmap](#roadmap)
40
+ - [Status Compatibility](#status-compatibility)
41
+ - [Useful Links](#useful-links)
42
+
43
+ ## Installation
44
+
45
+ ```bash
46
+ pip install wexample-filestate-python
47
+ ```
48
+
49
+ Requires Python >=3.10.
50
+
51
+ ## Tests
52
+
53
+ This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
54
+
55
+ ### Installation
56
+
57
+ First, install the required testing dependencies:
58
+ ```bash
59
+ .venv/bin/python -m pip install pytest pytest-cov
60
+ ```
61
+
62
+ ### Basic Usage
63
+
64
+ Run all tests with coverage:
65
+ ```bash
66
+ .venv/bin/python -m pytest --cov --cov-report=html
67
+ ```
68
+
69
+ ### Common Commands
70
+ ```bash
71
+ # Run tests with coverage for a specific module
72
+ .venv/bin/python -m pytest --cov=your_module
73
+
74
+ # Show which lines are not covered
75
+ .venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
76
+
77
+ # Generate an HTML coverage report
78
+ .venv/bin/python -m pytest --cov=your_module --cov-report=html
79
+
80
+ # Combine terminal and HTML reports
81
+ .venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
82
+
83
+ # Run specific test file with coverage
84
+ .venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
85
+ ```
86
+
87
+ ### Viewing HTML Reports
88
+
89
+ After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
90
+
91
+ ### Coverage Threshold
92
+
93
+ To enforce a minimum coverage percentage:
94
+ ```bash
95
+ .venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
96
+ ```
97
+
98
+ This will cause the test suite to fail if coverage drops below 80%.
99
+
100
+ ## Known Limitations & Roadmap
101
+
102
+ Current limitations and planned features are tracked in the GitHub issues.
103
+
104
+ See the [project roadmap](https://github.com/wexample/python-filestate_python/issues) for upcoming features and improvements.
105
+
106
+ ## Status & Compatibility
107
+
108
+ **Maturity**: Production-ready
109
+
110
+ **Python Support**: >=3.10
111
+
112
+ **OS Support**: Linux, macOS, Windows
113
+
114
+ **Status**: Actively maintained
115
+
116
+ ## Useful Links
117
+
118
+ - **Homepage**: https://github.com/wexample/python-filestate-python
119
+ - **Issue Tracker**: https://github.com/wexample/python-filestate-python/issues
120
+ - **Discussions**: https://github.com/wexample/python-filestate-python/discussions
121
+ - **PyPI**: [pypi.org/project/wexample-filestate-python](https://pypi.org/project/wexample-filestate-python/)
@@ -0,0 +1,93 @@
1
+ # filestate_python
2
+
3
+ Version: 9.2.0
4
+
5
+ Extends wexample-filestate with Python file options: format, sort imports, modernize typing, and reorder class members.
6
+
7
+ ## Table of Contents
8
+
9
+ - [Install](#install)
10
+ - [Tests](#tests)
11
+ - [Roadmap](#roadmap)
12
+ - [Status Compatibility](#status-compatibility)
13
+ - [Useful Links](#useful-links)
14
+
15
+ ## Installation
16
+
17
+ ```bash
18
+ pip install wexample-filestate-python
19
+ ```
20
+
21
+ Requires Python >=3.10.
22
+
23
+ ## Tests
24
+
25
+ This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
26
+
27
+ ### Installation
28
+
29
+ First, install the required testing dependencies:
30
+ ```bash
31
+ .venv/bin/python -m pip install pytest pytest-cov
32
+ ```
33
+
34
+ ### Basic Usage
35
+
36
+ Run all tests with coverage:
37
+ ```bash
38
+ .venv/bin/python -m pytest --cov --cov-report=html
39
+ ```
40
+
41
+ ### Common Commands
42
+ ```bash
43
+ # Run tests with coverage for a specific module
44
+ .venv/bin/python -m pytest --cov=your_module
45
+
46
+ # Show which lines are not covered
47
+ .venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
48
+
49
+ # Generate an HTML coverage report
50
+ .venv/bin/python -m pytest --cov=your_module --cov-report=html
51
+
52
+ # Combine terminal and HTML reports
53
+ .venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
54
+
55
+ # Run specific test file with coverage
56
+ .venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
57
+ ```
58
+
59
+ ### Viewing HTML Reports
60
+
61
+ After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
62
+
63
+ ### Coverage Threshold
64
+
65
+ To enforce a minimum coverage percentage:
66
+ ```bash
67
+ .venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
68
+ ```
69
+
70
+ This will cause the test suite to fail if coverage drops below 80%.
71
+
72
+ ## Known Limitations & Roadmap
73
+
74
+ Current limitations and planned features are tracked in the GitHub issues.
75
+
76
+ See the [project roadmap](https://github.com/wexample/python-filestate_python/issues) for upcoming features and improvements.
77
+
78
+ ## Status & Compatibility
79
+
80
+ **Maturity**: Production-ready
81
+
82
+ **Python Support**: >=3.10
83
+
84
+ **OS Support**: Linux, macOS, Windows
85
+
86
+ **Status**: Actively maintained
87
+
88
+ ## Useful Links
89
+
90
+ - **Homepage**: https://github.com/wexample/python-filestate-python
91
+ - **Issue Tracker**: https://github.com/wexample/python-filestate-python/issues
92
+ - **Discussions**: https://github.com/wexample/python-filestate-python/discussions
93
+ - **PyPI**: [pypi.org/project/wexample-filestate-python](https://pypi.org/project/wexample-filestate-python/)
@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
6
6
 
7
7
  [project]
8
8
  name = "wexample-filestate-python"
9
- version = "9.1.3"
9
+ version = "9.2.0"
10
10
  description = "Extends wexample-filestate with Python file options: format, sort imports, modernize typing, and reorder class members."
11
11
  authors = [
12
12
  { name = "weeger", email = "contact@wexample.com" },
@@ -29,7 +29,7 @@ dependencies = [
29
29
  "ruff",
30
30
  "tomli",
31
31
  "wexample-api>=6.8.0",
32
- "wexample-filestate>=17.5.0",
32
+ "wexample-filestate>=17.6.0",
33
33
  ]
34
34
 
35
35
  [project.readme]
@@ -1,310 +0,0 @@
1
- Metadata-Version: 2.1
2
- Name: wexample-filestate-python
3
- Version: 9.1.3
4
- Summary: Extends wexample-filestate with Python file options: format, sort imports, modernize typing, and reorder class members.
5
- Author-Email: weeger <contact@wexample.com>
6
- License: MIT
7
- Classifier: Programming Language :: Python :: 3
8
- Classifier: License :: OSI Approved :: MIT License
9
- Classifier: Operating System :: OS Independent
10
- Project-URL: homepage, https://github.com/wexample/python-filestate-python
11
- Requires-Python: >=3.10
12
- Requires-Dist: attrs>=23.1.0
13
- Requires-Dist: autoflake
14
- Requires-Dist: black
15
- Requires-Dist: cattrs>=23.1.0
16
- Requires-Dist: flynt
17
- Requires-Dist: isort
18
- Requires-Dist: libcst
19
- Requires-Dist: packaging
20
- Requires-Dist: ruff
21
- Requires-Dist: tomli
22
- Requires-Dist: wexample-api>=6.8.0
23
- Requires-Dist: wexample-filestate>=17.5.0
24
- Provides-Extra: dev
25
- Requires-Dist: pytest; extra == "dev"
26
- Requires-Dist: pytest-cov; extra == "dev"
27
- Description-Content-Type: text/markdown
28
-
29
- # filestate_python
30
-
31
- Version: 9.1.3
32
-
33
- `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.
34
-
35
- ## Table of Contents
36
-
37
- - [Installation](#installation)
38
- - [Quickstart](#quickstart)
39
- - [Tests](#tests)
40
- - [Architecture](#architecture)
41
- - [Integration in the Suite](#integration-in-the-suite)
42
- - [Dependencies](#dependencies)
43
- - [Versioning & Compatibility Policy](#versioning--compatibility-policy)
44
- - [License](#license)
45
- - [About us](#about-us)
46
- - [Known Limitations & Roadmap](#known-limitations--roadmap)
47
- - [Status & Compatibility](#status--compatibility)
48
- - [Useful Links](#useful-links)
49
- - [Migration Notes](#migration-notes)
50
-
51
- ## Installation
52
-
53
- ```bash
54
- pip install wexample-filestate-python
55
- ```
56
-
57
- Requires Python >=3.10.
58
-
59
- ## Quickstart
60
-
61
- Install the package:
62
-
63
- ```bash
64
- pip install wexample-filestate-python
65
- ```
66
-
67
- 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.
68
-
69
- Create a `FileStateManager` pointed at your project directory, pass `PythonOptionsProvider` so the `python` key is recognised, then call `apply()`:
70
-
71
- ```python
72
- from wexample_filestate.utils.file_state_manager import FileStateManager
73
- from wexample_filestate_python.options_provider.python_options_provider import PythonOptionsProvider
74
- from wexample_prompt.common.io_manager import IoManager
75
-
76
- manager = FileStateManager.create_from_path(
77
- path="/path/to/your/project",
78
- config={
79
- "children": [
80
- {
81
- "name": "my_module.py",
82
- "python": ["format", "sort_imports", "remove_unused"],
83
- }
84
- ]
85
- },
86
- io=IoManager(),
87
- options_providers=[PythonOptionsProvider],
88
- )
89
- manager.apply()
90
- ```
91
-
92
- `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.
93
-
94
- 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.
95
-
96
- ## Tests
97
-
98
- This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
99
-
100
- ### Installation
101
-
102
- First, install the required testing dependencies:
103
- ```bash
104
- .venv/bin/python -m pip install pytest pytest-cov
105
- ```
106
-
107
- ### Basic Usage
108
-
109
- Run all tests with coverage:
110
- ```bash
111
- .venv/bin/python -m pytest --cov --cov-report=html
112
- ```
113
-
114
- ### Common Commands
115
- ```bash
116
- # Run tests with coverage for a specific module
117
- .venv/bin/python -m pytest --cov=your_module
118
-
119
- # Show which lines are not covered
120
- .venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
121
-
122
- # Generate an HTML coverage report
123
- .venv/bin/python -m pytest --cov=your_module --cov-report=html
124
-
125
- # Combine terminal and HTML reports
126
- .venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
127
-
128
- # Run specific test file with coverage
129
- .venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
130
- ```
131
-
132
- ### Viewing HTML Reports
133
-
134
- After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
135
-
136
- ### Coverage Threshold
137
-
138
- To enforce a minimum coverage percentage:
139
- ```bash
140
- .venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
141
- ```
142
-
143
- This will cause the test suite to fail if coverage drops below 80%.
144
-
145
- ## Architecture
146
-
147
- 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/`.
148
-
149
- ### Registration
150
-
151
- 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.
152
-
153
- ### Option tree
154
-
155
- 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.
156
-
157
- ### Leaf options
158
-
159
- 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.
160
-
161
- The tools each option delegates to:
162
-
163
- - `FormatOption` — `black.format_file_contents()`; uses `WithBatchOptionMixin` to collect all target paths and pass them to Black in one call
164
- - `SortImportsOption` — `isort.code()` with the `"black"` profile; the `(code_fn, Config)` pair is constructed once via `@lru_cache(maxsize=1)`
165
- - `ModernizeTypingOption` — `ruff check --select=UP --fix` via subprocess; also uses `WithBatchOptionMixin`
166
- - `RemoveUnusedOption` — `autoflake.fix_code()` called in-process
167
- - `FstringifyOption` — `flynt.api.fstringify_code()`; wrapped by `WithStdoutWrappingMixin` to prevent flynt's stdout from corrupting progress indicators
168
- - `AddFutureAnnotationsOption` — uses `ast.parse()` to locate the docstring end, then inserts `from __future__ import annotations` at the correct line
169
- - `FixAttrsOption` — delegates to `python_attrs_utils.fix_attrs_kw_only()` through the CST cache
170
- - `RelocateImportsOption` — runs the five-class import relocation pipeline described below
171
- - 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
172
-
173
- `ClassNameMatchesFileNameOption` is the exception: it extends `OptionMixin` + `AbstractConfigOption` directly (not `AbstractFileContentOption`), declares `[Scope.NAME, Scope.CONTENT]`, and currently only reports mismatches rather than rewriting.
174
-
175
- 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.
176
-
177
- ### CST cache
178
-
179
- 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.
180
-
181
- ### Import relocation pipeline
182
-
183
- `RelocateImportsOption` coordinates five libcst classes in `utils/relocate_imports/`, applied in sequence on the same `cst.Module`:
184
-
185
- 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
186
- 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)
187
- 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`
188
- 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
189
- 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
190
-
191
- The rewriter's output feeds directly into the localizer: `final_module = rewritten.visit(PythonLocalizeRuntimeImports(...))`.
192
-
193
- ### Domain utils
194
-
195
- 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`:
196
-
197
- - `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)
198
- - `python_class_attributes_utils.py` — attribute ordering within classes
199
- - `python_blank_lines_utils.py` — removes leading blank lines after function/class signatures
200
- - `python_functions_utils.py` — collects module-level function groups, handling consecutive `@overload` sequences as a single unit
201
- - `python_attrs_utils.py` — ensures `@attrs.define` / `@attr.s` decorators carry `kw_only=True`
202
- - `python_iterable_utils.py` — sorts items inside flagged iterable literals
203
- - `python_constants_utils.py` — sorts flagged `UPPER_CASE` constant blocks at module level
204
- - `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)
205
-
206
- ### File types
207
-
208
- 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.
209
-
210
- 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.
211
-
212
- ### Config value
213
-
214
- 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.
215
-
216
- ### Helpers
217
-
218
- 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.
219
-
220
- 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.
221
-
222
- ### Constants
223
-
224
- src/wexample_filestate_python/const/path.py — `PATH_DIR_SRC` and `PATH_DIR_TESTS` as `Path` constants.
225
-
226
- src/wexample_filestate_python/const/python_file.py — `PYTHON_FILE_EXTENSION = "py"` and `PYTHON_FILE_PYTEST_COVERAGE_JSON`.
227
-
228
- src/wexample_filestate_python/const/name_pattern.py — `NAME_PATTERN_PYTHON_NOT_PYCACHE`, a regex string that excludes `__pycache__` from directory matches.
229
-
230
- ### PyPI gateway
231
-
232
- 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`.
233
-
234
- ## Integration in the Suite
235
-
236
- 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.
237
-
238
- ### Related Packages
239
-
240
- 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.
241
-
242
- ## Dependencies
243
-
244
- - attrs: >=23.1.0
245
- - autoflake:
246
- - black:
247
- - cattrs: >=23.1.0
248
- - flynt:
249
- - isort:
250
- - libcst:
251
- - packaging:
252
- - ruff:
253
- - tomli:
254
- - wexample-api: >=6.8.0
255
- - wexample-filestate: >=17.5.0
256
-
257
- ## Versioning & Compatibility Policy
258
-
259
- Wexample packages follow **Semantic Versioning** (SemVer):
260
-
261
- - **MAJOR**: Breaking changes
262
- - **MINOR**: New features, backward compatible
263
- - **PATCH**: Bug fixes, backward compatible
264
-
265
- We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
266
-
267
- ## License
268
-
269
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
270
-
271
- Free to use in both personal and commercial projects.
272
-
273
- ## About us
274
-
275
- [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.
276
-
277
- 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.
278
-
279
- 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.
280
-
281
- Built and maintained by [Romain Weeger](https://weeger.io).
282
-
283
- ## Known Limitations & Roadmap
284
-
285
- Current limitations and planned features are tracked in the GitHub issues.
286
-
287
- See the [project roadmap](https://github.com/wexample/python-filestate_python/issues) for upcoming features and improvements.
288
-
289
- ## Status & Compatibility
290
-
291
- **Maturity**: Production-ready
292
-
293
- **Python Support**: >=3.10
294
-
295
- **OS Support**: Linux, macOS, Windows
296
-
297
- **Status**: Actively maintained
298
-
299
- ## Useful Links
300
-
301
- - **Homepage**: https://github.com/wexample/python-filestate-python
302
- - **Issue Tracker**: https://github.com/wexample/python-filestate-python/issues
303
- - **Discussions**: https://github.com/wexample/python-filestate-python/discussions
304
- - **PyPI**: [pypi.org/project/wexample-filestate-python](https://pypi.org/project/wexample-filestate-python/)
305
-
306
- ## Migration Notes
307
-
308
- When upgrading between major versions, refer to the migration guides in the documentation.
309
-
310
- Breaking changes are clearly documented with upgrade paths and examples.
@@ -1,282 +0,0 @@
1
- # filestate_python
2
-
3
- Version: 9.1.3
4
-
5
- `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.
6
-
7
- ## Table of Contents
8
-
9
- - [Installation](#installation)
10
- - [Quickstart](#quickstart)
11
- - [Tests](#tests)
12
- - [Architecture](#architecture)
13
- - [Integration in the Suite](#integration-in-the-suite)
14
- - [Dependencies](#dependencies)
15
- - [Versioning & Compatibility Policy](#versioning--compatibility-policy)
16
- - [License](#license)
17
- - [About us](#about-us)
18
- - [Known Limitations & Roadmap](#known-limitations--roadmap)
19
- - [Status & Compatibility](#status--compatibility)
20
- - [Useful Links](#useful-links)
21
- - [Migration Notes](#migration-notes)
22
-
23
- ## Installation
24
-
25
- ```bash
26
- pip install wexample-filestate-python
27
- ```
28
-
29
- Requires Python >=3.10.
30
-
31
- ## Quickstart
32
-
33
- Install the package:
34
-
35
- ```bash
36
- pip install wexample-filestate-python
37
- ```
38
-
39
- 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.
40
-
41
- Create a `FileStateManager` pointed at your project directory, pass `PythonOptionsProvider` so the `python` key is recognised, then call `apply()`:
42
-
43
- ```python
44
- from wexample_filestate.utils.file_state_manager import FileStateManager
45
- from wexample_filestate_python.options_provider.python_options_provider import PythonOptionsProvider
46
- from wexample_prompt.common.io_manager import IoManager
47
-
48
- manager = FileStateManager.create_from_path(
49
- path="/path/to/your/project",
50
- config={
51
- "children": [
52
- {
53
- "name": "my_module.py",
54
- "python": ["format", "sort_imports", "remove_unused"],
55
- }
56
- ]
57
- },
58
- io=IoManager(),
59
- options_providers=[PythonOptionsProvider],
60
- )
61
- manager.apply()
62
- ```
63
-
64
- `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.
65
-
66
- 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.
67
-
68
- ## Tests
69
-
70
- This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
71
-
72
- ### Installation
73
-
74
- First, install the required testing dependencies:
75
- ```bash
76
- .venv/bin/python -m pip install pytest pytest-cov
77
- ```
78
-
79
- ### Basic Usage
80
-
81
- Run all tests with coverage:
82
- ```bash
83
- .venv/bin/python -m pytest --cov --cov-report=html
84
- ```
85
-
86
- ### Common Commands
87
- ```bash
88
- # Run tests with coverage for a specific module
89
- .venv/bin/python -m pytest --cov=your_module
90
-
91
- # Show which lines are not covered
92
- .venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
93
-
94
- # Generate an HTML coverage report
95
- .venv/bin/python -m pytest --cov=your_module --cov-report=html
96
-
97
- # Combine terminal and HTML reports
98
- .venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
99
-
100
- # Run specific test file with coverage
101
- .venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
102
- ```
103
-
104
- ### Viewing HTML Reports
105
-
106
- After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
107
-
108
- ### Coverage Threshold
109
-
110
- To enforce a minimum coverage percentage:
111
- ```bash
112
- .venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
113
- ```
114
-
115
- This will cause the test suite to fail if coverage drops below 80%.
116
-
117
- ## Architecture
118
-
119
- 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/`.
120
-
121
- ### Registration
122
-
123
- 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.
124
-
125
- ### Option tree
126
-
127
- 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.
128
-
129
- ### Leaf options
130
-
131
- 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.
132
-
133
- The tools each option delegates to:
134
-
135
- - `FormatOption` — `black.format_file_contents()`; uses `WithBatchOptionMixin` to collect all target paths and pass them to Black in one call
136
- - `SortImportsOption` — `isort.code()` with the `"black"` profile; the `(code_fn, Config)` pair is constructed once via `@lru_cache(maxsize=1)`
137
- - `ModernizeTypingOption` — `ruff check --select=UP --fix` via subprocess; also uses `WithBatchOptionMixin`
138
- - `RemoveUnusedOption` — `autoflake.fix_code()` called in-process
139
- - `FstringifyOption` — `flynt.api.fstringify_code()`; wrapped by `WithStdoutWrappingMixin` to prevent flynt's stdout from corrupting progress indicators
140
- - `AddFutureAnnotationsOption` — uses `ast.parse()` to locate the docstring end, then inserts `from __future__ import annotations` at the correct line
141
- - `FixAttrsOption` — delegates to `python_attrs_utils.fix_attrs_kw_only()` through the CST cache
142
- - `RelocateImportsOption` — runs the five-class import relocation pipeline described below
143
- - 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
144
-
145
- `ClassNameMatchesFileNameOption` is the exception: it extends `OptionMixin` + `AbstractConfigOption` directly (not `AbstractFileContentOption`), declares `[Scope.NAME, Scope.CONTENT]`, and currently only reports mismatches rather than rewriting.
146
-
147
- 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.
148
-
149
- ### CST cache
150
-
151
- 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.
152
-
153
- ### Import relocation pipeline
154
-
155
- `RelocateImportsOption` coordinates five libcst classes in `utils/relocate_imports/`, applied in sequence on the same `cst.Module`:
156
-
157
- 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
158
- 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)
159
- 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`
160
- 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
161
- 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
162
-
163
- The rewriter's output feeds directly into the localizer: `final_module = rewritten.visit(PythonLocalizeRuntimeImports(...))`.
164
-
165
- ### Domain utils
166
-
167
- 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`:
168
-
169
- - `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)
170
- - `python_class_attributes_utils.py` — attribute ordering within classes
171
- - `python_blank_lines_utils.py` — removes leading blank lines after function/class signatures
172
- - `python_functions_utils.py` — collects module-level function groups, handling consecutive `@overload` sequences as a single unit
173
- - `python_attrs_utils.py` — ensures `@attrs.define` / `@attr.s` decorators carry `kw_only=True`
174
- - `python_iterable_utils.py` — sorts items inside flagged iterable literals
175
- - `python_constants_utils.py` — sorts flagged `UPPER_CASE` constant blocks at module level
176
- - `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)
177
-
178
- ### File types
179
-
180
- 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.
181
-
182
- 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.
183
-
184
- ### Config value
185
-
186
- 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.
187
-
188
- ### Helpers
189
-
190
- 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.
191
-
192
- 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.
193
-
194
- ### Constants
195
-
196
- src/wexample_filestate_python/const/path.py — `PATH_DIR_SRC` and `PATH_DIR_TESTS` as `Path` constants.
197
-
198
- src/wexample_filestate_python/const/python_file.py — `PYTHON_FILE_EXTENSION = "py"` and `PYTHON_FILE_PYTEST_COVERAGE_JSON`.
199
-
200
- src/wexample_filestate_python/const/name_pattern.py — `NAME_PATTERN_PYTHON_NOT_PYCACHE`, a regex string that excludes `__pycache__` from directory matches.
201
-
202
- ### PyPI gateway
203
-
204
- 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`.
205
-
206
- ## Integration in the Suite
207
-
208
- 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.
209
-
210
- ### Related Packages
211
-
212
- 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.
213
-
214
- ## Dependencies
215
-
216
- - attrs: >=23.1.0
217
- - autoflake:
218
- - black:
219
- - cattrs: >=23.1.0
220
- - flynt:
221
- - isort:
222
- - libcst:
223
- - packaging:
224
- - ruff:
225
- - tomli:
226
- - wexample-api: >=6.8.0
227
- - wexample-filestate: >=17.5.0
228
-
229
- ## Versioning & Compatibility Policy
230
-
231
- Wexample packages follow **Semantic Versioning** (SemVer):
232
-
233
- - **MAJOR**: Breaking changes
234
- - **MINOR**: New features, backward compatible
235
- - **PATCH**: Bug fixes, backward compatible
236
-
237
- We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
238
-
239
- ## License
240
-
241
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
242
-
243
- Free to use in both personal and commercial projects.
244
-
245
- ## About us
246
-
247
- [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.
248
-
249
- 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.
250
-
251
- 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.
252
-
253
- Built and maintained by [Romain Weeger](https://weeger.io).
254
-
255
- ## Known Limitations & Roadmap
256
-
257
- Current limitations and planned features are tracked in the GitHub issues.
258
-
259
- See the [project roadmap](https://github.com/wexample/python-filestate_python/issues) for upcoming features and improvements.
260
-
261
- ## Status & Compatibility
262
-
263
- **Maturity**: Production-ready
264
-
265
- **Python Support**: >=3.10
266
-
267
- **OS Support**: Linux, macOS, Windows
268
-
269
- **Status**: Actively maintained
270
-
271
- ## Useful Links
272
-
273
- - **Homepage**: https://github.com/wexample/python-filestate-python
274
- - **Issue Tracker**: https://github.com/wexample/python-filestate-python/issues
275
- - **Discussions**: https://github.com/wexample/python-filestate-python/discussions
276
- - **PyPI**: [pypi.org/project/wexample-filestate-python](https://pypi.org/project/wexample-filestate-python/)
277
-
278
- ## Migration Notes
279
-
280
- When upgrading between major versions, refer to the migration guides in the documentation.
281
-
282
- Breaking changes are clearly documented with upgrade paths and examples.
File without changes
File without changes
File without changes