nc-py-api 0.9.0__py3-none-any.whl → 0.11.0__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
+from .files import FilePermissions, FsNode, LockType
 from .files.sharing import ShareType
 from .nextcloud import AsyncNextcloud, AsyncNextcloudApp, Nextcloud, NextcloudApp

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

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

@@ -1,49 +1,45 @@
 """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,
-    responses,
     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."""
-    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)
-    nextcloud_app = NextcloudApp(user=user, headers={"AA-REQUEST-ID": request_id} if request_id else {})
-    if not nextcloud_app.request_sign_check(request):
-        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
+    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."""
-    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)
-    nextcloud_app = AsyncNextcloudApp(user=user, headers={"AA-REQUEST-ID": request_id} if request_id else {})
-    if not nextcloud_app.request_sign_check(request):
-        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
+    nextcloud_app = AsyncNextcloudApp(**__nc_app(request))
+    __request_sign_check_if_needed(request, nextcloud_app)
     return nextcloud_app
 
 
@@ -60,8 +56,8 @@ async def atalk_bot_msg(request: Request) -> TalkBotMessage:
 def set_handlers(
     fast_api_app: FastAPI,
     enabled_handler: typing.Callable[[bool, AsyncNextcloudApp | NextcloudApp], typing.Awaitable[str] | str],
-    heartbeat_handler: typing.Callable[[], typing.Awaitable[str] | str] | None = None,
-    init_handler: typing.Callable[[AsyncNextcloudApp | NextcloudApp], typing.Awaitable[None] | None] | None = None,
+    default_heartbeat: bool = True,
+    default_init: bool = True,
     models_to_fetch: dict[str, dict] | None = None,
     map_app_static: bool = True,
 ):
@@ -69,85 +65,46 @@ def set_handlers(
 
     :param fast_api_app: FastAPI() call return value.
     :param enabled_handler: ``Required``, callback which will be called for `enabling`/`disabling` app event.
-    :param heartbeat_handler: Optional, callback that will be called for the `heartbeat` deploy event.
-    :param init_handler: Optional, callback that will be called for the `init`  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:: This parameter is **mutually exclusive** with ``models_to_fetch``.
+        .. 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.
+        .. 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 init_handler is not None:
-        raise ValueError("Only `init_handler` OR `models_to_fetch` can be defined.")
+    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 responses.JSONResponse(content={"error": await enabled_handler(enabled, nc)}, status_code=200)
+            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 responses.JSONResponse(content={"error": enabled_handler(enabled, nc)}, status_code=200)
-
-    if heartbeat_handler is None:
-
-        @fast_api_app.get("/heartbeat")
-        async def heartbeat_callback():
-            return responses.JSONResponse(content={"status": "ok"}, status_code=200)
+            return JSONResponse(content={"error": enabled_handler(enabled, nc)})
 
-    elif asyncio.iscoroutinefunction(heartbeat_handler):
+    if default_heartbeat:
 
         @fast_api_app.get("/heartbeat")
         async def heartbeat_callback():
-            return responses.JSONResponse(content={"status": await heartbeat_handler()}, status_code=200)
-
-    else:
-
-        @fast_api_app.get("/heartbeat")
-        def heartbeat_callback():
-            return responses.JSONResponse(content={"status": heartbeat_handler()}, status_code=200)
-
-    if init_handler is None:
+            return JSONResponse(content={"status": "ok"})
 
-        @fast_api_app.post("/init")
-        async def init_callback(
-            background_tasks: BackgroundTasks,
-            nc: typing.Annotated[NextcloudApp, Depends(nc_app)],
-        ):
-            background_tasks.add_task(
-                __fetch_models_task,
-                nc,
-                models_to_fetch if models_to_fetch else {},
-            )
-            return responses.JSONResponse(content={}, status_code=200)
-
-    elif asyncio.iscoroutinefunction(init_handler):
-
-        @fast_api_app.post("/init")
-        async def init_callback(
-            background_tasks: BackgroundTasks,
-            nc: typing.Annotated[AsyncNextcloudApp, Depends(anc_app)],
-        ):
-            background_tasks.add_task(init_handler, nc)
-            return responses.JSONResponse(content={}, status_code=200)
-
-    else:
+    if default_init:
 
         @fast_api_app.post("/init")
-        def init_callback(
-            background_tasks: BackgroundTasks,
-            nc: typing.Annotated[NextcloudApp, Depends(nc_app)],
-        ):
-            background_tasks.add_task(init_handler, nc)
-            return responses.JSONResponse(content={}, status_code=200)
+        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)
@@ -163,26 +120,100 @@ 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]) -> None:
     if models:
-        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(int((self.n * 100 / self.total) / len(models)), 100))
-                return super().display(msg, pos)
-
+        current_progress = 0
+        percent_for_each = min(int(100 / len(models)), 99)
         for model in models:
-            workers = models[model].pop("max_workers", 2)
-            cache = models[model].pop("cache_dir", persistent_storage())
-            snapshot_download(model, tqdm_class=TqdmProgress, **models[model], max_workers=workers, cache_dir=cache)
+            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."""
 
