nextcloud

class platypush.plugins.nextcloud.ClientConfig(url: str, username: str, password: str)

Bases: object

__init__(url: str, username: str, password: str) → None

class platypush.plugins.nextcloud.NextcloudPlugin(url: str | None = None, username: str | None = None, password: str | None = None, **kwargs)

Bases: Plugin

Plugin to interact with a NextCloud instance.

Requires:

• nextcloud-api-wrapper (pip install nextcloud-api-wrapper)

__init__(url: str | None = None, username: str | None = None, password: str | None = None, **kwargs)

Parameters:

• url – URL to the index of your default NextCloud instance.

• username – Default NextCloud username.

• password – Default NextCloud password.

add_group(group_id: str, **server_args)

Create a new group.

Parameters:

• group_id – New group unique ID.

• server_args – Override the default server settings (see _get_client() arguments).

add_to_group(user_id: str, group_id: str, **server_args)

Add a user to a group.

Parameters:

• user_id – User ID/name.

• group_id – Group ID.

• server_args – Override the default server settings (see _get_client() arguments).

copy(path: str, destination: str, user_id: str | None = None, overwrite: bool = False, **server_args)

Copy a resource to another path.

Parameters:

• path – Resource path.

• destination – Destination path.

• user_id – User ID associated to the resource (default: same as the configured user).

• overwrite – Set to True if you want to overwrite any existing file (default: False).

• server_args – Override the default server settings (see _get_client() arguments).

create_folder(path: str, user_id: str | None = None, **server_args)

Create a folder.

Parameters:

• path – Path to the folder.

• user_id – User ID associated to the folder (default: same as the configured user).

• server_args – Override the default server settings (see _get_client() arguments).

create_group_folder(name: str, **server_args)

Create a new group folder.

Parameters:

• name – Name/path of the folder.

• server_args – Override the default server settings (see _get_client() arguments).

create_share(path: str, share_type: str, share_with: str | None = None, public_upload: bool = False, password: str | None = None, permissions: List[str] | None = None, **server_args) → dict

Share a file/folder with a user/group or a public link.

Parameters:

• path – Path to the resource to be shared.

• share_type –

  Share type. Supported values:

  • user

  • group

  • public_link

  • email

  • federated_cloud_share

  • circle

  • talk_conversation

• share_with – User/group ID, email or conversation ID the resource should be shared with.

• public_upload – Whether public upload to the shared folder is allowed (default: False).

• password – Optional password to protect the share.

• permissions –

  Share permissions, as a list including any of the following (default: read):

  • read

  • update

  • create

  • delete

  • share

  • all

• server_args – Override the default server settings (see _get_client() arguments).

Returns:

The details of the newly created share. Example:

{
  "id": "4",
  "share_type": 3,
  "uid_owner": "your_uid",
  "displayname_owner": "Your Name",
  "permissions": 17,
  "can_edit": true,
  "can_delete": true,
  "stime": 1599691325,
  "parent": null,
  "expiration": null,
  "token": "AbCdEfG0123456789",
  "uid_file_owner": "your_uid",
  "note": "",
  "label": "",
  "displayname_file_owner": "Your Name",
  "path": "/Shared Path",
  "item_type": "folder",
  "mimetype": "httpd/unix-directory",
  "storage_id": "home::your-uid",
  "storage": 2,
  "item_source": 13960,
  "file_source": 13960,
  "file_parent": 6,
  "file_target": "/Shared Path",
  "share_with": null,
  "share_with_displayname": "(Shared link)",
  "password": null,
  "send_password_by_talk": false,
  "url": "https://your-domain/nextcloud/index.php/s/AbCdEfG0123456789",
  "mail_send": 1,
  "hide_download": 0
}

create_subadmin(user_id: str, group_id: str, **server_args)

Add a user as a subadmin for a group.

Parameters:

• user_id – User ID/name.

• group_id – Group ID.

• server_args – Override the default server settings (see _get_client() arguments).

create_user(user_id: str, password: str, **server_args)

Create a user.

Parameters:

• user_id – User ID/name.

• password – User password

