machineconfig 8.14__py3-none-any.whl → 8.45__py3-none-any.whl

machineconfig/type_hinting/typedict/ast_utils.py

@@ -0,0 +1,130 @@
+import ast
+from pathlib import Path
+from dataclasses import dataclass, field
+
+
+type FieldInfo = tuple[str, ast.expr | None, dict[str, tuple[str, str]]]
+type ClassFields = tuple[str, list[FieldInfo]]
+
+_file_cache: dict[Path, ast.Module] = {}
+
+
+def _get_ast(path: Path) -> ast.Module:
+    if path not in _file_cache:
+        _file_cache[path] = ast.parse(path.read_text(encoding="utf-8"))
+    return _file_cache[path]
+
+
+@dataclass
+class FileContext:
+    path: Path
+    tree: ast.Module
+    classes: dict[str, ast.ClassDef] = field(default_factory=dict)
+    imports: dict[str, tuple[str, str]] = field(default_factory=dict)
+
+    def __post_init__(self):
+        self.classes = {node.name: node for node in ast.walk(self.tree) if isinstance(node, ast.ClassDef)}
+        for node in ast.walk(self.tree):
+            if isinstance(node, ast.ImportFrom) and node.module:
+                for alias in node.names:
+                    self.imports[alias.asname or alias.name] = (node.module, alias.name)
+
+
+def _get_context(path: Path) -> FileContext:
+    tree = _get_ast(path)
+    return FileContext(path, tree)
+
+
+def _resolve_imported_class(module_name: str, class_name: str, search_paths: list[Path]) -> tuple[ast.ClassDef, FileContext] | None:
+    parts = module_name.split(".")
+    for root in search_paths:
+        file_path = root.joinpath(*parts).with_suffix(".py")
+        if file_path.exists():
+            try:
+                context = _get_context(file_path)
+                if class_name in context.classes:
+                    return context.classes[class_name], context
+            except Exception:
+                pass
+        init_path = root.joinpath(*parts, "__init__.py")
+        if init_path.exists():
+            try:
+                context = _get_context(init_path)
+                if class_name in context.classes:
+                    return context.classes[class_name], context
+            except Exception:
+                pass
+    return None
+
+
+def load_target_class_fields(source_file_path: Path, search_paths: list[Path] | None = None) -> list[ClassFields]:
+    source_path = Path(source_file_path).resolve()
+    if search_paths is None:
+        search_paths = []
+
+    if not source_path.exists():
+        raise FileNotFoundError(f"Source file not found: {source_path}")
+
+    initial_context = _get_context(source_path)
+
+    def get_parent_node(base: ast.expr, context: FileContext) -> tuple[ast.ClassDef, FileContext] | None:
+        if isinstance(base, ast.Name):
+            if base.id in context.classes:
+                return context.classes[base.id], context
+            if base.id in context.imports:
+                module_name, original_name = context.imports[base.id]
+                return _resolve_imported_class(module_name, original_name, search_paths)  # type: ignore
+        return None
+
+    def collect_fields(class_node: ast.ClassDef, context: FileContext, visited: set[str]) -> list[FieldInfo]:
+        key = f"{context.path}:{class_node.name}"
+        if key in visited:
+            return []
+        visited.add(key)
+        field_info: list[FieldInfo] = []
+        for base in class_node.bases:
+            parent_info = get_parent_node(base, context)
+            if parent_info:
+                parent_node, parent_context = parent_info
+                field_info.extend(collect_fields(parent_node, parent_context, visited))
+        for statement in class_node.body:
+            if isinstance(statement, ast.AnnAssign) and isinstance(statement.target, ast.Name):
+                field_info.append((statement.target.id, statement.annotation, context.imports))
+        return field_info
+
+    def deduplicate_fields(fields: list[FieldInfo]) -> list[FieldInfo]:
+        deduped: dict[str, FieldInfo] = {}
+        for item in fields:
+            field_name = item[0]
+            deduped[field_name] = item
+        return list(deduped.values())
+
+    def is_typeddict(node: ast.ClassDef, context: FileContext, visited: set[str]) -> bool:
+        key = f"{context.path}:{node.name}"
+        if key in visited:
+            return False
+        visited.add(key)
+        for base in node.bases:
+            if (isinstance(base, ast.Name) and base.id == "TypedDict") or (isinstance(base, ast.Attribute) and base.attr == "TypedDict"):
+                return True
+            parent_info = get_parent_node(base, context)
+            if parent_info:
+                parent_node, parent_context = parent_info
+                if is_typeddict(parent_node, parent_context, visited):
+                    return True
+        return False
+
+    target_classes: list[ClassFields] = []
+    for node in ast.walk(initial_context.tree):
+        if not isinstance(node, ast.ClassDef):
+            continue
+        is_dataclass = any(
+            (isinstance(decorator, ast.Name) and decorator.id == "dataclass")
+            or (isinstance(decorator, ast.Attribute) and decorator.attr == "dataclass")
+            or (isinstance(decorator, ast.Call) and ((isinstance(decorator.func, ast.Name) and decorator.func.id == "dataclass") or (isinstance(decorator.func, ast.Attribute) and decorator.func.attr == "dataclass")))
+            for decorator in node.decorator_list
+        )
+        if is_dataclass or is_typeddict(node, initial_context, set()):
+            fields = collect_fields(node, initial_context, set())
+            target_classes.append((node.name, deduplicate_fields(fields)))
+    return target_classes

