Errors, status, and panel hints

Distinguish environment status, operation exceptions, and application results

Environment status indicates availability. An operation exception means a call did not complete according to its contract. An action may also return normally with an application failure result. Keep these separate. Page-side WebUIError uses communication error codes; Python WebErrorKind uses public error categories. They are different enums.

Python operation exceptions

NexusWebError

Public definitions

class NexusWebError(RuntimeError):
  __init__(<signature-unavailable: ValueError>)

WebOperationError

Public definitions

class WebOperationError(NexusWebError):
  __init__(info: 'WebErrorInfo') -> 'None'
  hint: str | None
  info: WebErrorInfo
  kind: WebErrorKind

WebErrorInfo

Public definitions

class WebErrorInfo (dataclass frozen slots):
  __init__(kind: 'WebErrorKind', message: 'str', hint: 'str | None' = None) -> None
  kind: WebErrorKind
  message: str
  hint: str | None = None

WebErrorKind

Public definitions

class WebErrorKind (StrEnum):
  INVALID_INPUT = 'invalid_input'
  PERMISSION_DENIED = 'permission_denied'
  NOT_FOUND = 'not_found'
  ALREADY_EXISTS = 'already_exists'
  RESOURCE_EXHAUSTED = 'resource_exhausted'
  RUNTIME_MISSING = 'runtime_missing'
  RUNTIME_INCOMPATIBLE = 'runtime_incompatible'
  HELPER_FAILED = 'helper_failed'
  RENDER_FAILED = 'render_failed'
  NAVIGATION_BLOCKED = 'navigation_blocked'
  INTERNAL_ERROR = 'internal_error'

Item	Usage and limitations
invalid_input / permission_denied	Check arguments and declared access scope. Do not hide errors by widening permissions.
not_found / already_exists	Check resource existence and duplicate windows; follow the entry point's window behavior.
resource_exhausted	Check instance, resource, or capacity limits.
runtime_missing / runtime_incompatible	Guide users through the existing runtime installation flow.
helper_failed / render_failed	Preserve the original message and hint; investigate runtime and page-display issues.
navigation_blocked	Check supported page sources. Retries cannot bypass frozen remote capabilities.
internal_error	Preserve reproduction steps for the author. Do not treat unexpected errors as success.

After catching WebOperationError, read exc.info.message, exc.kind, and exc.hint. NexusWebError is the base class. signature-unavailable means the baseline could not reflect a built-in constructor signature; it is not an argument to supply.

Environment availability is a read-only check

WebRuntimeStatus

Public definitions

class WebRuntimeStatus (dataclass frozen slots):
  __init__(available: 'bool', status: 'str', reason: 'str', hint: 'str | None' = None, can_retry: 'bool' = False) -> None
  available: bool
  status: str
  reason: str
  hint: str | None = None
  can_retry: bool = False

probe_web_runtime_availability

Public definitions

def probe_web_runtime_availability() -> 'WebRuntimeStatus'

require_web_runtime_available

Public definitions

def require_web_runtime_available() -> 'None'

available indicates availability, reason/hint explain it, and can_retry indicates retryability. probe returns status; require raises when unavailable. Neither replaces real window and interaction verification. Preserve the actual status string; the common values listed here are not an exhaustive promise.

Show hints in a Blender panel

Import the separate public ui module with from .nexus_web import ui. It draws in Blender panels, not web notifications. retryable describes the hint; it does not create a retry button or install anything.

WebUINotice

Public definitions

class WebUINotice (dataclass frozen slots):
  __init__(code: 'str', severity: 'WebUINoticeSeverity', message: 'str', title: 'str' = '', retryable: 'bool' = False) -> None
  code: str
  severity: WebUINoticeSeverity
  message: str
  title: str = ''
  retryable: bool = False

WebUINoticeSeverity

Public definitions

WebUINoticeSeverity = typing.Literal['info', 'warning', 'error']

ui_notice

Public definitions

def ui_notice(message: 'str', *, code: 'str' = 'ui_notice', severity: 'WebUINoticeSeverity' = 'info', title: 'str' = '', retryable: 'bool' = False) -> 'WebUINotice'

web_runtime_notice

Public definitions

def web_runtime_notice(status: 'WebRuntimeStatus | None' = None) -> 'WebUINotice | None'

draw_ui_message

Public definitions

def draw_ui_message(layout: 'object', message: 'str', *, code: 'str' = 'ui_message', severity: 'WebUINoticeSeverity' = 'info', title: 'str' = '', width: 'int' = 72, max_lines: 'int | None' = None, boxed: 'bool' = True) -> 'bool'

draw_ui_notice

Public definitions

def draw_ui_notice(layout: 'object', notice: 'WebUINotice', *, width: 'int' = 72, max_lines: 'int | None' = None, boxed: 'bool' = True) -> 'bool'

draw_web_runtime_notice

Public definitions

def draw_web_runtime_notice(layout: 'object', status: 'WebRuntimeStatus | None' = None, *, width: 'int' = 72, max_lines: 'int | None' = None, boxed: 'bool' = True) -> 'bool'

wrap_ui_text

Public definitions

def wrap_ui_text(text: 'str', *, width: 'int' = 72, max_lines: 'int | None' = None, placeholder: 'str' = '...') -> 'tuple[str, ...]'

Item	Usage and limitations
ui_notice	Creates an immutable hint and normalizes title/text whitespace. severity is info, warning, or error.
web_runtime_notice	Pass status or omit it to check now. Returns None when available. Preparing is informational; other unavailable states are errors.
draw_ui_notice / draw_ui_message	Returns True when drawing nonempty text, otherwise False. layout needs Blender's label method and, with boxed=True, box.
draw_web_runtime_notice	Returns False when available without adding a success message.
wrap_ui_text	Returns a tuple of strings. width defaults to 72 with a minimum of 12 and measures display width, not pixels. max_lines must be positive or None. Invalid arguments raise ValueError.

Place in an existing panel's draw method after copying nexus_web into the package

python

from .nexus_web import ui

def draw(self, context):
    if ui.draw_web_runtime_notice(self.layout):
        return
    self.layout.label(text="网页功能可用")

Handle and verify

Do not download or install in draw. Let the existing card handle the user's choice, then open the window normally once available. See Installation troubleshooting, Restarts and conflicts and Page errors and asynchronous calls.