nc-py-api 0.11.0__tar.gz → 0.18.1__tar.gz

{nc_py_api-0.11.0 → nc_py_api-0.18.1}/AUTHORS

@@ -6,6 +6,7 @@ answer newbie questions, and generally made NC-Py-API that much better:
     Alexander Piskun <bigcat88@icloud.com>
     CooperGerman <https://github.com/CooperGerman>
     Tobias Tschech <Tobias@tschech-online.de>
+    Scott Williams <scottwilliams@ucsb.edu>
     <Please alphabetize new entries>
 
 A big THANK YOU goes to:

{nc_py_api-0.11.0 → nc_py_api-0.18.1}/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.18.1 - 2025-01-14]
+
+### Fixed
+
+- Chunked Upload V2 not working on Nextcloud 30 and later. #324 Thanks to @DrZoidberg09
+
+## [0.18.0 - 2024-10-09]
+
+### Added
+
+- New `webhooks.unregister_all` method. #309
+
+### Fixed
+
+- Files: `user` and `user_path` properties in `FSNode` when Nextcloud located in the sub-path. #297 Thanks to @vwbusguy
+- `files.download_directory_as_zip` method now supports upcoming Nextcloud 31. #304
+
+## [0.17.1 - 2024-09-06]
+
+### Added
+
+- NextcloudApp: `setup_nextcloud_logging` function to support transparently sending logs to Nextcloud. #294
+
+### Fixed
+
+- NextcloudApp: `nc.log` now suppresses all exceptions to safe call it anywhere(for example in exception handlers). #293
+
+## [0.17.0 - 2024-09-05]
+
+### Added
+
+- `message_type` property to TalkBotMessage. #292
+
+### Changed
+
+- NextcloudApp: `TextProcessing`, `Speech2Text` and `Translation` AI Providers API was removed. #289
+
+## [0.16.0 - 2024-08-12]
+
+### Changed
+
+- NextcloudApp: rework of TaskProcessing provider API. #284
+
+### Fixed
+
+- `nc.files.makedirs` not working properly on Windows. #280 Thanks to @Wuli6
+
+## [0.15.1 - 2024-07-30]
+
+### Fixed
+
+- Corrected behaviour of `ocs` function for `Group Folders` app routes(they are not fully OCS API). #279
+- NextcloudApp: `get_computation_device` function now correctly returns result in upper_case. #278
+
+## [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
+
+- Incorrect `Display name` when creating user, which led to the parameter being ignored. #239 Thanks to @derekbuckley
+
+## [0.12.0 - 2024-04-02]
+
+Update with new features only for `NextcloudApp` class. #233
+
+### Added
+
+- `ex_app.get_computation_device` function for retrieving GPU type(only with AppAPI `2.5.0`+).
+- `ex_app.integration_fastapi.fetch_models_task` are now public function, added `progress_init_start_value` param.
+- Global authentication when used now sets `request.scope["username"]` for easy use.
+
+### Changed
+
+- `UiActionFileInfo` class marked as deprecated, instead `ActionFileInfo` class should be used.
+
 ## [0.11.0 - 2024-02-17]
 
 ### Added

