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 1/5] 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 = { From 5cc480bf1d9e68cc6c0d658aa731ec662e259c60 Mon Sep 17 00:00:00 2001 From: Elliot <3186037+elliot-100@users.noreply.github.com> Date: Wed, 14 Aug 2024 15:52:19 +0100 Subject: [PATCH 2/5] `Spond.get_messages`: add `max_chats` parameter and populate `Spond.messages`. --- spond/spond.py | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/spond/spond.py b/spond/spond.py index 40c79d8..7970969 100644 --- a/spond/spond.py +++ b/spond/spond.py @@ -23,6 +23,7 @@ def __init__(self, username: str, password: str) -> None: self.auth = None self.groups = None self.events = None + self.messages = None async def login_chat(self) -> None: api_chat_url = f"{self.api_url}chat" @@ -117,10 +118,17 @@ async def get_person(self, user: str) -> dict: raise KeyError(errmsg) @_SpondBase.require_authentication - async def get_messages(self) -> Optional[list[dict]]: + async def get_messages(self, max_chats: int = 100) -> Optional[list[dict]]: """ Retrieve messages (chats). + Parameters + ---------- + max_chats : int, optional + Set a limit on the number of chats returned. + For performance reasons, defaults to 100. + Uses `max` API parameter. + Returns ------- list[dict] or None @@ -130,9 +138,14 @@ async def get_messages(self) -> Optional[list[dict]]: """ if not self.auth: await self.login_chat() - url = f"{self.chat_url}/chats/?max=10" - async with self.clientsession.get(url, headers={"auth": self.auth}) as r: - return await r.json() + url = f"{self.chat_url}/chats/" + async with self.clientsession.get( + url, + headers={"auth": self.auth}, + params={"max": str(max_chats)}, + ) as r: + self.messages = await r.json() + return self.messages @_SpondBase.require_authentication async def _continue_chat(self, chat_id: str, text: str): From 4f9a826b32f54e4f90ed8bf2ac2c501ebc7055c9 Mon Sep 17 00:00:00 2001 From: Elliot <3186037+elliot-100@users.noreply.github.com> Date: Fri, 26 Jul 2024 12:52:51 +0100 Subject: [PATCH 3/5] `manual_test_functions`: use `max_chats` parameter; extract constants --- manual_test_functions.py | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/manual_test_functions.py b/manual_test_functions.py index c76dfc6..46f255d 100644 --- a/manual_test_functions.py +++ b/manual_test_functions.py @@ -13,6 +13,10 @@ DUMMY_ID = "DUMMY_ID" +MAX_EVENTS = 10 +MAX_CHATS = 10 +MAX_TRANSACTIONS = 10 + async def main() -> None: s = spond.Spond(username=username, password=password) @@ -27,19 +31,19 @@ async def main() -> None: # EVENTS - print("\nGetting up to 10 events...") - events = await s.get_events(max_events=10) + print(f"\nGetting up to {MAX_EVENTS} events...") + events = await s.get_events(max_events=MAX_EVENTS) print(f"{len(events)} events:") for i, event in enumerate(events): print(f"[{i}] {_event_summary(event)}") - # MESSAGES + # CHATS (MESSAGES) - print("\nGetting up to 10 messages...") - messages = await s.get_messages() - print(f"{len(messages)} messages:") - for i, message in enumerate(messages): - print(f"[{i}] {_message_summary(message)}") + print(f"\nGetting up to {MAX_CHATS} chats...") + messages = await s.get_messages(max_chats=MAX_CHATS) + print(f"{len(messages)} chats:") + for i, chat in enumerate(messages): + print(f"[{i}] {_message_summary(chat)}") # ATTENDANCE EXPORT @@ -56,8 +60,10 @@ async def main() -> None: # SPOND CLUB sc = club.SpondClub(username=username, password=password) - print("\nGetting up to 10 transactions...") - transactions = await sc.get_transactions(club_id=club_id, max_items=10) + print(f"\nGetting up to {MAX_TRANSACTIONS} transactions...") + transactions = await sc.get_transactions( + club_id=club_id, max_items=MAX_TRANSACTIONS + ) print(f"{len(transactions)} transactions:") for i, t in enumerate(transactions): print(f"[{i}] {_transaction_summary(t)}") From 0267794b3e460b806a1c887b28ed04e8aecab19d Mon Sep 17 00:00:00 2001 From: Elliot <3186037+elliot-100@users.noreply.github.com> Date: Wed, 14 Aug 2024 16:03:02 +0100 Subject: [PATCH 4/5] docs: README update --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dd37b5d..ed4ad0b 100644 --- a/README.md +++ b/README.md @@ -50,8 +50,9 @@ Optional parameters allow filtering by start and end datetimes, group and subgro ### get_person() Get a member's details. -### get_messages() -Get all your messages. +### get_messages(max_chats=100) +Get chats, limited to 100 by default. +Optional parameter allows more events to be returned. ### send_message(text, user=None, group_uid=None, chat_id=None) Send a message with content `text`. From a6170640e234cdc6f0b461a0c480a665246795b0 Mon Sep 17 00:00:00 2001 From: Elliot <3186037+elliot-100@users.noreply.github.com> Date: Wed, 14 Aug 2024 18:30:09 +0100 Subject: [PATCH 5/5] refactor for consistency+clarity; docstring typo fix; also fixes line length issues --- manual_test_functions.py | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/manual_test_functions.py b/manual_test_functions.py index 46f255d..2dde9ad 100644 --- a/manual_test_functions.py +++ b/manual_test_functions.py @@ -1,6 +1,6 @@ """Use Spond 'get' functions to summarise available data. -Intended as a simple end-to-end test for assurance when making changes, where there are s +Intended as a simple end-to-end test for assurance when making changes, where there are gaps in test suite coverage. Doesn't yet use `get_person(user)` or any `send_`, `update_` methods.""" @@ -40,10 +40,10 @@ async def main() -> None: # CHATS (MESSAGES) print(f"\nGetting up to {MAX_CHATS} chats...") - messages = await s.get_messages(max_chats=MAX_CHATS) - print(f"{len(messages)} chats:") - for i, chat in enumerate(messages): - print(f"[{i}] {_message_summary(chat)}") + chats = await s.get_messages(max_chats=MAX_CHATS) + print(f"{len(chats)} chats:") + for i, chat in enumerate(chats): + print(f"[{i}] {_chat_summary(chat)}") # ATTENDANCE EXPORT @@ -82,11 +82,12 @@ def _event_summary(event) -> str: ) -def _message_summary(message) -> str: +def _chat_summary(chat) -> str: + msg_text = chat["message"].get("text", "") return ( - f"id='{message['id']}', " - f"timestamp='{message['message']['timestamp']}', " - f"text={_abbreviate(message['message']['text'] if message['message'].get('text') else '', length=64)}, " + f"id='{chat['id']}', " + f"timestamp='{chat['message']['timestamp']}', " + f"text={_abbreviate(msg_text, length=64)}" )