nc-py-api 0.17.0__tar.gz → 0.18.0__tar.gz

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/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.17.0 → nc_py_api-0.18.0}/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nc-py-api
-Version: 0.17.0
+Version: 0.18.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/
@@ -70,8 +70,8 @@ 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
 

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/nc_py_api/_session.py

@@ -301,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)
@@ -425,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)

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/nc_py_api/_version.py

@@ -1,3 +1,3 @@
 """Version of nc_py_api."""
 
-__version__ = "0.17.0"
+__version__ = "0.18.0"

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/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:
-        """**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.17.0 → nc_py_api-0.18.0}/nc_py_api/ex_app/__init__.py

@@ -10,6 +10,7 @@ from .integration_fastapi import (
     set_handlers,
     talk_bot_msg,
 )
+from .logging import setup_nextcloud_logging
 from .misc import (
     get_computation_device,
     get_model_path,

nc_py_api-0.18.0/nc_py_api/ex_app/logging.py

@@ -0,0 +1,46 @@
+"""Transparent logging support to store logs in the nextcloud.log."""
+
+import logging
+import threading
+
+from ..nextcloud import NextcloudApp
+from .defs import LogLvl
+
+LOGLVL_MAP = {
+    logging.NOTSET: LogLvl.DEBUG,
+    logging.DEBUG: LogLvl.DEBUG,
+    logging.INFO: LogLvl.INFO,
+    logging.WARNING: LogLvl.WARNING,
+    logging.ERROR: LogLvl.ERROR,
+    logging.CRITICAL: LogLvl.FATAL,
+}
+
+THREAD_LOCAL = threading.local()
+
+
+class _NextcloudLogsHandler(logging.Handler):
+    def __init__(self):
+        super().__init__()
+
+    def emit(self, record):
+        if THREAD_LOCAL.__dict__.get("nc_py_api.loghandler", False):
+            return
+
+        try:
+            THREAD_LOCAL.__dict__["nc_py_api.loghandler"] = True
+            log_entry = self.format(record)
+            log_level = record.levelno
+            NextcloudApp().log(LOGLVL_MAP.get(log_level, LogLvl.FATAL), log_entry, fast_send=True)
+        except Exception:  # noqa pylint: disable=broad-exception-caught
+            self.handleError(record)
+        finally:
+            THREAD_LOCAL.__dict__["nc_py_api.loghandler"] = False
+
+
+def setup_nextcloud_logging(logger_name: str | None = None, logging_level: int = logging.DEBUG):
+    """Function to easily send all or selected log entries to Nextcloud."""
+    logger = logging.getLogger(logger_name)
+    nextcloud_handler = _NextcloudLogsHandler()
+    nextcloud_handler.setLevel(logging_level)
+    logger.addHandler(nextcloud_handler)
+    return nextcloud_handler

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/nc_py_api/files/__init__.py

@@ -5,12 +5,18 @@ import datetime
 import email.utils
 import enum
 import os
+import re
 import warnings
 
 from pydantic import BaseModel
 
 from .. import _misc
 
+user_regex = re.compile(r"(?:files|trashbin|versions)/([^/]+)/")
+"""Regex for evaluating user from full path string; instantiated once on import."""
+user_path_regex = re.compile(r".*?(files|trashbin|versions)/([^/]+)/")
+"""Regex for evaluating user path from full path string; instantiated once on import."""
+
 
 class LockType(enum.IntEnum):
     """Nextcloud File Locks types."""
@@ -218,12 +224,12 @@ class FsNode:
     @property
     def user(self) -> str:
         """Returns user ID extracted from the `full_path`."""
-        return self.full_path.lstrip("/").split("/", maxsplit=2)[1]
+        return user_regex.findall(self.full_path)[0]
 
     @property
     def user_path(self) -> str:
         """Returns path relative to the user's root directory."""
-        return self.full_path.lstrip("/").split("/", maxsplit=2)[-1]
+        return user_path_regex.sub("", self.full_path, count=1)
 
     @property
     def is_shared(self) -> bool:

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/nc_py_api/files/files.py

@@ -115,9 +115,14 @@ class FilesAPI:
         path = path.user_path if isinstance(path, FsNode) else path
         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
-            )
+            if self._session.nc_version["major"] >= 31:
+                full_path = dav_get_obj_path(self._session.user, path)
+                accept_header = f"application/{kwargs.get('format', 'zip')}"
+                self._session.download2fp(quote(full_path), fp, dav=True, headers={"Accept": accept_header})
+            else:
+                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:

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/nc_py_api/files/files_async.py

@@ -119,9 +119,14 @@ class AsyncFilesAPI:
         path = path.user_path if isinstance(path, FsNode) else path
         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
-            )
+            if (await self._session.nc_version)["major"] >= 31:
+                full_path = dav_get_obj_path(await self._session.user, path)
+                accept_header = f"application/{kwargs.get('format', 'zip')}"
+                await self._session.download2fp(quote(full_path), fp, dav=True, headers={"Accept": accept_header})
+            else:
+                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:

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/nc_py_api/nextcloud.py

@@ -348,13 +348,18 @@ class NextcloudApp(_NextcloudBasic):
             return bool(self._session.ocs("GET", "/ocs/v1.php/apps/app_api/ex-app/state"))
         return False
 
-    def log(self, log_lvl: LogLvl, content: str) -> None:
+    def log(self, log_lvl: LogLvl, content: str, fast_send: bool = False) -> None:
         """Writes log to the Nextcloud log file."""
