platypush.plugins.nextcloud

class platypush.plugins.nextcloud.ClientConfig(url: str, username: str, password: str)[source]
__init__(url: str, username: str, password: str)None

Initialize self. See help(type(self)) for accurate signature.

class platypush.plugins.nextcloud.NextcloudPlugin(url: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, **kwargs)[source]

Plugin to interact with a NextCloud instance.

Requires:

  • nextcloud-API (pip install git+https://github.com/EnterpriseyIntranet/nextcloud-API.git)

__init__(url: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, **kwargs)[source]
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)[source]

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)[source]

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: Optional[str] = None, overwrite: bool = False, **server_args)[source]

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: Optional[str] = None, **server_args)[source]

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)[source]

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: Optional[str] = None, public_upload: bool = False, password: Optional[str] = None, permissions: Optional[List[str]] = None, **server_args)dict[source]

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)[source]

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)[source]

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)[source]

Delete a group.

Parameters
  • group_id – Group ID.

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

delete_group_folder(folder_id: Union[int, str], **server_args)[source]

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)[source]

Delete a notification.

Parameters
  • notification_id – Notification ID.

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

delete_notifications(**server_args)[source]

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: Optional[str] = None, **server_args)[source]

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)[source]

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)[source]

Delete a user.

Parameters
  • user_id – User ID/name.

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

disable_app(app_id: Union[str, int], **server_args)[source]

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)[source]

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: Optional[str] = None, **server_args)[source]

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)[source]

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: Union[str, int], **server_args)[source]

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)[source]

Enable a user.

Parameters
  • user_id – User ID/name.

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

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

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: Union[str, int], **server_args)dict[source]

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][source]

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[source]

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[source]

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: Union[int, str], **server_args)dict[source]

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[source]

Get the list new group folder.

Parameters

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

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

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)Union[dict, str][source]

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[source]

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[source]

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][source]

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][source]

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[source]

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: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, **server_args)List[str][source]

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: Union[int, str], group_id: str, **server_args)[source]

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: Optional[str] = None, depth: int = 1, all_properties: bool = False, **server_args)List[dict][source]

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: Optional[str] = None, user_id: Optional[str] = None, **server_args)List[dict][source]

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: Optional[str] = None, user_id: Optional[str] = None, **server_args)[source]

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: Optional[str] = None, overwrite: bool = False, **server_args)[source]

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)[source]

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)[source]

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: Union[int, str], new_name: str, **server_args)[source]

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: Union[int, str], group_id: str, **server_args)[source]

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: Union[int, str], group_id: str, permissions: List[str], **server_args)[source]

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: Union[int, str], quota: Optional[int], **server_args)[source]

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: Optional[bool] = None, password: Optional[str] = None, permissions: Optional[List[str]] = None, expire_date: Optional[str] = None, **server_args)[source]

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: Optional[str] = None, content: Optional[str] = None, user_id: Optional[str] = None, timestamp: Optional[Union[datetime.datetime, int, str]] = None, **server_args)[source]

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)[source]

An enumeration.

class platypush.plugins.nextcloud.ShareType(value)[source]

An enumeration.