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

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/_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/_version.py

@@ -1,3 +1,3 @@
 """Version of nc_py_api."""
 
-__version__ = "0.11.0"
+__version__ = "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/ex_app/__init__.py

@@ -1,6 +1,7 @@
 """All possible ExApp stuff for NextcloudApp that can be used."""
 
-from .defs import ApiScope, LogLvl
+from ..files import ActionFileInfo
+from .defs import FileSystemEventNotification, LogLvl
 from .integration_fastapi import (
     AppAPIAuthMiddleware,
     anc_app,
@@ -9,7 +10,16 @@ from .integration_fastapi import (
     set_handlers,
     talk_bot_msg,
 )
-from .misc import get_model_path, persistent_storage, verify_version
-from .ui.files_actions import UiActionFileInfo
+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/ex_app/defs.py

@@ -2,6 +2,10 @@
 
 import enum
 
+from pydantic import BaseModel
+
+from ..files import ActionFileInfo
+
 
 class LogLvl(enum.IntEnum):
     """Log levels."""
@@ -18,32 +22,16 @@ class LogLvl(enum.IntEnum):
     """Fatal log level"""
 
 
-class ApiScope(enum.IntEnum):
-    """Defined API scopes."""
-
-    SYSTEM = 2
-    """Allows access to the System APIs."""
-    FILES = 10
-    """Allows access to the Nextcloud file base."""
-    FILES_SHARING = 11
-    """Allows access to APIs that provide File Sharing."""
-    USER_INFO = 30
-    """Allows access to APIs that work with users."""
-    USER_STATUS = 31
-    """Allows access to APIs that work with users statuses."""
-    NOTIFICATIONS = 32
-    """Allows access to APIs that provide Notifications."""
-    WEATHER_STATUS = 33
-    """Allows access to APIs that provide Weather status."""
-    TALK = 50
-    """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."""
-    ALL = 9999
-    """All endpoints allowed."""
+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/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/ex_app/integration_fastapi.py

@@ -103,7 +103,7 @@ def set_handlers(
 
         @fast_api_app.post("/init")
         async def init_callback(b_tasks: BackgroundTasks, nc: typing.Annotated[NextcloudApp, Depends(nc_app)]):
-            b_tasks.add_task(__fetch_models_task, nc, models_to_fetch if models_to_fetch else {})
+            b_tasks.add_task(fetch_models_task, nc, models_to_fetch if models_to_fetch else {}, 0)
             return JSONResponse(content={})
 
     if map_app_static:
@@ -120,28 +120,33 @@ def __map_app_static_folders(fast_api_app: FastAPI):
             fast_api_app.mount(f"/{mnt_dir}", staticfiles.StaticFiles(directory=mnt_dir_path), name=mnt_dir)
 
 
-def __fetch_models_task(nc: NextcloudApp, models: dict[str, dict]) -> None:
+def fetch_models_task(nc: NextcloudApp, models: dict[str, dict], progress_init_start_value: int) -> None:
+    """Use for cases when you want to define custom `/init` but still need to easy download models."""
     if models:
-        current_progress = 0
-        percent_for_each = min(int(100 / len(models)), 99)
+        current_progress = progress_init_start_value
+        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:
@@ -162,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
@@ -173,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
 
@@ -190,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:
@@ -206,9 +217,9 @@ def __request_sign_check_if_needed(request: HTTPConnection, nextcloud_app: Nextc
         _request_sign_check(request, nextcloud_app)
 
 
-def _request_sign_check(request: HTTPConnection, nextcloud_app: NextcloudApp | AsyncNextcloudApp) -> None:
+def _request_sign_check(request: HTTPConnection, nextcloud_app: NextcloudApp | AsyncNextcloudApp) -> str:
     try:
-        nextcloud_app._session.sign_check(request)  # noqa pylint: disable=protected-access
+        return nextcloud_app._session.sign_check(request)  # noqa pylint: disable=protected-access
     except ValueError as e:
         print(e)
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) from None
@@ -238,7 +249,7 @@ class AppAPIAuthMiddleware:
         url_path = conn.url.path.lstrip("/")
         if not fnmatch.filter(self._disable_for, url_path):
             try:
-                _request_sign_check(conn, AsyncNextcloudApp())
+                scope["username"] = _request_sign_check(conn, AsyncNextcloudApp())
             except HTTPException as exc:
                 response = self._on_error(exc.status_code, exc.detail)
                 await response(scope, receive, send)

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/ex_app/misc.py

@@ -33,7 +33,7 @@ def verify_version(finalize_update: bool = True) -> tuple[str, str] | None:
     """
     version_file_path = os.path.join(persistent_storage(), "_version.info")
     r = None
-    with open(version_file_path, "a+t", encoding="UTF-8") as version_file:
+    with open(version_file_path, "a+", encoding="UTF-8") as version_file:
         version_file.seek(0)
         old_version = version_file.read()
         if old_version != os.environ["APP_VERSION"]:
@@ -50,3 +50,8 @@ def get_model_path(model_name: str) -> str:
     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())
+
+
+def get_computation_device() -> str:
+    """Returns computation device(`ROCM` or `CUDA`) if it is defined in the environment variable."""
+    return str(os.environ.get("COMPUTE_DEVICE", "")).upper()