Docs: fix documentation and type hints where functions may return None

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 = {