nc-py-api 0.12.1__py3-none-any.whl → 0.15.0__py3-none-any.whl

nc_py_api/ex_app/providers/task_processing.py

@@ -0,0 +1,197 @@
+"""Nextcloud API for declaring TaskProcessing provider."""
+
+import contextlib
+import dataclasses
+import typing
+
+from ..._exceptions import NextcloudException, NextcloudExceptionNotFound
+from ..._misc import clear_from_params_empty, require_capabilities
+from ..._session import AsyncNcSessionApp, NcSessionApp
+
+_EP_SUFFIX: str = "ai_provider/task_processing"
+
+
+@dataclasses.dataclass
+class TaskProcessingProvider:
+    """TaskProcessing provider description."""
+
+    def __init__(self, raw_data: dict):
+        self._raw_data = raw_data
+
+    @property
+    def name(self) -> str:
+        """Unique ID for the provider."""
+        return self._raw_data["name"]
+
+    @property
+    def display_name(self) -> str:
+        """Providers display name."""
+        return self._raw_data["display_name"]
+
+    @property
+    def task_type(self) -> str:
+        """The TaskType provided by this provider."""
+        return self._raw_data["task_type"]
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} name={self.name}, type={self.task_type}>"
+
+
+class _TaskProcessingProviderAPI:
+    """API for TaskProcessing providers, available as **nc.providers.task_processing.<method>**."""
+
+    def __init__(self, session: NcSessionApp):
+        self._session = session
+
+    def register(
+        self, name: str, display_name: str, task_type: str, custom_task_type: dict[str, typing.Any] | None = None
+    ) -> None:
+        """Registers or edit the TaskProcessing provider."""
+        require_capabilities("app_api", self._session.capabilities)
+        params = {
+            "name": name,
+            "displayName": display_name,
+            "taskType": task_type,
+            "customTaskType": custom_task_type,
+        }
+        clear_from_params_empty(["customTaskType"], params)
+        self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
+
+    def unregister(self, name: str, not_fail=True) -> None:
+        """Removes TaskProcessing provider."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            self._session.ocs("DELETE", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"name": name})
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    def next_task(self, provider_ids: list[str], task_types: list[str]) -> dict[str, typing.Any]:
+        """Get the next task processing task from Nextcloud."""
+        with contextlib.suppress(NextcloudException):
+            if r := self._session.ocs(
+                "GET",
+                "/ocs/v2.php/taskprocessing/tasks_provider/next",
+                json={"providerIds": provider_ids, "taskTypeIds": task_types},
+            ):
+                return r
+        return {}
+
+    def set_progress(self, task_id: int, progress: float) -> dict[str, typing.Any]:
+        """Report new progress value of the task to Nextcloud. Progress should be in range from 0.0 to 100.0."""
+        with contextlib.suppress(NextcloudException):
+            if r := self._session.ocs(
+                "POST",
+                f"/ocs/v2.php/taskprocessing/tasks_provider/{task_id}/progress",
+                json={"taskId": task_id, "progress": progress / 100.0},
+            ):
+                return r
+        return {}
+
+    def upload_result_file(self, task_id: int, file: bytes | str | typing.Any) -> int:
+        """Uploads file and returns fileID that should be used in the ``report_result`` function.
+
+        .. note:: ``file`` can be any file-like object.
+        """
+        return self._session.ocs(
+            "POST",
+            f"/ocs/v2.php/taskprocessing/tasks_provider/{task_id}/file",
+            files={"file": file},
+        )["fileId"]
+
+    def report_result(
+        self,
+        task_id: int,
+        output: dict[str, typing.Any] | None = None,
+        error_message: str | None = None,
+    ) -> dict[str, typing.Any]:
+        """Report result of the task processing to Nextcloud."""
+        with contextlib.suppress(NextcloudException):
+            if r := self._session.ocs(
+                "POST",
+                f"/ocs/v2.php/taskprocessing/tasks_provider/{task_id}/result",
+                json={"taskId": task_id, "output": output, "errorMessage": error_message},
+            ):
+                return r
+        return {}
+
+
+class _AsyncTaskProcessingProviderAPI:
+    """Async API for TaskProcessing providers."""
+
+    def __init__(self, session: AsyncNcSessionApp):
+        self._session = session
+
+    async def register(
+        self, name: str, display_name: str, task_type: str, custom_task_type: dict[str, typing.Any] | None = None
+    ) -> None:
+        """Registers or edit the TaskProcessing provider."""
+        require_capabilities("app_api", await self._session.capabilities)
+        params = {
+            "name": name,
+            "displayName": display_name,
+            "taskType": task_type,
+            "customTaskType": custom_task_type,
+        }
+        clear_from_params_empty(["customTaskType"], params)
+        await self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
+
+    async def unregister(self, name: str, not_fail=True) -> None:
+        """Removes TaskProcessing provider."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            await self._session.ocs("DELETE", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"name": name})
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    async def next_task(self, provider_ids: list[str], task_types: list[str]) -> dict[str, typing.Any]:
+        """Get the next task processing task from Nextcloud."""
+        with contextlib.suppress(NextcloudException):
+            if r := await self._session.ocs(
+                "GET",
+                "/ocs/v2.php/taskprocessing/tasks_provider/next",
+                json={"providerIds": provider_ids, "taskTypeIds": task_types},
+            ):
+                return r
+        return {}
+
+    async def set_progress(self, task_id: int, progress: float) -> dict[str, typing.Any]:
+        """Report new progress value of the task to Nextcloud. Progress should be in range from 0.0 to 100.0."""
+        with contextlib.suppress(NextcloudException):
+            if r := await self._session.ocs(
+                "POST",
+                f"/ocs/v2.php/taskprocessing/tasks_provider/{task_id}/progress",
+                json={"taskId": task_id, "progress": progress / 100.0},
+            ):
+                return r
+        return {}
+
+    async def upload_result_file(self, task_id: int, file: bytes | str | typing.Any) -> int:
+        """Uploads file and returns fileID that should be used in the ``report_result`` function.
+
+        .. note:: ``file`` can be any file-like object.
+        """
+        return (
+            await self._session.ocs(
+                "POST",
+                f"/ocs/v2.php/taskprocessing/tasks_provider/{task_id}/file",
+                files={"file": file},
+            )
+        )["fileId"]
+
+    async def report_result(
+        self,
+        task_id: int,
+        output: dict[str, typing.Any] | None = None,
+        error_message: str | None = None,
+    ) -> dict[str, typing.Any]:
+        """Report result of the task processing to Nextcloud."""
+        with contextlib.suppress(NextcloudException):
+            if r := await self._session.ocs(
+                "POST",
+                f"/ocs/v2.php/taskprocessing/tasks_provider/{task_id}/result",
+                json={"taskId": task_id, "output": output, "errorMessage": error_message},
+            ):
+                return r
+        return {}

