nc-py-api 0.7.1__tar.gz → 0.8.0__tar.gz

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/CHANGELOG.md

@@ -2,13 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.7.1 - 2022-12-2x]
+## [0.8.0 - 2024-01-12]
+
+### Added
+
+- `download_log` method to download `nextcloud.log`. #199
+- NextcloudApp: API for registering `Speech to Text` providers(*avalaible from Nextcloud 29*). #196
+- NextcloudApp: API for registering `Text Processing` providers(*avalaible from Nextcloud 29*). #198
+- NextcloudApp: added `get_model_path` wrapper around huggingface_hub:snapshot_download. #202
+
+### Fixed
+
+- OCS: Correctly handling of `HTTP 204 No Content` status. #197
+
+## [0.7.2 - 2023-12-28]
+
+### Fixed
+
+- files: proper url encoding of special chars in `mkdir` and `delete` methods. #191 Thanks to @tobenary
+- files: proper url encoding of special chars in all other `DAV` methods. #194
+
+## [0.7.1 - 2023-12-21]
 
 ### Added
 
 - The `ocs` method is now public, making it easy to use Nextcloud OCS that has not yet been described. #187
 
-## [0.7.0 - 2022-12-17]
+## [0.7.0 - 2023-12-17]
 
 ### Added
 

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nc-py-api
-Version: 0.7.1
+Version: 0.8.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/
@@ -89,21 +89,21 @@ 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 |
-|-----------------------|:------------:|:------------:|:------------:|
-| Calendar              |      ✅       |      ✅       |      ✅       |
-| File System & Tags    |      ✅       |      ✅       |      ✅       |
-| Nextcloud Talk        |      ✅       |      ✅       |      ✅       |
-| Notifications         |      ✅       |      ✅       |      ✅       |
-| Shares                |      ✅       |      ✅       |      ✅       |
-| Users & Groups        |      ✅       |      ✅       |      ✅       |
-| User & Weather status |      ✅       |      ✅       |      ✅       |
-| Other APIs***         |      ✅       |      ✅       |      ✅       |
-| Talk Bot API*         |     N/A      |      ✅       |      ✅       |
-| Text Processing*      |     N/A      |      ❌       |      ❌       |
-| SpeechToText*         |     N/A      |      ❌       |      ❌       |
-
-&ast;_available only for NextcloudApp_<br>
+| **_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      |      ✅       |      ✅       |      ✅       |
+| AI Providers API**    |     N/A      |     N/A      |     N/A      |      ✅       |
+
+&ast;_available only for **NextcloudApp**_<br>
+&ast;&ast;_available only for **NextcloudApp**: SpeechToText, TextProcessing_<br>
 &ast;&ast;&ast;_Activity, Notes_
 
 ### Differences between the Nextcloud and NextcloudApp classes

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/README.md

@@ -24,21 +24,21 @@ 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 |
-|-----------------------|:------------:|:------------:|:------------:|
-| Calendar              |      ✅       |      ✅       |      ✅       |
-| File System & Tags    |      ✅       |      ✅       |      ✅       |
-| Nextcloud Talk        |      ✅       |      ✅       |      ✅       |
-| Notifications         |      ✅       |      ✅       |      ✅       |
-| Shares                |      ✅       |      ✅       |      ✅       |
-| Users & Groups        |      ✅       |      ✅       |      ✅       |
-| User & Weather status |      ✅       |      ✅       |      ✅       |
-| Other APIs***         |      ✅       |      ✅       |      ✅       |
-| Talk Bot API*         |     N/A      |      ✅       |      ✅       |
-| Text Processing*      |     N/A      |      ❌       |      ❌       |
-| SpeechToText*         |     N/A      |      ❌       |      ❌       |
-
-&ast;_available only for NextcloudApp_<br>
+| **_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      |      ✅       |      ✅       |      ✅       |
+| AI Providers API**    |     N/A      |     N/A      |     N/A      |      ✅       |
+
+&ast;_available only for **NextcloudApp**_<br>
+&ast;&ast;_available only for **NextcloudApp**: SpeechToText, TextProcessing_<br>
 &ast;&ast;&ast;_Activity, Notes_
 
 ### Differences between the Nextcloud and NextcloudApp classes

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/nc_py_api/_session.py

@@ -1,5 +1,7 @@
 """Session represents one connection to Nextcloud. All related stuff for these live here."""
 
+import builtins
+import pathlib
 import re
 import typing
 from abc import ABC, abstractmethod
@@ -198,6 +200,8 @@ class NcSessionBasic(NcSessionBase, ABC):
             raise NextcloudException(408, info=info) from None
 
         check_error(response, info)
+        if response.status_code == 204:  # NO_CONTENT
+            return []
         response_data = loads(response.text)
         ocs_meta = response_data["ocs"]["meta"]
         if ocs_meta["status"] != "ok":
@@ -248,6 +252,15 @@ class NcSessionBasic(NcSessionBase, ABC):
     def set_user(self, user_id: str) -> None:
         self._user = user_id
 