-        if self.check_capabilities("app_api"):
-            return
-        if int(log_lvl) < self.capabilities["app_api"].get("loglevel", 0):
-            return
-        self._session.ocs("POST", f"{self._session.ae_url}/log", json={"level": int(log_lvl), "message": content})
+        int_log_lvl = int(log_lvl)
+        if int_log_lvl < 0 or int_log_lvl > 4:
+            raise ValueError("Invalid `log_lvl` value")
+        if not fast_send:
+            if self.check_capabilities("app_api"):
+                return
+            if int_log_lvl < self.capabilities["app_api"].get("loglevel", 0):
+                return
+        with contextlib.suppress(Exception):
+            self._session.ocs("POST", f"{self._session.ae_url}/log", json={"level": int_log_lvl, "message": content})
 
     def users_list(self) -> list[str]:
         """Returns list of users on the Nextcloud instance."""
@@ -478,13 +483,20 @@ class AsyncNextcloudApp(_AsyncNextcloudBasic):
             return bool(await self._session.ocs("GET", "/ocs/v1.php/apps/app_api/ex-app/state"))
         return False
 
-    async def log(self, log_lvl: LogLvl, content: str) -> None:
+    async def log(self, log_lvl: LogLvl, content: str, fast_send: bool = False) -> None:
         """Writes log to the Nextcloud log file."""
-        if await self.check_capabilities("app_api"):
-            return
-        if int(log_lvl) < (await self.capabilities)["app_api"].get("loglevel", 0):
-            return
-        await self._session.ocs("POST", f"{self._session.ae_url}/log", json={"level": int(log_lvl), "message": content})
+        int_log_lvl = int(log_lvl)
+        if int_log_lvl < 0 or int_log_lvl > 4:
+            raise ValueError("Invalid `log_lvl` value")
+        if not fast_send:
+            if await self.check_capabilities("app_api"):
+                return
+            if int_log_lvl < (await self.capabilities)["app_api"].get("loglevel", 0):
+                return
+        with contextlib.suppress(Exception):
+            await self._session.ocs(
+                "POST", f"{self._session.ae_url}/log", json={"level": int_log_lvl, "message": content}
+            )
 
     async def users_list(self) -> list[str]:
         """Returns list of users on the Nextcloud instance."""

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/nc_py_api/users.py

@@ -369,8 +369,8 @@ class _AsyncUsersAPI:
 
 
 def _create(user_id: str, display_name: str | None, **kwargs) -> dict[str, typing.Any]:
-    password = kwargs.get("password", None)
-    email = kwargs.get("email", None)
+    password = kwargs.get("password")
+    email = kwargs.get("email")
     if not password and not email:
         raise ValueError("Either password or email must be set")
     data = {"userid": user_id}

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/nc_py_api/webhooks.py

@@ -3,7 +3,7 @@
 import dataclasses
 
 from ._misc import clear_from_params_empty  # , require_capabilities
-from ._session import AsyncNcSessionBasic, NcSessionBasic
+from ._session import AppConfig, AsyncNcSessionBasic, NcSessionBasic
 
 
 @dataclasses.dataclass
@@ -140,6 +140,13 @@ class _WebhooksAPI:
     def unregister(self, webhook_id: int) -> bool:
         return self._session.ocs("DELETE", f"{self._ep_base}/{webhook_id}")
 
+    def unregister_all(self, appid: str = "") -> int:
+        if not appid and isinstance(self._session.cfg, AppConfig):
+            appid = self._session.cfg.app_name
+        else:
+            raise ValueError("The `appid` parameter cannot be empty for non-ExApp use.")
+        return self._session.ocs("DELETE", f"{self._ep_base}/byappid/{appid}")
+
 
 class _AsyncWebhooksAPI:
     """The class provides the async application management API on the Nextcloud server."""
@@ -208,3 +215,10 @@ class _AsyncWebhooksAPI:
 
     async def unregister(self, webhook_id: int) -> bool:
         return await self._session.ocs("DELETE", f"{self._ep_base}/{webhook_id}")
+
+    async def unregister_all(self, appid: str = "") -> int:
+        if not appid and isinstance(self._session.cfg, AppConfig):
+            appid = self._session.cfg.app_name
+        else:
+            raise ValueError("The `appid` parameter cannot be empty for non-ExApp use.")
+        return await self._session.ocs("DELETE", f"{self._ep_base}/byappid/{appid}")

{nc_py_api-0.17.0 → nc_py_api-0.18.0}/pyproject.toml

@@ -77,11 +77,11 @@ optional-dependencies.dev-min = [
 optional-dependencies.docs = [
   "autodoc-pydantic>=2.0.1",
   "nc-py-api[app,calendar]",
-  "sphinx>=6.2",
+  "sphinx<8",
   "sphinx-copybutton",
   "sphinx-inline-tabs",
   "sphinx-issues>=3.0.1",
-  "sphinx-rtd-theme>=1",
+  "sphinx-rtd-theme<3",
 ]
 urls.Changelog = "https://github.com/cloud-py-api/nc_py_api/blob/main/CHANGELOG.md"
 urls.Documentation = "https://cloud-py-api.github.io/nc_py_api/"
@@ -207,6 +207,7 @@ messages_control.disable = [
   "too-few-public-methods",
   "too-many-public-methods",
   "too-many-instance-attributes",
+  "too-many-positional-arguments",
 ]
 
 [tool.pytest.ini_options]