nc-py-api 0.12.1__tar.gz → 0.15.0__tar.gz

{nc_py_api-0.12.1 → nc_py_api-0.15.0}/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.15.0 - 2024-07-19]
+
+### Added
+
+- Initial Webhooks API support for the upcoming Nextcloud 30. #272
+
+### Changed
+
+- NextcloudApp: `fetch_models_task` function now saves paths to downloaded models. #274 Thanks to @kyteinsky
+
+## [0.14.0 - 2024-07-09]
+
+### Added
+
+- `LoginFlowV2` implementation by @blvdek #255
+- `files.get_tags` function to get all tags assigned to the file or directory. #260
+- NextcloudApp: `nc.ui.files_dropdown_menu.register_ex` to register new version of FileActions(AppAPI 2.6.0+) #252
+- NextcloudApp: `enabled_state` property to check if the current ExApp is disabled or enabled. #268
+- NextcloudApp: support for the new AI API for the Nextcloud 30. #254
+
+## [0.13.0 - 2024-04-28]
+
+### Added
+
+- NextcloudApp: `occ` commands registration API(AppAPI 2.5.0+). #247
+- NextcloudApp: `Nodes` events listener registration API(AppAPI 2.5.0+). #249
+
 ## [0.12.1 - 2024-04-05]
 
 ### Fixed

