Merge pull request #151 from elliot-100/147-correct-documentation-and…

…-type-hints-where-functions-may-return-none

Correct documentation and type hints where functions may return None

manual_test_functions.py

@@ -7,10 +7,14 @@
 
 import asyncio
 import tempfile
+from typing import TYPE_CHECKING
 
 from config import club_id, password, username
 from spond import club, spond
 
+if TYPE_CHECKING:
+    from spond import JSONDict
+
 DUMMY_ID = "DUMMY_ID"
 
 MAX_EVENTS = 10
@@ -70,19 +74,19 @@ async def main() -> None:
     await sc.clientsession.close()
 
 
-def _group_summary(group) -> str:
+def _group_summary(group: JSONDict) -> str:
     return f"id='{group['id']}', " f"name='{group['name']}'"
 
 
-def _event_summary(event) -> str:
+def _event_summary(event: JSONDict) -> str:
     return (
         f"id='{event['id']}', "
         f"heading='{event['heading']}', "
         f"startTimestamp='{event['startTimestamp']}'"
     )
 
 
-def _chat_summary(chat) -> str:
+def _chat_summary(chat: JSONDict) -> str:
     msg_text = chat["message"].get("text", "")
     return (
         f"id='{chat['id']}', "
@@ -91,7 +95,7 @@ def _chat_summary(chat) -> str:
     )
 
 
-def _transaction_summary(transaction) -> str:
+def _transaction_summary(transaction: JSONDict) -> str:
     return (
         f"id='{transaction['id']}', "
         f"timestamp='{transaction['paidAt']}', "

spond/__init__.py

@@ -0,0 +1,11 @@
+import sys
+from typing import Any, Dict
+
+if sys.version_info < (3, 10):
+    from typing_extensions import TypeAlias
+else:
+    from typing import TypeAlias
+
+
+JSONDict: TypeAlias = Dict[str, Any]
+"""Simple alias for type hinting `dict`s that can be passed to/from JSON-handling functions."""

spond/club.py

@@ -1,19 +1,22 @@
 from __future__ import annotations
 
-from typing import Optional
+from typing import TYPE_CHECKING
 
 from .base import _SpondBase
 
+if TYPE_CHECKING:
+    from . import JSONDict
+
 
 class SpondClub(_SpondBase):
     def __init__(self, username: str, password: str) -> None:
         super().__init__(username, password, "https://api.spond.com/club/v1/")
-        self.transactions = None
+        self.transactions: list[JSONDict] | None = None
 
     @_SpondBase.require_authentication
     async def get_transactions(
-        self, club_id: str, skip: Optional[int] = None, max_items: int = 100
-    ) -> list[dict]:
+        self, club_id: str, skip: int | None = None, max_items: int = 100
+    ) -> list[JSONDict]:
         """
         Retrieves a list of transactions/payments for a specified club.
 
@@ -33,7 +36,7 @@ async def get_transactions(
 
         Returns
         -------
-        list of dict
+        list[JSONDict]
             A list of transactions, each represented as a dictionary.
         """
         if self.transactions is None:

spond/spond.py

@@ -2,13 +2,15 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, ClassVar, Optional
+from typing import TYPE_CHECKING, ClassVar
 
 from .base import _SpondBase
 
 if TYPE_CHECKING:
     from datetime import datetime
 
+    from . import JSONDict
+
 
 class Spond(_SpondBase):
 
@@ -21,9 +23,9 @@ def __init__(self, username: str, password: str) -> None:
         super().__init__(username, password, "https://api.spond.com/core/v1/")
         self.chat_url = None
         self.auth = None
-        self.groups = None
-        self.events = None
-        self.messages = None
+        self.groups: list[JSONDict] | None = None
+        self.events: list[JSONDict] | None = None
+        self.messages: list[JSONDict] | None = None
 
     async def login_chat(self) -> None:
         api_chat_url = f"{self.api_url}chat"
@@ -33,13 +35,13 @@ async def login_chat(self) -> None:
         self.auth = result["auth"]
 
     @_SpondBase.require_authentication
-    async def get_groups(self) -> Optional[list[dict]]:
+    async def get_groups(self) -> list[JSONDict] | None:
         """
         Retrieve all groups, subject to authenticated user's access.
 
         Returns
         -------
-        list[dict] or None
+        list[JSONDict] or None
             A list of groups, each represented as a dictionary, or None if no groups
             are available.
 
@@ -49,7 +51,7 @@ async def get_groups(self) -> Optional[list[dict]]:
             self.groups = await r.json()
             return self.groups
 
-    async def get_group(self, uid: str) -> dict:
+    async def get_group(self, uid: str) -> JSONDict:
         """
         Get a group by unique ID.
         Subject to authenticated user's access.
@@ -61,7 +63,8 @@ async def get_group(self, uid: str) -> dict:
 
         Returns
         -------
-        Details of the group.
+        JSONDict
+            Details of the group.
 
         Raises
         ------
@@ -71,7 +74,7 @@ async def get_group(self, uid: str) -> dict:
         return await self._get_entity(self._GROUP, uid)
 
     @_SpondBase.require_authentication
-    async def get_person(self, user: str) -> dict:
+    async def get_person(self, user: str) -> JSONDict:
         """
         Get a member or guardian by matching various identifiers.
         Subject to authenticated user's access.
@@ -84,7 +87,8 @@ async def get_person(self, user: str) -> dict:
 
         Returns
         -------
-        Member or guardian's details.
+        JSONDict
+            Member or guardian's details.
 
         Raises
         ------
@@ -118,7 +122,7 @@ async def get_person(self, user: str) -> dict:
         raise KeyError(errmsg)
 
     @_SpondBase.require_authentication
-    async def get_messages(self, max_chats: int = 100) -> Optional[list[dict]]:
+    async def get_messages(self, max_chats: int = 100) -> list[JSONDict] | None:
         """
         Retrieve messages (chats).
 
