Function shell

tortoise/cli/cli.py:377–432

Launch an interactive shell with Tortoise ORM context. Prefers IPython if available, falls back to ptpython. Requires at least one shell provider to be installed. Raises: CLIError: If neither IPython nor ptpython is installed

(ctx: CLIContext)

async def shell(ctx: CLIContext) -> None:
    """Launch an interactive shell with Tortoise ORM context.

    Prefers IPython if available, falls back to ptpython.
    Requires at least one shell provider to be installed.

    Raises:
        CLIError: If neither IPython nor ptpython is installed
    """
    # Detect which shell provider is available
    provider = _get_available_shell_provider()

    if provider is None:
        raise utils.CLIError(
            "No interactive shell available. Please install one of the following:\n"
            "  - IPython (recommended): pip install tortoise-orm[ipython]\n"
            "  - ptpython: pip install tortoise-orm[ptpython]\n"
            "  - Or install directly: pip install ipython (or ptpython)"
        )

    config = _load_config(ctx)

    # For IPython: Initialize context, prepare namespace, then launch synchronously
    # IPython manages its own event loop for autoawait
    if provider == ShellProvider.IPYTHON:
        async with tortoise_cli_context(config) as tortoise_ctx:
            # Prepare namespace with Tortoise context and useful imports
            namespace = {
                "Tortoise": Tortoise,
                "tortoise": tortoise_ctx,
                "apps": tortoise_ctx.apps,
            }
            # Add all models to namespace for easy access
            if tortoise_ctx.apps:
                for app_name, models_dict in tortoise_ctx.apps.items():
                    for model_name, model_class in models_dict.items():
                        namespace[model_name] = model_class

            # Launch IPython synchronously - it will manage its own event loop
            _launch_ipython_shell(namespace)
    else:
        # ptpython works fine in async context
        async with tortoise_cli_context(config) as tortoise_ctx:
            # Prepare namespace with Tortoise context and useful imports
            namespace = {
                "Tortoise": Tortoise,
                "tortoise": tortoise_ctx,
                "apps": tortoise_ctx.apps,
            }
            # Add all models to namespace for easy access
            if tortoise_ctx.apps:
                for app_name, models_dict in tortoise_ctx.apps.items():
                    for model_name, model_class in models_dict.items():
                        namespace[model_name] = model_class

            await _launch_ptpython_shell(namespace)