yera.apps.exceptions

App-specific exceptions.

Symbols

class AppExit — Request to end the current app run immediately.
class AppQuit — Request to end the current app run because the user chose to stop.
class AppRuntimeError — Raised when an app exits with a non-zero exit code.
class ErrorCause — Structured metadata about the cause of an app exit error.

AppExit

Inherits: BaseException
Subclasses: AppQuit

Request to end the current app run immediately.

Raised by exit. Subclasses BaseException, like SystemExit, so an app's own except Exception handlers do not swallow it. The outermost app catches it and emits the run's single exit event.

Attributes

exit_code

Process-style exit code; 0 for success.

reason

Human-readable summary of why the run ended.

return_value

Value the run returns, checked against the outermost app's declared return type on success.

error_cause

Optional structured cause metadata for failure exits.

Methods

__init__ — Build an app exit request with its result and diagnostic details.

AppExit.__init__

__init__(
    exit_code: int,
    reason: str,
    return_value: object,
    error_cause: ErrorCause | None = None,
) → None

Build an app exit request with its result and diagnostic details.

Parameters

exit_code
type: int

Process-style code describing whether the run succeeded.

reason
type: str

Human-readable explanation for ending the run.

return_value
type: object

Value to return from the outermost app.

error_cause
type: ErrorCause | None = None

Structured metadata describing a failure, if present.

AppQuit

Inherits: AppExit

Request to end the current app run because the user chose to stop.

Raised by quit. Carries no return value, so it is not checked against the app's declared return type.

Methods

__init__ — Build a successful exit request representing a user-initiated quit.

AppQuit.__init__

__init__() → None

Build a successful exit request representing a user-initiated quit.

AppRuntimeError

Inherits: RuntimeError

Raised when an app exits with a non-zero exit code.

Raised by the app decorator instead of calling sys.exit, so callers can catch a normal exception and e.g. call sys.exit(exit_code) in a runner.

Methods

__init__ — Build an exception describing an unsuccessful app run.

AppRuntimeError.__init__

__init__(
    message: str,
    exit_code: int,
    reason: str | None = None,
    app_name: str | None = None,
    app_identifier: str,
    error_cause: ErrorCause,
) → None

Build an exception describing an unsuccessful app run.

Parameters

message
type: str

User-facing description of the runtime failure.

exit_code
type: int

Process-style non-zero failure code.

reason
type: str | None = None

App-supplied explanation for the failure, if available.

app_name
type: str | None = None

Display name of the failed app, if available.

app_identifier
type: str

Stable identifier of the failed app.

error_cause
type: ErrorCause

Structured metadata describing the underlying failure.

ErrorCause

Inherits: BaseModel

Structured metadata about the cause of an app exit error.

Always includes error_type. May include additional fields like block_type for specific error types (e.g., UnsupportedAwaitUserBlockError).

Fields

error_type
type: str (required)
block_type
type: str | None = None