API Reference

This page provides an automated reference for the sus-inspector API, extracted directly from the source code.

sus_inspector.core

Core logic for the sus-inspector explorer.

Classes

InteractiveExplorer

The main 'sus' interface supporting both calls and operator overloading.

Source code in src/sus_inspector/core.py

class InteractiveExplorer:
    """The main 'sus' interface supporting both calls and operator overloading."""

    def __call__(self, obj: object, name: str = "root") -> object:
        """Inspect the object via standard call: sus(obj, name='my_obj').

        Args:
            obj: Object to inspect.
            name: Label for the object.

        Returns:
            object: The object untouched.

        """
        self._run(obj, name)
        return obj

    def __truediv__(self, obj: object) -> object | None:
        """Operator overloading: sus / obj.

        Args:
            obj: Object to inspect or Ellipsis for locals.

        Returns:
            object | None: The object untouched, or None if Ellipsis was used.

        """
        if obj is Ellipsis:
            # Capture local variables from the caller's frame
            current_frame = inspect.currentframe()
            if current_frame and current_frame.f_back:
                frame: FrameType = current_frame.f_back
                local_items = frame.f_locals.items()
                local_vars = {
                    str(k): v for k, v in local_items if not str(k).startswith("__")
                }
                self._run(local_vars, "locals")
            return None

        # Determine a reasonable default name
        name = getattr(obj, "__name__", None) or type(obj).__name__
        self._run(obj, name)
        return obj

    @staticmethod
    def _run(obj: object, name: str) -> None:
        """Start the Textual App lazily."""
        from sus_inspector.tui.app import ObjectExplorerApp  # noqa: PLC0415

        app = ObjectExplorerApp(obj, obj_name=name)
        app.run()

Functions

__call__(obj, name='root')

Inspect the object via standard call: sus(obj, name='my_obj').

Parameters:

Name	Type	Description	Default
obj	object	Object to inspect.	required
name	str	Label for the object.	'root'

Returns:

Name	Type	Description
object	object	The object untouched.

Source code in src/sus_inspector/core.py

def __call__(self, obj: object, name: str = "root") -> object:
    """Inspect the object via standard call: sus(obj, name='my_obj').

    Args:
        obj: Object to inspect.
        name: Label for the object.

    Returns:
        object: The object untouched.

    """
    self._run(obj, name)
    return obj

__truediv__(obj)

Operator overloading: sus / obj.

Parameters:

Name	Type	Description	Default
obj	object	Object to inspect or Ellipsis for locals.	required

Returns:

Type	Description
object | None	object | None: The object untouched, or None if Ellipsis was used.

Source code in src/sus_inspector/core.py

def __truediv__(self, obj: object) -> object | None:
    """Operator overloading: sus / obj.

    Args:
        obj: Object to inspect or Ellipsis for locals.

    Returns:
        object | None: The object untouched, or None if Ellipsis was used.

    """
    if obj is Ellipsis:
        # Capture local variables from the caller's frame
        current_frame = inspect.currentframe()
        if current_frame and current_frame.f_back:
            frame: FrameType = current_frame.f_back
            local_items = frame.f_locals.items()
            local_vars = {
                str(k): v for k, v in local_items if not str(k).startswith("__")
            }
            self._run(local_vars, "locals")
        return None

    # Determine a reasonable default name
    name = getattr(obj, "__name__", None) or type(obj).__name__
    self._run(obj, name)
    return obj

sus_inspector.cli

CLI commands for sus-inspector, including global injection.

Functions

get_injection_code()

Return the code to be injected into usercustomize.py.

Returns:

Name	Type	Description
str	str	Python code block.

Source code in src/sus_inspector/cli.py

def get_injection_code() -> str:
    """Return the code to be injected into usercustomize.py.

    Returns:
        str: Python code block.

    """
    return f"""
{INJECTION_MARKER}
try:
    import builtins

    from sus_inspector import sus

    builtins.sus = sus
except ImportError:
    pass
{INJECTION_END_MARKER}
"""

