ASGI Mount API - pyserve

ASGI Mount API Reference

The pyserve.asgi_mount module provides a Python API for mounting ASGI and WSGI applications programmatically.

Classes

ASGIAppLoader

Loads and manages ASGI/WSGI applications from Python import paths.

from pyserve import ASGIAppLoader

loader = ASGIAppLoader()

# Load an ASGI app
app = loader.load_app(
    app_path="mymodule:app",
    app_type="asgi",
    module_path="/path/to/project",
    factory=False,
    factory_args=None
)

Methods

load_app(app_path, app_type="asgi", module_path=None, factory=False, factory_args=None)

Load an application from an import path.

app_path: Import path in format module:attribute
app_type: "asgi" or "wsgi"
module_path: Optional path to add to sys.path
factory: If True, call the attribute as a factory function
factory_args: Dict of arguments for factory function

Returns the loaded ASGI application or None on error.

get_app(app_path)

Get a previously loaded application by its path.

reload_app(app_path, **kwargs)

Reload an application, useful for development hot-reloading.

MountedApp

Represents an application mounted at a specific path.

from pyserve import MountedApp

mount = MountedApp(
    path="/api",
    app=my_asgi_app,
    name="my-api",
    strip_path=True
)

Attributes

path: str: The mount path (without trailing slash).
app: ASGIApp: The ASGI application.
name: str: Friendly name for logging.
strip_path: bool: Whether to strip the mount path from requests.

Methods

matches(request_path) → bool: Check if a request path matches this mount.
get_modified_path(original_path) → str: Get the modified path after stripping mount prefix.

ASGIMountManager

Manages multiple mounted applications and routes requests.

from pyserve import ASGIMountManager

manager = ASGIMountManager()

# Mount using app instance
manager.mount(path="/api", app=my_app)

# Mount using import path
manager.mount(
    path="/flask",
    app_path="myapp:flask_app",
    app_type="wsgi"
)

Methods

mount(path, app=None, app_path=None, app_type="asgi", module_path=None, factory=False, factory_args=None, name="", strip_path=True) → bool: Mount an application at a path. Either app or app_path must be provided. Returns True on success.
unmount(path) → bool: Remove a mounted application. Returns True if found and removed.
get_mount(request_path) → Optional[MountedApp]: Get the mount that matches a request path.
handle_request(scope, receive, send) → bool: Handle an ASGI request. Returns True if handled by a mounted app.
list_mounts() → List[Dict]: Get a list of all mounts with their configuration.

Properties

mounts: List[MountedApp]: Copy of the current mounts list (sorted by path length, longest first).

Helper Functions

Convenience functions for loading specific framework applications:

create_fastapi_app()

from pyserve import create_fastapi_app

app = create_fastapi_app(
    app_path="myapp.api:app",
    module_path=None,
    factory=False,
    factory_args=None
)

create_flask_app()

from pyserve import create_flask_app

app = create_flask_app(
    app_path="myapp.web:app",
    module_path=None,
    factory=False,
    factory_args=None
)

Automatically wraps the WSGI app for ASGI compatibility.

create_django_app()

from pyserve import create_django_app

app = create_django_app(
    settings_module="myproject.settings",
    module_path="/path/to/project"
)

Sets DJANGO_SETTINGS_MODULE and returns Django's ASGI application.

create_starlette_app()

from pyserve import create_starlette_app

app = create_starlette_app(
    app_path="myapp:starlette_app",
    module_path=None,
    factory=False,
    factory_args=None
)

Usage Example

Complete example mounting multiple applications:

from pyserve import (
    PyServeServer,
    ASGIMountManager,
    create_fastapi_app,
    create_flask_app
)

# Create mount manager
mounts = ASGIMountManager()

# Mount FastAPI
api_app = create_fastapi_app("myapp.api:app")
if api_app:
    mounts.mount("/api", app=api_app, name="api")

# Mount Flask
admin_app = create_flask_app("myapp.admin:app")
if admin_app:
    mounts.mount("/admin", app=admin_app, name="admin")

# List mounts
for mount in mounts.list_mounts():
    print(f"Mounted {mount['name']} at {mount['path']}")

Error Handling

All loader functions return None on failure and log errors. Check the return value before using:

app = create_fastapi_app("nonexistent:app")
if app is None:
    # Handle error - check logs for details
    print("Failed to load application")

WSGI Compatibility

For WSGI applications, pyserve uses adapters in this priority:

a2wsgi.WSGIMiddleware (recommended)
asgiref.wsgi.WsgiToAsgi (fallback)

Install an adapter:

pip install a2wsgi  # recommended
# or
pip install asgiref

See Also:

ASGI Mounting Guide — Configuration-based mounting
Extensions — ASGI extension configuration