nc-py-api 0.10.0__py3-none-any.whl → 0.18.1__py3-none-any.whl

nc_py_api/files/__init__.py

@@ -4,10 +4,76 @@ import dataclasses
 import datetime
 import email.utils
 import enum
+import os
+import re
 import warnings
 
+from pydantic import BaseModel
+
 from .. import _misc
 
+user_regex = re.compile(r"(?:files|trashbin|versions)/([^/]+)/")
+"""Regex for evaluating user from full path string; instantiated once on import."""
+user_path_regex = re.compile(r".*?(files|trashbin|versions)/([^/]+)/")
+"""Regex for evaluating user path from full path string; instantiated once on import."""
+
+
+class LockType(enum.IntEnum):
+    """Nextcloud File Locks types."""
+
+    MANUAL_LOCK = 0
+    COLLABORATIVE_LOCK = 1
+    WEBDAV_TOKEN = 2
+
+
+@dataclasses.dataclass
+class FsNodeLockInfo:
+    """File Lock information if Nextcloud `files_lock` is enabled."""
+
+    def __init__(self, **kwargs):
+        self._is_locked = bool(int(kwargs.get("is_locked", False)))
+        self._lock_owner_type = LockType(int(kwargs.get("lock_owner_type", 0)))
+        self._lock_owner = kwargs.get("lock_owner", "")
+        self._owner_display_name = kwargs.get("owner_display_name", "")
+        self._owner_editor = kwargs.get("lock_owner_editor", "")
+        self._lock_time = int(kwargs.get("lock_time", 0))
+        self._lock_ttl = int(kwargs.get("_lock_ttl", 0))
+
+    @property
+    def is_locked(self) -> bool:
+        """Returns ``True`` if the file is locked, ``False`` otherwise."""
+        return self._is_locked
+
+    @property
+    def type(self) -> LockType:
+        """Type of the lock."""
+        return LockType(self._lock_owner_type)
+
+    @property
+    def owner(self) -> str:
+        """User id of the lock owner."""
+        return self._lock_owner
+
+    @property
+    def owner_display_name(self) -> str:
+        """Display name of the lock owner."""
+        return self._owner_display_name
+
+    @property
+    def owner_editor(self) -> str:
+        """App id of an app owned lock to allow clients to suggest joining the collaborative editing session."""
+        return self._owner_editor
+
+    @property
+    def lock_creation_time(self) -> datetime.datetime:
+        """Lock creation time."""
+        return datetime.datetime.utcfromtimestamp(self._lock_time).replace(tzinfo=datetime.timezone.utc)
+
+    @property
+    def lock_ttl(self) -> int:
+        """TTL of the lock in seconds staring from the creation time. A value of 0 means the timeout is infinite."""
+        return self._lock_ttl
+
 
 @dataclasses.dataclass
 class FsNodeInfo:
@@ -116,11 +182,15 @@ class FsNode:
     info: FsNodeInfo
     """Additional extra information for the object"""
 
+    lock_info: FsNodeLockInfo
+    """Class describing `lock` information if any."""
+
     def __init__(self, full_path: str, **kwargs):
         self.full_path = full_path
         self.file_id = kwargs.get("file_id", "")
         self.etag = kwargs.get("etag", "")
         self.info = FsNodeInfo(**kwargs)
+        self.lock_info = FsNodeLockInfo(**kwargs)
 
     @property
     def is_dir(self) -> bool:
@@ -139,9 +209,7 @@ class FsNode:
         )
 
     def __eq__(self, other):
-        if self.file_id and self.file_id == other.file_id:
-            return True
-        return False
+        return bool(self.file_id and self.file_id == other.file_id)
 
     @property
     def has_extra(self) -> bool:
@@ -156,12 +224,12 @@ class FsNode:
     @property
     def user(self) -> str:
         """Returns user ID extracted from the `full_path`."""
-        return self.full_path.lstrip("/").split("/", maxsplit=2)[1]
+        return user_regex.findall(self.full_path)[0]
 
     @property
     def user_path(self) -> str:
         """Returns path relative to the user's root directory."""
-        return self.full_path.lstrip("/").split("/", maxsplit=2)[-1]
+        return user_path_regex.sub("", self.full_path, count=1)
 
     @property
     def is_shared(self) -> bool:
@@ -218,12 +286,13 @@ class FilePermissions(enum.IntFlag):
     """Access to re-share object(s)"""
 
 