+    def download2stream(self, url_path: str, fp, dav: bool = False, **kwargs):
+        if isinstance(fp, str | pathlib.Path):
+            with builtins.open(fp, "wb") as f:
+                self.download2fp(url_path, f, dav, **kwargs)
+        elif hasattr(fp, "write"):
+            self.download2fp(url_path, fp, dav, **kwargs)
+        else:
+            raise TypeError("`fp` must be a path to file or an object with `write` method.")
+
     def _get_adapter_kwargs(self, dav: bool) -> dict[str, typing.Any]:
         if dav:
             return {
@@ -274,6 +287,13 @@ class NcSessionBasic(NcSessionBase, ABC):
                 return
         self.response_headers = response.headers
 
+    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:
+            check_error(response)
+            for data_chunk in response.iter_raw(chunk_size=kwargs.get("chunk_size", 5 * 1024 * 1024)):
+                fp.write(data_chunk)
+
 
 class AsyncNcSessionBasic(NcSessionBase, ABC):
     adapter: AsyncClient
@@ -298,6 +318,8 @@ class AsyncNcSessionBasic(NcSessionBase, ABC):
             raise NextcloudException(408, info=info) from None
 
         check_error(response, info)
+        if response.status_code == 204:  # NO_CONTENT
+            return []
         response_data = loads(response.text)
         ocs_meta = response_data["ocs"]["meta"]
         if ocs_meta["status"] != "ok":
@@ -350,6 +372,15 @@ class AsyncNcSessionBasic(NcSessionBase, ABC):
     def set_user(self, user: str) -> None:
         self._user = user
 
+    async def download2stream(self, url_path: str, fp, dav: bool = False, **kwargs):
+        if isinstance(fp, str | pathlib.Path):
+            with builtins.open(fp, "wb") as f:
+                await self.download2fp(url_path, f, dav, **kwargs)
+        elif hasattr(fp, "write"):
+            await self.download2fp(url_path, fp, dav, **kwargs)
+        else:
+            raise TypeError("`fp` must be a path to file or an object with `write` method.")
+
     def _get_adapter_kwargs(self, dav: bool) -> dict[str, typing.Any]:
         if dav:
             return {
@@ -376,6 +407,13 @@ class AsyncNcSessionBasic(NcSessionBase, ABC):
                 return
         self.response_headers = response.headers
 
+    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:
+            check_error(response)
+            async for data_chunk in response.aiter_raw(chunk_size=kwargs.get("chunk_size", 5 * 1024 * 1024)):
+                fp.write(data_chunk)
+
 
 class NcSession(NcSessionBasic):
     cfg: Config

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/nc_py_api/_version.py

@@ -1,3 +1,3 @@
 """Version of nc_py_api."""
 
-__version__ = "0.7.1"
+__version__ = "0.8.0"

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/nc_py_api/ex_app/__init__.py

@@ -8,6 +8,6 @@ from .integration_fastapi import (
     set_handlers,
     talk_bot_app,
 )
-from .misc import persistent_storage, verify_version
+from .misc import get_model_path, persistent_storage, verify_version
 from .ui.files_actions import UiActionFileInfo
 from .uvicorn_fastapi import run_app

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/nc_py_api/ex_app/defs.py

@@ -39,7 +39,11 @@ class ApiScope(enum.IntEnum):
     """Allows access to Talk API endpoints."""
     TALK_BOT = 60
     """Allows to register Talk Bots."""
+    AI_PROVIDERS = 61
+    """Allows to register AI providers."""
     ACTIVITIES = 110
     """Activity App endpoints."""
     NOTES = 120
-    """Notes App endpoints"""
+    """Notes App endpoints."""
+    ALL = 9999
+    """All endpoints allowed."""

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/nc_py_api/ex_app/misc.py

@@ -43,3 +43,10 @@ def verify_version(finalize_update: bool = True) -> tuple[str, str] | None:
                 version_file.write(os.environ["APP_VERSION"])
                 version_file.truncate()
     return r
+
+
+def get_model_path(model_name: str) -> str:
+    """Wrapper around hugging_face's ``snapshot_download`` to return path to downloaded model directory."""
+    from huggingface_hub import snapshot_download  # noqa isort:skip pylint: disable=C0415 disable=E0401
+
+    return snapshot_download(model_name, local_files_only=True, cache_dir=persistent_storage())

nc_py_api-0.8.0/nc_py_api/ex_app/providers/__init__.py

@@ -0,0 +1 @@
+"""APIs related to Nextcloud Providers."""

nc_py_api-0.8.0/nc_py_api/ex_app/providers/providers.py

@@ -0,0 +1,31 @@
+"""Nextcloud API for AI Providers."""
+
+from ..._session import AsyncNcSessionApp, NcSessionApp
+from .speech_to_text import _AsyncSpeechToTextProviderAPI, _SpeechToTextProviderAPI
+from .text_processing import _AsyncTextProcessingProviderAPI, _TextProcessingProviderAPI
+
+
+class ProvidersApi:
+    """Class that encapsulates all AI Providers functionality."""
+
+    speech_to_text: _SpeechToTextProviderAPI
+    """SpeechToText Provider API."""
+    text_processing: _TextProcessingProviderAPI
+    """TextProcessing Provider API."""
+
+    def __init__(self, session: NcSessionApp):
+        self.speech_to_text = _SpeechToTextProviderAPI(session)
+        self.text_processing = _TextProcessingProviderAPI(session)
+
+
+class AsyncProvidersApi:
+    """Class that encapsulates all AI Providers functionality."""
+
+    speech_to_text: _AsyncSpeechToTextProviderAPI
+    """SpeechToText Provider API."""
+    text_processing: _AsyncTextProcessingProviderAPI
+    """TextProcessing Provider API."""
+
+    def __init__(self, session: AsyncNcSessionApp):
+        self.speech_to_text = _AsyncSpeechToTextProviderAPI(session)
+        self.text_processing = _AsyncTextProcessingProviderAPI(session)

nc_py_api-0.8.0/nc_py_api/ex_app/providers/speech_to_text.py

@@ -0,0 +1,130 @@
+"""Nextcloud API for declaring SpeechToText provider."""
+
+import contextlib
+import dataclasses
+
+from ..._exceptions import NextcloudException, NextcloudExceptionNotFound
+from ..._misc import require_capabilities
+from ..._session import AsyncNcSessionApp, NcSessionApp
+
+
+@dataclasses.dataclass
+class SpeechToTextProvider:
+    """Speech2Text 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 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__} name={self.name}, handler={self.action_handler}>"
+
+
+class _SpeechToTextProviderAPI:
+    """API for registering Speech2Text providers."""
+
+    _ep_suffix: str = "ai_provider/speech_to_text"
+
+    def __init__(self, session: NcSessionApp):
+        self._session = session
+
+    def register(self, name: str, display_name: str, callback_url: str) -> None:
+        """Registers or edit the SpeechToText provider."""
+        require_capabilities("app_api", self._session.capabilities)
+        params = {
+            "name": name,
+            "displayName": display_name,
+            "actionHandler": callback_url,
+        }
+        self._session.ocs("POST", f"{self._session.ae_url}/{self._ep_suffix}", json=params)
+
+    def unregister(self, name: str, not_fail=True) -> None:
+        """Removes SpeechToText provider."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            self._session.ocs("DELETE", f"{self._session.ae_url}/{self._ep_suffix}", params={"name": name})
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    def get_entry(self, name: str) -> SpeechToTextProvider | None:
+        """Get information of the SpeechToText."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            return SpeechToTextProvider(
+                self._session.ocs("GET", f"{self._session.ae_url}/{self._ep_suffix}", params={"name": name})
+            )
+        except NextcloudExceptionNotFound:
+            return None
+
+    def report_result(self, task_id: int, result: str = "", error: str = "") -> None:
+        """Report results of speech to text task to Nextcloud."""
+        require_capabilities("app_api", self._session.capabilities)
+        with contextlib.suppress(NextcloudException):
+            self._session.ocs(
+                "PUT",
+                f"{self._session.ae_url}/{self._ep_suffix}",
+                json={"taskId": task_id, "result": result, "error": error},
+            )
+
+
+class _AsyncSpeechToTextProviderAPI:
+    """API for registering Speech2Text providers."""
+
+    _ep_suffix: str = "ai_provider/speech_to_text"
+
+    def __init__(self, session: AsyncNcSessionApp):
+        self._session = session
+
+    async def register(self, name: str, display_name: str, callback_url: str) -> None:
+        """Registers or edit the SpeechToText provider."""
+        require_capabilities("app_api", await self._session.capabilities)
+        params = {
+            "name": name,
+            "displayName": display_name,
+            "actionHandler": callback_url,
+        }
+        await self._session.ocs("POST", f"{self._session.ae_url}/{self._ep_suffix}", json=params)
+
+    async def unregister(self, name: str, not_fail=True) -> None:
+        """Removes SpeechToText provider."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            await self._session.ocs("DELETE", f"{self._session.ae_url}/{self._ep_suffix}", params={"name": name})
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    async def get_entry(self, name: str) -> SpeechToTextProvider | None:
+        """Get information of the SpeechToText."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            return SpeechToTextProvider(
+                await self._session.ocs("GET", f"{self._session.ae_url}/{self._ep_suffix}", params={"name": name})
+            )
+        except NextcloudExceptionNotFound:
+            return None
+
+    async def report_result(self, task_id: int, result: str = "", error: str = "") -> None:
+        """Report results of speech to text task to Nextcloud."""
+        require_capabilities("app_api", await self._session.capabilities)
+        with contextlib.suppress(NextcloudException):
+            await self._session.ocs(
+                "PUT",
+                f"{self._session.ae_url}/{self._ep_suffix}",
+                json={"taskId": task_id, "result": result, "error": error},
+            )

nc_py_api-0.8.0/nc_py_api/ex_app/providers/text_processing.py

@@ -0,0 +1,137 @@
+"""Nextcloud API for declaring TextProcessing provider."""
+
+import contextlib
+import dataclasses
+
+from ..._exceptions import NextcloudException, NextcloudExceptionNotFound
+from ..._misc import require_capabilities
+from ..._session import AsyncNcSessionApp, NcSessionApp
+
+
+@dataclasses.dataclass
+class TextProcessingProvider:
+    """TextProcessing 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 action_handler(self) -> str:
+        """Relative ExApp url which will be called by Nextcloud."""
+        return self._raw_data["action_handler"]
+
+    @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}, handler={self.action_handler}>"
+
+
+class _TextProcessingProviderAPI:
+    """API for registering TextProcessing providers."""
+
+    _ep_suffix: str = "ai_provider/text_processing"
+
+    def __init__(self, session: NcSessionApp):
+        self._session = session
+
+    def register(self, name: str, display_name: str, callback_url: str, task_type: str) -> None:
+        """Registers or edit the TextProcessing provider."""
+        require_capabilities("app_api", self._session.capabilities)
+        params = {
+            "name": name,
+            "displayName": display_name,
+            "actionHandler": callback_url,
+            "taskType": task_type,
+        }
+        self._session.ocs("POST", f"{self._session.ae_url}/{self._ep_suffix}", json=params)
+
+    def unregister(self, name: str, not_fail=True) -> None:
+        """Removes TextProcessing provider."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            self._session.ocs("DELETE", f"{self._session.ae_url}/{self._ep_suffix}", params={"name": name})
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    def get_entry(self, name: str) -> TextProcessingProvider | None:
+        """Get information of the TextProcessing."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            return TextProcessingProvider(
+                self._session.ocs("GET", f"{self._session.ae_url}/{self._ep_suffix}", params={"name": name})
+            )
+        except NextcloudExceptionNotFound:
+            return None
+
+    def report_result(self, task_id: int, result: str = "", error: str = "") -> None:
+        """Report results of the text processing to Nextcloud."""
+        require_capabilities("app_api", self._session.capabilities)
+        with contextlib.suppress(NextcloudException):
+            self._session.ocs(
+                "PUT",
+                f"{self._session.ae_url}/{self._ep_suffix}",
+                json={"taskId": task_id, "result": result, "error": error},
+            )
+
+
+class _AsyncTextProcessingProviderAPI:
+    """API for registering TextProcessing providers."""
+
+    _ep_suffix: str = "ai_provider/text_processing"
+
+    def __init__(self, session: AsyncNcSessionApp):
+        self._session = session
+
+    async def register(self, name: str, display_name: str, callback_url: str, task_type: str) -> None:
+        """Registers or edit the TextProcessing provider."""
+        require_capabilities("app_api", await self._session.capabilities)
+        params = {
+            "name": name,
+            "displayName": display_name,
+            "actionHandler": callback_url,
+            "taskType": task_type,
+        }
+        await self._session.ocs("POST", f"{self._session.ae_url}/{self._ep_suffix}", json=params)
+
+    async def unregister(self, name: str, not_fail=True) -> None:
+        """Removes TextProcessing provider."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            await self._session.ocs("DELETE", f"{self._session.ae_url}/{self._ep_suffix}", params={"name": name})
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    async def get_entry(self, name: str) -> TextProcessingProvider | None:
+        """Get information of the TextProcessing."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            return TextProcessingProvider(
+                await self._session.ocs("GET", f"{self._session.ae_url}/{self._ep_suffix}", params={"name": name})
+            )
+        except NextcloudExceptionNotFound:
+            return None
+
+    async def report_result(self, task_id: int, result: str = "", error: str = "") -> None:
+        """Report results of the text processing to Nextcloud."""
+        require_capabilities("app_api", await self._session.capabilities)
+        with contextlib.suppress(NextcloudException):
+            await self._session.ocs(
+                "PUT",
+                f"{self._session.ae_url}/{self._ep_suffix}",
+                json={"taskId": task_id, "result": result, "error": error},
+            )

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/nc_py_api/ex_app/ui/files_actions.py