{nc_py_api-0.12.1 → nc_py_api-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nc-py-api
-Version: 0.12.1
+Version: 0.15.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/
@@ -38,13 +38,24 @@ Provides-Extra: app
 Requires-Dist: uvicorn[standard]>=0.23.2; extra == 'app'
 Provides-Extra: bench
 Requires-Dist: matplotlib; extra == 'bench'
-Requires-Dist: nc-py-api[app]; extra == 'bench'
 Requires-Dist: numpy; extra == 'bench'
 Requires-Dist: py-cpuinfo; extra == 'bench'
+Requires-Dist: uvicorn[standard]>=0.23.2; extra == 'bench'
 Provides-Extra: calendar
 Requires-Dist: caldav==1.3.6; extra == 'calendar'
 Provides-Extra: dev
-Requires-Dist: nc-py-api[bench,calendar,dev-min]; extra == 'dev'
+Requires-Dist: caldav==1.3.6; extra == 'dev'
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: huggingface-hub; extra == 'dev'
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: numpy; extra == 'dev'
+Requires-Dist: pillow; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: py-cpuinfo; extra == 'dev'
+Requires-Dist: pylint; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.23.2; extra == 'dev'
 Provides-Extra: dev-min
 Requires-Dist: coverage; extra == 'dev-min'
 Requires-Dist: huggingface-hub; extra == 'dev-min'
@@ -55,12 +66,13 @@ Requires-Dist: pytest; extra == 'dev-min'
 Requires-Dist: pytest-asyncio; extra == 'dev-min'
 Provides-Extra: docs
 Requires-Dist: autodoc-pydantic>=2.0.1; extra == 'docs'
-Requires-Dist: nc-py-api[app,calendar]; extra == 'docs'
+Requires-Dist: caldav==1.3.6; extra == 'docs'
 Requires-Dist: sphinx-copybutton; extra == 'docs'
 Requires-Dist: sphinx-inline-tabs; extra == 'docs'
 Requires-Dist: sphinx-issues>=3.0.1; extra == 'docs'
 Requires-Dist: sphinx-rtd-theme>=1; extra == 'docs'
 Requires-Dist: sphinx>=6.2; extra == 'docs'
+Requires-Dist: uvicorn[standard]>=0.23.2; extra == 'docs'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -73,7 +85,7 @@ Description-Content-Type: text/markdown
 [![Docs](https://github.com/cloud-py-api/nc_py_api/actions/workflows/docs.yml/badge.svg)](https://cloud-py-api.github.io/nc_py_api/)
 [![codecov](https://codecov.io/github/cloud-py-api/nc_py_api/branch/main/graph/badge.svg?token=C91PL3FYDQ)](https://codecov.io/github/cloud-py-api/nc_py_api)
 
-![NextcloudVersion](https://img.shields.io/badge/Nextcloud-26%20%7C%2027%20%7C%2028-blue)
+![NextcloudVersion](https://img.shields.io/badge/Nextcloud-27%20%7C%2028%20%7C%2029%20%7C%2030-blue)
 ![PythonVersion](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
 ![impl](https://img.shields.io/pypi/implementation/nc_py_api)
 ![pypi](https://img.shields.io/pypi/v/nc_py_api.svg)
@@ -89,7 +101,7 @@ Python library that provides a robust and well-documented API that allows develo
  * **Sync + Async**: Provides both sync and async APIs.
 
 ### Capabilities
-| **_Capability_**      | Nextcloud 26 | Nextcloud 27 | Nextcloud 28 | Nextcloud 29 |
+| **_Capability_**      | Nextcloud 27 | Nextcloud 28 | Nextcloud 29 | Nextcloud 30 |
 |-----------------------|:------------:|:------------:|:------------:|:------------:|
 | Calendar              |      ✅       |      ✅       |      ✅       |      ✅       |
 | File System & Tags    |      ✅       |      ✅       |      ✅       |      ✅       |
@@ -99,9 +111,9 @@ Python library that provides a robust and well-documented API that allows develo
 | Users & Groups        |      ✅       |      ✅       |      ✅       |      ✅       |
 | User & Weather status |      ✅       |      ✅       |      ✅       |      ✅       |
 | Other APIs***         |      ✅       |      ✅       |      ✅       |      ✅       |
-| Talk Bot API*         |     N/A      |      ✅       |      ✅       |      ✅       |
-| Settings UI API*      |     N/A      |     N/A      |     N/A      |      ✅       |
-| AI Providers API**    |     N/A      |     N/A      |     N/A      |      ✅       |
+| Talk Bot API*         |      ✅       |      ✅       |      ✅       |      ✅       |
+| Settings UI API*      |     N/A      |     N/A      |      ✅       |      ✅       |
+| AI Providers API**    |     N/A      |     N/A      |      ✅       |      ✅       |
 
 &ast;_available only for **NextcloudApp**_<br>
 &ast;&ast;_available only for **NextcloudApp**: SpeechToText, TextProcessing, Translation_<br>

{nc_py_api-0.12.1 → nc_py_api-0.15.0}/README.md

@@ -8,7 +8,7 @@
 [![Docs](https://github.com/cloud-py-api/nc_py_api/actions/workflows/docs.yml/badge.svg)](https://cloud-py-api.github.io/nc_py_api/)
 [![codecov](https://codecov.io/github/cloud-py-api/nc_py_api/branch/main/graph/badge.svg?token=C91PL3FYDQ)](https://codecov.io/github/cloud-py-api/nc_py_api)
 
-![NextcloudVersion](https://img.shields.io/badge/Nextcloud-26%20%7C%2027%20%7C%2028-blue)
+![NextcloudVersion](https://img.shields.io/badge/Nextcloud-27%20%7C%2028%20%7C%2029%20%7C%2030-blue)
 ![PythonVersion](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
 ![impl](https://img.shields.io/pypi/implementation/nc_py_api)
 ![pypi](https://img.shields.io/pypi/v/nc_py_api.svg)
@@ -24,7 +24,7 @@ Python library that provides a robust and well-documented API that allows develo
  * **Sync + Async**: Provides both sync and async APIs.
 
 ### Capabilities
-| **_Capability_**      | Nextcloud 26 | Nextcloud 27 | Nextcloud 28 | Nextcloud 29 |
+| **_Capability_**      | Nextcloud 27 | Nextcloud 28 | Nextcloud 29 | Nextcloud 30 |
 |-----------------------|:------------:|:------------:|:------------:|:------------:|
 | Calendar              |      ✅       |      ✅       |      ✅       |      ✅       |
 | File System & Tags    |      ✅       |      ✅       |      ✅       |      ✅       |
@@ -34,9 +34,9 @@ Python library that provides a robust and well-documented API that allows develo
 | Users & Groups        |      ✅       |      ✅       |      ✅       |      ✅       |
 | User & Weather status |      ✅       |      ✅       |      ✅       |      ✅       |
 | Other APIs***         |      ✅       |      ✅       |      ✅       |      ✅       |
-| Talk Bot API*         |     N/A      |      ✅       |      ✅       |      ✅       |
-| Settings UI API*      |     N/A      |     N/A      |     N/A      |      ✅       |
-| AI Providers API**    |     N/A      |     N/A      |     N/A      |      ✅       |
+| Talk Bot API*         |      ✅       |      ✅       |      ✅       |      ✅       |
+| Settings UI API*      |     N/A      |     N/A      |      ✅       |      ✅       |
+| AI Providers API**    |     N/A      |     N/A      |      ✅       |      ✅       |
 
 &ast;_available only for **NextcloudApp**_<br>
 &ast;&ast;_available only for **NextcloudApp**: SpeechToText, TextProcessing, Translation_<br>

{nc_py_api-0.12.1 → nc_py_api-0.15.0}/nc_py_api/__init__.py

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

{nc_py_api-0.12.1 → nc_py_api-0.15.0}/nc_py_api/_session.py

@@ -103,7 +103,10 @@ class Config(BasicConfig):
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
-        self.auth = (self._get_config_value("nc_auth_user", **kwargs), self._get_config_value("nc_auth_pass", **kwargs))
+        nc_auth_user = self._get_config_value("nc_auth_user", raise_not_found=False, **kwargs)
+        nc_auth_pass = self._get_config_value("nc_auth_pass", raise_not_found=False, **kwargs)
+        if nc_auth_user and nc_auth_pass:
+            self.auth = (nc_auth_user, nc_auth_pass)
 
 
 @dataclass
@@ -173,9 +176,14 @@ class NcSessionBase(ABC):
 
     @property
     def ae_url(self) -> str:
-        """Return base url for the App Ecosystem endpoints."""
+        """Return base url for the AppAPI endpoints."""
         return "/ocs/v1.php/apps/app_api/api/v1"
 
+    @property
+    def ae_url_v2(self) -> str:
+        """Return base url for the AppAPI endpoints(version 2)."""
+        return "/ocs/v1.php/apps/app_api/api/v2"
+
 
 class NcSessionBasic(NcSessionBase, ABC):
     adapter: Client
@@ -189,13 +197,16 @@ class NcSessionBasic(NcSessionBase, ABC):
         content: bytes | str | typing.Iterable[bytes] | typing.AsyncIterable[bytes] | None = None,
         json: dict | list | None = None,
         params: dict | None = None,
+        files: dict | None = None,
         **kwargs,
     ):
         self.init_adapter()
         info = f"request: {method} {path}"
         nested_req = kwargs.pop("nested_req", False)
         try:
-            response = self.adapter.request(method, path, content=content, json=json, params=params, **kwargs)
+            response = self.adapter.request(
+                method, path, content=content, json=json, params=params, files=files, **kwargs
+            )
         except ReadTimeout:
             raise NextcloudException(408, info=info) from None
 
@@ -307,13 +318,16 @@ class AsyncNcSessionBasic(NcSessionBase, ABC):
         content: bytes | str | typing.Iterable[bytes] | typing.AsyncIterable[bytes] | None = None,
         json: dict | list | None = None,
         params: dict | None = None,
+        files: dict | None = None,
         **kwargs,
     ):
         self.init_adapter()
         info = f"request: {method} {path}"
         nested_req = kwargs.pop("nested_req", False)
         try:
-            response = await self.adapter.request(method, path, content=content, json=json, params=params, **kwargs)
+            response = await self.adapter.request(
+                method, path, content=content, json=json, params=params, files=files, **kwargs
+            )
         except ReadTimeout:
             raise NextcloudException(408, info=info) from None
 

{nc_py_api-0.12.1 → nc_py_api-0.15.0}/nc_py_api/_version.py

@@ -1,3 +1,3 @@
 """Version of nc_py_api."""
 
-__version__ = "0.12.1"
+__version__ = "0.15.0"

{nc_py_api-0.12.1 → nc_py_api-0.15.0}/nc_py_api/apps.py

@@ -43,8 +43,8 @@ class ExAppInfo:
 
     @property
     def system(self) -> bool:
-        """Flag indicating if the application is a system application."""
-        return bool(self._raw_data["system"])
+        """**DEPRECATED** Flag indicating if the application is a system application."""
+        return True
 
     def __repr__(self):
         return f"<{self.__class__.__name__} id={self.app_id}, ver={self.version}>"

{nc_py_api-0.12.1 → nc_py_api-0.15.0}/nc_py_api/ex_app/__init__.py

@@ -21,4 +21,4 @@ from .uvicorn_fastapi import run_app
 
 
 class UiActionFileInfo(ActionFileInfo):
-    """``Deprecated``: use :py:class:`~nc_py_api.ex_app.ActionFileInfo` instead."""
+    """``Deprecated``: use :py:class:`~nc_py_api.files.ActionFileInfo` instead."""

nc_py_api-0.15.0/nc_py_api/ex_app/events_listener.py

@@ -0,0 +1,137 @@
+"""Nextcloud API for registering Events listeners for ExApps."""
+
+import dataclasses
+
+from .._exceptions import NextcloudExceptionNotFound
+from .._misc import require_capabilities
+from .._session import AsyncNcSessionApp, NcSessionApp
+
+_EP_SUFFIX: str = "events_listener"
+
+
+@dataclasses.dataclass
+class EventsListener:
+    """EventsListener description."""
+
+    def __init__(self, raw_data: dict):
+        self._raw_data = raw_data
+
+    @property
+    def event_type(self) -> str:
+        """Main type of event, e.g. ``node_event``."""
+        return self._raw_data["event_type"]
+
+    @property
+    def event_subtypes(self) -> str:
+        """Subtypes for which fire event, e.g. ``NodeCreatedEvent``, ``NodeDeletedEvent``."""
+        return self._raw_data["event_subtypes"]
+
+    @property
+    def action_handler(self) -> str:
+        """Relative ExApp url which will be called by Nextcloud."""
+        return self._raw_data["action_handler"]
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} event_type={self.event_type}, handler={self.action_handler}>"
+
+
+class EventsListenerAPI:
+    """API for registering Events listeners, avalaible as **nc.events_handler.<method>**."""
+
+    def __init__(self, session: NcSessionApp):
+        self._session = session
+
+    def register(
+        self,
+        event_type: str,
+        callback_url: str,
+        event_subtypes: list[str] | None = None,
+    ) -> None:
+        """Registers or edits the events listener."""
+        if event_subtypes is None:
+            event_subtypes = []
+        require_capabilities("app_api", self._session.capabilities)
+        params = {
+            "eventType": event_type,
+            "actionHandler": callback_url,
+            "eventSubtypes": event_subtypes,
+        }
+        self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
+
+    def unregister(self, event_type: str, not_fail=True) -> None:
+        """Removes the events listener."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            self._session.ocs(
+                "DELETE",
+                f"{self._session.ae_url}/{_EP_SUFFIX}",
+                params={"eventType": event_type},
+            )
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    def get_entry(self, event_type: str) -> EventsListener | None:
+        """Get information about the event listener."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            return EventsListener(
+                self._session.ocs(
+                    "GET",
+                    f"{self._session.ae_url}/{_EP_SUFFIX}",
+                    params={"eventType": event_type},
+                )
+            )
+        except NextcloudExceptionNotFound:
+            return None
+
+
+class AsyncEventsListenerAPI:
+    """API for registering Events listeners, avalaible as **nc.events_handler.<method>**."""
+
+    def __init__(self, session: AsyncNcSessionApp):
+        self._session = session
+
+    async def register(
+        self,
+        event_type: str,
+        callback_url: str,
+        event_subtypes: list[str] | None = None,
+    ) -> None:
+        """Registers or edits the events listener."""
+        if event_subtypes is None:
+            event_subtypes = []
+        require_capabilities("app_api", await self._session.capabilities)
+        params = {
+            "eventType": event_type,
+            "actionHandler": callback_url,
+            "eventSubtypes": event_subtypes,
+        }
+        await self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
+
+    async def unregister(self, event_type: str, not_fail=True) -> None:
+        """Removes the events listener."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            await self._session.ocs(
+                "DELETE",
+                f"{self._session.ae_url}/{_EP_SUFFIX}",
+                params={"eventType": event_type},
+            )
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    async def get_entry(self, event_type: str) -> EventsListener | None:
+        """Get information about the event listener."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            return EventsListener(
+                await self._session.ocs(
+                    "GET",
+                    f"{self._session.ae_url}/{_EP_SUFFIX}",
+                    params={"eventType": event_type},
+                )
+            )
+        except NextcloudExceptionNotFound:
+            return None

{nc_py_api-0.12.1 → nc_py_api-0.15.0}/nc_py_api/ex_app/integration_fastapi.py

@@ -127,22 +127,26 @@ def fetch_models_task(nc: NextcloudApp, models: dict[str, dict], progress_init_s
         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])
+                models[model]["path"] = __fetch_model_as_file(
+                    current_progress, percent_for_each, nc, model, models[model]
+                )
             else:
-                __fetch_model_as_snapshot(current_progress, percent_for_each, nc, model, models[model])
+                models[model]["path"] = __fetch_model_as_snapshot(
+                    current_progress, percent_for_each, nc, model, models[model]
+                )
             current_progress += percent_for_each
     nc.set_init_status(100)
 
 
 def __fetch_model_as_file(
     current_progress: int, progress_for_task: int, nc: NextcloudApp, model_path: str, download_options: dict
-) -> None:
+) -> str | None:
     result_path = download_options.pop("save_path", urlparse(model_path).path.split("/")[-1])
     try:
         with httpx.stream("GET", model_path, follow_redirects=True) as response:
             if not response.is_success:
                 nc.log(LogLvl.ERROR, f"Downloading of '{model_path}' returned {response.status_code} status.")
-                return
+                return None
             downloaded_size = 0
             linked_etag = ""
             for each_history in response.history:
@@ -163,7 +167,7 @@ def __fetch_model_as_file(
                         sha256_hash.update(byte_block)
                     if f'"{sha256_hash.hexdigest()}"' == linked_etag:
                         nc.set_init_status(min(current_progress + progress_for_task, 99))
-                        return
+                        return None
 
             with builtins.open(result_path, "wb") as file:
                 last_progress = current_progress
@@ -174,13 +178,17 @@ def __fetch_model_as_file(
                         if new_progress != last_progress:
                             nc.set_init_status(new_progress)
                             last_progress = new_progress
+
+        return result_path
     except Exception as e:  # noqa pylint: disable=broad-exception-caught
         nc.log(LogLvl.ERROR, f"Downloading of '{model_path}' raised an exception: {e}")
 
+    return None
+
 
 def __fetch_model_as_snapshot(
     current_progress: int, progress_for_task, nc: NextcloudApp, mode_name: str, download_options: dict
-) -> None:
+) -> str:
     from huggingface_hub import snapshot_download  # noqa isort:skip pylint: disable=C0415 disable=E0401
     from tqdm import tqdm  # noqa isort:skip pylint: disable=C0415 disable=E0401
 
@@ -191,7 +199,9 @@ def __fetch_model_as_snapshot(
 
     workers = download_options.pop("max_workers", 2)
     cache = download_options.pop("cache_dir", persistent_storage())
-    snapshot_download(mode_name, tqdm_class=TqdmProgress, **download_options, max_workers=workers, cache_dir=cache)
+    return snapshot_download(
+        mode_name, tqdm_class=TqdmProgress, **download_options, max_workers=workers, cache_dir=cache
+    )
 
 
 def __nc_app(request: HTTPConnection) -> dict:

nc_py_api-0.15.0/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-0.12.1 → nc_py_api-0.15.0}/nc_py_api/ex_app/providers/providers.py

@@ -2,6 +2,7 @@
 
 from ..._session import AsyncNcSessionApp, NcSessionApp
 from .speech_to_text import _AsyncSpeechToTextProviderAPI, _SpeechToTextProviderAPI
+from .task_processing import _AsyncTaskProcessingProviderAPI, _TaskProcessingProviderAPI
 from .text_processing import _AsyncTextProcessingProviderAPI, _TextProcessingProviderAPI
 from .translations import _AsyncTranslationsProviderAPI, _TranslationsProviderAPI
 
@@ -15,11 +16,14 @@ class ProvidersApi:
     """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:
@@ -31,8 +35,11 @@ class AsyncProvidersApi:
     """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)