wexample-filestate-python 0.0.48__py3-none-any.whl

wexample_filestate_python/option/order_iterable_items_option.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class OrderIterableItemsOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Sort items inside iterable literals following the '# filestate: python-iterable-sort' flag (primarily lists with one-item-per-line)."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Sort items inside flagged iterable literals (lists, and simple dicts where applicable).
+
+        Looks for the inline flag '# filestate: python-iterable-sort' and sorts the following
+        contiguous block of iterable items alphabetically (case-insensitive), preserving
+        indentation and punctuation. Intended primarily for list literals written one-item-per-line.
+        """
+        from wexample_filestate_python.utils.python_iterable_utils import (
+            reorder_flagged_iterables,
+        )
+
+        src = target.get_local_file().read()
+        modified = reorder_flagged_iterables(src)
+        return modified

wexample_filestate_python/option/order_main_guard_option.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class OrderMainGuardOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Ensure the if __name__ == '__main__': block is the last non-empty statement in the module."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Ensure the `if __name__ == "__main__":` block is at the very end of the file.
+
+        Moves any top-level main-guard blocks to be the last non-empty statement in the
+        module (before trailing blank lines), preserving content and spacing as much as possible.
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_main_guard_utils import (
+            find_main_guard_blocks,
+            is_main_guard_at_end,
+            move_main_guard_to_end,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        # No main guard present => nothing to do
+        if not find_main_guard_blocks(module):
+            return src
+
+        # Already at end => avoid whitespace-only diffs
+        if is_main_guard_at_end(module):
+            return src
+
+        modified = move_main_guard_to_end(module)
+        return modified.code

wexample_filestate_python/option/order_module_docstring_option.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class OrderModuleDocstringOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Move module docstring to the top of Python files. Ensures the module docstring appears as the first element before any imports or code."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Ensure module docstring is positioned at the very top of Python files.
+
+        Moves the module docstring (if present) to be the first element in the file,
+        before any imports or other code elements.
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_docstring_utils import (
+            find_module_docstring,
+            is_module_docstring_at_top,
+            move_docstring_to_top,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        # Check if there's a docstring and if it needs to be moved
+        docstring_node, position = find_module_docstring(module)
+
+        if docstring_node is None:
+            # No docstring found, nothing to do
+            return src
+
+        if is_module_docstring_at_top(module):
+            # Check if quotes need normalization
+            if len(docstring_node.body) > 0 and isinstance(
+                docstring_node.body[0], cst.Expr
+            ):
+                expr = docstring_node.body[0]
+                if isinstance(expr.value, cst.SimpleString):
+                    quote = expr.value.quote
+                    if quote.startswith("'''") or (
+                        quote.startswith("'") and not quote.startswith('"')
+                    ):
+                        # Need to normalize quotes
+                        from wexample_filestate_python.utils.python_docstring_utils import (
+                            normalize_docstring_quotes,
+                        )
+
+                        normalized_docstring = normalize_docstring_quotes(
+                            docstring_node
+                        )
+                        # Ensure no leading whitespace for the docstring at top
+                        clean_docstring = normalized_docstring.with_changes(
+                            leading_lines=[]
+                        )
+                        new_body = [clean_docstring] + list(module.body[1:])
+                        modified_module = module.with_changes(body=new_body)
+                        return modified_module.code
+            # Already at top and quotes are fine
+            return src
+
+        # Move docstring to top (this also normalizes quotes)
+        modified_module = move_docstring_to_top(module)
+        return modified_module.code

wexample_filestate_python/option/order_module_functions_option.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class OrderModuleFunctionsOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Order module-level functions: public A–Z, then private (_*), keeping @overload groups, and move them before classes."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Order module-level functions: public A–Z, then private (_*) A–Z, before classes.
+
+        - Keeps @overload groups attached to their implementation.
+        - Preserves spacing/comments by keeping each group's first function's leading_lines.
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_functions_utils import (
+            module_functions_sorted_before_classes,
+            reorder_module_functions,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        # Quick no-op detection: if there are no functions, or functions already sorted
+        # and placed before classes, the transformation may be a noop.
+        if module_functions_sorted_before_classes(module):
+            # We still need to check sorting (public then private) and alpha order.
+            # We will compute the transformed module and compare.
+            pass
+
+        modified = reorder_module_functions(module)
+        return modified.code

wexample_filestate_python/option/order_module_metadata_option.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class OrderModuleMetadataOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Group and sort module metadata (e.g., __all__, __version__, __author__) at module level with minimal spacing changes."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Group and sort module metadata assignments at module level.
+
+        Collects recognized metadata variables like `__all__`, `__version__`, `__author__`, etc.,
+        groups them as a contiguous block, and sorts them alphabetically by variable name.
+
+        Placement: after imports and `if TYPE_CHECKING:` blocks, before other module-level code.
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_module_metadata_utils import (
+            find_module_metadata_statements,
+            group_and_sort_module_metadata,
+            target_index_for_module_metadata,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        found = find_module_metadata_statements(module)
+        if not found:
+            return src
+
+        # Determine if already grouped and sorted at the correct position
+        indices = [i for i, _, _ in found]
+        # contiguous block?
+        contiguous = (
+            indices == list(range(indices[0], indices[0] + len(indices)))
+            if indices
+            else True
+        )
+        # names sorted?
+        names = [name for _, __, name in found]
+        names_sorted = sorted(names, key=lambda n: n.lower())
+        already_sorted = names == names_sorted
+        # at correct position?
+        desired_index = target_index_for_module_metadata(module)
+        at_target_position = indices and indices[0] == desired_index
+
+        # If everything is already correct, avoid making whitespace-only changes
+        if contiguous and already_sorted and at_target_position:
+            return src
+
+        modified = group_and_sort_module_metadata(module)
+        return modified.code

wexample_filestate_python/option/order_type_checking_block_option.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class OrderTypeCheckingBlockOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Move if TYPE_CHECKING blocks after imports. Keeps code layout predictable while preserving behavior."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Move `if TYPE_CHECKING:` blocks after regular imports.
+
+        Ensures that all top-level `if TYPE_CHECKING:` blocks are placed immediately
+        after the last regular import section (or after `from __future__ import ...`
+        if no regular imports exist). Keeps spacing minimal and preserves content.
+        """
+        import libcst as cst
+
+        from wexample_filestate_python.utils.python_type_checking_utils import (
+            find_type_checking_blocks,
+            move_type_checking_blocks_after_imports,
+            target_index_for_type_checking,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        blocks = find_type_checking_blocks(module)
+        if not blocks:
+            return src
+
+        # Compute current positions; if already correctly positioned, no change
+        current_indices = [i for i, _ in blocks]
+        desired_index = target_index_for_type_checking(module)
+        # Already correct if first block starts at desired index and blocks are contiguous
+        contiguous = current_indices == list(
+            range(current_indices[0], current_indices[0] + len(current_indices))
+        )
+        if contiguous and current_indices[0] == desired_index:
+            return src
+
+        modified = move_type_checking_blocks_after_imports(module)
+        return modified.code

wexample_filestate_python/option/python_option.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, Union
+
+from wexample_config.config_option.abstract_config_option import AbstractConfigOption
+from wexample_config.config_option.abstract_nested_config_option import (
+    AbstractNestedConfigOption,
+)
+from wexample_filestate.operation.abstract_operation import AbstractOperation
+from wexample_filestate.option.mixin.option_mixin import OptionMixin
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class PythonOption(OptionMixin, AbstractNestedConfigOption):
+    # filestate: python-constant-sort
+    # New preferred option name to add `from __future__ import annotations`
+    OPTION_NAME_ADD_FUTURE_ANNOTATIONS: ClassVar[str] = "add_future_annotations"
+    OPTION_NAME_ADD_RETURN_TYPES: ClassVar[str] = "add_return_types"
+    # Fix attrs usage (ensure kw_only=True, etc.)
+    OPTION_NAME_FIX_ATTRS: ClassVar[str] = "fix_attrs"
+    # Fix blank lines in Python files (after signatures, docstrings, etc.)
+    OPTION_NAME_FIX_BLANK_LINES: ClassVar[str] = "fix_blank_lines"
+    OPTION_NAME_FORMAT: ClassVar[str] = "format"
+    OPTION_NAME_FSTRINGIFY: ClassVar[str] = "fstringify"
+    OPTION_NAME_MODERNIZE_TYPING: ClassVar[str] = "modernize_typing"
+    # Sort class attributes: special first, then public A–Z, then private/protected A–Z
+    OPTION_NAME_ORDER_CLASS_ATTRIBUTES: ClassVar[str] = "order_class_attributes"
+    # Ensure class docstring is first statement after header/decorators
+    OPTION_NAME_ORDER_CLASS_DOCSTRING: ClassVar[str] = "order_class_docstring"
+    # Order class methods (dunders sequence, class/staticmethods, properties, instances)
+    OPTION_NAME_ORDER_CLASS_METHODS: ClassVar[str] = "order_class_methods"
+    # Sort flagged UPPER_CASE constant blocks at module level
+    OPTION_NAME_ORDER_CONSTANTS: ClassVar[str] = "order_constants"
+    # Sort items inside flagged iterable literals (lists/dicts)
+    OPTION_NAME_ORDER_ITERABLE_ITEMS: ClassVar[str] = "order_iterable_items"
+    # Ensure if __name__ == "__main__" block is at the very end
+    OPTION_NAME_ORDER_MAIN_GUARD: ClassVar[str] = "order_main_guard"
+    # Order module docstring to be at the top of the file
+    OPTION_NAME_ORDER_MODULE_DOCSTRING: ClassVar[str] = "order_module_docstring"
+    # Order module-level functions (public A–Z, then private)
+    OPTION_NAME_ORDER_MODULE_FUNCTIONS: ClassVar[str] = "order_module_functions"
+    # Group and sort module metadata at module level
+    OPTION_NAME_ORDER_MODULE_METADATA: ClassVar[str] = "order_module_metadata"
+    # Normalize blank lines between program structures (spacing rules)
+    OPTION_NAME_ORDER_SPACING: ClassVar[str] = "order_spacing"
+    # Move TYPE_CHECKING blocks to after regular imports
+    OPTION_NAME_ORDER_TYPE_CHECKING_BLOCK: ClassVar[str] = "order_type_checking_block"
+    # Relocate imports by usage (runtime-in-method, class property types, type-only)
+    OPTION_NAME_RELOCATE_IMPORTS: ClassVar[str] = "relocate_imports"
+    OPTION_NAME_REMOVE_UNUSED: ClassVar[str] = "remove_unused"
+    OPTION_NAME_SORT_IMPORTS: ClassVar[str] = "sort_imports"
+    # New policy: unquote annotations (remove string annotations)
+    OPTION_NAME_UNQUOTE_ANNOTATIONS: ClassVar[str] = "unquote_annotations"
+
+    @staticmethod
+    def get_raw_value_allowed_type() -> Any:
+        from wexample_filestate_python.config_value.python_config_value import (
+            PythonConfigValue,
+        )
+
+        return Union[list[str], dict, PythonConfigValue]
+
+    def create_required_operation(
+        self, target: TargetFileOrDirectoryType
+    ) -> AbstractOperation | None:
+        return self._create_child_required_operation(target=target)
+
+    def get_allowed_options(self) -> list[type[AbstractConfigOption]]:
+        # Import all the config options for each Python operation
+        from wexample_filestate_python.option.add_future_annotations_option import (
+            AddFutureAnnotationsOption,
+        )
+        from wexample_filestate_python.option.add_return_types_option import (
+            AddReturnTypesOption,
+        )
+        from wexample_filestate_python.option.fix_attrs_option import FixAttrsOption
+        from wexample_filestate_python.option.fix_blank_lines_option import (
+            FixBlankLinesOption,
+        )
+        from wexample_filestate_python.option.format_option import FormatOption
+        from wexample_filestate_python.option.fstringify_option import FstringifyOption
+        from wexample_filestate_python.option.modernize_typing_option import (
+            ModernizeTypingOption,
+        )
+        from wexample_filestate_python.option.order_class_attributes_option import (
+            OrderClassAttributesOption,
+        )
+        from wexample_filestate_python.option.order_class_docstring_option import (
+            OrderClassDocstringOption,
+        )
+        from wexample_filestate_python.option.order_class_methods_option import (
+            OrderClassMethodsOption,
+        )
+        from wexample_filestate_python.option.order_constants_option import (
+            OrderConstantsOption,
+        )
+        from wexample_filestate_python.option.order_iterable_items_option import (
+            OrderIterableItemsOption,
+        )
+        from wexample_filestate_python.option.order_main_guard_option import (
+            OrderMainGuardOption,
+        )
+        from wexample_filestate_python.option.order_module_docstring_option import (
+            OrderModuleDocstringOption,
+        )
+        from wexample_filestate_python.option.order_module_functions_option import (
+            OrderModuleFunctionsOption,
+        )
+        from wexample_filestate_python.option.order_module_metadata_option import (
+            OrderModuleMetadataOption,
+        )
+        from wexample_filestate_python.option.order_type_checking_block_option import (
+            OrderTypeCheckingBlockOption,
+        )
+        from wexample_filestate_python.option.relocate_imports_option import (
+            RelocateImportsOption,
+        )
+        from wexample_filestate_python.option.remove_unused_option import (
+            RemoveUnusedOption,
+        )
+        from wexample_filestate_python.option.sort_imports_option import (
+            SortImportsOption,
+        )
+        from wexample_filestate_python.option.unquote_annotations_option import (
+            UnquoteAnnotationsOption,
+        )
+
+        return [
+            AddFutureAnnotationsOption,
+            AddReturnTypesOption,
+            FixAttrsOption,
+            FixBlankLinesOption,
+            FormatOption,
+            FstringifyOption,
+            ModernizeTypingOption,
+            OrderClassAttributesOption,
+            OrderClassDocstringOption,
+            OrderClassMethodsOption,
+            OrderConstantsOption,
+            OrderIterableItemsOption,
+            OrderMainGuardOption,
+            OrderModuleDocstringOption,
+            OrderModuleFunctionsOption,
+            OrderModuleMetadataOption,
+            OrderTypeCheckingBlockOption,
+            RelocateImportsOption,
+            RemoveUnusedOption,
+            SortImportsOption,
+            UnquoteAnnotationsOption,
+        ]
+
+    def set_value(self, raw_value: Any) -> None:
+        # Convert list form to dict form for consistency
+        if isinstance(raw_value, list):
+            dict_value = {}
+            for option_name in raw_value:
+                dict_value[option_name] = True
+            raw_value = dict_value
+
+        super().set_value(raw_value=raw_value)

wexample_filestate_python/option/relocate_imports_option.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.decorator.base_class import base_class
+
+from .abstract_python_file_content_option import AbstractPythonFileContentOption
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+
+
+@base_class
+class RelocateImportsOption(AbstractPythonFileContentOption):
+    def get_description(self) -> str:
+        return "Keep module-level and type imports at the top; move runtime-only imports used inside methods into those methods."
+
+    def _apply_content_change(self, target: TargetFileOrDirectoryType) -> str:
+        """Relocate imports according to usage categories:
+
+        Rules:
+        - runtime_local (formerly A): names used at runtime inside functions/methods
+          (e.g., return MyClass(), typing.cast(x, MyClass)).
+          -> import locally at the top of each function using it.
+        - class_level (formerly B): names required at class-definition time
+          (e.g., class attribute annotations, base class references).
+          -> keep/import at module top level.
+        - type_only (formerly C): names used only in type annotations (function
+          params/returns, module-level annotations) and not in runtime_local or class_level.
+          -> move under `if TYPE_CHECKING:` at module top (add "from typing import TYPE_CHECKING"
+             if missing). Files already have `from __future__ import annotations`.
+        """
+        from collections import defaultdict
+        from typing import DefaultDict
+
+        import libcst as cst
+
+        from wexample_filestate_python.utils.relocate_imports.python_import_rewriter import (
+            PythonImportRewriter,
+        )
+        from wexample_filestate_python.utils.relocate_imports.python_localize_runtime_imports import (
+            PythonLocalizeRuntimeImports,
+        )
+        from wexample_filestate_python.utils.relocate_imports.python_parser_import_index import (
+            PythonParserImportIndex,
+        )
+        from wexample_filestate_python.utils.relocate_imports.python_runtime_symbol_collector import (
+            PythonRuntimeSymbolCollector,
+        )
+        from wexample_filestate_python.utils.relocate_imports.python_usage_collector import (
+            PythonUsageCollector,
+        )
+
+        src = target.get_local_file().read()
+        module = cst.parse_module(src)
+
+        # Index current imports using shared utility
+        idx = PythonParserImportIndex()
+        module.visit(idx)
+
+        imported_value_names: set[str] = set(idx.name_to_from.keys())
+
+        # Usage collection
+        # runtime_local: usage inside function bodies
+        # class_level: usage inside class body annotations (needed at definition time)
+        # type_only: type-only annotations across module if not in runtime_local or class_level
+        functions_needing_local: DefaultDict[str, set[str]] = defaultdict(
+            set
+        )  # func_qualified_name -> names
+        class_level_names: set[str] = set()
+        type_annotation_names: set[str] = set()
+        cast_type_names_anywhere: set[str] = set()
+        uc = PythonUsageCollector(
+            imported_value_names=imported_value_names,
+            functions_needing_local=functions_needing_local,
+            used_in_B=class_level_names,
+            used_in_C_annot=type_annotation_names,
+            cast_type_names_anywhere=cast_type_names_anywhere,
+            idx=idx,
+        )
+        module.visit(uc)
+
+        # Conservative fallback: collect any imported names used in non-annotation expressions
+        rsc = PythonRuntimeSymbolCollector(imported_value_names=imported_value_names)
+        module.visit(rsc)
+        runtime_used_anywhere: set[str] = rsc.runtime_used_anywhere
+
+        # Resolve categories
+        runtime_local_all: set[str] = (
+            set().union(*functions_needing_local.values())
+            if functions_needing_local
+            else set()
+        )
+        # class_level has priority over runtime_local: if a name is class-level, we do NOT local-import it
+        runtime_local_final: set[str] = {
+            n for n in runtime_local_all if n not in class_level_names
+        }
+        # type_only = in type annotations but not runtime_local_final or class_level
+        # Exclude any names that appear in cast() type expressions anywhere from C-only,
+        # since casts require runtime availability of the symbol.
+        type_only_names: set[str] = {
+            n
+            for n in type_annotation_names
+            if n not in runtime_local_final
+            and n not in class_level_names
+            and n not in cast_type_names_anywhere
+            and n not in runtime_used_anywhere
+        }
+
+        # Names to include under TYPE_CHECKING:
+        # Use all names that appear in annotations (params/returns/module-level), excluding class-level.
+        # Then subtract names that are already locally imported inside some function where
+        # they are used (to avoid redundant TYPE_CHECKING imports when a function-scoped
+        # import suffices, e.g., `from multiprocessing import Queue` inside a method).
+        annotation_names_candidate: set[str] = {
+            n for n in type_annotation_names if n not in class_level_names
+        }
+
+        # Collect names imported locally inside functions anywhere in the module
+        class _LocalImportNameCollector(cst.CSTVisitor):
+            def __init__(self) -> None:
+                self.stack: list[str] = []
+                self.local_imported: set[str] = set()
+
+            def visit_FunctionDef(self, node: cst.FunctionDef) -> bool:  # type: ignore[override]
+                self.stack.append(node.name.value)
+                return True
+
+            def leave_FunctionDef(self, node: cst.FunctionDef) -> None:  # type: ignore[override]
+                self.stack.pop()
+
+            def visit_ImportFrom(self, node: cst.ImportFrom) -> bool:  # type: ignore[override]
+                if not self.stack:
+                    return True
+                if node.names is None or isinstance(node.names, cst.ImportStar):
+                    return True
+                for alias in node.names:
+                    if isinstance(alias, cst.ImportAlias) and isinstance(
+                        alias.name, cst.Name
+                    ):
+                        name = (
+                            alias.asname.name.value
+                            if alias.asname
+                            else alias.name.value
+                        )
+                        self.local_imported.add(name)
+                return True
+
+        lic = _LocalImportNameCollector()
+        module.visit(lic)
+        type_only_for_block: set[str] = annotation_names_candidate - lic.local_imported
+
+        # For names used inside cast() anywhere in the module:
+        # - do NOT auto-add to TYPE_CHECKING (unless also in annotations via type_only_for_block)
+        # - remove module-level import unless also class_level
+        names_to_remove_from_module = (
+            set(runtime_local_final)
+            | set(type_only_names)
+            | (set(cast_type_names_anywhere) - set(class_level_names))
+        )
+
+        # Do not add to TYPE_CHECKING if the name's module-level import is kept
+        kept_module_imports: set[str] = {
+            n for n in imported_value_names if n not in names_to_remove_from_module
+        }
+        used_in_C_only_final: set[str] = set(type_only_for_block) - kept_module_imports
+
+        # Debug summary removed
+        rewritten = module.visit(
+            PythonImportRewriter(
+                used_in_B=class_level_names,
+                names_to_remove_from_module=names_to_remove_from_module,
+                used_in_C_only=used_in_C_only_final,
+                idx=idx,
+            )
+        )
+
+        # 2) Inject local imports into functions for runtime_local names
+        #    For each function with names, add `from <module> import Name` at top of body.
+        final_module = rewritten.visit(
+            PythonLocalizeRuntimeImports(
+                idx=idx,
+                functions_needing_local=functions_needing_local,
+                # Do not skip cast-used names so they are localized per method.
+                skip_local_names=set(class_level_names),
+            )
+        )
+
+        return final_module.code