{nc_py_api-0.11.0 → nc_py_api-0.18.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: nc-py-api
-Version: 0.11.0
+Version: 0.18.1
 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/
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Internet :: WWW/HTTP
@@ -38,13 +39,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 +67,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: sphinx-rtd-theme<3; extra == 'docs'
+Requires-Dist: sphinx<8; extra == 'docs'
+Requires-Dist: uvicorn[standard]>=0.23.2; extra == 'docs'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -73,7 +86,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,23 +102,22 @@ 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 |
-|-----------------------|:------------:|:------------:|:------------:|:------------:|
-| Calendar              |      ✅       |      ✅       |      ✅       |      ✅       |
-| File System & Tags    |      ✅       |      ✅       |      ✅       |      ✅       |
-| Nextcloud Talk        |      ✅       |      ✅       |      ✅       |      ✅       |
-| Notifications         |      ✅       |      ✅       |      ✅       |      ✅       |
-| Shares                |      ✅       |      ✅       |      ✅       |      ✅       |
-| 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      |      ✅       |
+| **_Capability_**             | Nextcloud 27 | Nextcloud 28 | Nextcloud 29 | Nextcloud 30 |
+|------------------------------|:------------:|:------------:|:------------:|:------------:|
+| Calendar                     |      ✅       |      ✅       |      ✅       |      ✅       |
+| File System & Tags           |      ✅       |      ✅       |      ✅       |      ✅       |
+| Nextcloud Talk               |      ✅       |      ✅       |      ✅       |      ✅       |
+| Notifications                |      ✅       |      ✅       |      ✅       |      ✅       |
+| Shares                       |      ✅       |      ✅       |      ✅       |      ✅       |
+| Users & Groups               |      ✅       |      ✅       |      ✅       |      ✅       |
+| User & Weather status        |      ✅       |      ✅       |      ✅       |      ✅       |
+| Other APIs**                 |      ✅       |      ✅       |      ✅       |      ✅       |
+| Talk Bot API*                |      ✅       |      ✅       |      ✅       |      ✅       |
+| Settings UI API*             |     N/A      |     N/A      |      ✅       |      ✅       |
+| TaskProcessing Provider API* |     N/A      |     N/A      |     N/A      |      ✅       |
 
 &ast;_available only for **NextcloudApp**_<br>
-&ast;&ast;_available only for **NextcloudApp**: SpeechToText, TextProcessing, Translation_<br>
-&ast;&ast;&ast;_Activity, Notes_
+&ast;&ast;_Activity, Notes_
 
 ### Differences between the Nextcloud and NextcloudApp classes
 

{nc_py_api-0.11.0 → nc_py_api-0.18.1}/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,23 +24,22 @@ 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 |
-|-----------------------|:------------:|:------------:|:------------:|:------------:|
-| Calendar              |      ✅       |      ✅       |      ✅       |      ✅       |
-| File System & Tags    |      ✅       |      ✅       |      ✅       |      ✅       |
-| Nextcloud Talk        |      ✅       |      ✅       |      ✅       |      ✅       |
-| Notifications         |      ✅       |      ✅       |      ✅       |      ✅       |
-| Shares                |      ✅       |      ✅       |      ✅       |      ✅       |
-| 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      |      ✅       |
+| **_Capability_**             | Nextcloud 27 | Nextcloud 28 | Nextcloud 29 | Nextcloud 30 |
+|------------------------------|:------------:|:------------:|:------------:|:------------:|
+| Calendar                     |      ✅       |      ✅       |      ✅       |      ✅       |
+| File System & Tags           |      ✅       |      ✅       |      ✅       |      ✅       |
+| Nextcloud Talk               |      ✅       |      ✅       |      ✅       |      ✅       |
+| Notifications                |      ✅       |      ✅       |      ✅       |      ✅       |
+| Shares                       |      ✅       |      ✅       |      ✅       |      ✅       |
+| Users & Groups               |      ✅       |      ✅       |      ✅       |      ✅       |
+| User & Weather status        |      ✅       |      ✅       |      ✅       |      ✅       |
+| Other APIs**                 |      ✅       |      ✅       |      ✅       |      ✅       |
+| Talk Bot API*                |      ✅       |      ✅       |      ✅       |      ✅       |
+| Settings UI API*             |     N/A      |     N/A      |      ✅       |      ✅       |
+| TaskProcessing Provider API* |     N/A      |     N/A      |     N/A      |      ✅       |
 
 &ast;_available only for **NextcloudApp**_<br>
-&ast;&ast;_available only for **NextcloudApp**: SpeechToText, TextProcessing, Translation_<br>
-&ast;&ast;&ast;_Activity, Notes_
+&ast;&ast;_Activity, Notes_
 
 ### Differences between the Nextcloud and NextcloudApp classes
 

{nc_py_api-0.11.0 → nc_py_api-0.18.1}/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.11.0 → nc_py_api-0.18.1}/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
@@ -123,7 +126,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)
@@ -147,7 +150,7 @@ class NcSessionBase(ABC):
         self.init_adapter()
         self.init_adapter_dav()
         self.response_headers = Headers()
-        self._ocs_regexp = re.compile(r"/ocs/v[12]\.php/")
+        self._ocs_regexp = re.compile(r"/ocs/v[12]\.php/|/apps/groupfolders/")
 
     def init_adapter(self, restart=False) -> None:
         if getattr(self, "adapter", None) is None or restart:
@@ -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
 
@@ -278,6 +289,7 @@ class NcSessionBasic(NcSessionBase, ABC):
         str_url = str(request.url)
         if re.search(self._ocs_regexp, str_url) is not None:  # this is OCS call
             request.url = request.url.copy_merge_params({"format": "json"})
