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

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

@@ -2,6 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.11.0 - 2024-02-17]
+
+### Added
+
+- Files: `lock` and `unlock` methods, lock file information to `FsNode`. #227
+
+### Fixed
+
+- NextcloudApp: `MachineTranslation` provider registration - added optional `actionDetectLang` param. #229
+
+## [0.10.0 - 2024-02-14]
+
+### Added
+
+- NextcloudApp: `set_handlers`: `models_to_fetch` can now accept direct links to a files to download. #217
+- NextcloudApp: DeclarativeSettings UI API for Nextcloud `29`. #222
+
+### Changed
+
+- NextcloudApp: adjusted code related to changes in AppAPI `2.0.3` #216
+- NextcloudApp: `set_handlers` **rework of optional parameters** see PR for information. #226
+
 ## [0.9.0 - 2024-01-25]
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nc-py-api
-Version: 0.9.0
+Version: 0.11.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/
@@ -10,7 +10,7 @@ License-Expression: BSD-3-Clause
 License-File: AUTHORS
 License-File: LICENSE.txt
 Keywords: api,client,framework,library,nextcloud
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: MacOS :: MacOS X
@@ -29,8 +29,8 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: fastapi>=0.101
-Requires-Dist: httpx>=0.24.1
+Requires-Dist: fastapi>=0.109.2
+Requires-Dist: httpx>=0.25.2
 Requires-Dist: pydantic>=2.1.1
 Requires-Dist: python-dotenv>=1
 Requires-Dist: xmltodict>=0.13
@@ -100,6 +100,7 @@ Python library that provides a robust and well-documented API that allows develo
 | 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      |      ✅       |
 
 &ast;_available only for **NextcloudApp**_<br>
@@ -132,16 +133,17 @@ from contextlib import asynccontextmanager
 from fastapi import FastAPI
 
 from nc_py_api import NextcloudApp
-from nc_py_api.ex_app import LogLvl, run_app, set_handlers
+from nc_py_api.ex_app import AppAPIAuthMiddleware, LogLvl, run_app, set_handlers
 
 
 @asynccontextmanager
-async def lifespan(_app: FastAPI):
-    set_handlers(APP, enabled_handler)
+async def lifespan(app: FastAPI):
+    set_handlers(app, enabled_handler)
     yield
 
 
 APP = FastAPI(lifespan=lifespan)
+APP.add_middleware(AppAPIAuthMiddleware)
 
 
 def enabled_handler(enabled: bool, nc: NextcloudApp) -> str:

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/README.md

@@ -35,6 +35,7 @@ Python library that provides a robust and well-documented API that allows develo
 | 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      |      ✅       |
 
 &ast;_available only for **NextcloudApp**_<br>
@@ -67,16 +68,17 @@ from contextlib import asynccontextmanager
 from fastapi import FastAPI
 
 from nc_py_api import NextcloudApp
-from nc_py_api.ex_app import LogLvl, run_app, set_handlers
+from nc_py_api.ex_app import AppAPIAuthMiddleware, LogLvl, run_app, set_handlers
 
 
 @asynccontextmanager
-async def lifespan(_app: FastAPI):
-    set_handlers(APP, enabled_handler)
+async def lifespan(app: FastAPI):
+    set_handlers(app, enabled_handler)
     yield
 
 
 APP = FastAPI(lifespan=lifespan)
+APP.add_middleware(AppAPIAuthMiddleware)
 
 
 def enabled_handler(enabled: bool, nc: NextcloudApp) -> str:

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/__init__.py

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

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/_preferences_ex.py

@@ -106,7 +106,7 @@ class _AsyncBasicAppCfgPref:
 
 
 class PreferencesExAPI(_BasicAppCfgPref):
-    """User specific preferences API."""
+    """User specific preferences API, avalaible as **nc.preferences_ex.<method>**."""
 
     _url_suffix = "ex-app/preference"
 
@@ -134,7 +134,7 @@ class AsyncPreferencesExAPI(_AsyncBasicAppCfgPref):
 
 
 class AppConfigExAPI(_BasicAppCfgPref):
-    """Non-user(App) specific preferences API."""
+    """Non-user(App) specific preferences API, avalaible as **nc.appconfig_ex.<method>**."""
 
     _url_suffix = "ex-app/config"
 

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/_talk_api.py

