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.
- 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 = “”.
- 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: favoritetags – List of
tags ids
orSystemTag
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_restore(path: str | FsNode) None [source]
Restore a file/directory from the TrashBin.
- Parameters:
path – path to delete, e.g., the
user_path
field fromFsNode
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 fromFsNode
or the FsNode class itself.not_fail – if set to
True
and the object is not found, it does not raise an exception.
- 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()
.
- 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.
- 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.
- 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 creation_date: datetime
Time when the object was created.
- 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.
Check if a file or folder is shared.
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, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[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, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[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 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.
- fileId: int
FileID without Nextcloud instance ID
- name: str
Name of the file/directory
- directory: str
Directory relative to the user’s home directory
- fileType: str
file or dir
- size: int
size of file/directory
- favorite: str
true or false
- permissions: int
Combination of
FilePermissions
values
- mtime: int
Last modified time
- userId: str
The ID of the user performing the action.
- instanceId: str | None
Nextcloud instance ID.
- 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.- files: list[ActionFileInfo]
Always list of
ActionFileInfo
with one element minimum.