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

nc_py_api/ex_app/occ_commands.py

@@ -0,0 +1,153 @@
+"""Nextcloud API for registering OCC commands for ExApps."""
+
+import dataclasses
+
+from .._exceptions import NextcloudExceptionNotFound
+from .._misc import clear_from_params_empty, require_capabilities
+from .._session import AsyncNcSessionApp, NcSessionApp
+
+_EP_SUFFIX: str = "occ_command"
+
+
+@dataclasses.dataclass
+class OccCommand:
+    """OccCommand description."""
+
+    def __init__(self, raw_data: dict):
+        self._raw_data = raw_data
+
+    @property
+    def name(self) -> str:
+        """Unique ID for the command."""
+        return self._raw_data["name"]
+
+    @property
+    def description(self) -> str:
+        """Command description."""
+        return self._raw_data["description"]
+
+    @property
+    def hidden(self) -> bool:
+        """Flag determining ss command hidden or not."""
+        return bool(self._raw_data["hidden"])
+
+    @property
+    def arguments(self) -> dict:
+        """Look at PHP Symfony framework for details."""
+        return self._raw_data["arguments"]
+
+    @property
+    def options(self) -> str:
+        """Look at PHP Symfony framework for details."""
+        return self._raw_data["options"]
+
+    @property
+    def usages(self) -> str:
+        """Look at PHP Symfony framework for details."""
+        return self._raw_data["usages"]
+
+    @property
+    def action_handler(self) -> str:
+        """Relative ExApp url which will be called by Nextcloud."""
+        return self._raw_data["execute_handler"]
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} name={self.name}, handler={self.action_handler}>"
+
+
+class OccCommandsAPI:
+    """API for registering OCC commands, avalaible as **nc.occ_command.<method>**."""
+
+    def __init__(self, session: NcSessionApp):
+        self._session = session
+
+    def register(
+        self,
+        name: str,
+        callback_url: str,
+        arguments: list | None = None,
+        options: list | None = None,
+        usages: list | None = None,
+        description: str = "",
+        hidden: bool = False,
+    ) -> None:
+        """Registers or edit the OCC command."""
+        require_capabilities("app_api", self._session.capabilities)
+        params = {
+            "name": name,
+            "description": description,
+            "arguments": arguments,
+            "hidden": int(hidden),
+            "options": options,
+            "usages": usages,
+            "execute_handler": callback_url,
+        }
+        clear_from_params_empty(["arguments", "options", "usages"], params)
+        self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
+
+    def unregister(self, name: str, not_fail=True) -> None:
+        """Removes the OCC command."""
+        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 get_entry(self, name: str) -> OccCommand | None:
+        """Get information of the OCC command."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            return OccCommand(self._session.ocs("GET", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"name": name}))
+        except NextcloudExceptionNotFound:
+            return None
+
+
+class AsyncOccCommandsAPI:
+    """Async API for registering OCC commands, avalaible as **nc.occ_command.<method>**."""
+
+    def __init__(self, session: AsyncNcSessionApp):
+        self._session = session
+
+    async def register(
+        self,
+        name: str,
+        callback_url: str,
+        arguments: list | None = None,
+        options: list | None = None,
+        usages: list | None = None,
+        description: str = "",
+        hidden: bool = False,
+    ) -> None:
+        """Registers or edit the OCC command."""
+        require_capabilities("app_api", await self._session.capabilities)
+        params = {
+            "name": name,
+            "description": description,
+            "arguments": arguments,
+            "hidden": int(hidden),
+            "options": options,
+            "usages": usages,
+            "execute_handler": callback_url,
+        }
+        clear_from_params_empty(["arguments", "options", "usages"], 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 the OCC command."""
+        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 get_entry(self, name: str) -> OccCommand | None:
+        """Get information of the OCC command."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            return OccCommand(
+                await self._session.ocs("GET", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"name": name})
+            )
+        except NextcloudExceptionNotFound:
+            return None

nc_py_api/ex_app/providers/providers.py

@@ -1,38 +1,24 @@
 """Nextcloud API for AI Providers."""
 
 from ..._session import AsyncNcSessionApp, NcSessionApp
-from .speech_to_text import _AsyncSpeechToTextProviderAPI, _SpeechToTextProviderAPI
-from .text_processing import _AsyncTextProcessingProviderAPI, _TextProcessingProviderAPI
-from .translations import _AsyncTranslationsProviderAPI, _TranslationsProviderAPI
+from .task_processing import _AsyncTaskProcessingProviderAPI, _TaskProcessingProviderAPI
 
 
 class ProvidersApi:
     """Class that encapsulates all AI Providers functionality."""
 
-    speech_to_text: _SpeechToTextProviderAPI
-    """SpeechToText Provider API."""
-    text_processing: _TextProcessingProviderAPI
-    """TextProcessing Provider API."""
-    translations: _TranslationsProviderAPI
-    """Translations Provider API."""
+    task_processing: _TaskProcessingProviderAPI
+    """TaskProcessing Provider API."""
 
     def __init__(self, session: NcSessionApp):
-        self.speech_to_text = _SpeechToTextProviderAPI(session)
-        self.text_processing = _TextProcessingProviderAPI(session)
-        self.translations = _TranslationsProviderAPI(session)
+        self.task_processing = _TaskProcessingProviderAPI(session)
 
 
 class AsyncProvidersApi:
     """Class that encapsulates all AI Providers functionality."""
 
-    speech_to_text: _AsyncSpeechToTextProviderAPI
-    """SpeechToText Provider API."""
-    text_processing: _AsyncTextProcessingProviderAPI
-    """TextProcessing Provider API."""
-    translations: _AsyncTranslationsProviderAPI
-    """Translations Provider API."""
+    task_processing: _AsyncTaskProcessingProviderAPI
+    """TaskProcessing Provider API."""
 
     def __init__(self, session: AsyncNcSessionApp):
-        self.speech_to_text = _AsyncSpeechToTextProviderAPI(session)
-        self.text_processing = _AsyncTextProcessingProviderAPI(session)
-        self.translations = _AsyncTranslationsProviderAPI(session)
+        self.task_processing = _AsyncTaskProcessingProviderAPI(session)

nc_py_api/ex_app/providers/task_processing.py

@@ -0,0 +1,261 @@
+"""Nextcloud API for declaring TaskProcessing provider."""
+
+import contextlib
+import dataclasses
+import typing
+from enum import IntEnum
+
+from pydantic import RootModel
+from pydantic.dataclasses import dataclass
+
+from ..._exceptions import NextcloudException, NextcloudExceptionNotFound
+from ..._misc import require_capabilities
+from ..._session import AsyncNcSessionApp, NcSessionApp
+
+_EP_SUFFIX: str = "ai_provider/task_processing"
+
+
+class ShapeType(IntEnum):
+    """Enum for shape types."""
+
+    NUMBER = 0
+    TEXT = 1
+    IMAGE = 2
+    AUDIO = 3
+    VIDEO = 4
+    FILE = 5
+    ENUM = 6
+    LIST_OF_NUMBERS = 10
+    LIST_OF_TEXTS = 11
+    LIST_OF_IMAGES = 12
+    LIST_OF_AUDIOS = 13
+    LIST_OF_VIDEOS = 14
+    LIST_OF_FILES = 15
+
+
+@dataclass
+class ShapeEnumValue:
+    """Data object for input output shape enum slot value."""
+
+    name: str
+    """Name of the enum slot value which will be displayed in the UI"""
+    value: str
+    """Value of the enum slot value"""
+
+
+@dataclass
+class ShapeDescriptor:
+    """Data object for input output shape entries."""
+
+    name: str
+    """Name of the shape entry"""
+    description: str
+    """Description of the shape entry"""
+    shape_type: ShapeType
+    """Type of the shape entry"""
+
+
+@dataclass
+class TaskType:
+    """TaskType description for the provider."""
+
+    id: str
+    """The unique ID for the task type."""
+    name: str
+    """The localized name of the task type."""
+    description: str
+    """The localized description of the task type."""
+    input_shape: list[ShapeDescriptor]
+    """The input shape of the task."""
+    output_shape: list[ShapeDescriptor]
+    """The output shape of the task."""
+
+
+@dataclass
+class TaskProcessingProvider:
+
+    id: str
+    """Unique ID for the provider."""
+    name: str
+    """The localized name of this provider"""
+    task_type: str
+    """The TaskType provided by this provider."""
+    expected_runtime: int = dataclasses.field(default=0)
+    """Expected runtime of the task in seconds."""
+    optional_input_shape: list[ShapeDescriptor] = dataclasses.field(default_factory=list)
+    """Optional input shape of the task."""
+    optional_output_shape: list[ShapeDescriptor] = dataclasses.field(default_factory=list)
+    """Optional output shape of the task."""
+    input_shape_enum_values: dict[str, list[ShapeEnumValue]] = dataclasses.field(default_factory=dict)
+    """The option dict for each input shape ENUM slot."""
+    input_shape_defaults: dict[str, str | int | float] = dataclasses.field(default_factory=dict)
+    """The default values for input shape slots."""
+    optional_input_shape_enum_values: dict[str, list[ShapeEnumValue]] = dataclasses.field(default_factory=dict)
+    """The option list for each optional input shape ENUM slot."""
+    optional_input_shape_defaults: dict[str, str | int | float] = dataclasses.field(default_factory=dict)
+    """The default values for optional input shape slots."""
+    output_shape_enum_values: dict[str, list[ShapeEnumValue]] = dataclasses.field(default_factory=dict)
+    """The option list for each output shape ENUM slot."""
+    optional_output_shape_enum_values: dict[str, list[ShapeEnumValue]] = dataclasses.field(default_factory=dict)
+    """The option list for each optional output shape ENUM slot."""
+
+    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,
+        provider: TaskProcessingProvider,
+        custom_task_type: TaskType | None = None,
+    ) -> None:
+        """Registers or edit the TaskProcessing provider."""
+        require_capabilities("app_api", self._session.capabilities)
+        params = {
+            "provider": RootModel(provider).model_dump(),
+            **({"customTaskType": RootModel(custom_task_type).model_dump()} if custom_task_type else {}),
+        }
+        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,
+        provider: TaskProcessingProvider,
+        custom_task_type: TaskType | None = None,
+    ) -> None:
+        """Registers or edit the TaskProcessing provider."""
+        require_capabilities("app_api", await self._session.capabilities)
+        params = {
+            "provider": RootModel(provider).model_dump(),
+            **({"customTaskType": RootModel(custom_task_type).model_dump()} if custom_task_type else {}),
+        }
+        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,15 +1,11 @@
 """Nextcloud API for working with drop-down file's menu."""
 
 import dataclasses
-import datetime
-import os
-
-from pydantic import BaseModel
+import warnings
 
 from ..._exceptions import NextcloudExceptionNotFound
 from ..._misc import require_capabilities
 from ..._session import AsyncNcSessionApp, NcSessionApp
-from ...files import FsNode, permissions_to_str
 
 
 @dataclasses.dataclass
@@ -59,65 +55,15 @@ 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}>"
 
 
-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>**."""
 
@@ -127,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,
@@ -140,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)
@@ -170,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,
@@ -182,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)