File System

The Files API is universal for both modes and provides all the necessary methods for working with the Nextcloud file system. Refer to the Files examples to see how to use them nicely.

All File APIs are designed to work relative to the current user.

class nc_py_api.files.files.FilesAPI(session: NcSessionBasic)[source]

Class that encapsulates file system and file sharing API, avalaible as nc.files.<method>.

sharing: _FilesSharingAPI: API for managing Files Shares

listdir(path: str | FsNode = '', depth: int = 1, exclude_self=True) → list[FsNode][source]

Returns a list of all entries in the specified directory.

Parameters:

path – path to the directory to get the list.
depth – how many directory levels should be included in output. Default = 1 (only specified directory)
exclude_self – boolean value indicating whether the path itself should be excluded from the list or not. Default = True.

by_id(file_id: int | str | FsNode) → FsNode | None[source]

Returns FsNode by file_id if any.

Parameters:: file_id – can be full file ID with Nextcloud instance ID or only clear file ID.

by_path(path: str | FsNode) → FsNode | None[source]: Returns FsNode by exact path if any.

find(req: list, path: str | FsNode = '') → list[FsNode][source]

Searches a directory for a file or subdirectory with a name.

Parameters:

req – list of conditions to search for. Detailed description here…
path – path where to search from. Default = “”.

download(path: str | FsNode) → bytes[source]: Downloads and returns the content of a file.

download2stream(path: str | FsNode, fp, **kwargs) → None[source]

Downloads file to the given fp object.

Parameters:

path – path to download file.
fp – filename (string), pathlib.Path object or a file object. The object must implement the file.write method and be able to write binary data.
kwargs – chunk_size an int value specifying chunk size to write. Default = 5Mb

download_directory_as_zip(path: str | FsNode, local_path: str | Path | None = None, **kwargs) → Path[source]

Downloads a remote directory as zip archive.

Parameters:

path – path to directory to download.
local_path – relative or absolute file path to save zip file.

Returns:

Path to the saved zip archive.

Note

This works only for directories, you should not use this to download a file.

upload(path: str | FsNode, content: bytes | str) → FsNode[source]

Creates a file with the specified content at the specified path.

Parameters:

path – file’s upload path.
content – content to create the file. If it is a string, it will be encoded into bytes using UTF-8.

upload_stream(path: str | FsNode, fp, **kwargs) → FsNode[source]

Creates a file with content provided by fp object at the specified path.

Parameters:

path – file’s upload path.
fp – filename (string), pathlib.Path object or a file object. The object must implement the file.read method providing data with str or bytes type.
kwargs – chunk_size an int value specifying chunk size to read. Default = 5Mb

mkdir(path: str | FsNode) → FsNode[source]

Creates a new directory.

Parameters:: path – path of the directory to be created.

makedirs(path: str | FsNode, exist_ok=False) → FsNode | None[source]

Creates a new directory and subdirectories.

Parameters:

path – path of the directories to be created.
exist_ok – ignore error if any of pathname components already exists.

Returns:

FsNode if directory was created or None if it was already created.

delete(path: str | FsNode, not_fail=False) → None[source]

Deletes a file/directory (moves to trash if trash is enabled).

Parameters:

path – path to delete.
not_fail – if set to True and the object is not found, it does not raise an exception.

move(path_src: str | FsNode, path_dest: str | FsNode, overwrite=False) → FsNode[source]

Moves an existing file or a directory.

Parameters:

path_src – path of an existing file/directory.
path_dest – name of the new one.
overwrite – if True and the destination object already exists, it gets overwritten. Default = False.

copy(path_src: str | FsNode, path_dest: str | FsNode, overwrite=False) → FsNode[source]

Copies an existing file/directory.

Parameters:

path_src – path of an existing file/directory.
path_dest – name of the new one.
overwrite – if True and the destination object already exists, it gets overwritten. Default = False.

list_by_criteria(properties: list[str] | None = None, tags: list[int | SystemTag] | None = None) → list[FsNode][source]

Returns a list of all files/directories for the current user filtered by the specified values.

Parameters:

properties – List of properties that should have been set for the file. Supported values: favorite
tags – List of tags ids or SystemTag that should have been set for the file.

setfav(path: str | FsNode, value: int | bool) → None[source]

Sets or unsets favourite flag for specific file.

Parameters:

path – path to the object to set the state.
value – value to set for the favourite state.

trashbin_list() → list[FsNode][source]: Returns a list of all entries in the TrashBin.

trashbin_restore(path: str | FsNode) → None[source]

Restore a file/directory from the TrashBin.

Parameters:: path – path to delete, e.g., the user_path field from FsNode or the FsNode class itself.

trashbin_delete(path: str | FsNode, not_fail=False) → None[source]

Deletes a file/directory permanently from the TrashBin.

Parameters:

path – path to delete, e.g., the user_path field from FsNode or the FsNode class itself.
not_fail – if set to True and the object is not found, it does not raise an exception.

trashbin_cleanup() → None[source]: Empties the TrashBin.

get_versions(file_object: FsNode) → list[FsNode][source]: Returns a list of all file versions if any.

restore_version(file_object: FsNode) → None[source]

Restore a file with specified version.

Parameters:: file_object – The FsNode class from get_versions().

list_tags() → list[SystemTag][source]: Returns list of the avalaible Tags.

get_tags(file_id: FsNode | int) → list[SystemTag][source]: Returns list of Tags assigned to the File or Directory.

create_tag(name: str, user_visible: bool = True, user_assignable: bool = True) → None[source]

Creates a new Tag.

Parameters:

name – Name of the tag.
user_visible – Should be Tag visible in the UI.
user_assignable – Can Tag be assigned from the UI.