@@ -131,7 +135,7 @@ async def get_messages(self, max_chats: int = 100) -> Optional[list[dict]]:
 
         Returns
         -------
-        list[dict] or None
+        list[JSONDict] or None
             A list of chats, each represented as a dictionary, or None if no chats
             are available.
 
@@ -148,7 +152,7 @@ async def get_messages(self, max_chats: int = 100) -> Optional[list[dict]]:
         return self.messages
 
     @_SpondBase.require_authentication
-    async def _continue_chat(self, chat_id: str, text: str):
+    async def _continue_chat(self, chat_id: str, text: str) -> JSONDict:
         """
         Send a given text in an existing given chat.
         Subject to authenticated user's access.
@@ -163,7 +167,7 @@ async def _continue_chat(self, chat_id: str, text: str):
 
         Returns
         -------
-        dict
+        JSONDict
              Result of the sending.
         """
         if not self.auth:
@@ -177,9 +181,9 @@ async def _continue_chat(self, chat_id: str, text: str):
     async def send_message(
         self,
         text: str,
-        user: Optional[str] = None,
-        group_uid: Optional[str] = None,
-        chat_id: Optional[str] = None,
+        user: str | None = None,
+        group_uid: str | None = None,
+        chat_id: str | None = None,
     ):
         """
         Start a new chat or continue an existing one.
@@ -232,15 +236,15 @@ async def send_message(
     @_SpondBase.require_authentication
     async def get_events(
         self,
-        group_id: Optional[str] = None,
-        subgroup_id: Optional[str] = None,
+        group_id: str | None = None,
+        subgroup_id: str | None = None,
         include_scheduled: bool = False,
-        max_end: Optional[datetime] = None,
-        min_end: Optional[datetime] = None,
-        max_start: Optional[datetime] = None,
-        min_start: Optional[datetime] = None,
+        max_end: datetime | None = None,
+        min_end: datetime | None = None,
+        max_start: datetime | None = None,
+        min_start: datetime | None = None,
         max_events: int = 100,
-    ) -> Optional[list[dict]]:
+    ) -> list[JSONDict] | None:
         """
         Retrieve events.
 
@@ -278,9 +282,9 @@ async def get_events(
 
         Returns
         -------
-        list[dict] or None
-            A list of events, each represented as a dictionary, or None if no events
-            are available.
+        list[JSONDict] or None
+             A list of events, each represented as a dictionary, or None if no events
+             are available.
 
         """
         url = f"{self.api_url}sponds/"
@@ -307,7 +311,7 @@ async def get_events(
             self.events = await r.json()
             return self.events
 
-    async def get_event(self, uid: str) -> dict:
+    async def get_event(self, uid: str) -> JSONDict:
         """
         Get an event by unique ID.
         Subject to authenticated user's access.
@@ -319,7 +323,8 @@ async def get_event(self, uid: str) -> dict:
 
         Returns
         -------
-        Details of the event.
+        JSONDict
+            Details of the event.
 
         Raises
         ------
@@ -329,15 +334,15 @@ async def get_event(self, uid: str) -> dict:
         return await self._get_entity(self._EVENT, uid)
 
     @_SpondBase.require_authentication
-    async def update_event(self, uid: str, updates: dict):
+    async def update_event(self, uid: str, updates: JSONDict):
         """
         Updates an existing event.
 
         Parameters
         ----------
         uid : str
            UID of the event.
-        updates : dict
+        updates : JSONDict
             The changes. e.g. if you want to change the description -> {'description': "New Description with changes"}
 
         Returns
@@ -353,7 +358,7 @@ async def update_event(self, uid: str, updates: dict):
 
         url = f"{self.api_url}sponds/{uid}"
 
-        base_event: dict = {
+        base_event: JSONDict = {
             "heading": None,
             "description": None,
             "spondType": "EVENT",
@@ -425,7 +430,7 @@ async def get_event_attendance_xlsx(self, uid: str) -> bytes:
             return output_data
 
     @_SpondBase.require_authentication
-    async def change_response(self, uid: str, user: str, payload: dict) -> dict:
+    async def change_response(self, uid: str, user: str, payload: JSONDict) -> JSONDict:
         """change a user's response for an event
 
         Parameters
@@ -436,12 +441,13 @@ async def change_response(self, uid: str, user: str, payload: dict) -> dict:
         user : str
             UID of the user
 
-        payload : dict
+        payload : JSONDict
             user response to event, e.g. {"accepted": "true"}
 
         Returns
         -------
-            json: event["responses"] with updated info
+        JSONDict
+            event["responses"] with updated info
         """
         url = f"{self.api_url}sponds/{uid}/responses/{user}"
         async with self.clientsession.put(
@@ -450,7 +456,7 @@ async def change_response(self, uid: str, user: str, payload: dict) -> dict:
             return await r.json()
 
     @_SpondBase.require_authentication
-    async def _get_entity(self, entity_type: str, uid: str) -> dict:
+    async def _get_entity(self, entity_type: str, uid: str) -> JSONDict:
         """
         Get an event or group by unique ID.
 
@@ -465,7 +471,8 @@ async def _get_entity(self, entity_type: str, uid: str) -> dict:
 
         Returns
         -------
-        Details of the entity.
+        JSONDict
+            Details of the entity.
 
         Raises
         ------