nc-py-api 0.12.0__tar.gz → 0.13.0__tar.gz

{nc_py_api-0.12.0 → nc_py_api-0.13.0}/CHANGELOG.md

@@ -2,13 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.13.0 - 2024-04-28]
+
+### Added
+
+- NextcloudApp: `occ` commands registration API(AppAPI 2.5.0+). #247
+- NextcloudApp: `Nodes` events listener registration API(AppAPI 2.5.0+). #249
+
+## [0.12.1 - 2024-04-05]
+
+### Fixed
+
+- Incorrect `Display name` when creating user, which led to the parameter being ignored. #239 Thanks to @derekbuckley
+
 ## [0.12.0 - 2024-04-02]
 
 Update with new features only for `NextcloudApp` class. #233
 
 ### Added
 
-- `ex_app.get_computation_device` function for retrieving GPU type(only with AppAPI `2.4.0`+).
+- `ex_app.get_computation_device` function for retrieving GPU type(only with AppAPI `2.5.0`+).
 - `ex_app.integration_fastapi.fetch_models_task` are now public function, added `progress_init_start_value` param.
 - Global authentication when used now sets `request.scope["username"]` for easy use.
 

{nc_py_api-0.12.0 → nc_py_api-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nc-py-api
-Version: 0.12.0
+Version: 0.13.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/
@@ -38,13 +38,24 @@ Provides-Extra: app
 Requires-Dist: uvicorn[standard]>=0.23.2; extra == 'app'
 Provides-Extra: bench
 Requires-Dist: matplotlib; extra == 'bench'
-Requires-Dist: nc-py-api[app]; extra == 'bench'
 Requires-Dist: numpy; extra == 'bench'
 Requires-Dist: py-cpuinfo; extra == 'bench'
+Requires-Dist: uvicorn[standard]>=0.23.2; extra == 'bench'
 Provides-Extra: calendar
 Requires-Dist: caldav==1.3.6; extra == 'calendar'
 Provides-Extra: dev
-Requires-Dist: nc-py-api[bench,calendar,dev-min]; extra == 'dev'
+Requires-Dist: caldav==1.3.6; extra == 'dev'
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: huggingface-hub; extra == 'dev'
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: numpy; extra == 'dev'
+Requires-Dist: pillow; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: py-cpuinfo; extra == 'dev'
+Requires-Dist: pylint; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.23.2; extra == 'dev'
 Provides-Extra: dev-min
 Requires-Dist: coverage; extra == 'dev-min'
 Requires-Dist: huggingface-hub; extra == 'dev-min'
@@ -55,12 +66,13 @@ Requires-Dist: pytest; extra == 'dev-min'
 Requires-Dist: pytest-asyncio; extra == 'dev-min'
 Provides-Extra: docs
 Requires-Dist: autodoc-pydantic>=2.0.1; extra == 'docs'
-Requires-Dist: nc-py-api[app,calendar]; extra == 'docs'
+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: uvicorn[standard]>=0.23.2; extra == 'docs'
 Description-Content-Type: text/markdown
 
 <p align="center">

{nc_py_api-0.12.0 → nc_py_api-0.13.0}/nc_py_api/_version.py

@@ -1,3 +1,3 @@
 """Version of nc_py_api."""
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"

nc_py_api-0.13.0/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-0.13.0/nc_py_api/ex_app/occ_commands.py

@@ -0,0 +1,153 @@
+"""Nextcloud API for registering OCC commands for ExApps."""
+
+import dataclasses
+
+from .._exceptions import NextcloudExceptionNotFound
+from .._misc import clear_from_params_empty, require_capabilities
+from .._session import AsyncNcSessionApp, NcSessionApp
+
+_EP_SUFFIX: str = "occ_command"
+
+
+@dataclasses.dataclass
+class OccCommand:
+    """OccCommand description."""
+
+    def __init__(self, raw_data: dict):
+        self._raw_data = raw_data
+
+    @property
+    def name(self) -> str:
+        """Unique ID for the command."""
+        return self._raw_data["name"]
+
+    @property
+    def description(self) -> str:
+        """Command description."""
+        return self._raw_data["description"]
+
+    @property
+    def hidden(self) -> bool:
+        """Flag determining ss command hidden or not."""
+        return bool(self._raw_data["hidden"])
+
+    @property
+    def arguments(self) -> dict:
+        """Look at PHP Symfony framework for details."""
+        return self._raw_data["arguments"]
+
+    @property
+    def options(self) -> str:
+        """Look at PHP Symfony framework for details."""
+        return self._raw_data["options"]
+
+    @property
+    def usages(self) -> str:
+        """Look at PHP Symfony framework for details."""
+        return self._raw_data["usages"]
+
+    @property
+    def action_handler(self) -> str:
+        """Relative ExApp url which will be called by Nextcloud."""
+        return self._raw_data["execute_handler"]
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} name={self.name}, handler={self.action_handler}>"
+
+
+class OccCommandsAPI:
+    """API for registering OCC commands, avalaible as **nc.occ_command.<method>**."""
+
+    def __init__(self, session: NcSessionApp):
+        self._session = session
+
+    def register(
+        self,
+        name: str,
+        callback_url: str,
+        arguments: list | None = None,
+        options: list | None = None,
+        usages: list | None = None,
+        description: str = "",
+        hidden: bool = False,
+    ) -> None:
+        """Registers or edit the OCC command."""
+        require_capabilities("app_api", self._session.capabilities)
+        params = {
+            "name": name,
+            "description": description,
+            "arguments": arguments,
+            "hidden": int(hidden),
+            "options": options,
+            "usages": usages,
+            "execute_handler": callback_url,
+        }
+        clear_from_params_empty(["arguments", "options", "usages"], params)
+        self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
+
+    def unregister(self, name: str, not_fail=True) -> None:
+        """Removes the OCC command."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            self._session.ocs("DELETE", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"name": name})
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    def get_entry(self, name: str) -> OccCommand | None:
+        """Get information of the OCC command."""
+        require_capabilities("app_api", self._session.capabilities)
+        try:
+            return OccCommand(self._session.ocs("GET", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"name": name}))
+        except NextcloudExceptionNotFound:
+            return None
+
+
+class AsyncOccCommandsAPI:
+    """Async API for registering OCC commands, avalaible as **nc.occ_command.<method>**."""
+
+    def __init__(self, session: AsyncNcSessionApp):
+        self._session = session
+
+    async def register(
+        self,
+        name: str,
+        callback_url: str,
+        arguments: list | None = None,
+        options: list | None = None,
+        usages: list | None = None,
+        description: str = "",
+        hidden: bool = False,
+    ) -> None:
+        """Registers or edit the OCC command."""
+        require_capabilities("app_api", await self._session.capabilities)
+        params = {
+            "name": name,
+            "description": description,
+            "arguments": arguments,
+            "hidden": int(hidden),
+            "options": options,
+            "usages": usages,
+            "execute_handler": callback_url,
+        }
+        clear_from_params_empty(["arguments", "options", "usages"], params)
+        await self._session.ocs("POST", f"{self._session.ae_url}/{_EP_SUFFIX}", json=params)
+
+    async def unregister(self, name: str, not_fail=True) -> None:
+        """Removes the OCC command."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            await self._session.ocs("DELETE", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"name": name})
+        except NextcloudExceptionNotFound as e:
+            if not not_fail:
+                raise e from None
+
+    async def get_entry(self, name: str) -> OccCommand | None:
+        """Get information of the OCC command."""
+        require_capabilities("app_api", await self._session.capabilities)
+        try:
+            return OccCommand(
+                await self._session.ocs("GET", f"{self._session.ae_url}/{_EP_SUFFIX}", params={"name": name})
+            )
+        except NextcloudExceptionNotFound:
+            return None

