Nextcloud Python API

0.30.0 · active · verified Sat Apr 11

nc-py-api is the official Python Framework for interacting with Nextcloud instances, enabling both client-side operations and the development of Nextcloud applications. It provides a comprehensive API for various Nextcloud features including users, files, and declarative settings. The current version is 0.30.0, and the library maintains an active release cadence with frequent updates.

Warnings

breaking The library switched its underlying HTTP client from `httpx` to `niquests`. If your code had deep integrations, custom client configurations, or relied on `httpx` specific exceptions/behavior, it might break.
Fix: Review any custom HTTP client configurations or direct `httpx` usage. The public API should largely remain compatible, but internal changes can affect advanced use cases. Adjust error handling if `httpx` exceptions were caught directly.
deprecated The `/apps/status/{appId}` endpoint for setting Nextcloud App status has been deprecated. The library now uses the `/ex-app/status` endpoint.
Fix: If you were manually interacting with Nextcloud's app status endpoints, switch to using the new `/ex-app/status` endpoint or rely on the `nc-py-api` methods which have been updated internally.
gotcha When developing a Nextcloud App, use `NextcloudApp` which gets its context from Nextcloud. For standalone scripts or external clients, use `Nextcloud` and provide explicit connection details (URL, app password/username). Mixing these can lead to incorrect behavior or connection issues.
Fix: Ensure you are using the correct class for your use case: `NextcloudApp` for in-app development, `Nextcloud` for external client scripts.
gotcha Error handling for external model downloads (e.g., in ExApps) has changed. If there's an error during a model download, an exception is now explicitly raised to prevent incorrect or partial ExApp installations.
Fix: Ensure your code robustly handles exceptions during ExApp model installations or related operations. Previously, some errors might have been silently ignored or led to partial installs; now, explicit failure is indicated.

Install

pip install nc-py-api Install stable version

Imports

Nextcloud
```
from nc_py_api import Nextcloud
```
Main client for general interaction with a Nextcloud instance.
NextcloudApp
```
from nc_py_api import NextcloudApp
```
NextcloudApp is primarily for developing applications *within* the Nextcloud ecosystem, where connection details are automatically provided. For standalone scripts or external clients, use `Nextcloud`.

Quickstart

This quickstart demonstrates how to connect to a Nextcloud instance using the `Nextcloud` client and retrieve information about the current user. It's recommended to use environment variables for sensitive credentials.

import os
from nc_py_api import Nextcloud

NEXTCLOUD_URL = os.environ.get('NEXTCLOUD_URL', 'https://nextcloud.example.com')
NEXTCLOUD_APP_PASS = os.environ.get('NEXTCLOUD_APP_PASS', 'your_app_password') # or username/password

if NEXTCLOUD_URL == 'https://nextcloud.example.com' or NEXTCLOUD_APP_PASS == 'your_app_password':
    print("Please set NEXTCLOUD_URL and NEXTCLOUD_APP_PASS environment variables or replace placeholders.")
else:
    try:
        nc = Nextcloud(
            nextcloud_url=NEXTCLOUD_URL,
            nextcloud_app_pass=NEXTCLOUD_APP_PASS
        )
        current_user = nc.users.get_current_user()
        print(f"Connected to Nextcloud as user: {current_user.user_id}")
        print(f"Display name: {current_user.display_name}")
    except Exception as e:
        print(f"Failed to connect or fetch user info: {e}")

view raw JSON →