feat: deprecate sync APIs and convert examples to async

Add DeprecationWarning to all remaining sync entry points:
- _NextcloudBasic.__init__ (covers Nextcloud and NextcloudApp)
- TalkBot.__init__
- nc_app and talk_bot_msg sync dependency injectors
- sync branches of set_handlers (enabled_handler, trigger_handler)

Convert README skeleton app and all client examples to async.

Author: Review

README.md

@@ -52,7 +52,7 @@ from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
 
-from nc_py_api import NextcloudApp
+from nc_py_api import AsyncNextcloudApp
 from nc_py_api.ex_app import AppAPIAuthMiddleware, LogLvl, run_app, set_handlers
 
 
@@ -66,11 +66,11 @@ APP = FastAPI(lifespan=lifespan)
 APP.add_middleware(AppAPIAuthMiddleware)
 
 
-def enabled_handler(enabled: bool, nc: NextcloudApp) -> str:
+async def enabled_handler(enabled: bool, nc: AsyncNextcloudApp) -> str:
     if enabled:
-        nc.log(LogLvl.WARNING, "Hello from nc_py_api.")
+        await nc.log(LogLvl.WARNING, "Hello from nc_py_api.")
     else:
-        nc.log(LogLvl.WARNING, "Bye bye from nc_py_api.")
+        await nc.log(LogLvl.WARNING, "Bye bye from nc_py_api.")
     return ""
 
 

examples/as_client/files/download.py

@@ -1,12 +1,17 @@
+import asyncio
 from io import BytesIO
 
 from PIL import Image  # this example requires `pillow` to be installed
 
 import nc_py_api
 
-if __name__ == "__main__":
+
+async def main():
     # run this example after ``files_upload.py`` or adjust the image file path.
-    nc = nc_py_api.Nextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
-    rgb_image = nc.files.download("RGB.png")
+    nc = nc_py_api.AsyncNextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
+    rgb_image = await nc.files.download("RGB.png")
     Image.open(BytesIO(rgb_image)).show()  # wrap `bytes` into BytesIO for Pillow
-    exit(0)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/as_client/files/find.py

@@ -1,16 +1,22 @@
+import asyncio
+
 import nc_py_api
 
-if __name__ == "__main__":
+
+async def main():
     # create Nextcloud client instance class
-    nc = nc_py_api.Nextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
+    nc = nc_py_api.AsyncNextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
 
     print("Searching for all files which names ends with `.txt`:")
-    result = nc.files.find(["like", "name", "%.txt"])
+    result = await nc.files.find(["like", "name", "%.txt"])
     for i in result:
         print(i)
     print("")
     print("Searching for all files which name is equal to `Nextcloud_Server_Administration_Manual.pdf`:")
-    result = nc.files.find(["eq", "name", "Nextcloud_Server_Administration_Manual.pdf"])
+    result = await nc.files.find(["eq", "name", "Nextcloud_Server_Administration_Manual.pdf"])
     for i in result:
         print(i)
-    exit(0)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/as_client/files/listing.py

@@ -1,17 +1,23 @@
+import asyncio
+
 import nc_py_api
 
-if __name__ == "__main__":
+
+async def main():
     # create Nextcloud client instance class
-    nc = nc_py_api.Nextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
+    nc = nc_py_api.AsyncNextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
 
-    def list_dir(directory):
+    async def list_dir(directory):
         # usual recursive traversing over directories
-        for node in nc.files.listdir(directory):
+        for node in await nc.files.listdir(directory):
             if node.is_dir:
-                list_dir(node)
+                await list_dir(node)
             else:
                 print(f"{node.user_path}")
 
     print("Files on the instance for the selected user:")
-    list_dir("")
-    exit(0)
+    await list_dir("")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/as_client/files/upload.py

@@ -1,11 +1,13 @@
+import asyncio
 from io import BytesIO
 
 from PIL import Image  # this example requires `pillow` to be installed
 
 import nc_py_api
 
