Framework entry points and lifecycle

Choose the call site first

These APIs are called from your add-on's Python code. Use relative imports within the add-on. Importing the framework does not start runtime components. For your first build, read Complete starter tutorial; use this reference for arguments and results while coding.

from .nexus_web import (
    bind, register_provider, unregister_provider,
    probe_web_runtime_availability, require_web_runtime_available,
    WebOperationError,
)
from .nexus_web import web

1. Register the framework copy when enabling the add-on, then register your operators and panels.
2. Bind a client on demand when the user opens a tool, then register actions and state.
3. Use the same client for windows, state queries, and communication.
4. On disable, remove your entry points and callbacks, release clients, then unregister the framework.

In public definitions, self denotes an instance method parameter that you do not pass explicitly. Quoted type annotations are Python forward references. Definitions are reference material, not a complete executable add-on.

Register and unregister

def register_provider() -> 'None'

Takes no arguments and returns no data. Call it in the add-on's register() to participate in service coordination. Repeated registration is idempotent but does not clear existing errors. Registration neither opens a window nor guarantees binding on the next line: cold-start coordination may return a retryable public binding error.

def unregister_provider() -> 'None'

Call it in the add-on's unregister() after releasing all its clients. Unregistration may be rejected while this copy serves other add-ons. Preserve and surface the error; do not swallow it and report success. Do not select, take over, or close other add-ons' services yourself.

Follow the complete registration and failure-handling structure in Starter template. Do not guess service readiness using fixed delays.

bind: obtain an add-on client

def bind(plugin_id: 'str', *, root: 'Path | str | None' = None, client_key: 'str | None' = None) -> 'WebPlugin'

Returns WebPlugin. Within one framework copy, valid bindings with the same add-on, client, and resource root reuse the existing handle. Changing the root for the same identity fails. Changing a client key cannot bypass window ownership or update an already loaded framework.

from pathlib import Path
from .nexus_web import bind, WebPlugin

_plugin: WebPlugin | None = None

def get_plugin() -> WebPlugin:
    global _plugin
    if _plugin is None or _plugin.disposed:
        _plugin = bind(__package__, root=Path(__file__).resolve().parent)
    return _plugin

Merge this fragment into the root entry point's existing lifecycle; it does not replace the complete template. Binding may fail before registration, during unstable startup, on identity or root conflicts, or when the old service is no longer usable. Show errors and recovery hints at the calling entry point.

WebPlugin: available members

class WebPlugin:
  begin_drag(self, window_key: 'str', *, preview: 'WebDragPreview', mode: "Literal['release', 'click']" = 'release', hide_source: 'bool' = False, validate_target: 'WebDragValidator | None' = None) -> 'WebDragState'
  bridge(self) -> 'WebBridge'
  browser(self, window_key: 'str') -> 'WebBrowser'
  cancel_drag(self, drag_id: 'str') -> 'WebDragState | None'
  @property client_key(self) -> 'str'
  close_window(self, window_key: 'str', *, reason: 'str' = 'window_close') -> 'WebWindowCloseResult'
  close_windows(self, logical_window_key: 'str', *, reason: 'str' = 'window_close') -> 'WebWindowCloseResult'
  dispose(self) -> 'None'
  @property disposed(self) -> 'bool'
  drag_state(self, drag_id: 'str') -> 'WebDragState | None'
  is_window_hidden(self, window_key: 'str') -> 'bool'
  open_window(self, window_key: 'str', spec: 'WebWindowSpec', *, target: 'WebAreaTarget | None' = None, replace_existing: 'bool' = False) -> 'WebWindowOpenResult'
  @property plugin_id(self) -> 'str'
  @property root(self) -> 'Path | None'
  show_window(self, window_key: 'str') -> 'bool'

Obtain clients through bind. Do not construct WebPlugin directly, read underscore-prefixed members, or depend on internal service objects.

Check runtime component availability

def probe_web_runtime_availability() -> 'WebRuntimeStatus'

Returns readable status without starting runtime components. Useful for panel hints and pre-enable checks. It does not replace user-confirmed download or local installation, and does not prove a page loaded successfully.

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

• available: current availability. Check this boolean rather than the reason wording.
• status: status identifier; reason is explanatory text and hint is an optional recovery suggestion.
• can_retry: retryability hint, False by default. It neither guarantees success nor authorizes unlimited retries.

def require_web_runtime_available() -> 'None'

Returns None when available; otherwise raises WebOperationError. Use probe to display status and require to handle unavailability as an exception. Neither is an installation command. Use the template's panel notice and see Install and check runtime components.

Release, failure, and restart

plugin.dispose() After successful release, the client no longer accepts application operations. Releasing it again returns immediately. It does not remove panels, timers, or callbacks registered by your add-on. Calling only bridge.dispose() clears bridge registrations and does not replace full client disposal.

def release_plugin() -> None:
    global _plugin
    if _plugin is not None:
        _plugin.dispose()
        _plugin = None

This fragment uses the _plugin above. Clear its reference only after dispose succeeds. If cleanup fails, retain the object and error, but do not continue using it as a healthy client. After your own cleanup and client release, call unregister_provider. Updating disk files does not replace the running service. For required restarts, see Framework update guide.

Handle exceptions and result objects separately

Binding, declarations, and browser controls may raise WebOperationError; window open/close operations instead require checking the returned ok. Catching exceptions is not enough; inspect failed results and do not treat the result object itself as a success boolean.

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

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

exc.kind identifies the error category; exc.info.message explains it; exc.hint is an optional suggestion. Fix invalid declaration parameters, install missing runtime components, and investigate source or restart for identity/generation issues. Reinstallation is not a universal fix.

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'

This page covers entry-point errors. Full details: Errors and hints and Action callback reference.