From a39e43ce947168091db479e0ed9472cf77da6003 Mon Sep 17 00:00:00 2001
From: Elliot <3186037+elliot-100@users.noreply.github.com>
Date: Wed, 10 Jul 2024 18:48:04 +0100
Subject: [PATCH] docs/typing: correct docstrings and type hints where
 functions can return None

---
 spond/spond.py | 34 +++++++++++++++++++++++-----------
 1 file changed, 23 insertions(+), 11 deletions(-)

diff --git a/spond/spond.py b/spond/spond.py
index ad8c4b0..40c79d8 100644
--- a/spond/spond.py
+++ b/spond/spond.py
@@ -32,15 +32,16 @@ async def login_chat(self) -> None:
         self.auth = result["auth"]
 
     @_SpondBase.require_authentication
-    async def get_groups(self) -> list[dict]:
+    async def get_groups(self) -> Optional[list[dict]]:
         """
-        Get all groups.
-        Subject to authenticated user's access.
+        Retrieve all groups, subject to authenticated user's access.
 
         Returns
         -------
-        list of dict
-            Groups; each group is a dict.
+        list[dict] or None
+            A list of groups, each represented as a dictionary, or None if no groups
+            are available.
+
         """
         url = f"{self.api_url}groups/"
         async with self.clientsession.get(url, headers=self.auth_headers) as r:
@@ -116,7 +117,17 @@ async def get_person(self, user: str) -> dict:
         raise KeyError(errmsg)
 
     @_SpondBase.require_authentication
-    async def get_messages(self) -> list[dict]:
+    async def get_messages(self) -> Optional[list[dict]]:
+        """
+        Retrieve messages (chats).
+
+        Returns
+        -------
+        list[dict] or None
+            A list of chats, each represented as a dictionary, or None if no chats
+            are available.
+
+        """
         if not self.auth:
             await self.login_chat()
         url = f"{self.chat_url}/chats/?max=10"
@@ -216,10 +227,9 @@ async def get_events(
         max_start: Optional[datetime] = None,
         min_start: Optional[datetime] = None,
         max_events: int = 100,
-    ) -> list[dict]:
+    ) -> Optional[list[dict]]:
         """
-        Get events.
-        Subject to authenticated user's access.
+        Retrieve events.
 
         Parameters
         ----------
@@ -255,8 +265,10 @@ async def get_events(
 
         Returns
         -------
-        list of dict
-            Events; each event is a dict.
+        list[dict] or None
+            A list of events, each represented as a dictionary, or None if no events
+            are available.
+
         """
         url = f"{self.api_url}sponds/"
         params = {