-if __name__ == "__main__":
-    nc = nc_py_api.Nextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
+
+async def main():
+    nc = nc_py_api.AsyncNextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
     buf = BytesIO()
     Image.merge(
         "RGB",
@@ -18,5 +20,8 @@
         buf, format="PNG"
     )  # saving image to the buffer
     buf.seek(0)  # setting the pointer to the start of buffer
-    nc.files.upload_stream("RGB.png", buf)  # uploading file from the memory to the user's root folder
-    exit(0)
+    await nc.files.upload_stream("RGB.png", buf)  # uploading file from the memory to the user's root folder
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

nc_py_api/ex_app/integration_fastapi.py

@@ -7,6 +7,7 @@
 import json
 import os
 import typing
+import warnings
 from traceback import format_exc
 from urllib.parse import urlparse
 
@@ -34,6 +35,11 @@
 
 def nc_app(request: HTTPConnection) -> NextcloudApp:
     """Authentication handler for requests from Nextcloud to the application."""
+    warnings.warn(
+        "nc_app (sync) is deprecated and will be removed in v0.31.0. Use anc_app instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     nextcloud_app = NextcloudApp(**__nc_app(request))
     __request_sign_check_if_needed(request, nextcloud_app)
     return nextcloud_app
@@ -48,6 +54,11 @@ def anc_app(request: HTTPConnection) -> AsyncNextcloudApp:
 
 def talk_bot_msg(request: Request) -> TalkBotMessage:
     """Authentication handler for bot requests from Nextcloud Talk to the application."""
+    warnings.warn(
+        "talk_bot_msg (sync) is deprecated and will be removed in v0.31.0. Use atalk_bot_msg instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     return TalkBotMessage(json.loads(asyncio.run(request.body())))
 
 
@@ -109,6 +120,12 @@ async def enabled_callback(enabled: bool, nc: typing.Annotated[AsyncNextcloudApp
             return JSONResponse(content={"error": await enabled_handler(enabled, nc)})
 
     else:
+        warnings.warn(
+            "Passing a sync enabled_handler to set_handlers is deprecated and will be removed in v0.31.0. "
+            "Use an async enabled_handler instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
 
         @fast_api_app.put("/enabled")
         def enabled_callback(enabled: bool, nc: typing.Annotated[NextcloudApp, Depends(nc_app)]):
@@ -139,6 +156,12 @@ async def trigger_callback(providerId: str):  # pylint: disable=invalid-name
                 return JSONResponse(content={})
 
         else:
+            warnings.warn(
+                "Passing a sync trigger_handler to set_handlers is deprecated and will be removed in v0.31.0. "
+                "Use an async trigger_handler instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
 
             @fast_api_app.post("/trigger")
             def trigger_callback(providerId: str):  # pylint: disable=invalid-name

nc_py_api/nextcloud.py

@@ -2,6 +2,7 @@
 
 import contextlib
 import typing
+import warnings
 from abc import ABC
 
 from niquests.structures import CaseInsensitiveDict
@@ -69,6 +70,12 @@ class _NextcloudBasic(ABC):  # pylint: disable=too-many-instance-attributes
     _session: NcSessionBasic
 
     def __init__(self, session: NcSessionBasic):
+        warnings.warn(
+            "Sync Nextcloud/NextcloudApp classes are deprecated and will be removed in v0.31.0. "
+            "Migrate to AsyncNextcloud/AsyncNextcloudApp.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
         self.apps = _AppsAPI(session)
         self.cal = _CalendarAPI(session)
         self.files = FilesAPI(session)

nc_py_api/talk_bot.py

@@ -6,6 +6,7 @@
 import json
 import os
 import typing
+import warnings
 
 import niquests
 
@@ -114,6 +115,11 @@ def __init__(self, callback_url: str, display_name: str, description: str = ""):
         :param display_name: The display name of the bot that is shown as author when it posts a message or reaction.
         :param description: Description of the bot helping moderators to decide if they want to enable this bot.
         """
+        warnings.warn(
+            "TalkBot is deprecated and will be removed in v0.31.0. Use AsyncTalkBot instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.callback_url = callback_url.lstrip("/")
         self.display_name = display_name
         self.description = description