-def permissions_to_str(permissions: int, is_dir: bool = False) -> str:
+def permissions_to_str(permissions: int | str, is_dir: bool = False) -> str:
     """Converts integer permissions to string permissions.
 
     :param permissions: concatenation of ``FilePermissions`` integer flags.
     :param is_dir: Flag indicating is permissions related to the directory object or not.
     """
+    permissions = int(permissions) if not isinstance(permissions, int) else permissions
     r = ""
     if permissions & FilePermissions.PERMISSION_SHARE:
         r += "R"
@@ -400,3 +469,65 @@ class Share:
             f"{self.share_type.name}: `{self.path}` with id={self.share_id}"
             f" from {self.share_owner} to {self.share_with}"
         )
+
+
+class ActionFileInfo(BaseModel):
+    """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"""
+    etag: str
+    mime: str
+    fileType: str
+    """**file** or **dir**"""
+    size: int
+    """size of file/directory"""
+    favorite: str
+    """**true** or **false**"""
+    permissions: int
+    """Combination of :py:class:`~nc_py_api.files.FilePermissions` values"""
+    mtime: int
+    """Last modified time"""
+    userId: str
+    """The ID of the user performing the action."""
+    shareOwner: str | None = None
+    """If the object is shared, this is a display name of the share owner."""
+    shareOwnerId: str | None = None
+    """If the object is shared, this is the owner ID of the share."""
+    instanceId: str | None = None
+    """Nextcloud instance ID."""
+
+    def to_fs_node(self) -> FsNode:
+        """Returns usual :py:class:`~nc_py_api.files.FsNode` created from this class."""
+        user_path = os.path.join(self.directory, self.name).rstrip("/")
+        is_dir = bool(self.fileType.lower() == "dir")
+        if is_dir:
+            user_path += "/"
+        full_path = os.path.join(f"files/{self.userId}", user_path.lstrip("/"))
+        file_id = str(self.fileId).rjust(8, "0")
+
+        permissions = "S" if self.shareOwnerId else ""
+        permissions += permissions_to_str(self.permissions, is_dir)
+        return FsNode(
+            full_path,
+            etag=self.etag,
+            size=self.size,
+            content_length=0 if is_dir else self.size,
+            permissions=permissions,
+            favorite=bool(self.favorite.lower() == "true"),
+            file_id=file_id + self.instanceId if self.instanceId else file_id,
+            fileid=self.fileId,
+            last_modified=datetime.datetime.utcfromtimestamp(self.mtime).replace(tzinfo=datetime.timezone.utc),
+            mimetype=self.mime,
+        )
+
+
+class ActionFileInfoEx(BaseModel):
+    """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."""

nc_py_api/files/_files.py

@@ -10,7 +10,7 @@ import xmltodict
 from httpx import Response
 
 from .._exceptions import NextcloudException, check_error
-from .._misc import clear_from_params_empty
+from .._misc import check_capabilities, clear_from_params_empty
 from . import FsNode, SystemTag
 
 PROPFIND_PROPERTIES = [
@@ -29,13 +29,16 @@ PROPFIND_PROPERTIES = [
     "oc:share-types",
     "oc:favorite",
     "nc:is-encrypted",
+]
+
+PROPFIND_LOCKING_PROPERTIES = [
     "nc:lock",
     "nc:lock-owner-displayname",
     "nc:lock-owner",
     "nc:lock-owner-type",
-    "nc:lock-owner-editor",
-    "nc:lock-time",
-    "nc:lock-timeout",
+    "nc:lock-owner-editor",  # App id of an app owned lock
+    "nc:lock-time",  # Timestamp of the log creation time
+    "nc:lock-timeout",  # TTL of the lock in seconds staring from the creation time
 ]
 
 SEARCH_PROPERTIES_MAP = {
@@ -57,7 +60,14 @@ class PropFindType(enum.IntEnum):
     VERSIONS_FILE_ID = 3
 
 
-def build_find_request(req: list, path: str | FsNode, user: str) -> ElementTree.Element:
+def get_propfind_properties(capabilities: dict) -> list:
+    r = PROPFIND_PROPERTIES
+    if not check_capabilities("files.locking", capabilities):
+        r += PROPFIND_LOCKING_PROPERTIES
+    return r
+
+
+def build_find_request(req: list, path: str | FsNode, user: str, capabilities: dict) -> ElementTree.Element:
     path = path.user_path if isinstance(path, FsNode) else path
     root = ElementTree.Element(
         "d:searchrequest",
@@ -65,7 +75,7 @@ def build_find_request(req: list, path: str | FsNode, user: str) -> ElementTree.
     )
     xml_search = ElementTree.SubElement(root, "d:basicsearch")
     xml_select_prop = ElementTree.SubElement(ElementTree.SubElement(xml_search, "d:select"), "d:prop")
-    for i in PROPFIND_PROPERTIES:
+    for i in get_propfind_properties(capabilities):
         ElementTree.SubElement(xml_select_prop, i)
     xml_from_scope = ElementTree.SubElement(ElementTree.SubElement(xml_search, "d:from"), "d:scope")
     href = f"/files/{user}/{path.removeprefix('/')}"
@@ -76,7 +86,9 @@ def build_find_request(req: list, path: str | FsNode, user: str) -> ElementTree.
     return root
 
 
-def build_list_by_criteria_req(properties: list[str] | None, tags: list[int | SystemTag] | None) -> ElementTree.Element:
+def build_list_by_criteria_req(
+    properties: list[str] | None, tags: list[int | SystemTag] | None, capabilities: dict
+) -> ElementTree.Element:
     if not properties and not tags:
         raise ValueError("Either specify 'properties' or 'tags' to filter results.")
     root = ElementTree.Element(
@@ -84,7 +96,7 @@ def build_list_by_criteria_req(properties: list[str] | None, tags: list[int | Sy
         attrib={"xmlns:d": "DAV:", "xmlns:oc": "http://owncloud.org/ns", "xmlns:nc": "http://nextcloud.org/ns"},
     )
     prop = ElementTree.SubElement(root, "d:prop")
-    for i in PROPFIND_PROPERTIES:
+    for i in get_propfind_properties(capabilities):
         ElementTree.SubElement(prop, i)
     xml_filter_rules = ElementTree.SubElement(root, "oc:filter-rules")
     if properties and "favorite" in properties:
@@ -156,6 +168,18 @@ def build_list_tags_response(response: Response) -> list[SystemTag]:
     return result
 
 
+def build_tags_ids_for_object(url_to_fetch: str, response: Response) -> list[int]:
+    result = []
+    records = _webdav_response_to_records(response, "list_tags_ids")
+    for record in records:
+        prop_stat = record["d:propstat"]
+        if str(prop_stat.get("d:status", "")).find("200 OK") != -1:
+            href_suffix = str(record["d:href"]).removeprefix(url_to_fetch).strip("/")
+            if href_suffix:
+                result.append(int(href_suffix))
+    return result
+
+
 def build_update_tag_req(
     name: str | None, user_visible: bool | None, user_assignable: bool | None
 ) -> ElementTree.Element:
@@ -243,7 +267,7 @@ def etag_fileid_from_response(response: Response) -> dict:
     return {"etag": response.headers.get("OC-Etag", ""), "file_id": response.headers["OC-FileId"]}
 
 
-def _parse_record(full_path: str, prop_stats: list[dict]) -> FsNode:
+def _parse_record(full_path: str, prop_stats: list[dict]) -> FsNode:  # noqa pylint: disable = too-many-branches
     fs_node_args = {}
     for prop_stat in prop_stats:
         if str(prop_stat.get("d:status", "")).find("200 OK") == -1:
@@ -274,7 +298,17 @@ def _parse_record(full_path: str, prop_stats: list[dict]) -> FsNode:
             fs_node_args["trashbin_original_location"] = prop["nc:trashbin-original-location"]
         if "nc:trashbin-deletion-time" in prop_keys:
             fs_node_args["trashbin_deletion_time"] = prop["nc:trashbin-deletion-time"]
-        # xz = prop.get("oc:dDC", "")
+        for k, v in {
+            "nc:lock": "is_locked",
+            "nc:lock-owner-type": "lock_owner_type",
+            "nc:lock-owner": "lock_owner",
+            "nc:lock-owner-displayname": "lock_owner_displayname",
+            "nc:lock-owner-editor": "lock_owner_editor",
+            "nc:lock-time": "lock_time",
+            "nc:lock-timeout": "lock_ttl",
+        }.items():
+            if k in prop_keys and prop[k] is not None:
+                fs_node_args[v] = prop[k]
     return FsNode(full_path, **fs_node_args)