machineconfig/type_hinting/typedict/generator_helpers.py

@@ -0,0 +1,319 @@
+import ast
+import inspect
+from pathlib import Path
+from typing import Literal
+
+
+WRAPPER_TYPES = {"ReadOnly", "NotRequired", "Optional", "Required", "Final"}
+BUILTIN_TYPES = {"str", "int", "float", "bool", "bytes", "None", "list", "dict", "set", "tuple", "Any", "Literal"}
+PYTHON_TYPE_TO_SERIES_TYPE: dict[str, str] = {"str": "str", "int": "int", "float": "float", "bool": "bool", "bytes": "bytes"}
+PYTHON_TYPE_TO_POLARS_DTYPE: dict[str, str] = {"str": '"pl.String"', "int": '"pl.Int64"', "float": '"pl.Float64"', "bool": '"pl.Boolean"', "bytes": '"pl.Binary"'}
+
+
+def get_types_class_name(class_name: str) -> str:
+    return f"{class_name}_Types"
+
+
+def collect_type_names_from_annotation(annotation: ast.expr | None) -> set[str]:
+    if annotation is None:
+        return set()
+    names: set[str] = set()
+    if isinstance(annotation, ast.Name):
+        if annotation.id not in BUILTIN_TYPES and annotation.id not in WRAPPER_TYPES:
+            names.add(annotation.id)
+    elif isinstance(annotation, ast.Subscript):
+        names.update(collect_type_names_from_annotation(annotation.value))
+        names.update(collect_type_names_from_annotation(annotation.slice))
+    elif isinstance(annotation, ast.BinOp):
+        names.update(collect_type_names_from_annotation(annotation.left))
+        names.update(collect_type_names_from_annotation(annotation.right))
+    elif isinstance(annotation, ast.Tuple):
+        for elt in annotation.elts:
+            names.update(collect_type_names_from_annotation(elt))
+    return names
+
+
+def extract_imports_from_source(source_file_path: Path) -> tuple[dict[str, str], dict[str, str], set[str]]:
+    source_content = source_file_path.read_text(encoding="utf-8")
+    tree = ast.parse(source_content)
+    imports: dict[str, str] = {}
+    local_type_aliases: dict[str, str] = {}
+    local_classes: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module:
+            for alias in node.names:
+                name = alias.asname or alias.name
+                imports[name] = node.module
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            if isinstance(node.annotation, ast.Name) and node.annotation.id == "TypeAlias" and node.value is not None:
+                local_type_aliases[node.target.id] = ast.unparse(node.value)
+        elif isinstance(node, ast.ClassDef):
+            local_classes.add(node.name)
+    return imports, local_type_aliases, local_classes
+
+
+def unwrap_type_annotation(annotation: ast.expr | None) -> ast.expr | None:
+    if annotation is None:
+        return None
+    if isinstance(annotation, ast.Subscript) and isinstance(annotation.value, ast.Name) and annotation.value.id in WRAPPER_TYPES:
+        return unwrap_type_annotation(annotation.slice)
+    if isinstance(annotation, ast.Subscript) and isinstance(annotation.value, ast.Attribute) and annotation.value.attr in WRAPPER_TYPES:
+        return unwrap_type_annotation(annotation.slice)
+    return annotation
+
+
+def is_builtin_type(annotation: ast.expr) -> bool:
+    if isinstance(annotation, ast.Name):
+        return annotation.id in BUILTIN_TYPES
+    if isinstance(annotation, ast.Constant):
+        return True
+    if isinstance(annotation, ast.Subscript):
+        return is_builtin_type(annotation.value) and is_builtin_type(annotation.slice)
+    if isinstance(annotation, ast.Attribute):
+        return False
+    if isinstance(annotation, ast.BinOp):
+        return is_builtin_type(annotation.left) and is_builtin_type(annotation.right)
+    if isinstance(annotation, ast.Tuple):
+        return all(is_builtin_type(elt) for elt in annotation.elts)
+    return False
+
+
+def python_type_to_iterable_str(annotation: ast.expr | None) -> str:
+    unwrapped = unwrap_type_annotation(annotation)
+    if unwrapped is None:
+        return 'Iterable["Any"]'
+    type_str = ast.unparse(unwrapped)
+    if not is_builtin_type(unwrapped):
+        return f'Iterable["{type_str}"]'
+    return f"Iterable[{type_str}]"
+
+
+def get_iterable_type_for_col(annotation: ast.expr | None) -> str:
+    unwrapped = unwrap_type_annotation(annotation)
+    if unwrapped is None:
+        return 'Annotated["pl.Series", Any]'
+    if isinstance(unwrapped, ast.Name):
+        dtype = PYTHON_TYPE_TO_POLARS_DTYPE.get(unwrapped.id)
+        if dtype:
+            return f'Annotated["pl.Series", {dtype}]'
+        return 'Annotated["pl.Series", Any]'
+    if isinstance(unwrapped, ast.Subscript) and isinstance(unwrapped.value, ast.Name):
+        if unwrapped.value.id == "list":
+            return 'Annotated["pl.Series", "pl.List"]'
+    return 'Annotated["pl.Series", Any]'
+
+
+def get_random_value_expr(annotation: ast.expr | None) -> str:
+    unwrapped = unwrap_type_annotation(annotation)
+    if unwrapped is None:
+        return "None"
+    if isinstance(unwrapped, ast.Name):
+        type_name = unwrapped.id
+        if type_name == "str":
+            return "pl.Series([secrets.token_hex(8) for _ in range(n_rows)])"
+        if type_name == "int":
+            return "pl.Series(random.choices(range(-1000, 1000), k=n_rows))"
+        if type_name == "float":
+            return "pl.Series([random.uniform(-1000.0, 1000.0) for _ in range(n_rows)])"
+        if type_name == "bool":
+            return "pl.Series(random.choices([True, False], k=n_rows))"
+        if type_name == "bytes":
+            return "pl.Series([secrets.token_bytes(16) for _ in range(n_rows)])"
+        return "pl.Series([None] * n_rows)"
+    if isinstance(unwrapped, ast.Subscript) and isinstance(unwrapped.value, ast.Name):
+        if unwrapped.value.id == "list":
+            return "pl.Series([[random.randint(0, 100) for _ in range(3)] for _ in range(n_rows)])"
+    return "pl.Series([None] * n_rows)"
+
+
+# def _check_random_imports_needed(field_infos: list[tuple[str, ast.expr | None]]) -> tuple[bool, bool]:
+#     needs_random = False
+#     needs_secrets = False
+#     for _field_name, annotation in field_infos:
+#         unwrapped = unwrap_type_annotation(annotation)
+#         if unwrapped is None:
+#             continue
+#         if isinstance(unwrapped, ast.Name):
+#             type_name = unwrapped.id
+#             if type_name in {"int", "float", "bool"}:
+#                 needs_random = True
+#             elif type_name in {"str", "bytes"}:
+#                 needs_secrets = True
+#         elif isinstance(unwrapped, ast.Subscript) and isinstance(unwrapped.value, ast.Name):
+#             if unwrapped.value.id == "list":
+#                 needs_random = True
+#     return needs_random, needs_secrets
+
+
+def quote_pl_in_annotation(annotation_str: str) -> str:
+    """Quote pl.X types in annotation strings since pl is only available under TYPE_CHECKING."""
+    import re
+    # Match pl.X only when NOT already inside quotes (preceded by ' or ")
+    # Use negative lookbehind for quotes
+    return re.sub(r"(?<!['\"])(\bpl\.\w+)(?!['\"])", r"'\1'", annotation_str)
+
+
+def _get_module_name_from_output_path(file_path: Path) -> str:
+    """Get the module name from the output file path."""
+    resolved = file_path.resolve()
+    parts: list[str] = []
+    current = resolved.parent
+    while current != current.parent:
+        if not (current / "__init__.py").exists():
+            break
+        parts.append(current.name)
+        current = current.parent
+    parts.reverse()
+    return ".".join(parts) if parts else ""
+
+
+def get_module_level_helper_functions() -> list[str]:
+    """Get helper functions to be defined once at module level for self-contained mode.
+    Returns only the function definitions, not imports (imports are handled separately at file top).
+    """
+    from machineconfig.type_hinting.typedict import polars_schema_typeddict
+    
+    lines = []
+    lines.append("# Helper functions for self-contained mode (defined once at module level)")
+    lines.append("")
+    
+    # Add all helper functions
+    for func_name in ["_unwrap_type", "_get_polars_type", "get_polars_schema_from_typeddict", "get_polars_df_random_data_from_typeddict"]:
+        func = getattr(polars_schema_typeddict, func_name)
+        source = inspect.getsource(func)
+        for line in source.splitlines():
+            lines.append(line)
+        lines.append("")
+    
+    return lines
+
+
+def generate_for_class(class_name: str, field_infos: list[tuple[str, ast.expr | None]], source_module: str, dependency: Literal["import", "self-contained"] = "self-contained", output_file_path: Path | None = None) -> list[str]:
+    lines: list[str] = []
+    field_names = [fn for fn, _ in field_infos]
+
+    types_class_name = get_types_class_name(class_name)
+
+    names_class_name = f"{class_name}Names"
+    lines.append(f"class {names_class_name}:")
+    if field_infos:
+        for field_name in field_names:
+            lines.append(f'    {field_name}: Literal["{field_name}"] = "{field_name}"')
+    else:
+        lines.append("    pass")
+    lines.append("")
+    lines.append("")
+
+    names_literal = f"{class_name}_NAMES"
+    if field_names:
+        literal_values = ", ".join(f'"{fn}"' for fn in field_names)
+        lines.append(f'{names_literal}: TypeAlias = Literal[{literal_values}]')
+    else:
+        lines.append(f'{names_literal}: TypeAlias = Literal[""]')
+    lines.append("")
+    lines.append("")
+
+    lines.append(f"class {types_class_name}:")
+    if field_infos:
+        for field_name, annotation in field_infos:
+            if annotation is None:
+                raise ValueError(f"Field '{field_name}' in class '{class_name}' lacks an annotation")
+            unwrapped = unwrap_type_annotation(annotation)
+            if unwrapped is None:
+                raise ValueError(f"Field '{field_name}' in class '{class_name}' lacks an annotation")
+            annotation_source = ast.unparse(unwrapped)
+            annotation_source = quote_pl_in_annotation(annotation_source)
+            lines.append(f"    {field_name}: TypeAlias = {annotation_source}")
+    else:
+        lines.append("    pass")
+    lines.append("")
+    lines.append("")
+
+    wrapper_class_name = f"{class_name}_Wrapper"
+    lines.append(f"class {wrapper_class_name}:")
+    lines.append(f"    c = {names_class_name}")
+    lines.append(f"    ct: TypeAlias = {names_literal}")
+    lines.append(f'    e: TypeAlias = {class_name}')
+    lines.append(f"    t: TypeAlias = {types_class_name}")
+    lines.append("")
+    lines.append('    def __init__(self, df: "pl.DataFrame") -> None:')
+    lines.append("        self.df = df")
+    lines.append("")
+
+    if field_infos:
+        # Group fields by their return type to reduce number of overloads
+        grouped_fields: dict[str, list[str]] = {}
+        for field_name, annotation in field_infos:
+            col_type = get_iterable_type_for_col(annotation)
+            grouped_fields.setdefault(col_type, []).append(field_name)
+
+        if len(grouped_fields) == 1:
+            col_type = list(grouped_fields.keys())[0]
+            lines.append(f'    def get_col(self, name: {names_literal}) -> {col_type}:')
+            lines.append("        return self.df.select(name).to_series()")
+            lines.append("")
+        else:
+            for col_type, fields in grouped_fields.items():
+                lines.append("    @overload")
+                if len(fields) == 1:
+                    lines.append(f'    def get_col(self, name: Literal["{fields[0]}"]) -> {col_type}: ...')
+                else:
+                    literals = ", ".join(f'"{f}"' for f in fields)
+                    lines.append(f'    def get_col(self, name: Literal[{literals}]) -> {col_type}: ...')
+
+            lines.append(f'    def get_col(self, name: {names_literal}) -> Annotated["pl.Series", Any]:')
+            lines.append("        return self.df.select(name).to_series()")
+            lines.append("")
+
+        params: list[str] = []
+        dict_entries: list[str] = []
+        for field_name, annotation in field_infos:
+            iterable_type = python_type_to_iterable_str(annotation)
+            params.append(f"{field_name}: {iterable_type}")
+            dict_entries.append(f'"{field_name}": {field_name}')
+        params_str = ", ".join(params)
+        dict_str = "{" + ", ".join(dict_entries) + "}"
+        lines.append("    @staticmethod")
+        lines.append(f'    def make({params_str}) -> "{wrapper_class_name}":')
+        
+        if dependency == "import":
+            # Use fully qualified import from dtypes_utils
+            if output_file_path:
+                output_module = _get_module_name_from_output_path(output_file_path)
+                lines.append(f"        from {output_module}.dtypes_utils import get_polars_schema_from_typeddict as get_polars_schema")
+            else:
+                lines.append("        from machineconfig.type_hinting.polars_schema_typeddict import get_polars_schema_from_typeddict as get_polars_schema")
+        else:  # self-contained - use module-level function
+            lines.append("        get_polars_schema = get_polars_schema_from_typeddict")
+        
+        lines.append(f"        return {wrapper_class_name}(pl.DataFrame({dict_str}, schema=get_polars_schema({class_name})))")
+        lines.append("")
+
+        lines.append("    @staticmethod")
+        lines.append(f'    def make_fake(n_rows: int) -> "{wrapper_class_name}":')
+        
+        if dependency == "import":
+            # Use fully qualified import from dtypes_utils
+            if output_file_path:
+                output_module = _get_module_name_from_output_path(output_file_path)
+                lines.append(f"        from {output_module}.dtypes_utils import get_polars_df_random_data_from_typeddict")
+            else:
+                lines.append("        from machineconfig.type_hinting.polars_schema_typeddict import get_polars_df_random_data_from_typeddict")
+        else:  # self-contained - use module-level function
+            pass  # No imports needed, function is at module level
+        
+        lines.append(f"        return {wrapper_class_name}(get_polars_df_random_data_from_typeddict({class_name}, n_rows))")
+    else:
+        lines.append("    @staticmethod")
+        lines.append(f'    def make() -> "{wrapper_class_name}":')
+        lines.append("        import polars as pl")
+        lines.append(f"        return {wrapper_class_name}(pl.DataFrame())")
+        lines.append("")
+        lines.append("    @staticmethod")
+        lines.append(f'    def make_fake(n_rows: int) -> "{wrapper_class_name}":')
+        lines.append("        import polars as pl")
+        lines.append("        _ = n_rows")
+        lines.append(f"        return {wrapper_class_name}(pl.DataFrame())")
+    lines.append("")
+    lines.append("")
+    return lines