@@ -26,7 +26,7 @@ from .talk import (
 
 
 class _TalkAPI:
-    """Class provides API to work with Nextcloud Talk."""
+    """Class provides API to work with Nextcloud Talk, avalaible as **nc.talk.<method>**."""
 
     _ep_base: str = "/ocs/v2.php/apps/spreed"
     config_sha: str

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/_version.py

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

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/ex_app/__init__.py

@@ -11,4 +11,5 @@ from .integration_fastapi import (
 )
 from .misc import get_model_path, persistent_storage, verify_version
 from .ui.files_actions import UiActionFileInfo
+from .ui.settings import SettingsField, SettingsFieldType, SettingsForm
 from .uvicorn_fastapi import run_app

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/ex_app/defs.py

@@ -19,7 +19,7 @@ class LogLvl(enum.IntEnum):
 
 
 class ApiScope(enum.IntEnum):
-    """Default API scopes. Should be used as a parameter to the :py:meth:`~.NextcloudApp.scope_allowed` method."""
+    """Defined API scopes."""
 
     SYSTEM = 2
     """Allows access to the System APIs."""

nc_py_api-0.11.0/nc_py_api/ex_app/integration_fastapi.py

@@ -0,0 +1,251 @@
+"""FastAPI directly related stuff."""
+
+import asyncio
+import builtins
+import fnmatch
+import hashlib
+import json
+import os
+import typing
+from urllib.parse import urlparse
+
+import httpx
+from fastapi import (
+    BackgroundTasks,
+    Depends,
+    FastAPI,
+    HTTPException,
+    staticfiles,
+    status,
+)
+from fastapi.responses import JSONResponse, PlainTextResponse
+from starlette.requests import HTTPConnection, Request
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from .._misc import get_username_secret_from_headers
+from ..nextcloud import AsyncNextcloudApp, NextcloudApp
+from ..talk_bot import TalkBotMessage
+from .defs import LogLvl
+from .misc import persistent_storage
+
+
+def nc_app(request: HTTPConnection) -> NextcloudApp:
+    """Authentication handler for requests from Nextcloud to the application."""
+    nextcloud_app = NextcloudApp(**__nc_app(request))
+    __request_sign_check_if_needed(request, nextcloud_app)
+    return nextcloud_app
+
+
+def anc_app(request: HTTPConnection) -> AsyncNextcloudApp:
+    """Async Authentication handler for requests from Nextcloud to the application."""
+    nextcloud_app = AsyncNextcloudApp(**__nc_app(request))
+    __request_sign_check_if_needed(request, nextcloud_app)
+    return nextcloud_app
+
+
+def talk_bot_msg(request: Request) -> TalkBotMessage:
+    """Authentication handler for bot requests from Nextcloud Talk to the application."""
+    return TalkBotMessage(json.loads(asyncio.run(request.body())))
+
+
+async def atalk_bot_msg(request: Request) -> TalkBotMessage:
+    """Async Authentication handler for bot requests from Nextcloud Talk to the application."""
+    return TalkBotMessage(json.loads(await request.body()))
+
+
+def set_handlers(
+    fast_api_app: FastAPI,
+    enabled_handler: typing.Callable[[bool, AsyncNextcloudApp | NextcloudApp], typing.Awaitable[str] | str],
+    default_heartbeat: bool = True,
+    default_init: bool = True,
+    models_to_fetch: dict[str, dict] | None = None,
+    map_app_static: bool = True,
+):
+    """Defines handlers for the application.
+
+    :param fast_api_app: FastAPI() call return value.
+    :param enabled_handler: ``Required``, callback which will be called for `enabling`/`disabling` app event.
+    :param default_heartbeat: Set to ``False`` to disable the default `heartbeat` route handler.
+    :param default_init: Set to ``False`` to disable the default `init` route handler.
+
+        .. note:: When this parameter is ``False``, the provision of ``models_to_fetch`` is not allowed.
+
+    :param models_to_fetch: Dictionary describing which models should be downloaded during `init`.
+
+        .. note:: ``huggingface_hub`` package should be present for automatic models fetching.
+
+    :param map_app_static: Should be folders ``js``, ``css``, ``l10n``, ``img`` automatically mounted in FastAPI or not.
+
+        .. note:: First, presence of these directories in the current working dir is checked, then one directory higher.
+    """
+    if models_to_fetch is not None and default_init is False:
+        raise ValueError("`models_to_fetch` can be defined only with `default_init`=True.")
+
+    if asyncio.iscoroutinefunction(enabled_handler):
+
+        @fast_api_app.put("/enabled")
+        async def enabled_callback(enabled: bool, nc: typing.Annotated[AsyncNextcloudApp, Depends(anc_app)]):
+            return JSONResponse(content={"error": await enabled_handler(enabled, nc)})
+
+    else:
+
+        @fast_api_app.put("/enabled")
+        def enabled_callback(enabled: bool, nc: typing.Annotated[NextcloudApp, Depends(nc_app)]):
+            return JSONResponse(content={"error": enabled_handler(enabled, nc)})
+
+    if default_heartbeat:
+
+        @fast_api_app.get("/heartbeat")
+        async def heartbeat_callback():
+            return JSONResponse(content={"status": "ok"})
+
+    if default_init:
+
+        @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 {})
+            return JSONResponse(content={})
+
+    if map_app_static:
+        __map_app_static_folders(fast_api_app)
+
+
+def __map_app_static_folders(fast_api_app: FastAPI):
+    """Function to mount all necessary static folders to FastAPI."""
+    for mnt_dir in ("js", "l10n", "css", "img"):
+        mnt_dir_path = os.path.join(os.getcwd(), mnt_dir)
+        if not os.path.exists(mnt_dir_path):
+            mnt_dir_path = os.path.join(os.path.dirname(os.getcwd()), mnt_dir)
+        if os.path.exists(mnt_dir_path):
+            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:
+    if models:
+        current_progress = 0
+        percent_for_each = min(int(100 / 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])
+            else:
+                __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:
+    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
+            downloaded_size = 0
+            linked_etag = ""
+            for each_history in response.history:
+                linked_etag = each_history.headers.get("X-Linked-ETag", "")
+                if linked_etag:
+                    break
+            if not linked_etag:
+                linked_etag = response.headers.get("X-Linked-ETag", response.headers.get("ETag", ""))
+            total_size = int(response.headers.get("Content-Length"))
+            try:
+                existing_size = os.path.getsize(result_path)
+            except OSError:
+                existing_size = 0
+            if linked_etag and total_size == existing_size:
+                with builtins.open(result_path, "rb") as file:
+                    sha256_hash = hashlib.sha256()
+                    for byte_block in iter(lambda: file.read(4096), b""):
+                        sha256_hash.update(byte_block)
+                    if f'"{sha256_hash.hexdigest()}"' == linked_etag:
+                        nc.set_init_status(min(current_progress + progress_for_task, 99))
+                        return
+
+            with builtins.open(result_path, "wb") as file:
+                last_progress = current_progress
+                for chunk in response.iter_bytes(5 * 1024 * 1024):
+                    downloaded_size += file.write(chunk)
+                    if total_size:
+                        new_progress = min(current_progress + int(progress_for_task * downloaded_size / total_size), 99)
+                        if new_progress != last_progress:
+                            nc.set_init_status(new_progress)
+                            last_progress = new_progress
+    except Exception as e:  # noqa pylint: disable=broad-exception-caught
+        nc.log(LogLvl.ERROR, f"Downloading of '{model_path}' raised an exception: {e}")
+
+
+def __fetch_model_as_snapshot(
+    current_progress: int, progress_for_task, nc: NextcloudApp, mode_name: str, download_options: dict
+) -> None:
+    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
+
+    class TqdmProgress(tqdm):
+        def display(self, msg=None, pos=None):
+            nc.set_init_status(min(current_progress + int(progress_for_task * self.n / self.total), 99))
+            return super().display(msg, pos)
+
+    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)
+
+
+def __nc_app(request: HTTPConnection) -> dict:
+    user = get_username_secret_from_headers(
+        {"AUTHORIZATION-APP-API": request.headers.get("AUTHORIZATION-APP-API", "")}
+    )[0]
+    request_id = request.headers.get("AA-REQUEST-ID", None)
+    return {"user": user, "headers": {"AA-REQUEST-ID": request_id} if request_id else {}}
+
+
+def __request_sign_check_if_needed(request: HTTPConnection, nextcloud_app: NextcloudApp | AsyncNextcloudApp) -> None:
+    if not [i for i in getattr(request.app, "user_middleware", []) if i.cls == AppAPIAuthMiddleware]:
+        _request_sign_check(request, nextcloud_app)
+
+
+def _request_sign_check(request: HTTPConnection, nextcloud_app: NextcloudApp | AsyncNextcloudApp) -> None:
+    try:
+        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
+
+
+class AppAPIAuthMiddleware:
+    """Pure ASGI AppAPIAuth Middleware."""
+
+    _disable_for: list[str]
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        disable_for: list[str] | None = None,
+    ) -> None:
+        self.app = app
+        disable_for = [] if disable_for is None else [i.lstrip("/") for i in disable_for]
+        self._disable_for = [i for i in disable_for if i != "heartbeat"] + ["heartbeat"]
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Method that will be called by Starlette for each event."""
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        conn = HTTPConnection(scope)
+        url_path = conn.url.path.lstrip("/")
+        if not fnmatch.filter(self._disable_for, url_path):
+            try:
+                _request_sign_check(conn, AsyncNextcloudApp())
+            except HTTPException as exc:
+                response = self._on_error(exc.status_code, exc.detail)
+                await response(scope, receive, send)
+                return
+
+        await self.app(scope, receive, send)
+
+    @staticmethod
+    def _on_error(status_code: int = 400, content: str = "") -> PlainTextResponse:
+        return PlainTextResponse(content, status_code=status_code)

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/ex_app/providers/speech_to_text.py

@@ -37,7 +37,7 @@ class SpeechToTextProvider:
 
 
 class _SpeechToTextProviderAPI:
-    """API for Speech2Text providers."""
+    """API for Speech2Text providers, avalaible as **nc.providers.text_processing.<method>**."""
 
     def __init__(self, session: NcSessionApp):
         self._session = session
@@ -83,7 +83,7 @@ class _SpeechToTextProviderAPI:
 
 
 class _AsyncSpeechToTextProviderAPI:
-    """API for Speech2Text providers."""
+    """Async API for Speech2Text providers."""
 
     def __init__(self, session: AsyncNcSessionApp):
         self._session = session

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/ex_app/providers/text_processing.py

@@ -42,7 +42,7 @@ class TextProcessingProvider:
 
 
 class _TextProcessingProviderAPI:
-    """API for TextProcessing providers."""
+    """API for TextProcessing providers, avalaible as **nc.providers.speech_to_text.<method>**."""
 
     def __init__(self, session: NcSessionApp):
         self._session = session
@@ -89,7 +89,7 @@ class _TextProcessingProviderAPI:
 
 
 class _AsyncTextProcessingProviderAPI:
-    """API for TextProcessing providers."""
+    """Async API for TextProcessing providers."""
 
     def __init__(self, session: AsyncNcSessionApp):
         self._session = session

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/ex_app/providers/translations.py

@@ -42,12 +42,17 @@ class TranslationsProvider:
         """Relative ExApp url which will be called by Nextcloud."""
         return self._raw_data["action_handler"]
 
+    @property
+    def action_handler_detect_lang(self) -> str:
+        """Relative ExApp url which will be called by Nextcloud to detect language."""
+        return self._raw_data.get("action_detect_lang", "")
+
     def __repr__(self):
         return f"<{self.__class__.__name__} name={self.name}, handler={self.action_handler}>"
 
 
 class _TranslationsProviderAPI:
-    """API for Translations providers."""
+    """API for Translations providers, avalaible as **nc.providers.translations.<method>**."""
 
     def __init__(self, session: NcSessionApp):
         self._session = session
@@ -59,6 +64,7 @@ class _TranslationsProviderAPI:
         callback_url: str,
         from_languages: dict[str, str],
         to_languages: dict[str, str],
+        detect_lang_callback_url: str = "",
     ) -> None:
         """Registers or edit the Translations provider."""
         require_capabilities("app_api", self._session.capabilities)
@@ -68,6 +74,7 @@ class _TranslationsProviderAPI:
             "fromLanguages": from_languages,
             "toLanguages": to_languages,
             "actionHandler": callback_url,
+            "actionDetectLang": detect_lang_callback_url,
         }
         self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
 
@@ -102,7 +109,7 @@ class _TranslationsProviderAPI:
 
 
 class _AsyncTranslationsProviderAPI:
-    """API for Translations providers."""
+    """Async API for Translations providers."""
 
     def __init__(self, session: AsyncNcSessionApp):
         self._session = session
@@ -114,6 +121,7 @@ class _AsyncTranslationsProviderAPI:
         callback_url: str,
         from_languages: dict[str, str],
         to_languages: dict[str, str],
+        detect_lang_callback_url: str = "",
     ) -> None:
         """Registers or edit the Translations provider."""
         require_capabilities("app_api", await self._session.capabilities)
@@ -123,6 +131,7 @@ class _AsyncTranslationsProviderAPI:
             "fromLanguages": from_languages,
             "toLanguages": to_languages,
             "actionHandler": callback_url,
+            "actionDetectLang": detect_lang_callback_url,
         }
         await self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
 

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/ex_app/ui/files_actions.py

@@ -119,7 +119,7 @@ class UiActionFileInfo(BaseModel):
 
 
 class _UiFilesActionsAPI:
-    """API for the drop-down menu in Nextcloud **Files app**."""
+    """API for the drop-down menu in Nextcloud **Files app**, avalaible as **nc.ui.files_dropdown_menu.<method>**."""
 
     _ep_suffix: str = "ui/files-actions-menu"
 

{nc_py_api-0.9.0 → nc_py_api-0.11.0}/nc_py_api/ex_app/ui/resources.py

@@ -77,7 +77,7 @@ class UiStyle(UiBase):
 
 
 class _UiResources:
-    """API for adding scripts, styles, initial-states to the TopMenu pages."""
+    """API for adding scripts, styles, initial-states to the pages, avalaible as **nc.ui.resources.<method>**."""
 
     _ep_suffix_init_state: str = "ui/initial-state"
     _ep_suffix_js: str = "ui/script"