Nextcloud ExApp Python Framework

Python framework for building Nextcloud ExApps (External Applications).

Built on top of nc_py_api, this package provides everything needed to create full-featured Nextcloud applications with their own UI, AI providers, Talk bots, and more.

Key features

• Full ExApp lifecycle: Handles registration, authentication, heartbeat, and initialization.
• FastAPI integration: Middleware, dependency injection, and static file mounting out of the box.
• UI APIs: Register top menu entries, file actions, declarative settings, scripts, and styles.
• AI Providers: TaskProcessing provider registration and task management.
• Talk Bots: Build conversational bots for Nextcloud Talk.
• OCC Commands: Register custom OCC commands from your ExApp.
• Async: Fully async API built on top of niquests.

Nextcloud skeleton app

from contextlib import asynccontextmanager

from fastapi import FastAPI

from nc_py_app import NextcloudApp
from nc_py_app.ex_app import AppAPIAuthMiddleware, LogLvl, run_app, set_handlers


@asynccontextmanager
async def lifespan(app: FastAPI):
    set_handlers(app, enabled_handler)
    yield


APP = FastAPI(lifespan=lifespan)
APP.add_middleware(AppAPIAuthMiddleware)


async def enabled_handler(enabled: bool, nc: NextcloudApp) -> str:
    if enabled:
        await nc.log(LogLvl.WARNING, "Hello from nc_py_app.")
    else:
        await nc.log(LogLvl.WARNING, "Bye bye from nc_py_app.")
    return ""


if __name__ == "__main__":
    run_app("main:APP", log_level="trace")

Migration from nc_py_api

If your ExApp currently imports from nc_py_api, migration is straightforward:

- from nc_py_api import NextcloudApp
- from nc_py_api.ex_app import set_handlers, nc_app, run_app
- from nc_py_api.talk_bot import TalkBot
+ from nc_py_app import NextcloudApp
+ from nc_py_app.ex_app import set_handlers, nc_app, run_app
+ from nc_py_app.talk_bot import TalkBot

Common types like NextcloudException, FsNode, FilePermissions are re-exported from nc_py_app so you don't need to import from both packages.

Support

• Create an Issue or feature request
• Join the Discussions
• Contribute via Pull Requests

More Information

• nc_py_api - Nextcloud Python client library
• AppAPI - Nextcloud AppAPI framework
• Changelog