wexample-filestate-python 0.0.44__tar.gz → 0.0.45__tar.gz

wexample_filestate_python-0.0.45/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.1
+Name: wexample-filestate-python
+Version: 0.0.45
+Summary: Helpers for Python.
+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: cattrs>=23.1.0
+Requires-Dist: libcst
+Requires-Dist: packaging
+Requires-Dist: tomli
+Requires-Dist: wexample-filestate==0.0.56
+Requires-Dist: wexample-helpers-api==0.0.37
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Description-Content-Type: text/markdown
+
+# wexample-filestate-python
+
+Version: 0.0.45
+
+Helpers for Python.
+
+## Code Quality & Typing
+
+All the suite packages follow strict quality standards:
+
+- **Type hints**: Full type coverage with mypy validation
+- **Code formatting**: Enforced with black and isort
+- **Linting**: Comprehensive checks with custom scripts and tools
+- **Testing**: High test coverage requirements
+
+These standards ensure reliability and maintainability across the suite.
+
+## 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.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history and release notes.
+
+Major changes are documented with migration guides when applicable.
+
+## 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.
+
+## 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.
+
+## Security Policy
+
+### Reporting Vulnerabilities
+
+If you discover a security vulnerability, please email security@wexample.com.
+
+**Do not** open public issues for security vulnerabilities.
+
+We take security seriously and will respond promptly to verified reports.
+
+## Privacy & Telemetry
+
+This package does **not** collect any telemetry or usage data.
+
+Your privacy is respected — no data is transmitted to external services.
+
+## Support Channels
+
+- **GitHub Issues**: Bug reports and feature requests
+- **GitHub Discussions**: Questions and community support
+- **Documentation**: Comprehensive guides and API reference
+- **Email**: contact@wexample.com for general inquiries
+
+Community support is available through GitHub Discussions.
+
+## Contribution Guidelines
+
+We welcome contributions to the Wexample suite! 
+
+### How to Contribute
+
+1. **Fork** the repository
+2. **Create** a feature branch
+3. **Make** your changes
+4. **Test** thoroughly
+5. **Submit** a pull request
+
+## Maintainers & Authors
+
+Maintained by the Wexample team and community contributors.
+
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the full list of contributors.
+
+## License
+
+MIT
+
+## 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/)
+
+## Integration in the Suite
+
+This package is part of the **Wexample Suite** — a collection of high-quality Python packages designed to work seamlessly together.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+# About us
+
+Wexample 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.
+

wexample_filestate_python-0.0.45/README.md

@@ -0,0 +1,118 @@
+# wexample-filestate-python
+
+Version: 0.0.45
+
+Helpers for Python.
+
+## Code Quality & Typing
+
+All the suite packages follow strict quality standards:
+
+- **Type hints**: Full type coverage with mypy validation
+- **Code formatting**: Enforced with black and isort
+- **Linting**: Comprehensive checks with custom scripts and tools
+- **Testing**: High test coverage requirements
+
+These standards ensure reliability and maintainability across the suite.
+
+## 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.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history and release notes.
+
+Major changes are documented with migration guides when applicable.
+
+## 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.
+
+## 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.
+
+## Security Policy
+
+### Reporting Vulnerabilities
+
+If you discover a security vulnerability, please email security@wexample.com.
+
+**Do not** open public issues for security vulnerabilities.
+
+We take security seriously and will respond promptly to verified reports.
+
+## Privacy & Telemetry
+
+This package does **not** collect any telemetry or usage data.
+
+Your privacy is respected — no data is transmitted to external services.
+
+## Support Channels
+
+- **GitHub Issues**: Bug reports and feature requests
+- **GitHub Discussions**: Questions and community support
+- **Documentation**: Comprehensive guides and API reference
+- **Email**: contact@wexample.com for general inquiries
+
+Community support is available through GitHub Discussions.
+
+## Contribution Guidelines
+
+We welcome contributions to the Wexample suite! 
+
+### How to Contribute
+
+1. **Fork** the repository
+2. **Create** a feature branch
+3. **Make** your changes
+4. **Test** thoroughly
+5. **Submit** a pull request
+
+## Maintainers & Authors
+
+Maintained by the Wexample team and community contributors.
+
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the full list of contributors.
+
+## License
+
+MIT
+
+## 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/)
+
+## Integration in the Suite
+
+This package is part of the **Wexample Suite** — a collection of high-quality Python packages designed to work seamlessly together.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+# About us
+
+Wexample 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.
+