+            request.headers["Accept"] = "application/json"
 
     def _response_event(self, response: Response) -> None:
         str_url = str(response.request.url)
@@ -289,7 +301,7 @@ class NcSessionBasic(NcSessionBase, ABC):
 
     def download2fp(self, url_path: str, fp, dav: bool, params=None, **kwargs):
         adapter = self.adapter_dav if dav else self.adapter
-        with adapter.stream("GET", url_path, params=params) as response:
+        with adapter.stream("GET", url_path, params=params, headers=kwargs.get("headers")) as response:
             check_error(response)
             for data_chunk in response.iter_raw(chunk_size=kwargs.get("chunk_size", 5 * 1024 * 1024)):
                 fp.write(data_chunk)
@@ -307,13 +319,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
 
@@ -398,6 +413,7 @@ class AsyncNcSessionBasic(NcSessionBase, ABC):
         str_url = str(request.url)
         if re.search(self._ocs_regexp, str_url) is not None:  # this is OCS call
             request.url = request.url.copy_merge_params({"format": "json"})
+            request.headers["Accept"] = "application/json"
 
     async def _response_event(self, response: Response) -> None:
         str_url = str(response.request.url)
@@ -409,7 +425,7 @@ class AsyncNcSessionBasic(NcSessionBase, ABC):
 
     async def download2fp(self, url_path: str, fp, dav: bool, params=None, **kwargs):
         adapter = self.adapter_dav if dav else self.adapter
-        async with adapter.stream("GET", url_path, params=params) as response:
+        async with adapter.stream("GET", url_path, params=params, headers=kwargs.get("headers")) as response:
             check_error(response)
             async for data_chunk in response.aiter_raw(chunk_size=kwargs.get("chunk_size", 5 * 1024 * 1024)):
                 fp.write(data_chunk)
@@ -459,7 +475,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 +490,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-0.11.0 → nc_py_api-0.18.1}/nc_py_api/_version.py

@@ -1,3 +1,3 @@
 """Version of nc_py_api."""
 
-__version__ = "0.11.0"
+__version__ = "0.18.1"

{nc_py_api-0.11.0 → nc_py_api-0.18.1}/nc_py_api/apps.py

@@ -1,7 +1,6 @@
 """Nextcloud API for working with applications."""
 
 import dataclasses
-import datetime
 
 from ._misc import require_capabilities
 from ._session import AsyncNcSessionBasic, NcSessionBasic
@@ -34,18 +33,6 @@ class ExAppInfo:
         """Flag indicating if the application enabled."""
         return bool(self._raw_data["enabled"])
 
-    @property
-    def last_check_time(self) -> datetime.datetime:
-        """Time of the last successful application check."""
-        return datetime.datetime.utcfromtimestamp(int(self._raw_data["last_check_time"])).replace(
-            tzinfo=datetime.timezone.utc
-        )
-
-    @property
-    def system(self) -> bool:
-        """Flag indicating if the application is a system application."""
-        return bool(self._raw_data["system"])
-
     def __repr__(self):
         return f"<{self.__class__.__name__} id={self.app_id}, ver={self.version}>"
 

nc_py_api-0.18.1/nc_py_api/ex_app/__init__.py

@@ -0,0 +1,25 @@
+"""All possible ExApp stuff for NextcloudApp that can be used."""
+
+from ..files import ActionFileInfo
+from .defs import FileSystemEventNotification, LogLvl
+from .integration_fastapi import (
+    AppAPIAuthMiddleware,
+    anc_app,
+    atalk_bot_msg,
+    nc_app,
+    set_handlers,
+    talk_bot_msg,
+)
+from .logging import setup_nextcloud_logging
+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.files.ActionFileInfo` instead."""

nc_py_api-0.18.1/nc_py_api/ex_app/defs.py

@@ -0,0 +1,37 @@
+"""Additional definitions for NextcloudApp."""
+
+import enum
+
+from pydantic import BaseModel
+
+from ..files import ActionFileInfo
+
+
+class LogLvl(enum.IntEnum):
+    """Log levels."""
+
+    DEBUG = 0
+    """Debug log level"""
+    INFO = 1
+    """Informational log level"""
+    WARNING = 2
+    """Warning log level. ``Default``"""
+    ERROR = 3
+    """Error log level"""
+    FATAL = 4
+    """Fatal log level"""
+
+
+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-0.18.1/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