duck.app.base

Base application primitives shared by Duck application classes.

Module Contents

Classes

BaseApp

Provides shared configuration and URL helpers for Duck app classes.

Data

APPS_REGISTRY

API

duck.app.base.APPS_REGISTRY: Dict[str, duck.app.base.BaseApp]

None

class duck.app.base.BaseApp(name: Optional[str] = None, addr: str = DEFAULT_ADDR, port: int = DEFAULT_PORT, domain: Optional[str] = None, server_url: Optional[str] = None, uses_ipv6: bool = False, enable_https: bool = False, no_checks: bool = False, workers: Optional[int] = None, force_worker_processes: bool = False, events: Optional[Dict[str, Optional[Callable]]] = None)

Provides shared configuration and URL helpers for Duck app classes.

Subclasses are responsible for creating their own server instance and implementing lifecycle methods such as start_server, run, and stop.

Initialization

Initializes shared app configuration.

Parameters:

• name – Unique name to your application.

• addr – Address the server binds to.

• port – Port the server binds to.

• domain – Public-facing domain. Defaults to the bind address.

• server_url – Public-facing absolute server URL.

• uses_ipv6 – Whether the app should bind using IPv6.

• enable_https – Whether HTTPS is enabled for this app.

• workers – Optional number of server workers.

• force_worker_processes –

  Determines whether to use worker processes instead of the default worker threads. By default, when workers is greater than 1, the server will use worker threads. Threads avoid cross-process synchronization issues—such as component registry mismatches (e.g., issues with Lively components) that occur when state lives in separate processes.

  Set this flag to True only when process isolation is explicitly desired and you do not require shared in-memory synchronization between workers.

• events – Events to handle e.g. {“on_start”: some_callable}. Defaults to None.

Raises:

ApplicationError – If the provided bind address is invalid.

DEFAULT_ADDR

‘localhost’

DEFAULT_PORT

8000

_on_app_start()

Internal method called on application start.

property absolute_uri: str

Returns application server absolute URL.

property absolute_ws_uri: str

Returns application server absolute WebSockets URL.

build_absolute_uri(path: str = '') → str

Builds an absolute HTTP URL from a path.

Parameters:

path – URL path to append to the app URL.

Returns:

Normalized absolute URL.

build_absolute_ws_uri(path: str = '') → str

Builds an absolute WebSocket URL from a path.

Parameters:

path – URL path to append to the WebSocket URL.

Returns:

Normalized absolute WebSocket URL.

dispatch_event(event: str)

Dispatch an event and make event handlers handle the event.

classmethod get_all_apps() → Dict[str, duck.app.base.BaseApp]

Returns all created apps.

classmethod get_app_by_name()

Returns an app instance by name or else an ApplicationError is raised.

classmethod register_app(name: str, app: duck.app.base.BaseApp)

Registers an application.

register_event(event: str, handler: Optional[Callable] = None)

Register an event.

Parameters:

• event – The event to be handled.

• handler – An optional callable to handle the event. Defaults to None.

register_ports() → None

Registers a ports as occupied by this app - will be implemented by subclass.

Note: It registers the app port by default.

static resolve_domain(addr: str, domain: Optional[str] = None, uses_ipv6: bool = False) → str

Resolves the public domain for the app.

Parameters:

• addr – Bind address used as fallback.

• domain – Explicit public-facing domain.

• uses_ipv6 – Whether the address is IPv6.

Returns:

A browser-safe domain string.

resolve_name(name: Optional[str] = None) → str

Resolves a unique identifier for the app.

Parameters:

name – Name to use.

Returns:

A unique name string.

resolve_server_url(server_url: Optional[str] = None) → str

Resolves the public absolute server URL.

Parameters:

server_url – Explicit public-facing URL.

Returns:

Absolute server URL for URL generation.

abstractmethod run()

The method for running the web application.

run_checks()

Run applications checks, will be implemented by subclass.

property running: bool

Returns True if the main server running else False.

property server_up: bool

Checks whether the assigned server is running.

Returns:

True if the server exists and is running, otherwise False.

abstractmethod stop()

The method for stopping the web application.

static validate_addr(addr: str, uses_ipv6: bool = False) → None

Validates the bind address.

Parameters:

• addr – Address to validate.

• uses_ipv6 – Whether the address should be validated as IPv6.

Raises:

ApplicationError – If the address is invalid.