{wexample_filestate_python-0.0.44 → wexample_filestate_python-0.0.45}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-filestate-python"
-version = "0.0.44"
+version = "0.0.45"
 description = "Helpers for Python."
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -20,8 +20,11 @@ classifiers = [
 dependencies = [
     "attrs>=23.1.0",
     "cattrs>=23.1.0",
-    "wexample-filestate==0.0.54",
-    "wexample-helpers-api==0.0.35",
+    "libcst",
+    "packaging",
+    "tomli",
+    "wexample-filestate==0.0.56",
+    "wexample-helpers-api==0.0.37",
 ]
 
 [project.readme]
@@ -37,6 +40,7 @@ homepage = "https://github.com/wexample/python-filestate-python"
 [project.optional-dependencies]
 dev = [
     "pytest",
+    "pytest-cov",
 ]
 
 [tool.pdm]
@@ -53,3 +57,11 @@ keep = [
     "black",
     "isort",
 ]
+
+[tool.setuptools.packages.find]
+include = [
+    "*",
+]
+exclude = [
+    "wexample_filestate_python.testing*",
+]

wexample_filestate_python-0.0.45/src/wexample_filestate_python/config_option/mixin/with_stdout_wrapping_mixin.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+
+class WithStdoutWrappingMixin:
+    @classmethod
+    def _execute_and_wrap_stdout(cls, callback):
+        """Execute a callback and wrap any stdout/stderr output with additional newlines.
+
+        This ensures that output from external tools doesn't interfere with progress indicators
+        by adding a newline after any captured output.
+
+        Args:
+            callback: Function to execute that may produce stdout/stderr output
+
+        Returns:
+            The return value of the callback function
+        """
+        import io
+        import sys
+
+        old_stdout = sys.stdout
+        old_stderr = sys.stderr
+        captured_stdout = io.StringIO()
+        captured_stderr = io.StringIO()
+        sys.stdout = captured_stdout
+        sys.stderr = captured_stderr
+
+        try:
+            result = callback()
+        finally:
+            sys.stdout = old_stdout
+            sys.stderr = old_stderr
+
+            stdout_content = captured_stdout.getvalue()
+            stderr_content = captured_stderr.getvalue()
+
+            if stdout_content.strip():
+                sys.stdout.write(stdout_content.rstrip())
+                sys.stdout.write("\n")
+                sys.stdout.write("\n")
+            if stderr_content.strip():
+                sys.stderr.write(stderr_content.rstrip())
+                sys.stderr.write("\n")
+                sys.stderr.write("\n")
+
+        return result

wexample_filestate_python-0.0.45/src/wexample_filestate_python/config_value/python_config_value.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wexample_config.config_value.config_value import ConfigValue
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+
+@base_class
+class PythonConfigValue(ConfigValue):
+    add_future_annotations: bool | None = public_field(
+        default=None,
+        description="Add `from __future__ import annotations`",
+    )
+    add_return_types: bool | None = public_field(
+        default=None,
+        description="Add return type annotations",
+    )
+    fix_attrs: bool | None = public_field(
+        default=None,
+        description="Fix attrs usage (ensure kw_only=True, etc.)",
+    )
+    fix_blank_lines: bool | None = public_field(
+        default=None,
+        description="Fix blank lines in Python files",
+    )
+    format: bool | None = public_field(
+        default=None,
+        description="Format Python code",
+    )
+    fstringify: bool | None = public_field(
+        default=None,
+        description="Convert string formatting to f-strings",
+    )
+    modernize_typing: bool | None = public_field(
+        default=None,
+        description="Modernize typing annotations",
+    )
+    order_class_attributes: bool | None = public_field(
+        default=None,
+        description="Sort class attributes: special first, then public A–Z, then private/protected A–Z",
+    )
+    order_class_docstring: bool | None = public_field(
+        default=None,
+        description="Ensure class docstring is first statement after header/decorators",
+    )
+    order_class_methods: bool | None = public_field(
+        default=None,
+        description="Order class methods (dunders sequence, class/staticmethods, properties, instances)",
+    )
+    order_constants: bool | None = public_field(
+        default=None,
+        description="Sort flagged UPPER_CASE constant blocks at module level",
+    )
+    order_iterable_items: bool | None = public_field(
+        default=None,
+        description="Sort items inside flagged iterable literals (lists/dicts)",
+    )
+    order_main_guard: bool | None = public_field(
+        default=None,
+        description="Ensure if __name__ == '__main__' block is at the very end",
+    )
+    order_module_docstring: bool | None = public_field(
+        default=None,
+        description="Order module docstring to be at the top of the file",
+    )
+    order_module_functions: bool | None = public_field(
+        default=None,
+        description="Order module-level functions (public A–Z, then private)",
+    )
+    order_module_metadata: bool | None = public_field(
+        default=None,
+        description="Group and sort module metadata at module level",
+    )
+    order_spacing: bool | None = public_field(
+        default=None,
+        description="Normalize blank lines between program structures (spacing rules)",
+    )
+    order_type_checking_block: bool | None = public_field(
+        default=None,
+        description="Move TYPE_CHECKING blocks to after regular imports",
+    )
+    raw: Any = public_field(
+        default=None, description="Disabled raw value for this config."
+    )
+    relocate_imports: bool | None = public_field(
+        default=None,
+        description="Relocate imports by usage (runtime-in-method, class property types, type-only)",
+    )
+    remove_unused: bool | None = public_field(
+        default=None,
+        description="Remove unused imports",
+    )
+    sort_imports: bool | None = public_field(
+        default=None,
+        description="Sort imports",
+    )
+    unquote_annotations: bool | None = public_field(
+        default=None,
+        description="Unquote annotations (remove string annotations)",
+    )
+
+    def to_option_raw_value(self) -> Any:
+        from wexample_filestate_python.config_option.add_future_annotations_config_option import (
+            AddFutureAnnotationsConfigOption,
+        )
+        from wexample_filestate_python.config_option.add_return_types_config_option import (
+            AddReturnTypesConfigOption,
+        )
+        from wexample_filestate_python.config_option.fix_attrs_config_option import (
+            FixAttrsConfigOption,
+        )
+        from wexample_filestate_python.config_option.fix_blank_lines_config_option import (
+            FixBlankLinesConfigOption,
+        )
+        from wexample_filestate_python.config_option.format_config_option import (
+            FormatConfigOption,
+        )
+        from wexample_filestate_python.config_option.fstringify_config_option import (
+            FstringifyConfigOption,
+        )
+        from wexample_filestate_python.config_option.modernize_typing_config_option import (
+            ModernizeTypingConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_class_attributes_config_option import (
+            OrderClassAttributesConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_class_docstring_config_option import (
+            OrderClassDocstringConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_class_methods_config_option import (
+            OrderClassMethodsConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_constants_config_option import (
+            OrderConstantsConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_iterable_items_config_option import (
+            OrderIterableItemsConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_main_guard_config_option import (
+            OrderMainGuardConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_module_docstring_config_option import (
+            OrderModuleDocstringConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_module_functions_config_option import (
+            OrderModuleFunctionsConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_module_metadata_config_option import (
+            OrderModuleMetadataConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_spacing_config_option import (
+            OrderSpacingConfigOption,
+        )
+        from wexample_filestate_python.config_option.order_type_checking_block_config_option import (
+            OrderTypeCheckingBlockConfigOption,
+        )
+        from wexample_filestate_python.config_option.relocate_imports_config_option import (
+            RelocateImportsConfigOption,
+        )
+        from wexample_filestate_python.config_option.remove_unused_config_option import (
+            RemoveUnusedConfigOption,
+        )
+        from wexample_filestate_python.config_option.sort_imports_config_option import (
+            SortImportsConfigOption,
+        )
+        from wexample_filestate_python.config_option.unquote_annotations_config_option import (
+            UnquoteAnnotationsConfigOption,
+        )
+
+        return {
+            AddFutureAnnotationsConfigOption.get_name(): self.add_future_annotations,
+            AddReturnTypesConfigOption.get_name(): self.add_return_types,
+            FixAttrsConfigOption.get_name(): self.fix_attrs,
+            FixBlankLinesConfigOption.get_name(): self.fix_blank_lines,
+            FormatConfigOption.get_name(): self.format,
+            FstringifyConfigOption.get_name(): self.fstringify,
+            ModernizeTypingConfigOption.get_name(): self.modernize_typing,
+            OrderClassAttributesConfigOption.get_name(): self.order_class_attributes,
+            OrderClassDocstringConfigOption.get_name(): self.order_class_docstring,
+            OrderClassMethodsConfigOption.get_name(): self.order_class_methods,
+            OrderConstantsConfigOption.get_name(): self.order_constants,
+            OrderIterableItemsConfigOption.get_name(): self.order_iterable_items,
+            OrderMainGuardConfigOption.get_name(): self.order_main_guard,
+            OrderModuleDocstringConfigOption.get_name(): self.order_module_docstring,
+            OrderModuleFunctionsConfigOption.get_name(): self.order_module_functions,
+            OrderModuleMetadataConfigOption.get_name(): self.order_module_metadata,
+            OrderSpacingConfigOption.get_name(): self.order_spacing,
+            OrderTypeCheckingBlockConfigOption.get_name(): self.order_type_checking_block,
+            RelocateImportsConfigOption.get_name(): self.relocate_imports,
+            RemoveUnusedConfigOption.get_name(): self.remove_unused,
+            SortImportsConfigOption.get_name(): self.sort_imports,
+            UnquoteAnnotationsConfigOption.get_name(): self.unquote_annotations,
+        }

{wexample_filestate_python-0.0.44 → wexample_filestate_python-0.0.45}/src/wexample_filestate_python/helpers/package.py

@@ -70,25 +70,6 @@ def package_get_info(package_dir: Path) -> tuple[str, set[str]] | None:
     return name, set(deps)
 
 
-def package_list_sorted(root_dir: str | Path) -> list[str]:
-    """
-    Get a list of package names sorted by dependency order.
-    """
-    from wexample_filestate.helpers.dependencies import dependencies_sort
-
-    dependencies = package_get_dependencies(root_dir)
-    if not dependencies:
-        return []
-
-    # Convert dependencies dict to list for sorting
-    packages = list(dependencies.keys())
-
-    def get_deps(pkg: str) -> set[str]:
-        return dependencies[pkg]
-
-    return dependencies_sort(packages, get_deps)
-
-
 def package_normalize_name(val: str) -> str:
     import re as _re
 

wexample_filestate_python-0.0.45/src/wexample_filestate_python/option/abstract_python_file_content_option.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from wexample_config.config_option.abstract_config_option import AbstractConfigOption
+from wexample_filestate.option.mixin.option_mixin import OptionMixin
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class AbstractPythonFileContentOption(OptionMixin, AbstractConfigOption):
+    @staticmethod
+    def get_raw_value_allowed_type() -> Any:
+        return bool
+
+    def create_required_operation(
+        self, target: TargetFileOrDirectoryType
+    ) -> AbstractOperation | None:
+        from wexample_filestate.operation.file_write_operation import FileWriteOperation
+
+        """Create FileWriteOperation if add_future_annotations is enabled and needed."""
+        # Get current content
+        current_content = target.get_local_file().read()
+
+        # Apply add_future_annotations transformation
+        new_content = self._apply_content_change(target=target)
+
+        # If content changed, create FileWriteOperation
+        if new_content != current_content:
+            return FileWriteOperation(
+                option=self,
+                target=target,
+                content=new_content,
+                description=self.get_description(),
+            )
+
+        return None
+
+    @abstract_method
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> None:
+        pass