get_target_info(*, is_global_user)

Return the site-packages directory and the filename to use.

Parameters:

Name	Type	Description	Default
is_global_user	bool	Whether to target global user site-packages.	required

Returns:

Type	Description
tuple[Path, str]	tuple[Path, str]: (target_directory, filename).

Source code in src/sus_inspector/cli.py

def get_target_info(*, is_global_user: bool) -> tuple[Path, str]:
    """Return the site-packages directory and the filename to use.

    Args:
        is_global_user: Whether to target global user site-packages.

    Returns:
        tuple[Path, str]: (target_directory, filename).

    """
    if is_global_user:
        # User-specific global site-packages
        return Path(site.getusersitepackages()), "usercustomize.py"

    # Virtual environment or system-wide site-packages
    # We prefer the first one in the list
    site_packages = site.getsitepackages()
    if site_packages:
        target_dir = Path(site_packages[0])
    else:
        target_dir = Path(site.getusersitepackages())
    return target_dir, "sitecustomize.py"

inject_permanently(*, is_global_user=False)

Inject sus permanently into builtins. Targets venv by default.

Parameters:

Name	Type	Description	Default
is_global_user	bool	Whether to target global user site-packages.	False

Source code in src/sus_inspector/cli.py

def inject_permanently(*, is_global_user: bool = False) -> None:
    """Inject sus permanently into builtins. Targets venv by default.

    Args:
        is_global_user: Whether to target global user site-packages.

    """
    target_dir, filename = get_target_info(is_global_user=is_global_user)
    target_path = target_dir / filename
    scope_name = "GLOBAL USER" if is_global_user else "VIRTUAL ENV"

    msg = (
        f"This command will inject [bold]sus[/bold] into your environment.\n\n"
        f"• Target: [blue]{target_path}[/blue]\n"
        "• [bold]sus[/bold] will be available globally in this environment.\n"
        "• [italic]try/except[/italic] ensures your Python won't break."
    )
    console.print(Panel(msg, title=f"🔍 Setup ({scope_name})", expand=False))

    prompt = f"Do you want to proceed with the {scope_name.lower()} installation?"
    if not Confirm.ask(prompt):
        console.print("[red]Aborted.[/red]")
        return

    if not _ensure_dir(target_dir):
        sys.exit(1)

    if _check_already_injected(target_path, filename):
        return

    _write_injection(target_path)

remove_injection(*, is_global_user=False)

Remove the sus-inspector injection. Targets venv by default.

Parameters:

Name	Type	Description	Default
is_global_user	bool	Whether to target global user site-packages.	False

Source code in src/sus_inspector/cli.py

def remove_injection(*, is_global_user: bool = False) -> None:
    """Remove the sus-inspector injection. Targets venv by default.

    Args:
        is_global_user: Whether to target global user site-packages.

    """
    target_dir, filename = get_target_info(is_global_user=is_global_user)
    target_path = target_dir / filename

    if not target_path.exists():
        console.print(f"[yellow]No {filename} found at {target_path}.[/yellow]")
        return

    with target_path.open(encoding="utf-8") as f:
        lines = f.readlines()

    new_lines: list[str] = []
    in_block = False
    found = False

    for line in lines:
        if INJECTION_MARKER in line:
            in_block = True
            found = True
            continue
        if INJECTION_END_MARKER in line:
            in_block = False
            continue
        if not in_block:
            new_lines.append(line)

    if not found:
        path_str = str(target_path)
        msg = f"[yellow]No sus-inspector injection found in {path_str}.[/yellow]"
        console.print(msg)
        return

    try:
        with target_path.open("w", encoding="utf-8") as f:
            f.writelines(new_lines)
        path_str = str(target_path)
        msg = f"[bold green]Success![/bold green] Removed from {path_str}."
        console.print(msg)
    except OSError as e:
        console.print(f"[red]Failed to update {target_path}:[/red] {e}")
        sys.exit(1)