Skip to main content

trellis.app.apploader

AppLoader class and global accessors for Trellis applications.

find_app_path​

def find_app_path() -> Path

Find the directory containing trellis_config.py by walking up from cwd.

Searches from the current working directory toward the filesystem root, returning the first directory that contains a trellis_config.py file.

Returns:

Path to the directory containing trellis_config.py

Raises:

  • FileNotFoundError - If no trellis_config.py is found

resolve_app_root​

def resolve_app_root(cli_value: Path | None = None) -> Path

Resolve app root from CLI > ENV > auto-detect.

Resolution order:

  1. If cli_value is provided, use it
  2. Else check TRELLIS_APP_ROOT environment variable
  3. Else call find_app_path() for auto-detection

For any explicit path (CLI or ENV): if it's a file, use its parent directory. Always validates that the resulting directory contains trellis_config.py.

Arguments:

  • cli_value - Path from --app-root CLI option (None if not provided)

Returns:

Path to directory containing trellis_config.py

Raises:

  • FileNotFoundError - If path doesn't exist or no trellis_config.py found

AppLoader Objects​

class AppLoader()

Loads and manages a Trellis application.

The AppLoader class manages application configuration loaded from trellis_config.py.

Attributes:

  • path - Directory containing the trellis_config.py file
  • config - Loaded configuration, or None if not yet loaded

__init__​

def __init__(path: Path) -> None

Initialize an AppLoader instance.

Arguments:

  • path - Directory containing the trellis_config.py file

from_config​

@classmethod
def from_config(cls, config: Config) -> AppLoader

Create an AppLoader from a Config object directly.

Used in Pyodide where there's no filesystem to load trellis_config.py from. Sets path to None and clears python_path since wheels are already installed in site-packages. Without an app root, config paths are left as-coerced rather than normalized to absolute paths.

Arguments:

  • config - A pre-built Config instance

Returns:

A new AppLoader with config set and path=None

load_config​

def load_config() -> None

Load configuration from trellis_config.py.

Executes the trellis_config.py file and extracts the config variable, which must be a Config instance.

Raises:

  • FileNotFoundError - If trellis_config.py doesn't exist at self.path
  • ValueError - If config variable is not defined in trellis_config.py
  • TypeError - If config is not a Config instance
  • SyntaxError - If trellis_config.py has syntax errors (passed through)
  • ModuleNotFoundError - If trellis_config.py has import errors (passed through)

import_module​

def import_module() -> ModuleType

Import the application module specified in config.module.

Adds each path from config.python_path to sys.path, then imports the module. File-backed configs are normalized to absolute paths during load_config(); AppLoader.from_config() is the rootless exception.

Returns:

The imported module object

Raises:

  • RuntimeError - If load_config() has not been called first
  • ModuleNotFoundError - If the module cannot be found
  • SyntaxError - If the module has syntax errors (passed through)
  • ImportError - If the module has import errors (passed through)

load_app​

def load_app() -> None

Load the App instance from the application module.

Imports the module via import_module() and extracts the app variable. Requires load_config() to have been called first.

Raises:

  • RuntimeError - If load_config() has not been called first
  • ValueError - If app variable is not defined in the module
  • TypeError - If app is not an App instance

load_app_from_source​

def load_app_from_source(code: str) -> None

Load the App instance from user-provided source code.

Executes the source code in a clean namespace and extracts the app variable. Used in the browser platform to run code from the playground or inline TrellisDemo components instead of importing a pre-bundled module.

Requires config to have been loaded first (via load_config() or from_config()).

Arguments:

  • code - Python source code that defines an app = App(...) variable

Raises:

  • RuntimeError - If config has not been loaded first
  • ValueError - If app variable is not defined in the source
  • TypeError - If app is not an App instance
  • code1 - If the source code has syntax errors (passed through)

platform​

@property
def platform() -> Platform

Get the platform instance for this application.

Lazily imports and instantiates the platform based on config.platform. For browser platform, returns BrowserPlatform if running in Pyodide, otherwise returns BrowserServePlatform.

Returns:

The platform instance

Raises:

  • RuntimeError - If config has not been loaded

bundle​

def bundle(dest: Path | None = None) -> Path

Build the client bundle for this application.

Uses the platform's get_build_config() to determine entry point and build steps, then runs the build pipeline.

Arguments:

  • dest - Custom output directory (default: {app_root}/.dist)

Returns:

The workspace Path used for the build

Raises:

  • RuntimeError - If config has not been loaded

get_apploader​

def get_apploader() -> AppLoader

Get the global AppLoader instance.

Returns:

The global AppLoader instance

Raises:

  • RuntimeError - If set_apploader() has not been called

set_apploader​

def set_apploader(apploader: AppLoader) -> None

Set the global AppLoader instance.

Arguments:

  • apploader - The AppLoader instance to set as global

get_config​

def get_config() -> Config | None

Get the config from the global AppLoader.

Returns:

The Config from the global AppLoader, or None if not loaded

Raises:

  • RuntimeError - If set_apploader() has not been called

get_app​

def get_app() -> App | None

Get the app from the global AppLoader.

Returns:

The App from the global AppLoader, or None if not loaded

Raises:

  • RuntimeError - If set_apploader() has not been called

get_app_root​

def get_app_root() -> Path

Get the app root path from the global AppLoader.

Returns:

The path to the directory containing trellis_config.py

Raises:

  • RuntimeError - If set_apploader() has not been called, or if the apploader was created via from_config() with no app root directory

get_workspace_dir​

def get_workspace_dir() -> Path

Get the workspace directory for the application.

Returns:

Path to {app_root}/.workspace

Raises:

  • RuntimeError - If set_apploader() has not been called

get_dist_dir​

def get_dist_dir() -> Path

Get the output directory for built bundles.

Returns:

Path to {app_root}/.dist

Raises:

  • RuntimeError - If set_apploader() has not been called