• server_args – Override the default server settings (see _get_client() arguments).

delete_group(group_id: str, **server_args)

Delete a group.

Parameters:

• group_id – Group ID.

• server_args – Override the default server settings (see _get_client() arguments).

delete_group_folder(folder_id: int | str, **server_args)

Delete a new group folder.

Parameters:

• folder_id – Folder ID.

• server_args – Override the default server settings (see _get_client() arguments).

delete_notification(notification_id: int, **server_args)

Delete a notification.

Parameters:

• notification_id – Notification ID.

• server_args – Override the default server settings (see _get_client() arguments).

delete_notifications(**server_args)

Delete all notifications for the logged user.

Parameters:

server_args – Override the default server settings (see _get_client() arguments).

delete_path(path: str, user_id: str | None = None, **server_args)

Delete a file or folder.

Parameters:

• path – Path to the resource.

• user_id – User ID associated to the resource (default: same as the configured user).

• server_args – Override the default server settings (see _get_client() arguments).

delete_share(share_id: int, **server_args)

Remove the shared state of a resource.

Parameters:

• share_id – Share ID.

• server_args – Override the default server settings (see _get_client() arguments).

delete_user(user_id: str, **server_args)

Delete a user.

Parameters:

• user_id – User ID/name.

• server_args – Override the default server settings (see _get_client() arguments).

disable_app(app_id: str | int, **server_args)

Disable an app.

Parameters:

• app_id – App ID.

• server_args – Override the default server settings (see _get_client() arguments).

disable_user(user_id: str, **server_args)

Disable a user.

Parameters:

• user_id – User ID/name.

• server_args – Override the default server settings (see _get_client() arguments).

download_file(remote_path: str, local_path: str, user_id: str | None = None, **server_args)

Download a file.

Parameters:

• remote_path – Path to the remote resource.

• local_path – Path to the local folder.

• user_id – User ID associated to the resource (default: same as the configured user).

• server_args – Override the default server settings (see _get_client() arguments).

edit_user(user_id: str, properties: Dict[str, str], **server_args)

Update a set of properties of a user.

Parameters:

• user_id – User ID/name.

• properties – Key-value pair of user attributes to be edited.

• server_args – Override the default server settings (see _get_client() arguments).

enable_app(app_id: str | int, **server_args)

Enable an app.

Parameters:

• app_id – App ID.

• server_args – Override the default server settings (see _get_client() arguments).

enable_user(user_id: str, **server_args)

Enable a user.

Parameters:

• user_id – User ID/name.

• server_args – Override the default server settings (see _get_client() arguments).

get_activities(since: id | None = None, limit: int | None = None, object_type: str | None = None, object_id: int | None = None, sort: str = 'desc', **server_args) → List[str]

Get the list of recent activities on an instance.

Parameters:

• since – Only return the activities that have occurred since the specified ID.

• limit – Maximum number of activities to be returned (default: None).

• object_type – Filter by object type.

• object_id – Only get the activities related to a specific object_id.

• sort – Sort mode, asc for ascending, desc for descending (default: desc).

• server_args – Override the default server settings (see _get_client() arguments).

Returns:

The list of selected activities.

get_app(app_id: str | int, **server_args) → dict

Provides information about an application.

Parameters:

• app_id – App ID.

• server_args – Override the default server settings (see _get_client() arguments).

get_apps(**server_args) → List[str]

Get the list of apps installed on a NextCloud instance.

Parameters:

server_args – Override the default server settings (see _get_client() arguments).

Returns:

The list of installed apps as strings.

get_capabilities(**server_args) → dict

Returns the capabilities of the server.

Parameters:

server_args – Override the default server settings (see _get_client() arguments).

get_group(group_id: str, **server_args) → dict

Get the information of a group.

Parameters:

• group_id – Group ID.

• server_args – Override the default server settings (see _get_client() arguments).

get_group_folder(folder_id: int | str, **server_args) → dict

Get a new group folder.

Parameters:

• folder_id – Folder ID.

• server_args – Override the default server settings (see _get_client() arguments).

get_group_folders(**server_args) → list

Get the list new group folder.