update_tag(tag_id: int | SystemTag, name: str | None = None, user_visible: bool | None = None, user_assignable: bool | None = None) → None[source]: Updates the Tag information.

delete_tag(tag_id: int | SystemTag) → None[source]: Deletes the tag.

tag_by_name(tag_name: str) → SystemTag[source]: Returns Tag info by its name if found or None otherwise.

assign_tag(file_id: FsNode | int, tag_id: SystemTag | int) → None[source]: Assigns Tag to a file/directory.

unassign_tag(file_id: FsNode | int, tag_id: SystemTag | int) → None[source]: Removes Tag from a file/directory.

lock(path: FsNode | str, lock_type: LockType = LockType.MANUAL_LOCK) → None[source]: Locks the file.

Note

Exception codes: 423 - existing lock present.

unlock(path: FsNode | str) → None[source]: Unlocks the file.

Note

Exception codes: 412 - the file is not locked, 423 - the lock is owned by another user.

class nc_py_api.files.FsNodeInfo(**kwargs)[source]

Extra FS object attributes from Nextcloud.

favorite: bool: Flag indicating if the object is marked as favorite.

is_version: bool: Flag indicating if the object is File Version representation

fileid: int: Clear file ID without Nextcloud instance ID.

property content_length: int: Length of file in bytes, zero for directories.

property size: int: In the case of directories it is the size of all content, for files it is equal to content_length.

property mimetype: str: Mimetype of a file. Empty for the directories.

property permissions: str: Permissions for the object.

property last_modified: datetime: Time when the object was last modified.

Note

ETag is a more preferable way to check if the object was changed.

property in_trash: bool: Returns True if the object is in trash.

property trashbin_filename: str: Returns the name of the object in the trashbin.

property trashbin_original_location: str: Returns the original path of the object.

property trashbin_deletion_time: int: Returns deletion time of the object.

class nc_py_api.files.FsNode(full_path: str, **kwargs)[source]

A class that represents a Nextcloud file object.

Acceptable itself as a path parameter for the most file APIs.

full_path: str: Path to the object, including the username. Does not include dav prefix

file_id: str: File ID + NC instance ID

etag: str: An entity tag (ETag) of the object

info: FsNodeInfo: Additional extra information for the object

lock_info: FsNodeLockInfo: Class describing lock information if any.

property is_dir: bool: Returns True for the directories, False otherwise.

property has_extra: bool: Flag showing that this “FsNode” originates from the mkdir/upload methods and lacks extended information.

property name: str: Returns last pathname component.

property user: str: Returns user ID extracted from the full_path.

property user_path: str: Returns path relative to the user’s root directory.

property is_shared: bool: Check if a file or folder is shared.

property is_shareable: bool: Check if a file or folder can be shared.

property is_mounted: bool: Check if a file or folder is mounted.

property is_readable: bool: Check if the file or folder is readable.

property is_deletable: bool: Check if a file or folder can be deleted.

property is_updatable: bool: Check if file/directory is writable.

property is_creatable: bool: Check whether new files or folders can be created inside this folder.

class nc_py_api.files.FilePermissions(value)[source]

List of available permissions for files/directories.

PERMISSION_READ = 1: Access to read

PERMISSION_UPDATE = 2: Access to write

PERMISSION_CREATE = 4: Access to create new objects in the directory

PERMISSION_DELETE = 8: Access to remove object(s)

PERMISSION_SHARE = 16: Access to re-share object(s)

class nc_py_api.files.SystemTag(raw_data: dict)[source]

Nextcloud System Tag.

property tag_id: int: Unique numeric identifier of the Tag.

property display_name: str: The visible Tag name.

property user_visible: bool: Flag indicating if the Tag is visible in the UI.

property user_assignable: bool: Flag indicating if User can assign this Tag.

class nc_py_api.files.LockType(value)[source]: Nextcloud File Locks types.

class nc_py_api.files.FsNodeLockInfo(**kwargs)[source]

File Lock information if Nextcloud files_lock is enabled.

property is_locked: bool: Returns True if the file is locked, False otherwise.

property type: LockType: Type of the lock.

property owner: str: User id of the lock owner.

property owner_display_name: str: Display name of the lock owner.

property owner_editor: str: App id of an app owned lock to allow clients to suggest joining the collaborative editing session.

property lock_creation_time: datetime: Lock creation time.

property lock_ttl: int: TTL of the lock in seconds staring from the creation time. A value of 0 means the timeout is infinite.

class nc_py_api.files.ActionFileInfo(*, fileId: int, name: str, directory: str, etag: str, mime: str, fileType: str, size: int, favorite: str, permissions: int, mtime: int, userId: str, shareOwner: str | None = None, shareOwnerId: str | None = None, instanceId: str | None = None)[source]

Information Nextcloud sends to the External Application about File Nodes affected in action.

field fileId: int [Required]: FileID without Nextcloud instance ID

field name: str [Required]: Name of the file/directory

field directory: str [Required]: Directory relative to the user’s home directory

field fileType: str [Required]: file or dir

field size: int [Required]: size of file/directory

field favorite: str [Required]: true or false

field permissions: int [Required]: Combination of FilePermissions values

field mtime: int [Required]: Last modified time

field userId: str [Required]: The ID of the user performing the action.

field instanceId: str | None = None: Nextcloud instance ID.

to_fs_node() → FsNode[source]: Returns usual FsNode created from this class.

class nc_py_api.files.ActionFileInfoEx(*, files: list[ActionFileInfo])[source]

New register_ex uses new data format which allowing receiving multiple NC Nodes in one request.

field files: list[ActionFileInfo] [Required]: Always list of ActionFileInfo with one element minimum.