{nc_py_api-0.12.0 → nc_py_api-0.13.0}/nc_py_api/files/__init__.py

@@ -282,12 +282,13 @@ class FilePermissions(enum.IntFlag):
     """Access to re-share object(s)"""
 
 
-def permissions_to_str(permissions: int, is_dir: bool = False) -> str:
+def permissions_to_str(permissions: int | str, is_dir: bool = False) -> str:
     """Converts integer permissions to string permissions.
 
     :param permissions: concatenation of ``FilePermissions`` integer flags.
     :param is_dir: Flag indicating is permissions related to the directory object or not.
     """
+    permissions = int(permissions) if not isinstance(permissions, int) else permissions
     r = ""
     if permissions & FilePermissions.PERMISSION_SHARE:
         r += "R"

{nc_py_api-0.12.0 → nc_py_api-0.13.0}/nc_py_api/nextcloud.py

@@ -30,6 +30,8 @@ from .activity import _ActivityAPI, _AsyncActivityAPI
 from .apps import _AppsAPI, _AsyncAppsAPI
 from .calendar import _CalendarAPI
 from .ex_app.defs import LogLvl
+from .ex_app.events_listener import AsyncEventsListenerAPI, EventsListenerAPI
+from .ex_app.occ_commands import AsyncOccCommandsAPI, OccCommandsAPI
 from .ex_app.providers.providers import AsyncProvidersApi, ProvidersApi
 from .ex_app.ui.ui import AsyncUiApi, UiApi
 from .files.files import AsyncFilesAPI, FilesAPI
