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

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

machineconfig/type_hinting/typedict/polars_schema.py

@@ -0,0 +1,24 @@
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import polars as pl
+
+
+def get_polars_schema(typed_dict: type) -> "dict[str, pl.DataType]":
+    import polars as pl
+
+    def _get_polars_type(python_type: Any) -> pl.DataType:
+        if python_type == str:
+            return pl.String()
+        if python_type == float:
+            return pl.Float64()
+        if python_type == int:
+            return pl.Int64()
+        if python_type == bool:
+            return pl.Boolean()
+        return pl.String()
+
+    schema: dict[str, pl.DataType] = {}
+    for k, v in typed_dict.__annotations__.items():
+        schema[k] = _get_polars_type(v)
+    return schema

machineconfig/type_hinting/typedict/polars_schema_typeddict.py

@@ -0,0 +1,63 @@
+from typing import Any, ReadOnly, get_origin, get_args, TYPE_CHECKING
+import random
+import secrets
+
+if TYPE_CHECKING:
+    import polars as pl
+
+
+def _unwrap_type(python_type: Any) -> Any:
+    """Unwrap ReadOnly and other type wrappers to get the inner type."""
+    origin = get_origin(python_type)
+    if origin is ReadOnly:
+        args = get_args(python_type)
+        return args[0] if args else python_type
+    return python_type
+
+
+def _get_polars_type(python_type: Any) -> "pl.DataType":
+    """Convert Python types to appropriate Polars types, handling ReadOnly wrappers."""
+    unwrapped = _unwrap_type(python_type)
+    import polars as pl
+    if unwrapped is str:
+        return pl.String()
+    if unwrapped is float:
+        return pl.Float64()
+    if unwrapped is int:
+        return pl.Int64()
+    if unwrapped is bool:
+        return pl.Boolean()
+    return pl.String()
+
+
+def get_polars_schema_from_typeddict(typed_dict: type) -> dict[str, "pl.DataType"]:
+    """Convert a TypedDict to a Polars schema, properly handling ReadOnly wrappers."""
+    # import polars as pl
+    schema: dict[str, "pl.DataType"] = {}
+    for k, v in typed_dict.__annotations__.items():
+        schema[k] = _get_polars_type(v)
+    return schema
+
+
+def get_polars_df_random_data_from_typeddict(typed_dict: type, n_rows: int) -> "pl.DataFrame":
+    """Generate a Polars DataFrame with random data based on a TypedDict definition."""
+    data: dict[str, "pl.Series"] = {}
+    import polars as pl
+    for k, v in typed_dict.__annotations__.items():
+        unwrapped = _unwrap_type(v)
+        if unwrapped is str:
+            data[k] = pl.Series([secrets.token_hex(8) for _ in range(n_rows)])
+        elif unwrapped is int:
+            data[k] = pl.Series(random.choices(range(-1000, 1000), k=n_rows))
+        elif unwrapped is float:
+            data[k] = pl.Series([random.uniform(-1000.0, 1000.0) for _ in range(n_rows)])
+        elif unwrapped is bool:
+            data[k] = pl.Series(random.choices([True, False], k=n_rows))
+        elif unwrapped is bytes:
+            data[k] = pl.Series([secrets.token_bytes(16) for _ in range(n_rows)])
+        elif get_origin(unwrapped) is list:
+             data[k] = pl.Series([[random.randint(0, 100) for _ in range(3)] for _ in range(n_rows)])
+        else:
+            data[k] = pl.Series([None] * n_rows)
+            
+    return pl.DataFrame(data, schema=get_polars_schema_from_typeddict(typed_dict))

machineconfig/utils/accessories.py

@@ -110,3 +110,27 @@ def get_repo_root(path: "Path") -> Optional["Path"]:
 
 if __name__ == "__main__":
     from pathlib import Path
+
+
+def display_with_flashy_style(msg: str, title: str) -> None:
+    """Display a flashy, unmissable share URL announcement."""
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.text import Text
+    from rich.align import Align
+    console = Console()
+    url_text = Text(msg, style="bold bright_cyan underline")
+    message = Text.assemble(
+        ("🚀 ", "bright_red"),
+        url_text,
+        (" 🚀", "bright_red")
+    )
+    panel = Panel(
+        Align.center(message),
+        title=f"[bold bright_green]🌐 {title} 🌐[/bold bright_green]",
+        subtitle="[italic bright_yellow]⚡ Click the link above to access your shared files! ⚡[/italic bright_yellow]",
+        border_style="bright_magenta",
+        padding=(1, 2),
+        expand=False
+    )
+    console.print(panel)