Nextcloud

Two base classes for working with Nextcloud. The first for working as a client, the second as an application.

All required functionality is incorporated in them, they contains all other classes required to work with the Nextcloud.

class nc_py_api.nextcloud.Nextcloud(**kwargs)[source]

Nextcloud client class.

Allows you to connect to Nextcloud and perform operations on files, shares, users, and everything else.

__init__(**kwargs)[source]

If the parameters are not specified, they will be taken from the environment.

Parameters:

  • nextcloud_url – url of the nextcloud instance.

  • nc_auth_user – login username. Optional.

  • nc_auth_pass – password or app-password for the username. Optional.

property capabilities: dict

Returns the capabilities of the Nextcloud instance.

check_capabilities(capabilities: str | list[str]) → list[str]

Returns the list with missing capabilities if any.

download_log(fp) → None

Downloads Nextcloud log file. Requires Admin privileges.

ocs(method: str, path: str, *, content: bytes | str | Iterable[bytes] | AsyncIterable[bytes] | None = None, json: dict | list | None = None, params: dict | None = None, **kwargs)

Performs OCS call and returns OCS response payload data.

perform_login() → bool

Performs login into Nextcloud if not already logged in; manual invocation of this method is unnecessary.

property response_headers: Headers

Returns the HTTPX headers from the last response.

property srv_version: ServerVersion

Returns dictionary with the server version.

property theme: ThemingInfo | None

Returns Theme information.

update_server_info() → None

Updates the capabilities and the Nextcloud version.

In normal cases, it is called automatically and there is no need to call it manually.

apps: _AppsAPI

Nextcloud API for App management

activity: _ActivityAPI

Activity Application API

cal: _CalendarAPI

Nextcloud Calendar API

files: FilesAPI

Nextcloud API for File System and Files Sharing

preferences: PreferencesAPI

Nextcloud User Preferences API

notes: _NotesAPI

Nextcloud Notes API

notifications: _NotificationsAPI

Nextcloud API for managing user notifications

talk: _TalkAPI

Nextcloud Talk API

users: _UsersAPI

Nextcloud API for managing users.

users_groups: _UsersGroupsAPI

Nextcloud API for managing user groups.

user_status: _UserStatusAPI

Nextcloud API for managing users statuses

weather_status: _WeatherStatusAPI

Nextcloud API for managing user weather statuses

webhooks: _WebhooksAPI

Nextcloud API for managing webhooks

loginflow_v2: _LoginFlowV2API

Nextcloud Login flow v2.

property user: str

Returns current user ID.

class nc_py_api.nextcloud.NextcloudApp(**kwargs)[source]

Class for communication with Nextcloud in Nextcloud applications.

Provides additional API required for applications such as user impersonation, endpoint registration, new authentication method, etc.

Note

Instance of this class should not be created directly in normal applications, it will be provided for each app endpoint call.

property capabilities: dict

Returns the capabilities of the Nextcloud instance.

check_capabilities(capabilities: str | list[str]) → list[str]

Returns the list with missing capabilities if any.

download_log(fp) → None

Downloads Nextcloud log file. Requires Admin privileges.

ocs(method: str, path: str, *, content: bytes | str | Iterable[bytes] | AsyncIterable[bytes] | None = None, json: dict | list | None = None, params: dict | None = None, **kwargs)

Performs OCS call and returns OCS response payload data.

perform_login() → bool

Performs login into Nextcloud if not already logged in; manual invocation of this method is unnecessary.

property response_headers: Headers

Returns the HTTPX headers from the last response.

property srv_version: ServerVersion

Returns dictionary with the server version.

property theme: ThemingInfo | None

Returns Theme information.

update_server_info() → None

Updates the capabilities and the Nextcloud version.

In normal cases, it is called automatically and there is no need to call it manually.

apps: _AppsAPI

Nextcloud API for App management

activity: _ActivityAPI

Activity Application API

cal: _CalendarAPI

Nextcloud Calendar API

files: FilesAPI

Nextcloud API for File System and Files Sharing

preferences: PreferencesAPI

Nextcloud User Preferences API

notes: _NotesAPI

Nextcloud Notes API

notifications: _NotificationsAPI

Nextcloud API for managing user notifications

talk: _TalkAPI

Nextcloud Talk API

users: _UsersAPI

Nextcloud API for managing users.

users_groups: _UsersGroupsAPI

Nextcloud API for managing user groups.

user_status: _UserStatusAPI

Nextcloud API for managing users statuses

weather_status: _WeatherStatusAPI

Nextcloud API for managing user weather statuses

webhooks: _WebhooksAPI

Nextcloud API for managing webhooks

appconfig_ex: AppConfigExAPI

Nextcloud App Preferences API for ExApps

preferences_ex: PreferencesExAPI

Nextcloud User Preferences API for ExApps

ui: UiApi

Nextcloud UI API for ExApps

providers: ProvidersApi

API for registering providers for Nextcloud

events_listener: EventsListenerAPI

API for registering Events listeners for ExApps

occ_commands: OccCommandsAPI

API for registering OCC command for ExApps

property enabled_state: bool

Returns True if ExApp is enabled, False otherwise.

log(log_lvl: LogLvl, content: str, fast_send: bool = False) → None[source]

Writes log to the Nextcloud log file.

users_list() → list[str][source]

Returns list of users on the Nextcloud instance.

property user: str

Property containing the current user ID.

ExApps can change user ID they impersonate with set_user method.

set_user(user_id: str)[source]

Changes current User ID.

property app_cfg: AppConfig

Returns deploy config, with AppAPI version, Application version and name.

register_talk_bot(callback_url: str, display_name: str, description: str = '') → tuple[str, str][source]

Registers Talk BOT.

Note

AppAPI will add a record in a case of successful registration to the appconfig_ex table.

Parameters:

  • callback_url – URL suffix for fetching new messages. MUST be UNIQ for each bot the app provides.

  • display_name – The name under which the messages will be posted.

  • description – Optional description shown in the admin settings.

Returns:

Tuple with ID and the secret used for signing requests.

unregister_talk_bot(callback_url: str) → bool[source]

Unregisters Talk BOT.

set_init_status(progress: int, error: str = '') → None[source]

Sets state of the app initialization.

Parameters:

  • progress – a number from 0 to 100 indicating the percentage of application readiness for work. After sending 100 AppAPI will enable the application.

  • error – if non-empty, signals to AppAPI that the application cannot be initialized successfully.