added CalendarAPI with the help of caldav (#136)

Fixes #120

In future we should use our own DAV stuff that was written for Files
already and Objects API from `caldav`, so we need to implement our
custom `DAVClient` and `DAVResponse` with compatible format for
`caldav`.

---------

Signed-off-by: Alexander Piskun <[email protected]>

Author: bigcat88

.github/workflows/analysis-coverage.yml

@@ -414,7 +414,7 @@ jobs:
 
       - name: Install NcPyApi
         working-directory: nc_py_api
-        run: python3 -m pip -v install ".[dev]"
+        run: python3 -m pip -v install ".[app,dev-min]"
 
       - name: Checkout AppAPI
         uses: actions/checkout@v4
@@ -533,7 +533,7 @@ jobs:
 
       - name: Install NcPyApi
         working-directory: nc_py_api
-        run: python3 -m pip -v install ".[dev]"
+        run: python3 -m pip -v install ".[dev-min,app]"
 
       - name: Checkout AppAPI
         uses: actions/checkout@v4

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.1 - 2023-09-30]
+
+### Added
+
+- CalendarAPI with the help of [caldav](https://pypi.org/project/caldav/) package.
+
 ## [0.3.0 - 2023-09-28]
 
 ### Added

README.md

@@ -25,8 +25,9 @@ Python library that provides a robust and well-documented API that allows develo
 ### Capabilities
 | **_Capability_**      | Nextcloud 26 | Nextcloud 27 | Nextcloud 28 |
 |-----------------------|:------------:|:------------:|:------------:|
+| Calendar              |      ✅       |      ✅       |      ✅       |
 | File System & Tags    |      ✅       |      ✅       |      ✅       |
-| Nextcloud Talk**      |      ✅       |      ✅       |      ✅       |
+| Nextcloud Talk        |      ✅       |      ✅       |      ✅       |
 | Notifications         |      ✅       |      ✅       |      ✅       |
 | Shares                |      ✅       |      ✅       |      ✅       |
 | Users & Groups        |      ✅       |      ✅       |      ✅       |
@@ -37,7 +38,6 @@ Python library that provides a robust and well-documented API that allows develo
 | SpeechToText*         |     N/A      |      ❌       |      ❌       |
 
 &ast;_available only for NextcloudApp_<br>
-&ast;&ast; _work is in progress, not all API's is described, yet._
 
 ### Differences between the Nextcloud and NextcloudApp classes
 

docs/Installation.rst

@@ -13,6 +13,10 @@ To use in the Nextcloud Application mode install it with additional ``app`` depe
 
     python -m pip install --upgrade "nc_py_api[app]"
 
+To use **Calendar API** just add **calendar** dependency, and command will look like this :command:`pip`::
+
+    python -m pip install --upgrade "nc_py_api[app,calendar]"
+
 To join the development of **nc_py_api** api install development dependencies with :command:`pip`::
 
     python -m pip install --upgrade "nc_py_api[dev]"

docs/reference/Calendar.rst

@@ -0,0 +1,22 @@
+.. py:currentmodule:: nc_py_api.calendar
+
+Calendar API
+============
+
+.. note:: To make this API work you should install **nc_py_api** with **calendar** extra dependency.
+
+.. code-block:: python
+
+    principal = nc.cal.principal()
+    calendars = principal.calendars()  # get list of calendars
+
+``nc.cal`` is usual ``caldav.DAVClient`` object with the same API.
+
+Documentation for ``caldav`` can be found here: `CalDAV <"https://caldav.readthedocs.io/en/latest">`_
+
+.. class:: _CalendarAPI
+
+    Class that encapsulates ``caldav.DAVClient``. Avalaible as **cal** in the Nextcloud class.
+
+    .. note:: You should not call ``close`` or ``request`` methods of CalendarAPI, they will be removed somewhere
+        in the future when ``caldav.DAVClient`` will be rewritten(API compatability will remains).

docs/reference/index.rst

@@ -13,4 +13,5 @@ Reference
    Exceptions
    Talk
    TalkBot
+   Calendar
    Session

nc_py_api/_session.py

@@ -240,7 +240,13 @@ def dav(
         elif json is not None:
             headers.update({"Content-Type": "application/json"})
             data_bytes = dumps(json).encode("utf-8")
-        return self._dav(method, quote(self.cfg.dav_url_suffix + path), headers, data_bytes, **kwargs)
+        return self._dav(
+            method,
+            quote(self.cfg.dav_url_suffix + path) if isinstance(path, str) else path,
+            headers,
+            data_bytes,
+            **kwargs,
+        )
 
     def dav_stream(
         self, method: str, path: str, data: Optional[Union[str, bytes]] = None, **kwargs
@@ -255,7 +261,12 @@ def _dav(self, method: str, path: str, headers: dict, data: Optional[bytes], **k
         self.init_adapter()
         timeout = kwargs.pop("timeout", self.cfg.options.timeout_dav)
         result = self.adapter.request(
-            method, self.cfg.endpoint + path, headers=headers, content=data, timeout=timeout, **kwargs
+            method,
+            self.cfg.endpoint + path if isinstance(path, str) else str(path),
+            headers=headers,
+            content=data,
+            timeout=timeout,
+            **kwargs,
         )
         self.response_headers = result.headers
         return result

nc_py_api/_version.py

@@ -1,3 +1,3 @@
 """Version of nc_py_api."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.1.dev0"

nc_py_api/calendar.py

@@ -0,0 +1,39 @@
+"""Nextcloud Calendar DAV API."""
+
+from ._session import NcSessionBasic
+
+try:
+    from caldav.davclient import DAVClient, DAVResponse
+
+    class _CalendarAPI(DAVClient):
+        """Class that encapsulates ``caldav.DAVClient`` to work with the Nextcloud calendar."""
+
+        def __init__(self, session: NcSessionBasic):
+            self._session = session
+            super().__init__(session.cfg.dav_endpoint)
+
+        @property
+        def available(self) -> bool:
+            """Returns True if ``caldav`` package is avalaible, False otherwise."""
+            return True
+
+        def request(self, url, method="GET", body="", headers={}):  # noqa pylint: disable=dangerous-default-value
+            if isinstance(body, str):
+                body = body.encode("UTF-8")
+            if body:
+                body = body.replace(b"\n", b"\r\n").replace(b"\r\r\n", b"\r\n")
+            r = self._session.dav(method, url, data=body, headers=headers)
+            return DAVResponse(r)
+
+except ImportError:
+
+    class _CalendarAPI:  # type: ignore
+        """A stub class in case **caldav** is missing."""
+
+        def __init__(self, session: NcSessionBasic):
+            self._session = session
+
+        @property
+        def available(self) -> bool:
+            """Returns True if ``caldav`` package is avalaible, False otherwise."""
+            return False

nc_py_api/nextcloud.py

@@ -14,6 +14,7 @@
 from ._theming import ThemingInfo, get_parsed_theme
 from .activity import _ActivityAPI
 from .apps import _AppsAPI
+from .calendar import _CalendarAPI
 from .ex_app.defs import ApiScope, LogLvl
 from .ex_app.ui.ui import UiApi
 from .files.files import FilesAPI
@@ -29,6 +30,8 @@ class _NextcloudBasic(ABC):  # pylint: disable=too-many-instance-attributes
     """Nextcloud API for App management"""
     activity: _ActivityAPI
     """Activity Application API"""
+    cal: _CalendarAPI
+    """Nextcloud Calendar API"""
     files: FilesAPI
     """Nextcloud API for File System and Files Sharing"""
     preferences: PreferencesAPI
@@ -50,6 +53,7 @@ class _NextcloudBasic(ABC):  # pylint: disable=too-many-instance-attributes
     def _init_api(self, session: NcSessionBasic):
         self.apps = _AppsAPI(session)
         self.activity = _ActivityAPI(session)
+        self.cal = _CalendarAPI(session)
         self.files = FilesAPI(session)
         self.preferences = PreferencesAPI(session)
         self.notifications = _NotificationsAPI(session)