nc_py_api/ex_app/ui/files_actions.py

@@ -1,6 +1,7 @@
 """Nextcloud API for working with drop-down file's menu."""
 
 import dataclasses
+import warnings
 
 from ..._exceptions import NextcloudExceptionNotFound
 from ..._misc import require_capabilities
@@ -54,6 +55,11 @@ class UiFileActionEntry:
         """Relative ExApp url which will be called if user click on the entry."""
         return self._raw_data["action_handler"]
 
+    @property
+    def version(self) -> str:
+        """AppAPI `2.6.0` supports new version of UiActions(https://github.com/cloud-py-api/app_api/pull/284)."""
+        return self._raw_data.get("version", "1.0")
+
     def __repr__(self):
         return f"<{self.__class__.__name__} name={self.name}, mime={self.mime}, handler={self.action_handler}>"
 
@@ -67,7 +73,12 @@ class _UiFilesActionsAPI:
         self._session = session
 
     def register(self, name: str, display_name: str, callback_url: str, **kwargs) -> None:
-        """Registers the files a dropdown menu element."""
+        """Registers the files dropdown menu element."""
+        warnings.warn(
+            "register() is deprecated and will be removed in a future version. Use register_ex() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         require_capabilities("app_api", self._session.capabilities)
         params = {
             "name": name,
@@ -80,6 +91,20 @@ class _UiFilesActionsAPI:
         }
         self._session.ocs("POST", f"{self._session.ae_url}/{self._ep_suffix}", json=params)
 
+    def register_ex(self, name: str, display_name: str, callback_url: str, **kwargs) -> None:
+        """Registers the files dropdown menu element(extended version that receives ``ActionFileInfoEx``)."""
+        require_capabilities("app_api", self._session.capabilities)
+        params = {
+            "name": name,
+            "displayName": display_name,
+            "actionHandler": callback_url,
+            "icon": kwargs.get("icon", ""),
+            "mime": kwargs.get("mime", "file"),
+            "permissions": kwargs.get("permissions", 31),
+            "order": kwargs.get("order", 0),
+        }
+        self._session.ocs("POST", f"{self._session.ae_url_v2}/{self._ep_suffix}", json=params)
+
     def unregister(self, name: str, not_fail=True) -> None:
         """Removes files dropdown menu element."""
         require_capabilities("app_api", self._session.capabilities)
@@ -110,6 +135,11 @@ class _AsyncUiFilesActionsAPI:
 
     async def register(self, name: str, display_name: str, callback_url: str, **kwargs) -> None:
         """Registers the files a dropdown menu element."""
+        warnings.warn(
+            "register() is deprecated and will be removed in a future version. Use register_ex() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         require_capabilities("app_api", await self._session.capabilities)
         params = {
             "name": name,
@@ -122,6 +152,20 @@ class _AsyncUiFilesActionsAPI:
         }
         await self._session.ocs("POST", f"{self._session.ae_url}/{self._ep_suffix}", json=params)
 
+    async def register_ex(self, name: str, display_name: str, callback_url: str, **kwargs) -> None:
+        """Registers the files dropdown menu element(extended version that receives ``ActionFileInfoEx``)."""
+        require_capabilities("app_api", await self._session.capabilities)
+        params = {
+            "name": name,
+            "displayName": display_name,
+            "actionHandler": callback_url,
+            "icon": kwargs.get("icon", ""),
+            "mime": kwargs.get("mime", "file"),
+            "permissions": kwargs.get("permissions", 31),
+            "order": kwargs.get("order", 0),
+        }
+        await self._session.ocs("POST", f"{self._session.ae_url_v2}/{self._ep_suffix}", json=params)
+
     async def unregister(self, name: str, not_fail=True) -> None:
         """Removes files dropdown menu element."""
         require_capabilities("app_api", await self._session.capabilities)

nc_py_api/files/__init__.py

@@ -203,9 +203,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:
@@ -282,12 +280,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"
@@ -519,3 +518,10 @@ class ActionFileInfo(BaseModel):
             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

@@ -168,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: