{"id":4129,"library":"nc-py-api","title":"Nextcloud Python API","description":"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.","status":"active","version":"0.30.0","language":"en","source_language":"en","source_url":"https://github.com/cloud-py-api/nc_py_api","tags":["nextcloud","cloud","api","framework","app-development"],"install":[{"cmd":"pip install nc-py-api","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Main client for general interaction with a Nextcloud instance.","symbol":"Nextcloud","correct":"from nc_py_api import Nextcloud"},{"note":"NextcloudApp is primarily for developing applications *within* the Nextcloud ecosystem, where connection details are automatically provided. For standalone scripts or external clients, use `Nextcloud`.","wrong":"from nc_py_api import NextcloudApp; nc = NextcloudApp(url, auth)","symbol":"NextcloudApp","correct":"from nc_py_api import NextcloudApp"}],"quickstart":{"code":"import os\nfrom nc_py_api import Nextcloud\n\nNEXTCLOUD_URL = os.environ.get('NEXTCLOUD_URL', 'https://nextcloud.example.com')\nNEXTCLOUD_APP_PASS = os.environ.get('NEXTCLOUD_APP_PASS', 'your_app_password') # or username/password\n\nif NEXTCLOUD_URL == 'https://nextcloud.example.com' or NEXTCLOUD_APP_PASS == 'your_app_password':\n    print(\"Please set NEXTCLOUD_URL and NEXTCLOUD_APP_PASS environment variables or replace placeholders.\")\nelse:\n    try:\n        nc = Nextcloud(\n            nextcloud_url=NEXTCLOUD_URL,\n            nextcloud_app_pass=NEXTCLOUD_APP_PASS\n        )\n        current_user = nc.users.get_current_user()\n        print(f\"Connected to Nextcloud as user: {current_user.user_id}\")\n        print(f\"Display name: {current_user.display_name}\")\n    except Exception as e:\n        print(f\"Failed to connect or fetch user info: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"v0.21.0 and later"},{"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.","message":"The `/apps/status/{appId}` endpoint for setting Nextcloud App status has been deprecated. The library now uses the `/ex-app/status` endpoint.","severity":"deprecated","affected_versions":"v0.24.2 and later"},{"fix":"Ensure you are using the correct class for your use case: `NextcloudApp` for in-app development, `Nextcloud` for external client scripts.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"v0.21.1 and later"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}