Parameters:

server_args – Override the default server settings (see _get_client() arguments).

get_groups(search: str | None = None, limit: int | None = None, offset: int | None = None, **server_args) → List[str]

Search for groups.

Parameters:

• search – Search for groups matching the specified substring.

• limit – Maximum number of returned entries.

• offset – Start offset.

• server_args – Override the default server settings (see _get_client() arguments).

get_notification(notification_id: int, **server_args) → dict | str

Get the content of a notification.

Parameters:

• notification_id – Notification ID.

• server_args – Override the default server settings (see _get_client() arguments).

get_notifications(**server_args) → list

Get the list of notifications for the logged user.

Parameters:

server_args – Override the default server settings (see _get_client() arguments).

get_share(share_id: int, **server_args) → dict

Get the information of a shared resource.

Parameters:

• share_id – Share ID.

• server_args – Override the default server settings (see _get_client() arguments).

get_shares(**server_args) → List[dict]

Get the list of shares available on the server.

Parameters:

server_args – Override the default server settings (see _get_client() arguments).

Returns:

List of available shares. Example:

[
    {
      "id": "4",
      "share_type": 3,
      "uid_owner": "your_uid",
      "displayname_owner": "Your Name",
      "permissions": 17,
      "can_edit": true,
      "can_delete": true,
      "stime": 1599691325,
      "parent": null,
      "expiration": null,
      "token": "AbCdEfG0123456789",
      "uid_file_owner": "your_uid",
      "note": "",
      "label": "",
      "displayname_file_owner": "Your Name",
      "path": "/Shared Path",
      "item_type": "folder",
      "mimetype": "httpd/unix-directory",
      "storage_id": "home::your-uid",
      "storage": 2,
      "item_source": 13960,
      "file_source": 13960,
      "file_parent": 6,
      "file_target": "/Shared Path",
      "share_with": null,
      "share_with_displayname": "(Shared link)",
      "password": null,
      "send_password_by_talk": false,
      "url": "https://your-domain/nextcloud/index.php/s/AbCdEfG0123456789",
      "mail_send": 1,
      "hide_download": 0
    }
]

get_subadmin_groups(user_id: str, **server_args) → List[str]

Get the groups where a given user is subadmin.

Parameters:

• user_id – User ID/name.

• server_args – Override the default server settings (see _get_client() arguments).

Returns:

List of matched groups as strings.

get_user(user_id: str, **server_args) → dict

Get the details of a user.

Parameters:

• user_id – User ID/name.

• server_args – Override the default server settings (see _get_client() arguments).

Returns:

User details. Example:

{
  "enabled": true,
  "storageLocation": "/mnt/hd/nextcloud/user",
  "id": "user",
  "lastLogin": 1599693750000,
  "backend": "Database",
  "subadmin": [],
  "quota": {
    "free": 6869434515456,
    "used": 1836924441,
    "total": 6871271439897,
    "relative": 0.03,
    "quota": -3
  },
  "email": "info@yourdomain.com",
  "displayname": "Your Name",
  "phone": "+1234567890",
  "address": "",
  "website": "https://yourdomain.com",
  "twitter": "@You",
  "groups": [
    "admin"
  ],
  "language": "en",
  "locale": "",
  "backendCapabilities": {
    "setDisplayName": true,
    "setPassword": true
  }
}

get_users(search: str | None = None, limit: int | None = None, offset: int | None = None, **server_args) → List[str]

Get the list of users matching some search criteria.

Parameters:

• search – Return users matching the provided string.

• limit – Maximum number of results to be returned (default: no limit).

• offset – Search results offset (default: None).

Returns:

List of the matched user IDs.

grant_access_to_group_folder(folder_id: int | str, group_id: str, **server_args)

Grant access to a group folder to a given group.

Parameters:

• folder_id – Folder ID.

• group_id – Group ID.

• server_args – Override the default server settings (see _get_client() arguments).

list(path: str, user_id: str | None = None, depth: int = 1, all_properties: bool = False, **server_args) → List[dict]

List the content of a folder on the NextCloud instance.

Parameters:

