Ops Exceptions

Exception hierarchy for the ops (session management) subsystem.

Exception Hierarchy

KstlibError
└── OpsError
    ├── BackendNotFoundError
    │   ├── TmuxNotFoundError
    │   └── ContainerRuntimeNotFoundError
    └── SessionError
        ├── SessionExistsError
        ├── SessionNotFoundError
        ├── SessionStartError
        ├── SessionAttachError
        ├── SessionStopError
        └── SessionAmbiguousError

Base Exception

exception kstlib.ops.exceptions.OpsError

Bases: KstlibError

Base exception for all ops module errors.

All ops-specific exceptions inherit from this class, allowing for easy catching of any ops error.

Backend Not Found Errors

exception kstlib.ops.exceptions.BackendNotFoundError

Bases: OpsError, FileNotFoundError

Backend binary (tmux, podman, docker) not found in PATH.

Raised when the required backend binary is not installed or not accessible from the current PATH.

exception kstlib.ops.exceptions.TmuxNotFoundError

Bases: BackendNotFoundError

tmux binary not found in PATH.

Install tmux to use the tmux backend: - macOS: brew install tmux - Ubuntu/Debian: apt install tmux - Windows: Use WSL2 with tmux installed

exception kstlib.ops.exceptions.ContainerRuntimeNotFoundError

Bases: BackendNotFoundError

Container runtime (podman or docker) not found in PATH.

Install podman or docker to use the container backend: - Podman: https://podman.io/getting-started/installation - Docker: https://docs.docker.com/get-docker/

Raised when the required backend binary is not installed or not in PATH.

Session Errors

exception kstlib.ops.exceptions.SessionError

Bases: OpsError

Base exception for session-related errors.

All session operation exceptions inherit from this class.

exception kstlib.ops.exceptions.SessionExistsError(name, backend)

Bases: SessionError

Session or container with this name already exists.

Raised when attempting to create a session with a name that is already in use by another session or container.

__init__(self, name: 'str', backend: 'str') → 'None' -> None

Initialize SessionExistsError.

Parameters:

• name (str) – The session name that already exists.

• backend (str) – The backend type (tmux, container).

exception kstlib.ops.exceptions.SessionNotFoundError(name, backend)

Bases: SessionError

Session or container not found.

Raised when attempting to access a session that does not exist.

__init__(self, name: 'str', backend: 'str') → 'None' -> None

Initialize SessionNotFoundError.

Parameters:

• name (str) – The session name that was not found.

• backend (str) – The backend type (tmux, container).

exception kstlib.ops.exceptions.SessionStartError(name, backend, reason)

Bases: SessionError

Failed to start session or container.

Raised when the backend command to create a new session fails.

__init__(self, name: 'str', backend: 'str', reason: 'str') → 'None' -> None

Initialize SessionStartError.

Parameters:

• name (str) – The session name that failed to start.

• backend (str) – The backend type (tmux, container).

• reason (str) – The reason for the failure.

exception kstlib.ops.exceptions.SessionAttachError(name, backend, reason)

Bases: SessionError

Failed to attach to session or container.

Raised when the backend command to attach to a session fails. This can happen if the session is not running or if the terminal is not interactive.

__init__(self, name: 'str', backend: 'str', reason: 'str') → 'None' -> None

Initialize SessionAttachError.

Parameters:

• name (str) – The session name that failed to attach.

• backend (str) – The backend type (tmux, container).

• reason (str) – The reason for the failure.

exception kstlib.ops.exceptions.SessionStopError(name, backend, reason)

Bases: SessionError

Failed to stop session or container.

Raised when the backend command to stop a session fails.

__init__(self, name: 'str', backend: 'str', reason: 'str') → 'None' -> None

Initialize SessionStopError.

Parameters:

• name (str) – The session name that failed to stop.

• backend (str) – The backend type (tmux, container).

• reason (str) – The reason for the failure.

exception kstlib.ops.exceptions.SessionAmbiguousError(name, backends)

Bases: SessionError

Session exists in multiple backends.

Raised when auto-detection finds a session in both tmux and container backends, requiring explicit backend specification.

__init__(self, name: 'str', backends: 'list[str]') → 'None' -> None

Initialize SessionAmbiguousError.

Parameters:

• name (str) – The session name that exists in multiple backends.

• backends (list[str]) – List of backend names where the session was found.

Raised when auto-detection finds a session in both tmux and container backends. Use --backend to disambiguate.

Usage Examples

from kstlib.ops.exceptions import (
    OpsError,
    SessionExistsError,
    SessionNotFoundError,
    TmuxNotFoundError,
    ContainerRuntimeNotFoundError,
    SessionAmbiguousError,
)

try:
    session.start("python app.py")
except TmuxNotFoundError:
    print("Install tmux: apt install tmux")
except ContainerRuntimeNotFoundError:
    print("Install podman or docker")
except SessionExistsError:
    print("Session already running, stop it first")
except SessionAmbiguousError as e:
    print(f"Found in {e.backends}, use --backend to specify")
except OpsError as e:
    print(f"Ops error: {e}")