@@ -304,6 +306,10 @@ class NextcloudApp(_NextcloudBasic):
     """Nextcloud UI API for ExApps"""
     providers: ProvidersApi
     """API for registering providers for Nextcloud"""
+    events_listener: EventsListenerAPI
+    """API for registering Events listeners for ExApps"""
+    occ_commands: OccCommandsAPI
+    """API for registering OCC command for ExApps"""
 
     def __init__(self, **kwargs):
         """The parameters will be taken from the environment.
@@ -316,6 +322,8 @@ class NextcloudApp(_NextcloudBasic):
         self.preferences_ex = PreferencesExAPI(self._session)
         self.ui = UiApi(self._session)
         self.providers = ProvidersApi(self._session)
+        self.events_listener = EventsListenerAPI(self._session)
+        self.occ_commands = OccCommandsAPI(self._session)
 
     def log(self, log_lvl: LogLvl, content: str) -> None:
         """Writes log to the Nextcloud log file."""
@@ -421,6 +429,10 @@ class AsyncNextcloudApp(_AsyncNextcloudBasic):
     """Nextcloud UI API for ExApps"""
     providers: AsyncProvidersApi
     """API for registering providers for Nextcloud"""
+    events_listener: AsyncEventsListenerAPI
+    """API for registering Events listeners for ExApps"""
+    occ_commands: AsyncOccCommandsAPI
+    """API for registering OCC command for ExApps"""
 
     def __init__(self, **kwargs):
         """The parameters will be taken from the environment.
@@ -433,6 +445,8 @@ class AsyncNextcloudApp(_AsyncNextcloudBasic):
         self.preferences_ex = AsyncPreferencesExAPI(self._session)
         self.ui = AsyncUiApi(self._session)
         self.providers = AsyncProvidersApi(self._session)
+        self.events_listener = AsyncEventsListenerAPI(self._session)
+        self.occ_commands = AsyncOccCommandsAPI(self._session)
 
     async def log(self, log_lvl: LogLvl, content: str) -> None:
         """Writes log to the Nextcloud log file."""

{nc_py_api-0.12.0 → nc_py_api-0.13.0}/nc_py_api/users.py

@@ -378,5 +378,5 @@ def _create(user_id: str, display_name: str | None, **kwargs) -> dict[str, typin
         if k in kwargs:
             data[k] = kwargs[k]
     if display_name is not None:
-        data["displayname"] = display_name
+        data["displayName"] = display_name
     return data

{nc_py_api-0.12.0 → nc_py_api-0.13.0}/pyproject.toml

@@ -136,7 +136,7 @@ design.max-attributes = 8
 design.max-locals = 20
 design.max-branches = 16
 design.max-returns = 8
-design.max-args = 7
+design.max-args = 8
 basic.good-names = [
     "a", "b", "c", "d", "e", "f", "i", "j", "k", "r", "v",
     "ex", "_", "fp", "im", "nc", "ui",