• path – Remote path.

• user_id – User ID associated to the resource (default: same as the configured user).

• depth – Search depth (default: 1).

• all_properties – Return all the file properties available (default: False).

• server_args – Override the default server settings (see _get_client() arguments).

list_favorites(path: str | None = None, user_id: str | None = None, **server_args) → List[dict]

List the favorite items for a user.

Parameters:

• path – Return only the favorites under this path.

• user_id – User ID associated to the resource (default: same as the configured user).

• server_args – Override the default server settings (see _get_client() arguments).

mark_favorite(path: str | None = None, user_id: str | None = None, **server_args)

Add a path to a user’s favorites.

Parameters:

• path – Resource path.

• user_id – User ID associated to the resource (default: same as the configured user).

• server_args – Override the default server settings (see _get_client() arguments).

move(path: str, destination: str, user_id: str | None = None, overwrite: bool = False, **server_args)

Move a resource to another path.

Parameters:

• path – Resource path.

• destination – Destination path.

• user_id – User ID associated to the resource (default: same as the configured user).

• overwrite – Set to True if you want to overwrite any existing file (default: False).

• server_args – Override the default server settings (see _get_client() arguments).

remove_from_group(user_id: str, group_id: str, **server_args)

Remove a user from a group.

Parameters:

• user_id – User ID/name.

• group_id – Group ID.

• server_args – Override the default server settings (see _get_client() arguments).

remove_subadmin(user_id: str, group_id: str, **server_args)

Remove a user as a subadmin from a group.

Parameters:

• user_id – User ID/name.

• group_id – Group ID.

• server_args – Override the default server settings (see _get_client() arguments).

rename_group_folder(folder_id: int | str, new_name: str, **server_args)

Rename a group folder.

Parameters:

• folder_id – Folder ID.

• new_name – New folder name.

• server_args – Override the default server settings (see _get_client() arguments).

revoke_access_to_group_folder(folder_id: int | str, group_id: str, **server_args)

Revoke access to a group folder to a given group.

Parameters:

• folder_id – Folder ID.

• group_id – Group ID.

• server_args – Override the default server settings (see _get_client() arguments).

set_group_folder_permissions(folder_id: int | str, group_id: str, permissions: List[str], **server_args)

Set the permissions on a folder for a group.

Parameters:

• folder_id – Folder ID.

• group_id – Group ID.

• permissions –

  New permissions, as a list including any of the following:

  • read

  • update

  • create

  • delete

  • share

  • all

• server_args – Override the default server settings (see _get_client() arguments).

set_group_folder_quota(folder_id: int | str, quota: int | None, **server_args)

Set the quota of a group folder.

Parameters:

• folder_id – Folder ID.

• quota – Quota in bytes - set None for unlimited.

• server_args – Override the default server settings (see _get_client() arguments).

update_share(share_id: int, public_upload: bool | None = None, password: str | None = None, permissions: List[str] | None = None, expire_date: str | None = None, **server_args)

Update the permissions of a shared resource.

Parameters:

• share_id – Share ID.

• public_upload – Whether public upload to the shared folder is allowed (default: False).

• password – Optional password to protect the share.

• permissions –

  Share permissions, as a list including any of the following (default: read):

  • read

  • update

  • create

  • delete

  • share

  • all

• expire_date – Share expiration date, in the format YYYY-MM-DD.

• server_args – Override the default server settings (see _get_client() arguments).

upload_file(remote_path: str, local_path: str | None = None, content: str | None = None, user_id: str | None = None, timestamp: datetime | int | str | None = None, **server_args)

Upload a file.

Parameters:

• remote_path – Path to the remote resource.

• local_path – If set, identifies the path to the local file to be uploaded.

• content – If set, create a new file with this content instead of uploading an existing file.

• user_id – User ID associated to the resource (default: same as the configured user).

• timestamp – File timestamp. If not specified it will be retrieved from the file info or set to now if content is specified.

• server_args – Override the default server settings (see _get_client() arguments).

class platypush.plugins.nextcloud.Permission(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

class platypush.plugins.nextcloud.ShareType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum