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

nc_py_api/__init__.py

@@ -7,6 +7,6 @@ from ._exceptions import (
     NextcloudMissingCapabilities,
 )
 from ._version import __version__
-from .files import FilePermissions, FsNode
+from .files import FilePermissions, FsNode, LockType
 from .files.sharing import ShareType
 from .nextcloud import AsyncNextcloud, AsyncNextcloudApp, Nextcloud, NextcloudApp

nc_py_api/_session.py

@@ -123,7 +123,7 @@ class AppConfig(BasicConfig):
         super().__init__(**kwargs)
         self.aa_version = self._get_config_value("aa_version", raise_not_found=False, **kwargs)
         if not self.aa_version:
-            self.aa_version = "1.0.0"
+            self.aa_version = "2.2.0"
         self.app_name = self._get_config_value("app_id", **kwargs)
         self.app_version = self._get_config_value("app_version", **kwargs)
         self.app_secret = self._get_config_value("app_secret", **kwargs)
@@ -459,7 +459,7 @@ class NcSessionAppBasic(ABC):
         self.cfg = AppConfig(**kwargs)
         super().__init__(**kwargs)
 
-    def sign_check(self, request: HTTPConnection) -> None:
+    def sign_check(self, request: HTTPConnection) -> str:
         headers = {
             "AA-VERSION": request.headers.get("AA-VERSION", ""),
             "EX-APP-ID": request.headers.get("EX-APP-ID", ""),
@@ -474,13 +474,10 @@ class NcSessionAppBasic(ABC):
         if headers["EX-APP-ID"] != self.cfg.app_name:
             raise ValueError(f"Invalid EX-APP-ID:{headers['EX-APP-ID']} != {self.cfg.app_name}")
 
-        our_version = self.adapter.headers.get("EX-APP-VERSION", "")
-        if headers["EX-APP-VERSION"] != our_version:
-            raise ValueError(f"Invalid EX-APP-VERSION:{headers['EX-APP-VERSION']} <=> {our_version}")
-
-        app_secret = get_username_secret_from_headers(headers)[1]
+        username, app_secret = get_username_secret_from_headers(headers)
         if app_secret != self.cfg.app_secret:
             raise ValueError(f"Invalid App secret:{app_secret} != {self.cfg.app_secret}")
+        return username
 
 
 class NcSessionApp(NcSessionAppBasic, NcSessionBasic):

nc_py_api/_version.py

@@ -1,3 +1,3 @@
 """Version of nc_py_api."""
 
-__version__ = "0.10.0"
+__version__ = "0.12.0"

nc_py_api/ex_app/__init__.py

@@ -1,6 +1,7 @@
 """All possible ExApp stuff for NextcloudApp that can be used."""
 
-from .defs import ApiScope, LogLvl
+from ..files import ActionFileInfo
+from .defs import FileSystemEventNotification, LogLvl
 from .integration_fastapi import (
     AppAPIAuthMiddleware,
     anc_app,
@@ -9,7 +10,15 @@ from .integration_fastapi import (
     set_handlers,
     talk_bot_msg,
 )
-from .misc import get_model_path, persistent_storage, verify_version
-from .ui.files_actions import UiActionFileInfo
+from .misc import (
+    get_computation_device,
+    get_model_path,
+    persistent_storage,
+    verify_version,
+)
 from .ui.settings import SettingsField, SettingsFieldType, SettingsForm
 from .uvicorn_fastapi import run_app
+
+
+class UiActionFileInfo(ActionFileInfo):
+    """``Deprecated``: use :py:class:`~nc_py_api.ex_app.ActionFileInfo` instead."""

nc_py_api/ex_app/defs.py

@@ -2,6 +2,10 @@
 
 import enum
 
+from pydantic import BaseModel
+
+from ..files import ActionFileInfo
+
 
 class LogLvl(enum.IntEnum):
     """Log levels."""
@@ -18,32 +22,16 @@ class LogLvl(enum.IntEnum):
     """Fatal log level"""
 
 
-class ApiScope(enum.IntEnum):
-    """Defined API scopes."""
-
-    SYSTEM = 2
-    """Allows access to the System APIs."""
-    FILES = 10
-    """Allows access to the Nextcloud file base."""
-    FILES_SHARING = 11
-    """Allows access to APIs that provide File Sharing."""
-    USER_INFO = 30
-    """Allows access to APIs that work with users."""
-    USER_STATUS = 31
-    """Allows access to APIs that work with users statuses."""
-    NOTIFICATIONS = 32
-    """Allows access to APIs that provide Notifications."""
-    WEATHER_STATUS = 33
-    """Allows access to APIs that provide Weather status."""
-    TALK = 50
-    """Allows access to Talk API endpoints."""
-    TALK_BOT = 60
-    """Allows to register Talk Bots."""
-    AI_PROVIDERS = 61
-    """Allows to register AI providers."""
-    ACTIVITIES = 110
-    """Activity App endpoints."""
-    NOTES = 120
-    """Notes App endpoints."""
-    ALL = 9999
-    """All endpoints allowed."""
+class FileSystemEventData(BaseModel):
+    """FileSystem events format."""
+
+    target: ActionFileInfo
+    source: ActionFileInfo | None = None
+
+
+class FileSystemEventNotification(BaseModel):
+    """AppAPI event notification common data."""
+
+    event_type: str
+    event_subtype: str
+    event_data: FileSystemEventData

nc_py_api/ex_app/integration_fastapi.py

@@ -103,7 +103,7 @@ def set_handlers(
 
         @fast_api_app.post("/init")
         async def init_callback(b_tasks: BackgroundTasks, nc: typing.Annotated[NextcloudApp, Depends(nc_app)]):
-            b_tasks.add_task(__fetch_models_task, nc, models_to_fetch if models_to_fetch else {})
+            b_tasks.add_task(fetch_models_task, nc, models_to_fetch if models_to_fetch else {}, 0)
             return JSONResponse(content={})
 
     if map_app_static:
@@ -120,10 +120,11 @@ def __map_app_static_folders(fast_api_app: FastAPI):
             fast_api_app.mount(f"/{mnt_dir}", staticfiles.StaticFiles(directory=mnt_dir_path), name=mnt_dir)
 
 
-def __fetch_models_task(nc: NextcloudApp, models: dict[str, dict]) -> None:
+def fetch_models_task(nc: NextcloudApp, models: dict[str, dict], progress_init_start_value: int) -> None:
+    """Use for cases when you want to define custom `/init` but still need to easy download models."""
     if models:
-        current_progress = 0
-        percent_for_each = min(int(100 / len(models)), 99)
+        current_progress = progress_init_start_value
+        percent_for_each = min(int((100 - progress_init_start_value) / len(models)), 99)
         for model in models:
             if model.startswith(("http://", "https://")):
                 __fetch_model_as_file(current_progress, percent_for_each, nc, model, models[model])
@@ -206,9 +207,9 @@ def __request_sign_check_if_needed(request: HTTPConnection, nextcloud_app: Nextc
         _request_sign_check(request, nextcloud_app)
 
 
-def _request_sign_check(request: HTTPConnection, nextcloud_app: NextcloudApp | AsyncNextcloudApp) -> None:
+def _request_sign_check(request: HTTPConnection, nextcloud_app: NextcloudApp | AsyncNextcloudApp) -> str:
     try:
-        nextcloud_app._session.sign_check(request)  # noqa pylint: disable=protected-access
+        return nextcloud_app._session.sign_check(request)  # noqa pylint: disable=protected-access
     except ValueError as e:
         print(e)
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) from None
@@ -238,7 +239,7 @@ class AppAPIAuthMiddleware:
         url_path = conn.url.path.lstrip("/")
         if not fnmatch.filter(self._disable_for, url_path):
             try:
-                _request_sign_check(conn, AsyncNextcloudApp())
+                scope["username"] = _request_sign_check(conn, AsyncNextcloudApp())
             except HTTPException as exc:
                 response = self._on_error(exc.status_code, exc.detail)
                 await response(scope, receive, send)

nc_py_api/ex_app/misc.py

@@ -50,3 +50,8 @@ def get_model_path(model_name: str) -> str:
     from huggingface_hub import snapshot_download  # noqa isort:skip pylint: disable=C0415 disable=E0401
 
     return snapshot_download(model_name, local_files_only=True, cache_dir=persistent_storage())
+
+
+def get_computation_device() -> str:
+    """Returns computation device(`ROCM` or `CUDA`) if it is defined in the environment variable."""
+    return os.environ.get("COMPUTE_DEVICE", "")

nc_py_api/ex_app/providers/translations.py

@@ -42,6 +42,11 @@ class TranslationsProvider:
         """Relative ExApp url which will be called by Nextcloud."""
         return self._raw_data["action_handler"]
 
+    @property
+    def action_handler_detect_lang(self) -> str:
+        """Relative ExApp url which will be called by Nextcloud to detect language."""
+        return self._raw_data.get("action_detect_lang", "")
+
     def __repr__(self):
         return f"<{self.__class__.__name__} name={self.name}, handler={self.action_handler}>"
 
@@ -59,6 +64,7 @@ class _TranslationsProviderAPI:
         callback_url: str,
         from_languages: dict[str, str],
         to_languages: dict[str, str],
+        detect_lang_callback_url: str = "",
     ) -> None:
         """Registers or edit the Translations provider."""
         require_capabilities("app_api", self._session.capabilities)
@@ -68,6 +74,7 @@ class _TranslationsProviderAPI:
             "fromLanguages": from_languages,
             "toLanguages": to_languages,
             "actionHandler": callback_url,
+            "actionDetectLang": detect_lang_callback_url,
         }
         self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
 
@@ -114,6 +121,7 @@ class _AsyncTranslationsProviderAPI:
         callback_url: str,
         from_languages: dict[str, str],
         to_languages: dict[str, str],
+        detect_lang_callback_url: str = "",
     ) -> None:
         """Registers or edit the Translations provider."""
         require_capabilities("app_api", await self._session.capabilities)
@@ -123,6 +131,7 @@ class _AsyncTranslationsProviderAPI:
             "fromLanguages": from_languages,
             "toLanguages": to_languages,
             "actionHandler": callback_url,
+            "actionDetectLang": detect_lang_callback_url,
         }
         await self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
 

nc_py_api/ex_app/ui/files_actions.py

@@ -1,15 +1,10 @@
 """Nextcloud API for working with drop-down file's menu."""
 
 import dataclasses
-import datetime
-import os
-
-from pydantic import BaseModel
 
 from ..._exceptions import NextcloudExceptionNotFound
 from ..._misc import require_capabilities
 from ..._session import AsyncNcSessionApp, NcSessionApp
-from ...files import FsNode, permissions_to_str
 
 
 @dataclasses.dataclass
@@ -63,61 +58,6 @@ class UiFileActionEntry:
         return f"<{self.__class__.__name__} name={self.name}, mime={self.mime}, handler={self.action_handler}>"
 
 
-class UiActionFileInfo(BaseModel):
-    """File Information Nextcloud sends to the External Application."""
-
-    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
-    """If the object is shared, this is a display name of the share owner."""
-    shareOwnerId: str | None
-    """If the object is shared, this is the owner ID of the share."""
-    instanceId: str | 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 _UiFilesActionsAPI:
     """API for the drop-down menu in Nextcloud **Files app**, avalaible as **nc.ui.files_dropdown_menu.<method>**."""
 

nc_py_api/files/__init__.py

@@ -4,11 +4,71 @@ import dataclasses
 import datetime
 import email.utils
 import enum
+import os
 import warnings
 
+from pydantic import BaseModel
+
 from .. import _misc
 
 
+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:
     """Extra FS object attributes from Nextcloud."""
@@ -116,11 +176,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:
@@ -400,3 +464,58 @@ 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,
+        )

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:
@@ -243,7 +255,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 +286,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)
 
 

nc_py_api/files/files.py

@@ -10,7 +10,7 @@ from httpx import Headers
 from .._exceptions import NextcloudException, NextcloudExceptionNotFound, check_error
 from .._misc import random_string, require_capabilities
 from .._session import AsyncNcSessionBasic, NcSessionBasic
-from . import FsNode, SystemTag
+from . import FsNode, LockType, SystemTag
 from ._files import (
     PROPFIND_PROPERTIES,
     PropFindType,
@@ -25,6 +25,7 @@ from ._files import (
     dav_get_obj_path,
     element_tree_as_str,
     etag_fileid_from_response,
+    get_propfind_properties,
     lf_parse_webdav_response,
 )
 from .sharing import _AsyncFilesSharingAPI, _FilesSharingAPI
@@ -50,7 +51,7 @@ class FilesAPI:
         """
         if exclude_self and not depth:
             raise ValueError("Wrong input parameters, query will return nothing.")
-        properties = PROPFIND_PROPERTIES
+        properties = get_propfind_properties(self._session.capabilities)
         path = path.user_path if isinstance(path, FsNode) else path
         return self._listdir(self._session.user, path, properties=properties, depth=depth, exclude_self=exclude_self)
 
@@ -76,7 +77,7 @@ class FilesAPI:
         :param path: path where to search from. Default = **""**.
         """
         # `req` possible keys: "name", "mime", "last_modified", "size", "favorite", "fileid"
-        root = build_find_request(req, path, self._session.user)
+        root = build_find_request(req, path, self._session.user, self._session.capabilities)
         webdav_response = self._session.adapter_dav.request(
             "SEARCH", "", content=element_tree_as_str(root), headers={"Content-Type": "text/xml"}
         )
@@ -248,7 +249,7 @@ class FilesAPI:
             Supported values: **favorite**
         :param tags: List of ``tags ids`` or ``SystemTag`` that should have been set for the file.
         """
-        root = build_list_by_criteria_req(properties, tags)
+        root = build_list_by_criteria_req(properties, tags, self._session.capabilities)
         webdav_response = self._session.adapter_dav.request(
             "REPORT", dav_get_obj_path(self._session.user), content=element_tree_as_str(root)
         )
@@ -332,7 +333,7 @@ class FilesAPI:
         headers = Headers({"Destination": dest}, encoding="utf-8")
         response = self._session.adapter_dav.request(
             "MOVE",
-            f"/versions/{self._session.user}/{file_object.user_path}",
+            quote(f"/versions/{self._session.user}/{file_object.user_path}"),
             headers=headers,
         )
         check_error(response, f"restore_version: user={self._session.user}, src={file_object.user_path}")
@@ -396,6 +397,34 @@ class FilesAPI:
         """Removes Tag from a file/directory."""
         self._file_change_tag_state(file_id, tag_id, False)
 
+    def lock(self, path: FsNode | str, lock_type: LockType = LockType.MANUAL_LOCK) -> None:
+        """Locks the file.
+
+        .. note:: Exception codes: 423 - existing lock present.
+        """
+        require_capabilities("files.locking", self._session.capabilities)
+        full_path = dav_get_obj_path(self._session.user, path.user_path if isinstance(path, FsNode) else path)
+        response = self._session.adapter_dav.request(
+            "LOCK",
+            quote(full_path),
+            headers={"X-User-Lock": "1", "X-User-Lock-Type": str(lock_type.value)},
+        )
+        check_error(response, f"lock: user={self._session.user}, path={full_path}")
+
+    def unlock(self, path: FsNode | str) -> None:
+        """Unlocks the file.
+
+        .. note:: Exception codes: 412 - the file is not locked, 423 - the lock is owned by another user.
+        """
+        require_capabilities("files.locking", self._session.capabilities)
+        full_path = dav_get_obj_path(self._session.user, path.user_path if isinstance(path, FsNode) else path)
+        response = self._session.adapter_dav.request(
+            "UNLOCK",
+            quote(full_path),
+            headers={"X-User-Lock": "1"},
+        )
+        check_error(response, f"unlock: user={self._session.user}, path={full_path}")
+
     def _file_change_tag_state(self, file_id: FsNode | int, tag_id: SystemTag | int, tag_state: bool) -> None:
         fs_object = file_id.info.fileid if isinstance(file_id, FsNode) else file_id
         tag = tag_id.tag_id if isinstance(tag_id, SystemTag) else tag_id
@@ -493,7 +522,7 @@ class AsyncFilesAPI:
         """
         if exclude_self and not depth:
             raise ValueError("Wrong input parameters, query will return nothing.")
-        properties = PROPFIND_PROPERTIES
+        properties = get_propfind_properties(await self._session.capabilities)
         path = path.user_path if isinstance(path, FsNode) else path
         return await self._listdir(
             await self._session.user, path, properties=properties, depth=depth, exclude_self=exclude_self
@@ -521,7 +550,7 @@ class AsyncFilesAPI:
         :param path: path where to search from. Default = **""**.
         """
         # `req` possible keys: "name", "mime", "last_modified", "size", "favorite", "fileid"
-        root = build_find_request(req, path, await self._session.user)
+        root = build_find_request(req, path, await self._session.user, await self._session.capabilities)
         webdav_response = await self._session.adapter_dav.request(
             "SEARCH", "", content=element_tree_as_str(root), headers={"Content-Type": "text/xml"}
         )
@@ -695,7 +724,7 @@ class AsyncFilesAPI:
             Supported values: **favorite**
         :param tags: List of ``tags ids`` or ``SystemTag`` that should have been set for the file.
         """
-        root = build_list_by_criteria_req(properties, tags)
+        root = build_list_by_criteria_req(properties, tags, await self._session.capabilities)
         webdav_response = await self._session.adapter_dav.request(
             "REPORT", dav_get_obj_path(await self._session.user), content=element_tree_as_str(root)
         )
@@ -784,7 +813,7 @@ class AsyncFilesAPI:
         headers = Headers({"Destination": dest}, encoding="utf-8")
         response = await self._session.adapter_dav.request(
             "MOVE",
-            f"/versions/{await self._session.user}/{file_object.user_path}",
+            quote(f"/versions/{await self._session.user}/{file_object.user_path}"),
             headers=headers,
         )
         check_error(response, f"restore_version: user={await self._session.user}, src={file_object.user_path}")
@@ -848,6 +877,34 @@ class AsyncFilesAPI:
         """Removes Tag from a file/directory."""
         await self._file_change_tag_state(file_id, tag_id, False)
 
+    async def lock(self, path: FsNode | str, lock_type: LockType = LockType.MANUAL_LOCK) -> None:
+        """Locks the file.
+
+        .. note:: Exception codes: 423 - existing lock present.
+        """
+        require_capabilities("files.locking", await self._session.capabilities)
+        full_path = dav_get_obj_path(await self._session.user, path.user_path if isinstance(path, FsNode) else path)
+        response = await self._session.adapter_dav.request(
+            "LOCK",
+            quote(full_path),
+            headers={"X-User-Lock": "1", "X-User-Lock-Type": str(lock_type.value)},
+        )
+        check_error(response, f"lock: user={self._session.user}, path={full_path}")
+
+    async def unlock(self, path: FsNode | str) -> None:
+        """Unlocks the file.
+
+        .. note:: Exception codes: 412 - the file is not locked, 423 - the lock is owned by another user.
+        """
+        require_capabilities("files.locking", await self._session.capabilities)
+        full_path = dav_get_obj_path(await self._session.user, path.user_path if isinstance(path, FsNode) else path)
+        response = await self._session.adapter_dav.request(
+            "UNLOCK",
+            quote(full_path),
+            headers={"X-User-Lock": "1"},
+        )
+        check_error(response, f"unlock: user={self._session.user}, path={full_path}")
+
     async def _file_change_tag_state(self, file_id: FsNode | int, tag_id: SystemTag | int, tag_state: bool) -> None:
         fs_object = file_id.info.fileid if isinstance(file_id, FsNode) else file_id
         tag = tag_id.tag_id if isinstance(tag_id, SystemTag) else tag_id

{nc_py_api-0.10.0.dist-info → nc_py_api-0.12.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: nc-py-api
-Version: 0.10.0
+Version: 0.12.0
 Summary: Nextcloud Python Framework
 Project-URL: Changelog, https://github.com/cloud-py-api/nc_py_api/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://cloud-py-api.github.io/nc_py_api/
@@ -10,7 +10,7 @@ License-Expression: BSD-3-Clause
 License-File: AUTHORS
 License-File: LICENSE.txt
 Keywords: api,client,framework,library,nextcloud
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: MacOS :: MacOS X

{nc_py_api-0.10.0.dist-info → nc_py_api-0.12.0.dist-info}/RECORD

@@ -1,13 +1,13 @@
-nc_py_api/__init__.py,sha256=IHPyeXjkOwX6cJlYGnyPpF9RR5E7E3LZ6lAuZ3J_L4M,418
+nc_py_api/__init__.py,sha256=F-ZEHHtUIDe2Tb95wf9XE3KD0F76VxqtTgTBysV3SMc,428
 nc_py_api/_deffered_error.py,sha256=BpEe_tBqflwfj2Zolb67nhW-K16XX-WbcY2IH_6u8fo,319
 nc_py_api/_exceptions.py,sha256=7vbUECaLmD7RJBCU27t4fuP6NmQK6r4508u_gS4szhI,2298
 nc_py_api/_misc.py,sha256=dUzCP9VmyhtICTsn1aexlFAYUioBm40k6Zh-YE5WwCY,3333
 nc_py_api/_preferences.py,sha256=OtovFZuGHnHYKjdDjSnUappO795tW8Oxj7qVaejHWpQ,2479
 nc_py_api/_preferences_ex.py,sha256=tThj6U0ZZMaBZ-jUkjrbaI0xDnafWsBowQKsC6gjOQs,7179
-nc_py_api/_session.py,sha256=G8xFMMpiUlEShX5iWjUZvuU-TW-bQfxxycPkMbgXfCw,19761
+nc_py_api/_session.py,sha256=pp_DMgIVaTo3PUmToh7OL760YBgg-Id_BlA7um4FhWc,19566
 nc_py_api/_talk_api.py,sha256=0Uo7OduYniuuX3UQPb468RyGJJ-PWBCgJ5HoPuz5Qa0,51068
 nc_py_api/_theming.py,sha256=hTr3nuOemSuRFZaPy9iXNmBM7rDgQHECH43tHMWGqEY,1870
-nc_py_api/_version.py,sha256=0DrBatRjxF1-R7fHDYPHU9ghEOcSaQcNxy3eQm1iDII,52
+nc_py_api/_version.py,sha256=qqj1wAOMaCXyBsxPuKBq2xzDPc5IZfwNJnRLXV8dbcc,52
 nc_py_api/activity.py,sha256=t9VDSnnaXRNOvALqOSGCeXSQZ-426pCOMSfQ96JHys4,9574
 nc_py_api/apps.py,sha256=6vOFFs6vNHCCvZ_SwXxPq5-X1xfgyLjW8uZSfJKduC8,9774
 nc_py_api/calendar.py,sha256=-T6CJ8cRbJZTLtxSEDWuuYpD29DMJGCTfLONmtxZV9w,1445
@@ -21,29 +21,29 @@ nc_py_api/user_status.py,sha256=I101nwYS8X1WvC8AnLa2f3qJUCPDPHrbq-ke0h1VT4E,1328
 nc_py_api/users.py,sha256=B6By-H9oUNvJj2omaRCMPIsQ17xeeDV_udn0VioRO7A,15488
 nc_py_api/users_groups.py,sha256=IPxw-Ks5NjCm6r8_HC9xmf3IYptH00ulITbp5iazhAo,6289
 nc_py_api/weather_status.py,sha256=wAkjuJPjxc0Rxe4za0BzfwB0XeUmkCXoisJtTH3-qdQ,7582
-nc_py_api/ex_app/__init__.py,sha256=JNFZl1LRr8Qu7SqOK9W6CZw4Mf0ATFrRSo7HfVQBJQ0,470
-nc_py_api/ex_app/defs.py,sha256=Suh_PpBlkQ8nbHne2-ypoEnl7Plsq39HPLI9Ns3NT2s,1267
-nc_py_api/ex_app/integration_fastapi.py,sha256=lNxeMT6Jlhr8GEmP-4bu2tnjtyCD0J2MDYAcSER3tVM,10603
-nc_py_api/ex_app/misc.py,sha256=6tPZuDVQa3lyXhK9M66M0dLNFQvrECRtXmULMjIa8-w,2098
+nc_py_api/ex_app/__init__.py,sha256=hELGo3yLzxUOyvEVcIDYK3wYA4FD984ExnckM9PC3CA,648
+nc_py_api/ex_app/defs.py,sha256=FaQInH3jLugKxDUqpwrXdkMT-lBxmoqWmXJXc11fa6A,727
+nc_py_api/ex_app/integration_fastapi.py,sha256=2yt24zlfmNcbs-RCueyWhpWHmiD6vKVgXsobJ1iSY7I,10817
+nc_py_api/ex_app/misc.py,sha256=wA6KrcB05SQGwVAo7dgBxXAVm_2r9bgDf6SqioyOJPc,2286
 nc_py_api/ex_app/persist_transformers_cache.py,sha256=ZoEBb1RnNaQrtxK_CjSZ8LZ36Oakz2Xciau_ZpNp8Ic,213
 nc_py_api/ex_app/uvicorn_fastapi.py,sha256=WLtNmWXMBKN6CMip2uhKcgy4mC2Ch9AmNfwRScBUsP0,752
 nc_py_api/ex_app/providers/__init__.py,sha256=jmUBdbAgzUCdYyHl8V5UCNYJI-FFpxPQQ4iEAoURKQs,43
 nc_py_api/ex_app/providers/providers.py,sha256=jHDhxeQZdYh_ajN88rdNXYTMECCjx9YIt5I6_BlH9QQ,1548
 nc_py_api/ex_app/providers/speech_to_text.py,sha256=JFD1ksdhXjpr5UFm5npqCxepqB5x-kdHG9CpPoGofx0,4959
 nc_py_api/ex_app/providers/text_processing.py,sha256=VUZMZ2fof-c6JD7mTKHTZBWbDMOqxDllMCNQFOlHXXk,5265
-nc_py_api/ex_app/providers/translations.py,sha256=xxe-uTyBNmYlS0_mMXtyeU4rEDk64tDPy6hvWI9YQgM,5697
+nc_py_api/ex_app/providers/translations.py,sha256=io8UgVhdQXFmP7KnrJQx5Vtl8Dz0Z0EVZ0bt3hV7C7A,6112
 nc_py_api/ex_app/ui/__init__.py,sha256=jUMU7_miFF-Q8BQNT90KZYQiLy_a3OvEyK6y8eRMKRk,38
-nc_py_api/ex_app/ui/files_actions.py,sha256=bPohXjL-szrYQvI0JORLju3G6y8kTXZ0yzLD2g-dcyc,7465
+nc_py_api/ex_app/ui/files_actions.py,sha256=7SV1u5G9puEDImrJicG7jy_3eVJ3h6Ch1pXOqN_GxWE,5339
 nc_py_api/ex_app/ui/resources.py,sha256=Vwx69oZ93Ouh6HJtGUqaKFUr4Reo74H4vT1YCpb-7j0,12492
 nc_py_api/ex_app/ui/settings.py,sha256=f0R17lGhBfo2JQULVw_hFxhpfoPw_CW7vBu0Rb1ABJw,6623
 nc_py_api/ex_app/ui/top_menu.py,sha256=oCgGtIoMYbp-5iN5aXEbT7Q88HtccR7hg6IBFgbbyX4,5118
 nc_py_api/ex_app/ui/ui.py,sha256=OqFHKn6oIZli8T1wnv6YtQ4glNfeNb90WwGCvtWI1Z4,1632
-nc_py_api/files/__init__.py,sha256=rtQTrWIMPjxMk8l7mrvyoBsg9ZHs_2S2woUwdfkJ-CY,12564
-nc_py_api/files/_files.py,sha256=IJibj0_y3UQyyVhVI2RgQapPFPsOAV6tyH2sFlLy09I,12226
-nc_py_api/files/files.py,sha256=Y86rJABa0Gfqq2lxg2RUCD5RP-mM0FjPd8L2metNho0,44940
+nc_py_api/files/__init__.py,sha256=AcHQT6cCyLMfuHDOWZCsDwRjNJ5hTh3YZKdWOMFILQQ,16695
+nc_py_api/files/_files.py,sha256=XIAhjkDf92_FpPwsbA_X7_oh1_vZY2EZFefI5NjF-Wk,13180
+nc_py_api/files/files.py,sha256=GZDS0AD_wY1-PVNP_KcMWXaB6GyP7TGBlDCObmsoj5s,47819
 nc_py_api/files/sharing.py,sha256=VRZCl-TYK6dbu9rUHPs3_jcVozu1EO8bLGZwoRpiLsU,14439
-nc_py_api-0.10.0.dist-info/METADATA,sha256=5PjDRWaqloZeyi9FotkMylQzo5WmGCYakSFQXKKsPh0,8944
-nc_py_api-0.10.0.dist-info/WHEEL,sha256=TJPnKdtrSue7xZ_AVGkp9YXcvDrobsjBds1du3Nx6dc,87
-nc_py_api-0.10.0.dist-info/licenses/AUTHORS,sha256=Y1omFHyI8ned9k4jJXs2ATgmgi1GmQ7EZ6S1gxqnX2k,572
-nc_py_api-0.10.0.dist-info/licenses/LICENSE.txt,sha256=OLEMh401fAumGHfRSna365MLIfnjdTcdOHZ6QOzMjkg,1551
-nc_py_api-0.10.0.dist-info/RECORD,,
+nc_py_api-0.12.0.dist-info/METADATA,sha256=eif47row0QfeHml3aI715IRfMAWkZiMexjOY_OfWzjQ,8943
+nc_py_api-0.12.0.dist-info/WHEEL,sha256=uNdcs2TADwSd5pVaP0Z_kcjcvvTUklh2S7bxZMF8Uj0,87
+nc_py_api-0.12.0.dist-info/licenses/AUTHORS,sha256=Y1omFHyI8ned9k4jJXs2ATgmgi1GmQ7EZ6S1gxqnX2k,572
+nc_py_api-0.12.0.dist-info/licenses/LICENSE.txt,sha256=OLEMh401fAumGHfRSna365MLIfnjdTcdOHZ6QOzMjkg,1551
+nc_py_api-0.12.0.dist-info/RECORD,,

{nc_py_api-0.10.0.dist-info → nc_py_api-0.12.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.21.1
+Generator: hatchling 1.22.4
 Root-Is-Purelib: true
 Tag: py3-none-any