machineconfig/type_hinting/typedict/generators.py

@@ -0,0 +1,231 @@
+import ast
+import shutil
+from pathlib import Path
+from typing import Literal
+
+from machineconfig.type_hinting.typedict.ast_utils import load_target_class_fields
+from machineconfig.type_hinting.typedict.generator_helpers import (
+    collect_type_names_from_annotation,
+    extract_imports_from_source,
+    generate_for_class,
+    get_types_class_name,
+    unwrap_type_annotation,
+)
+
+
+def _get_module_name_from_path(file_path: Path) -> str:
+    resolved = file_path.resolve()
+    parts: list[str] = [resolved.stem]
+    current = resolved.parent
+    while current != current.parent:
+        if not (current / "__init__.py").exists():
+            break
+        parts.append(current.name)
+        current = current.parent
+    parts.reverse()
+    return ".".join(parts)
+
+
+def generate_names_file(source_file_path: Path, output_file_path: Path, search_paths: list[Path] | None = None, dependency: Literal["import", "self-contained"] = "self-contained") -> Path:
+    target_classes = load_target_class_fields(source_file_path, search_paths)
+    target_path = Path(output_file_path).resolve()
+    
+    # Handle dependency mode: copy dtypes_utils.py for 'import' mode
+    if dependency == "import":
+        source_polars_schema = Path(__file__).parent / "polars_schema_typeddict.py"
+        target_dtypes_utils = target_path.parent / "dtypes_utils.py"
+        shutil.copy2(source_polars_schema, target_dtypes_utils)
+
+    source_imports, local_type_aliases, local_classes = extract_imports_from_source(Path(source_file_path))
+
+    all_custom_types: dict[str, str | None] = {}
+    for _class_name, field_infos in target_classes:
+        for _field_name, annotation, field_imports in field_infos:
+            unwrapped = unwrap_type_annotation(annotation)
+            type_names = collect_type_names_from_annotation(unwrapped)
+            for type_name in type_names:
+                if type_name not in all_custom_types:
+                    if type_name in field_imports:
+                        all_custom_types[type_name] = field_imports[type_name][0]
+                    else:
+                        all_custom_types[type_name] = None
+
+    grouped_imports: dict[str, list[str]] = {}
+    needed_local_aliases: list[str] = []
+    needed_local_classes: list[str] = []
+    for type_name in sorted(all_custom_types.keys()):
+        module = all_custom_types[type_name]
+        if module:
+            grouped_imports.setdefault(module, []).append(type_name)
+        elif type_name in source_imports:
+            module = source_imports[type_name]
+            grouped_imports.setdefault(module, []).append(type_name)
+        elif type_name in local_type_aliases:
+            needed_local_aliases.append(type_name)
+        elif type_name in local_classes:
+            needed_local_classes.append(type_name)
+    
+    # Check if Any is actually used in get_col return type annotations
+    uses_any = False
+    for _class_name, field_infos in target_classes:
+        if not field_infos:  # Empty class won't have get_col with Any
+            continue
+        # Check if there are multiple different column types (which means we need Any fallback)
+        from machineconfig.type_hinting.typedict.generator_helpers import get_iterable_type_for_col
+        col_types = set()
+        for _field_name, annotation in [(fn, ann) for fn, ann, _ in field_infos]:
+            col_types.add(get_iterable_type_for_col(annotation))
+        if len(col_types) > 1:
+            uses_any = True
+            break
+
+    # Build typing imports based on what's needed
+    typing_imports = ["Annotated", "Literal", "TypeAlias", "TYPE_CHECKING", "overload"]
+    if uses_any:
+        typing_imports.insert(1, "Any")  # Insert after Annotated
+    
+    lines: list[str] = ["from collections.abc import Iterable", f"from typing import {', '.join(typing_imports)}"]
+    
+    # Add self-contained mode imports right at the top
+    if dependency == "self-contained":
+        lines.append("from typing import ReadOnly, get_origin, get_args")
+        lines.append("import polars as pl")
+        lines.append("import random")
+        lines.append("import secrets")
+    
+    lines.append("")
+
+    target_class_names = [class_name for class_name, _ in target_classes]
+    source_module = _get_module_name_from_path(source_file_path)
+    if target_class_names:
+        lines.append(f"from {source_module} import {', '.join(sorted(target_class_names))}")
+
+    for alias_name in sorted(needed_local_aliases):
+        lines.append(f"{alias_name}: TypeAlias = {local_type_aliases[alias_name]}")
+    if needed_local_aliases:
+        lines.append("")
+
+    # Runtime imports: types used in _Types classes (TypeAlias assignments) need to be available at runtime
+    for module, type_names in sorted(grouped_imports.items()):
+        lines.append(f"from {module} import {', '.join(sorted(type_names))}")
+    
+    # Check if numpy (np) is used in type aliases - look through all annotations
+    needs_numpy = False
+    for _class_name, field_infos in target_classes:
+        for _field_name, annotation, _field_imports in field_infos:
+            if annotation:
+                import ast
+                annotation_str = ast.unparse(annotation)
+                if 'np.' in annotation_str:
+                    needs_numpy = True
+                    break
+        if needs_numpy:
+            break
+    
+    if needs_numpy:
+        lines.append("import numpy as np")
+
+    lines.append("")
+    # Only add TYPE_CHECKING block for non-self-contained mode (self-contained imports polars at top)
+    if dependency != "self-contained":
+        lines.append("if TYPE_CHECKING:")
+        lines.append("    import polars as pl")
+    else:
+        # For self-contained, polars is already imported at the top
+        lines.append("if TYPE_CHECKING:")
+        lines.append("    pass")
+    all_type_checking_imports = sorted(set(needed_local_classes) - set(target_class_names))
+    if all_type_checking_imports:
+        lines.append(f"    from {source_module} import {', '.join(all_type_checking_imports)}")
+    lines.append("")
+    
+    # For self-contained mode, add helper functions at module level
+    if dependency == "self-contained":
+        from machineconfig.type_hinting.typedict.generator_helpers import get_module_level_helper_functions
+        helper_lines = get_module_level_helper_functions()
+        lines.extend(helper_lines)
+        lines.append("")
+
+    for class_name, field_infos in target_classes:
+        source_module = _get_module_name_from_path(source_file_path)
+        stripped_field_infos = [(fn, ann) for fn, ann, _ in field_infos]
+        lines.extend(generate_for_class(class_name, stripped_field_infos, source_module, dependency=dependency, output_file_path=target_path))
+
+    lines.append("")
+    lines.append('if __name__ == "__main__":')
+    lines.append("    import polars as pl")
+    lines.append("")
+
+    output_content = "\n".join(lines)
+    with target_path.open(mode="w", encoding="utf-8") as f:
+        f.write(output_content)
+    return target_path
+
+
+def generate_types_file(source_file_path: Path, output_file_path: Path, search_paths: list[Path] | None = None) -> Path:
+    target_classes = load_target_class_fields(source_file_path, search_paths)
+    target_path = Path(output_file_path).resolve()
+
+    source_imports, local_type_aliases, local_classes = extract_imports_from_source(Path(source_file_path))
+
+    all_custom_types: dict[str, str | None] = {}
+    for _class_name, field_infos in target_classes:
+        for _field_name, annotation, field_imports in field_infos:
+            unwrapped = unwrap_type_annotation(annotation)
+            type_names = collect_type_names_from_annotation(unwrapped)
+            for type_name in type_names:
+                if type_name not in all_custom_types:
+                    if type_name in field_imports:
+                        all_custom_types[type_name] = field_imports[type_name][0]
+                    else:
+                        all_custom_types[type_name] = None
+
+    grouped_imports: dict[str, list[str]] = {}
+    needed_local_aliases: list[str] = []
+    needed_local_classes: list[str] = []
+    for type_name in sorted(all_custom_types.keys()):
+        module = all_custom_types[type_name]
+        if module:
+            grouped_imports.setdefault(module, []).append(type_name)
+        elif type_name in source_imports:
+            module = source_imports[type_name]
+            grouped_imports.setdefault(module, []).append(type_name)
+        elif type_name in local_type_aliases:
+            needed_local_aliases.append(type_name)
+        elif type_name in local_classes:
+            needed_local_classes.append(type_name)
+
+    lines: list[str] = ["from typing import TypeAlias"]
+    for module, type_names in sorted(grouped_imports.items()):
+        lines.append(f"from {module} import {', '.join(sorted(type_names))}")
+    if needed_local_classes:
+        source_module = _get_module_name_from_path(source_file_path)
+        lines.append(f"from {source_module} import {', '.join(sorted(needed_local_classes))}")
+    lines.append("")
+    for alias_name in sorted(needed_local_aliases):
+        lines.append(f"{alias_name}: TypeAlias = {local_type_aliases[alias_name]}")
+    if needed_local_aliases:
+        lines.append("")
+    lines.append("")
+
+    for class_name, field_infos in target_classes:
+        types_class_name = get_types_class_name(class_name)
+        lines.append(f"class {types_class_name}:")
+        if field_infos:
+            for field_name, annotation, _ in field_infos:
+                if annotation is None:
+                    raise ValueError(f"Field '{field_name}' in class '{class_name}' lacks an annotation")
+                unwrapped = unwrap_type_annotation(annotation)
+                if unwrapped is None:
+                    raise ValueError(f"Field '{field_name}' in class '{class_name}' lacks an annotation")
+                annotation_source = ast.unparse(unwrapped)
+                lines.append(f"    {field_name}: TypeAlias = {annotation_source}")
+        else:
+            lines.append("    pass")
+        lines.append("")
+        lines.append("")
+
+    output_content = "\n".join(lines)
+    with target_path.open(mode="w", encoding="utf-8") as f:
+        f.write(output_content)
+    return target_path