File Sharing

The Shares API is universal for both modes and provides all the necessary methods for working with the Nextcloud Shares system.

class nc_py_api.files.sharing._FilesSharingAPI(session: NcSessionBasic)[source]

Class provides all File Sharing functionality, avalaible as nc.files.sharing.<method>.

property available: bool

Returns True if the Nextcloud instance supports this feature, False otherwise.

get_list(shared_with_me=False, reshares=False, subfiles=False, path: str | FsNode = '') list[Share][source]

Returns lists of shares.

Parameters:
  • shared_with_me – Shares should be with the current user.

  • reshares – Only get shares by the current user and reshares.

  • subfiles – Only get all sub shares in a folder.

  • path – Get shares for a specific path.

get_by_id(share_id: int) Share[source]

Get Share by share ID.

get_inherited(path: str) list[Share][source]

Get all shares relative to a file, e.g., parent folders shares.

create(path: str | FsNode, share_type: ShareType, permissions: FilePermissions | None = None, share_with: str = '', **kwargs) Share[source]

Creates a new share.

Parameters:
  • path – The path of an existing file/directory.

  • share_typeShareType value.

  • permissions – combination of the FilePermissions values.

  • share_with – the recipient of the shared object.

  • kwargs – See below.

Additionally supported arguments:

  • public_upload - indicating should share be available for upload for non-registered users. default = False

  • password - string with password to protect share. default = ""

  • send_password_by_talk - boolean indicating should password be automatically delivered using Talk. default = False

  • expire_date - datetime time when share should expire. hours, minutes, seconds are ignored. default = None

  • note - string with note, if any. default = ""

  • label - string with label, if any. default = ""

update(share_id: int | Share, **kwargs) Share[source]

Updates the share options.

Parameters:
  • share_id – ID of the Share to update.

  • kwargs – Available for update: permissions, password, send_password_by_talk, public_upload, expire_date, note, label.

delete(share_id: int | Share) None[source]

Removes the given share.

get_pending() list[Share][source]

Returns all pending shares for current user.

accept_share(share_id: int | Share) None[source]

Accept pending share.

decline_share(share_id: int | Share) None[source]

Decline pending share.

get_deleted() list[Share][source]

Get a list of deleted shares.

undelete(share_id: int | Share) None[source]

Undelete a deleted share.

class nc_py_api.files.sharing.Share(raw_data: dict)[source]

Information about Share.

property share_id: int

Unique ID of the share.

property share_type: ShareType

Type of the share.

property share_with: str

To whom Share was created.

property permissions: FilePermissions

Recipient permissions.

property url: str

URL at which Share is avalaible.

property path: str

Share path relative to the user’s root directory.

property label: str

Label for the Shared object.

property note: str

Note for the Shared object.

property mimetype: str

Mimetype of the Shared object.

property share_owner: str

Share’s creator ID.

property file_owner: str

File/directory owner ID.

property password: str

Password to access share.

property send_password_by_talk: bool

Flag indicating was password send by Talk.

property expire_date: datetime

Share expiration time.

property file_source_id: int

File source ID.

property can_edit: bool

Does caller have write permissions.

property can_delete: bool

Does caller have delete permissions.

class nc_py_api.files.sharing.ShareType(value)[source]

Type of the object that will receive share.

TYPE_USER = 0

Share to the user

TYPE_GROUP = 1

Share to the group

Share by link

TYPE_EMAIL = 4

Share by the email

TYPE_REMOTE = 6

Share to the Federation

TYPE_CIRCLE = 7

Share to the Nextcloud Circle

TYPE_GUEST = 8

Share to Guest

TYPE_REMOTE_GROUP = 9

Share to the Federation group

TYPE_ROOM = 10

Share to the Talk room

TYPE_DECK = 11

Share to the Nextcloud Deck

TYPE_SCIENCE_MESH = 15

Share to the Reva instance(Science Mesh)