@@ -150,7 +150,7 @@ class _UiFilesActionsAPI:
                 raise e from None
 
     def get_entry(self, name: str) -> UiFileActionEntry | None:
-        """Get information of the file action meny entry for current app."""
+        """Get information of the file action meny entry."""
         require_capabilities("app_api", self._session.capabilities)
         try:
             return UiFileActionEntry(

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/nc_py_api/files/files.py

@@ -3,6 +3,7 @@
 import builtins
 import os
 from pathlib import Path
+from urllib.parse import quote
 
 from httpx import Headers
 
@@ -85,7 +86,7 @@ class FilesAPI:
     def download(self, path: str | FsNode) -> bytes:
         """Downloads and returns the content of a file."""
         path = path.user_path if isinstance(path, FsNode) else path
-        response = self._session.adapter_dav.get(dav_get_obj_path(self._session.user, path))
+        response = self._session.adapter_dav.get(quote(dav_get_obj_path(self._session.user, path)))
         check_error(response, f"download: user={self._session.user}, path={path}")
         return response.content
 
@@ -97,14 +98,8 @@ class FilesAPI:
             The object must implement the ``file.write`` method and be able to write binary data.
         :param kwargs: **chunk_size** an int value specifying chunk size to write. Default = **5Mb**
         """
-        path = path.user_path if isinstance(path, FsNode) else path
-        if isinstance(fp, str | Path):
-            with builtins.open(fp, "wb") as f:
-                self.__download2stream(path, f, **kwargs)
-        elif hasattr(fp, "write"):
-            self.__download2stream(path, fp, **kwargs)
-        else:
-            raise TypeError("`fp` must be a path to file or an object with `write` method.")
+        path = quote(dav_get_obj_path(self._session.user, path.user_path if isinstance(path, FsNode) else path))
+        self._session.download2stream(path, fp, dav=True, **kwargs)
 
     def download_directory_as_zip(self, path: str | FsNode, local_path: str | Path | None = None, **kwargs) -> Path:
         """Downloads a remote directory as zip archive.
@@ -116,17 +111,11 @@ class FilesAPI:
         .. note:: This works only for directories, you should not use this to download a file.
         """
         path = path.user_path if isinstance(path, FsNode) else path
-        with self._session.adapter.stream(
-            "GET", "/index.php/apps/files/ajax/download.php", params={"dir": path}
-        ) as response:
-            check_error(response, f"download_directory_as_zip: user={self._session.user}, path={path}")
-            result_path = local_path if local_path else os.path.basename(path)
-            with open(
-                result_path,
-                "wb",
-            ) as fp:
-                for data_chunk in response.iter_raw(chunk_size=kwargs.get("chunk_size", 5 * 1024 * 1024)):
-                    fp.write(data_chunk)
+        result_path = local_path if local_path else os.path.basename(path)
+        with open(result_path, "wb") as fp:
+            self._session.download2fp(
+                "/index.php/apps/files/ajax/download.php", fp, dav=False, params={"dir": path}, **kwargs
+            )
         return Path(result_path)
 
     def upload(self, path: str | FsNode, content: bytes | str) -> FsNode:
@@ -137,7 +126,7 @@ class FilesAPI:
         """
         path = path.user_path if isinstance(path, FsNode) else path
         full_path = dav_get_obj_path(self._session.user, path)
-        response = self._session.adapter_dav.put(full_path, content=content)
+        response = self._session.adapter_dav.put(quote(full_path), content=content)
         check_error(response, f"upload: user={self._session.user}, path={path}, size={len(content)}")
         return FsNode(full_path.strip("/"), **etag_fileid_from_response(response))
 
@@ -166,7 +155,7 @@ class FilesAPI:
         """
         path = path.user_path if isinstance(path, FsNode) else path
         full_path = dav_get_obj_path(self._session.user, path)
-        response = self._session.adapter_dav.request("MKCOL", full_path)
+        response = self._session.adapter_dav.request("MKCOL", quote(full_path))
         check_error(response)
         full_path += "/" if not full_path.endswith("/") else ""
         return FsNode(full_path.lstrip("/"), **etag_fileid_from_response(response))
@@ -201,7 +190,7 @@ class FilesAPI:
         :param not_fail: if set to ``True`` and the object is not found, it does not raise an exception.
         """
         path = path.user_path if isinstance(path, FsNode) else path
-        response = self._session.adapter_dav.delete(dav_get_obj_path(self._session.user, path))
+        response = self._session.adapter_dav.delete(quote(dav_get_obj_path(self._session.user, path)))
         if response.status_code == 404 and not_fail:
             return
         check_error(response)
@@ -218,11 +207,11 @@ class FilesAPI:
         full_dest_path = dav_get_obj_path(
             self._session.user, path_dest.user_path if isinstance(path_dest, FsNode) else path_dest
         )
-        dest = self._session.cfg.dav_endpoint + full_dest_path
+        dest = self._session.cfg.dav_endpoint + quote(full_dest_path)
         headers = Headers({"Destination": dest, "Overwrite": "T" if overwrite else "F"}, encoding="utf-8")
         response = self._session.adapter_dav.request(
             "MOVE",
-            dav_get_obj_path(self._session.user, path_src),
+            quote(dav_get_obj_path(self._session.user, path_src)),
             headers=headers,
         )
         check_error(response, f"move: user={self._session.user}, src={path_src}, dest={dest}, {overwrite}")
@@ -240,11 +229,11 @@ class FilesAPI:
         full_dest_path = dav_get_obj_path(
             self._session.user, path_dest.user_path if isinstance(path_dest, FsNode) else path_dest
         )
-        dest = self._session.cfg.dav_endpoint + full_dest_path
+        dest = self._session.cfg.dav_endpoint + quote(full_dest_path)
         headers = Headers({"Destination": dest, "Overwrite": "T" if overwrite else "F"}, encoding="utf-8")
         response = self._session.adapter_dav.request(
             "COPY",
-            dav_get_obj_path(self._session.user, path_src),
+            quote(dav_get_obj_path(self._session.user, path_src)),
             headers=headers,
         )
         check_error(response, f"copy: user={self._session.user}, src={path_src}, dest={dest}, {overwrite}")
@@ -276,7 +265,7 @@ class FilesAPI:
         path = path.user_path if isinstance(path, FsNode) else path
         root = build_setfav_req(value)
         webdav_response = self._session.adapter_dav.request(
-            "PROPPATCH", dav_get_obj_path(self._session.user, path), content=element_tree_as_str(root)
+            "PROPPATCH", quote(dav_get_obj_path(self._session.user, path)), content=element_tree_as_str(root)
         )
         check_error(webdav_response, f"setfav: path={path}, value={value}")
 
@@ -300,7 +289,7 @@ class FilesAPI:
         headers = Headers({"Destination": dest}, encoding="utf-8")
         response = self._session.adapter_dav.request(
             "MOVE",
-            f"/trashbin/{self._session.user}/{path}",
+            quote(f"/trashbin/{self._session.user}/{path}"),
             headers=headers,
         )
         check_error(response, f"trashbin_restore: user={self._session.user}, src={path}, dest={dest}")
@@ -312,7 +301,7 @@ class FilesAPI:
         :param not_fail: if set to ``True`` and the object is not found, it does not raise an exception.
         """
         path = path.user_path if isinstance(path, FsNode) else path
-        response = self._session.adapter_dav.delete(f"/trashbin/{self._session.user}/{path}")
+        response = self._session.adapter_dav.delete(quote(f"/trashbin/{self._session.user}/{path}"))
         if response.status_code == 404 and not_fail:
             return
         check_error(response)
@@ -430,7 +419,7 @@ class FilesAPI:
         root, dav_path = build_listdir_req(user, path, properties, prop_type)
         webdav_response = self._session.adapter_dav.request(
             "PROPFIND",
-            dav_path,
+            quote(dav_path),
             content=element_tree_as_str(root),
             headers={"Depth": "infinity" if depth == -1 else str(depth)},
         )
@@ -438,17 +427,12 @@ class FilesAPI:
             self._session.cfg.dav_url_suffix, webdav_response, user, path, properties, exclude_self, prop_type
         )
 
-    def __download2stream(self, path: str, fp, **kwargs) -> None:
-        with self._session.adapter_dav.stream("GET", dav_get_obj_path(self._session.user, path)) as response:
-            check_error(response, f"download_stream: user={self._session.user}, path={path}")
-            for data_chunk in response.iter_raw(chunk_size=kwargs.get("chunk_size", 5 * 1024 * 1024)):
-                fp.write(data_chunk)
-
     def __upload_stream(self, path: str, fp, chunk_size: int) -> FsNode:
-        _dav_path = dav_get_obj_path(self._session.user, "nc-py-api-" + random_string(56), root_path="/uploads")
+        _tmp_path = "nc-py-api-" + random_string(56)
+        _dav_path = quote(dav_get_obj_path(self._session.user, _tmp_path, root_path="/uploads"))
         _v2 = bool(self._session.cfg.options.upload_chunk_v2 and chunk_size >= 5 * 1024 * 1024)
         full_path = dav_get_obj_path(self._session.user, path)
-        headers = Headers({"Destination": self._session.cfg.dav_endpoint + full_path}, encoding="utf-8")
+        headers = Headers({"Destination": self._session.cfg.dav_endpoint + quote(full_path)}, encoding="utf-8")
         if _v2:
             response = self._session.adapter_dav.request("MKCOL", _dav_path, headers=headers)
         else:
@@ -547,7 +531,7 @@ class AsyncFilesAPI:
     async def download(self, path: str | FsNode) -> bytes:
         """Downloads and returns the content of a file."""
         path = path.user_path if isinstance(path, FsNode) else path
-        response = await self._session.adapter_dav.get(dav_get_obj_path(await self._session.user, path))
+        response = await self._session.adapter_dav.get(quote(dav_get_obj_path(await self._session.user, path)))
         check_error(response, f"download: user={await self._session.user}, path={path}")
         return response.content
 
@@ -559,14 +543,8 @@ class AsyncFilesAPI:
             The object must implement the ``file.write`` method and be able to write binary data.
         :param kwargs: **chunk_size** an int value specifying chunk size to write. Default = **5Mb**
         """
-        path = path.user_path if isinstance(path, FsNode) else path
-        if isinstance(fp, str | Path):
-            with builtins.open(fp, "wb") as f:
-                await self.__download2stream(path, f, **kwargs)
-        elif hasattr(fp, "write"):
-            await self.__download2stream(path, fp, **kwargs)
-        else:
-            raise TypeError("`fp` must be a path to file or an object with `write` method.")
+        path = quote(dav_get_obj_path(await self._session.user, path.user_path if isinstance(path, FsNode) else path))
+        await self._session.download2stream(path, fp, dav=True, **kwargs)
 
     async def download_directory_as_zip(
         self, path: str | FsNode, local_path: str | Path | None = None, **kwargs
@@ -580,17 +558,11 @@ class AsyncFilesAPI:
         .. note:: This works only for directories, you should not use this to download a file.
         """
         path = path.user_path if isinstance(path, FsNode) else path
-        async with self._session.adapter.stream(
-            "GET", "/index.php/apps/files/ajax/download.php", params={"dir": path}
-        ) as response:
-            check_error(response, f"download_directory_as_zip: user={await self._session.user}, path={path}")
-            result_path = local_path if local_path else os.path.basename(path)
-            with open(
-                result_path,
-                "wb",
-            ) as fp:
-                async for data_chunk in response.aiter_raw(chunk_size=kwargs.get("chunk_size", 5 * 1024 * 1024)):
-                    fp.write(data_chunk)
+        result_path = local_path if local_path else os.path.basename(path)
+        with open(result_path, "wb") as fp:
+            await self._session.download2fp(
+                "/index.php/apps/files/ajax/download.php", fp, dav=False, params={"dir": path}, **kwargs
+            )
         return Path(result_path)
 
     async def upload(self, path: str | FsNode, content: bytes | str) -> FsNode:
@@ -601,7 +573,7 @@ class AsyncFilesAPI:
         """
         path = path.user_path if isinstance(path, FsNode) else path
         full_path = dav_get_obj_path(await self._session.user, path)
-        response = await self._session.adapter_dav.put(full_path, content=content)
+        response = await self._session.adapter_dav.put(quote(full_path), content=content)
         check_error(response, f"upload: user={await self._session.user}, path={path}, size={len(content)}")
         return FsNode(full_path.strip("/"), **etag_fileid_from_response(response))
 
@@ -630,7 +602,7 @@ class AsyncFilesAPI:
         """
         path = path.user_path if isinstance(path, FsNode) else path
         full_path = dav_get_obj_path(await self._session.user, path)
-        response = await self._session.adapter_dav.request("MKCOL", full_path)
+        response = await self._session.adapter_dav.request("MKCOL", quote(full_path))
         check_error(response)
         full_path += "/" if not full_path.endswith("/") else ""
         return FsNode(full_path.lstrip("/"), **etag_fileid_from_response(response))
@@ -665,7 +637,7 @@ class AsyncFilesAPI:
         :param not_fail: if set to ``True`` and the object is not found, it does not raise an exception.
         """
         path = path.user_path if isinstance(path, FsNode) else path
-        response = await self._session.adapter_dav.delete(dav_get_obj_path(await self._session.user, path))
+        response = await self._session.adapter_dav.delete(quote(dav_get_obj_path(await self._session.user, path)))
         if response.status_code == 404 and not_fail:
             return
         check_error(response)
@@ -682,11 +654,11 @@ class AsyncFilesAPI:
         full_dest_path = dav_get_obj_path(
             await self._session.user, path_dest.user_path if isinstance(path_dest, FsNode) else path_dest
         )
-        dest = self._session.cfg.dav_endpoint + full_dest_path
+        dest = self._session.cfg.dav_endpoint + quote(full_dest_path)
         headers = Headers({"Destination": dest, "Overwrite": "T" if overwrite else "F"}, encoding="utf-8")
         response = await self._session.adapter_dav.request(
             "MOVE",
-            dav_get_obj_path(await self._session.user, path_src),
+            quote(dav_get_obj_path(await self._session.user, path_src)),
             headers=headers,
         )
         check_error(response, f"move: user={await self._session.user}, src={path_src}, dest={dest}, {overwrite}")
@@ -704,11 +676,11 @@ class AsyncFilesAPI:
         full_dest_path = dav_get_obj_path(
             await self._session.user, path_dest.user_path if isinstance(path_dest, FsNode) else path_dest
         )
-        dest = self._session.cfg.dav_endpoint + full_dest_path
+        dest = self._session.cfg.dav_endpoint + quote(full_dest_path)
         headers = Headers({"Destination": dest, "Overwrite": "T" if overwrite else "F"}, encoding="utf-8")
         response = await self._session.adapter_dav.request(
             "COPY",
-            dav_get_obj_path(await self._session.user, path_src),
+            quote(dav_get_obj_path(await self._session.user, path_src)),
             headers=headers,
         )
         check_error(response, f"copy: user={await self._session.user}, src={path_src}, dest={dest}, {overwrite}")
@@ -740,7 +712,7 @@ class AsyncFilesAPI:
         path = path.user_path if isinstance(path, FsNode) else path
         root = build_setfav_req(value)
         webdav_response = await self._session.adapter_dav.request(
-            "PROPPATCH", dav_get_obj_path(await self._session.user, path), content=element_tree_as_str(root)
+            "PROPPATCH", quote(dav_get_obj_path(await self._session.user, path)), content=element_tree_as_str(root)
         )
         check_error(webdav_response, f"setfav: path={path}, value={value}")
 
@@ -769,7 +741,7 @@ class AsyncFilesAPI:
         headers = Headers({"Destination": dest}, encoding="utf-8")
         response = await self._session.adapter_dav.request(
             "MOVE",
-            f"/trashbin/{await self._session.user}/{path}",
+            quote(f"/trashbin/{await self._session.user}/{path}"),
             headers=headers,
         )
         check_error(response, f"trashbin_restore: user={await self._session.user}, src={path}, dest={dest}")
@@ -781,7 +753,7 @@ class AsyncFilesAPI:
         :param not_fail: if set to ``True`` and the object is not found, it does not raise an exception.
         """
         path = path.user_path if isinstance(path, FsNode) else path
-        response = await self._session.adapter_dav.delete(f"/trashbin/{await self._session.user}/{path}")
+        response = await self._session.adapter_dav.delete(quote(f"/trashbin/{await self._session.user}/{path}"))
         if response.status_code == 404 and not_fail:
             return
         check_error(response)
@@ -899,7 +871,7 @@ class AsyncFilesAPI:
         root, dav_path = build_listdir_req(user, path, properties, prop_type)
         webdav_response = await self._session.adapter_dav.request(
             "PROPFIND",
-            dav_path,
+            quote(dav_path),
             content=element_tree_as_str(root),
             headers={"Depth": "infinity" if depth == -1 else str(depth)},
         )
@@ -907,19 +879,12 @@ class AsyncFilesAPI:
             self._session.cfg.dav_url_suffix, webdav_response, user, path, properties, exclude_self, prop_type
         )
 
-    async def __download2stream(self, path: str, fp, **kwargs) -> None:
-        async with self._session.adapter_dav.stream(
-            "GET", dav_get_obj_path(await self._session.user, path)
-        ) as response:
-            check_error(response, f"download_stream: user={await self._session.user}, path={path}")
-            async for data_chunk in response.aiter_raw(chunk_size=kwargs.get("chunk_size", 5 * 1024 * 1024)):
-                fp.write(data_chunk)
-
     async def __upload_stream(self, path: str, fp, chunk_size: int) -> FsNode:
-        _dav_path = dav_get_obj_path(await self._session.user, "nc-py-api-" + random_string(56), root_path="/uploads")
+        _tmp_path = "nc-py-api-" + random_string(56)
+        _dav_path = quote(dav_get_obj_path(await self._session.user, _tmp_path, root_path="/uploads"))
         _v2 = bool(self._session.cfg.options.upload_chunk_v2 and chunk_size >= 5 * 1024 * 1024)
         full_path = dav_get_obj_path(await self._session.user, path)
-        headers = Headers({"Destination": self._session.cfg.dav_endpoint + full_path}, encoding="utf-8")
+        headers = Headers({"Destination": self._session.cfg.dav_endpoint + quote(full_path)}, encoding="utf-8")
         if _v2:
             response = await self._session.adapter_dav.request("MKCOL", _dav_path, headers=headers)
         else:

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/nc_py_api/nextcloud.py

@@ -31,6 +31,7 @@ from .activity import _ActivityAPI, _AsyncActivityAPI
 from .apps import _AppsAPI, _AsyncAppsAPI
 from .calendar import _CalendarAPI
 from .ex_app.defs import ApiScope, LogLvl
+from .ex_app.providers.providers import AsyncProvidersApi, ProvidersApi
 from .ex_app.ui.ui import AsyncUiApi, UiApi
 from .files.files import AsyncFilesAPI, FilesAPI
 from .notes import _AsyncNotesAPI, _NotesAPI
@@ -113,6 +114,14 @@ class _NextcloudBasic(ABC):  # pylint: disable=too-many-instance-attributes
         """Returns Theme information."""
         return get_parsed_theme(self.capabilities["theming"]) if "theming" in self.capabilities else None
 
+    def perform_login(self) -> bool:
+        """Performs login into Nextcloud if not already logged in; manual invocation of this method is unnecessary."""
+        try:
+            self.update_server_info()
+        except Exception:  # noqa pylint: disable=broad-exception-caught
+            return False
+        return True
+
     def ocs(
         self,
         method: str,
@@ -126,6 +135,10 @@ class _NextcloudBasic(ABC):  # pylint: disable=too-many-instance-attributes
         """Performs OCS call and returns OCS response payload data."""
         return self._session.ocs(method, path, content=content, json=json, params=params, **kwargs)
 
+    def download_log(self, fp) -> None:
+        """Downloads Nextcloud log file. Requires Admin privileges."""
+        self._session.download2stream("/index.php/settings/admin/log/download", fp)
+
 
 class _AsyncNextcloudBasic(ABC):  # pylint: disable=too-many-instance-attributes
     apps: _AsyncAppsAPI
@@ -199,6 +212,14 @@ class _AsyncNextcloudBasic(ABC):  # pylint: disable=too-many-instance-attributes
         """Returns Theme information."""
         return get_parsed_theme((await self.capabilities)["theming"]) if "theming" in await self.capabilities else None
 
+    async def perform_login(self) -> bool:
+        """Performs login into Nextcloud if not already logged in; manual invocation of this method is unnecessary."""
+        try:
+            await self.update_server_info()
+        except Exception:  # noqa pylint: disable=broad-exception-caught
+            return False
+        return True
+
     async def ocs(
         self,
         method: str,
@@ -212,6 +233,10 @@ class _AsyncNextcloudBasic(ABC):  # pylint: disable=too-many-instance-attributes
         """Performs OCS call and returns OCS response payload data."""
         return await self._session.ocs(method, path, content=content, json=json, params=params, **kwargs)
 
+    async def download_log(self, fp) -> None:
+        """Downloads Nextcloud log file. Requires Admin privileges."""
+        await self._session.download2stream("/index.php/settings/admin/log/download", fp)
+
 
 class Nextcloud(_NextcloudBasic):
     """Nextcloud client class.
@@ -278,6 +303,8 @@ class NextcloudApp(_NextcloudBasic):
     """Nextcloud User Preferences API for ExApps"""
     ui: UiApi
     """Nextcloud UI API for ExApps"""
+    providers: ProvidersApi
+    """API for registering providers for Nextcloud"""
 
     def __init__(self, **kwargs):
         """The parameters will be taken from the environment.
@@ -289,6 +316,7 @@ class NextcloudApp(_NextcloudBasic):
         self.appconfig_ex = AppConfigExAPI(self._session)
         self.preferences_ex = PreferencesExAPI(self._session)
         self.ui = UiApi(self._session)
+        self.providers = ProvidersApi(self._session)
 
     def log(self, log_lvl: LogLvl, content: str) -> None:
         """Writes log to the Nextcloud log file."""
@@ -415,6 +443,8 @@ class AsyncNextcloudApp(_AsyncNextcloudBasic):
     """Nextcloud User Preferences API for ExApps"""
     ui: AsyncUiApi
     """Nextcloud UI API for ExApps"""
+    providers: AsyncProvidersApi
+    """API for registering providers for Nextcloud"""
 
     def __init__(self, **kwargs):
         """The parameters will be taken from the environment.
@@ -426,6 +456,7 @@ class AsyncNextcloudApp(_AsyncNextcloudBasic):
         self.appconfig_ex = AsyncAppConfigExAPI(self._session)
         self.preferences_ex = AsyncPreferencesExAPI(self._session)
         self.ui = AsyncUiApi(self._session)
+        self.providers = AsyncProvidersApi(self._session)
 
     async def log(self, log_lvl: LogLvl, content: str) -> None:
         """Writes log to the Nextcloud log file."""

{nc_py_api-0.7.1 → nc_py_api-0.8.0}/pyproject.toml

@@ -143,7 +143,7 @@ basic.good-names = [
 ]
 reports.output-format = "colorized"
 similarities.ignore-imports = "yes"
-similarities.min-similarity-lines = 6
+similarities.min-similarity-lines = 10
 messages_control.disable = [
     "missing-class-docstring",
     "missing-function-docstring",