@@ -205,9 +236,9 @@ class AppAPIAuthMiddleware:
 
         conn = HTTPConnection(scope)
         url_path = conn.url.path.lstrip("/")
-        if url_path not in self._disable_for:
+        if not fnmatch.filter(self._disable_for, url_path):
             try:
-                anc_app(conn)
+                _request_sign_check(conn, AsyncNextcloudApp())
             except HTTPException as exc:
                 response = self._on_error(exc.status_code, exc.detail)
                 await response(scope, receive, send)
@@ -216,5 +247,5 @@ class AppAPIAuthMiddleware:
         await self.app(scope, receive, send)
 
     @staticmethod
-    def _on_error(status_code: int = 400, content: str = "") -> responses.PlainTextResponse:
-        return responses.PlainTextResponse(content, status_code=status_code)
+    def _on_error(status_code: int = 400, content: str = "") -> PlainTextResponse:
+        return PlainTextResponse(content, status_code=status_code)

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/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/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/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/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"

nc_py_api/ex_app/ui/settings.py

@@ -0,0 +1,178 @@
+"""Nextcloud API for declaring UI for settings."""
+
+import dataclasses
+import enum
+import typing
+
+from ..._exceptions import NextcloudExceptionNotFound
+from ..._misc import require_capabilities
+from ..._session import AsyncNcSessionApp, NcSessionApp
+
+
+class SettingsFieldType(enum.Enum):  # StrEnum
+    """Declarative Settings Field Type."""
+
+    TEXT = "text"
+    """NcInputField type text"""
+    PASSWORD = "password"  # noqa
+    """NcInputField type password"""
+    EMAIL = "email"
+    """NcInputField type email"""
+    TEL = "tel"
+    """NcInputField type tel"""
+    URL = "url"
+    """NcInputField type url"""
+    NUMBER = "number"
+    """NcInputField type number"""
+    CHECKBOX = "checkbox"
+    """NcCheckboxRadioSwitch type checkbox"""
+    MULTI_CHECKBOX = "multi-checkbox"
+    """Multiple NcCheckboxRadioSwitch type checkbox representing a one config value (saved as JSON object)"""
+    RADIO = "radio"
+    """NcCheckboxRadioSwitch type radio"""
+    SELECT = "select"
+    """NcSelect"""
+    MULTI_SELECT = "multi-select"
+    """Multiple NcSelect representing a one config value (saved as JSON array)"""
+
+
+@dataclasses.dataclass
+class SettingsField:
+    """Section field."""
+
+    id: str
+    title: str
+    type: SettingsFieldType
+    default: bool | int | float | str | list[bool | int | float | str] | dict[str, typing.Any]
+    options: dict | list = dataclasses.field(default_factory=dict)
+    description: str = ""
+    placeholder: str = ""
+    label: str = ""
+    notify = False  # to be supported in future
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SettingsField":
+        """Creates instance of class from dict, ignoring unknown keys."""
+        filtered_data = {
+            k: SettingsFieldType(v) if k == "type" else v for k, v in data.items() if k in cls.__annotations__
+        }
+        return cls(**filtered_data)
+
+    def to_dict(self) -> dict:
+        """Returns data in format that is accepted by AppAPI."""
+        return {
+            "id": self.id,
+            "title": self.title,
+            "type": self.type.value,
+            "default": self.default,
+            "description": self.description,
+            "options": (
+                [{"name": key, "value": value} for key, value in self.options.items()]
+                if isinstance(self.options, dict)
+                else self.options
+            ),
+            "placeholder": self.placeholder,
+            "label": self.label,
+            "notify": self.notify,
+        }
+
+
+@dataclasses.dataclass
+class SettingsForm:
+    """Settings Form and Section."""
+
+    id: str
+    section_id: str
+    title: str
+    fields: list[SettingsField] = dataclasses.field(default_factory=list)
+    description: str = ""
+    priority: int = 50
+    doc_url: str = ""
+    section_type: str = "personal"
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SettingsForm":
+        """Creates instance of class from dict, ignoring unknown keys."""
+        filtered_data = {k: v for k, v in data.items() if k in cls.__annotations__}
+        filtered_data["fields"] = [SettingsField.from_dict(i) for i in filtered_data.get("fields", [])]
+        return cls(**filtered_data)
+
+    def to_dict(self) -> dict:
+        """Returns data in format that is accepted by AppAPI."""
+        return {
+            "id": self.id,
+            "priority": self.priority,
+            "section_type": self.section_type,
+            "section_id": self.section_id,
+            "title": self.title,
+            "description": self.description,
+            "doc_url": self.doc_url,
+            "fields": [i.to_dict() for i in self.fields],
+        }
+
+
+_EP_SUFFIX: str = "ui/settings"
+
+
+class _DeclarativeSettingsAPI:
+    """Class providing API for creating UI for the ExApp settings, avalaible as **nc.ui.settings.<method>**."""
+
+    def __init__(self, session: NcSessionApp):
+        self._session = session
+
+    def register_form(self, form_schema: SettingsForm | dict[str, typing.Any]) -> None:
+        """Registers or edit the Settings UI Form."""
+        require_capabilities("app_api", self._session.capabilities)
+        param = {"formScheme": form_schema.to_dict() if isinstance(form_schema, SettingsForm) else form_schema}
+        self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=param)
+
+    def unregister_form(self, form_id: str, not_fail=True) -> None:
+        """Removes Settings UI Form."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            self._session.ocs("DELETE", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"formId": form_id})
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    def get_entry(self, form_id: str) -> SettingsForm | None:
+        """Get information of the Settings UI Form."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            return SettingsForm.from_dict(
+                self._session.ocs("GET", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"formId": form_id})
+            )
+        except NextcloudExceptionNotFound:
+            return None
+
+
+class _AsyncDeclarativeSettingsAPI:
+    """Class providing async API for creating UI for the ExApp settings."""
+
+    def __init__(self, session: AsyncNcSessionApp):
+        self._session = session
+
+    async def register_form(self, form_schema: SettingsForm | dict[str, typing.Any]) -> None:
+        """Registers or edit the Settings UI Form."""
+        require_capabilities("app_api", await self._session.capabilities)
+        param = {"formScheme": form_schema.to_dict() if isinstance(form_schema, SettingsForm) else form_schema}
+        await self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=param)
+
+    async def unregister_form(self, form_id: str, not_fail=True) -> None:
+        """Removes Settings UI Form."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            await self._session.ocs("DELETE", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"formId": form_id})
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    async def get_entry(self, form_id: str) -> SettingsForm | None:
+        """Get information of the Settings UI Form."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            return SettingsForm.from_dict(
+                await self._session.ocs("GET", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"formId": form_id})
+            )
+        except NextcloudExceptionNotFound:
+            return None