From 5145beed5e5716d3e3d557fe7ecc00f39686f9dd Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 27 Apr 2022 14:21:23 -0400 Subject: [PATCH 1/8] Add/update some docstrings. --- changelog.d/12581.misc | 1 + synapse/storage/databases/main/receipts.py | 44 +++++++++++++++++++++- 2 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 changelog.d/12581.misc diff --git a/changelog.d/12581.misc b/changelog.d/12581.misc new file mode 100644 index 000000000000..38d40b262b25 --- /dev/null +++ b/changelog.d/12581.misc @@ -0,0 +1 @@ +Improve docstrings for the receipts store. diff --git a/synapse/storage/databases/main/receipts.py b/synapse/storage/databases/main/receipts.py index 332e901dda40..a71982d0e8e5 100644 --- a/synapse/storage/databases/main/receipts.py +++ b/synapse/storage/databases/main/receipts.py @@ -126,6 +126,16 @@ async def get_users_with_read_receipts_in_room(self, room_id: str) -> Set[str]: async def get_receipts_for_room( self, room_id: str, receipt_type: str ) -> List[Dict[str, Any]]: + """ + Fetch the event IDs for the latest receipt for all users in a room with the given receipt type. + + Args: + room_id: The room ID to fetch the receipt for. + receipt_type: The receipt type to fetch. + + Returns: + A list of dictionaries of the user ID and event ID of the latest receipt for each user. + """ return await self.db_pool.simple_select_list( table="receipts_linearized", keyvalues={"room_id": room_id, "receipt_type": receipt_type}, @@ -137,6 +147,17 @@ async def get_receipts_for_room( async def get_last_receipt_event_id_for_user( self, user_id: str, room_id: str, receipt_type: str ) -> Optional[str]: + """ + Fetch the event ID for the latest receipt in a room with the given receipt type. + + Args: + user_id: The user to fetch receipts for. + room_id: The room ID to fetch the receipt for. + receipt_type: The receipt type to fetch. + + Returns: + The event ID of the latest receipt, if one exists. + """ return await self.db_pool.simple_select_one_onecol( table="receipts_linearized", keyvalues={ @@ -153,6 +174,16 @@ async def get_last_receipt_event_id_for_user( async def get_receipts_for_user( self, user_id: str, receipt_type: str ) -> Dict[str, str]: + """ + Fetch the event IDs for the latest receipt in all rooms with the given receipt type. + + Args: + user_id: The user to fetch receipts for. + receipt_type: The receipt types to fetch. + + Returns: + A map of room ID to the event ID of the latest receipt for that room. + """ rows = await self.db_pool.simple_select_list( table="receipts_linearized", keyvalues={"user_id": user_id, "receipt_type": receipt_type}, @@ -165,6 +196,17 @@ async def get_receipts_for_user( async def get_receipts_for_user_with_orderings( self, user_id: str, receipt_type: str ) -> JsonDict: + """ + Fetch receipts in all rooms for a user. + + Args: + user_id: The user to fetch receipts for. + receipt_type: The receipt type to fetch. + + Returns: + A map of room ID to the latest receipt information. + """ + def f(txn: LoggingTransaction) -> List[Tuple[str, str, int, int]]: sql = ( "SELECT rl.room_id, rl.event_id," @@ -541,7 +583,7 @@ def insert_linearized_receipt_txn( data: JsonDict, stream_id: int, ) -> Optional[int]: - """Inserts a read-receipt into the database if it's newer than the current RR + """Inserts a receipt into the database if it's newer than the current one. Returns: None if the RR is older than the current RR From 06a4d0be4368bf784d4784cd0b8955aa47857ce6 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 28 Apr 2022 09:20:34 -0400 Subject: [PATCH 2/8] Remove unneeded num_args in @cached decorators. --- synapse/storage/databases/main/receipts.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/synapse/storage/databases/main/receipts.py b/synapse/storage/databases/main/receipts.py index a71982d0e8e5..6d7afd86bcdc 100644 --- a/synapse/storage/databases/main/receipts.py +++ b/synapse/storage/databases/main/receipts.py @@ -122,7 +122,7 @@ async def get_users_with_read_receipts_in_room(self, room_id: str) -> Set[str]: receipts = await self.get_receipts_for_room(room_id, ReceiptTypes.READ) return {r["user_id"] for r in receipts} - @cached(num_args=2) + @cached() async def get_receipts_for_room( self, room_id: str, receipt_type: str ) -> List[Dict[str, Any]]: @@ -143,7 +143,7 @@ async def get_receipts_for_room( desc="get_receipts_for_room", ) - @cached(num_args=3) + @cached() async def get_last_receipt_event_id_for_user( self, user_id: str, room_id: str, receipt_type: str ) -> Optional[str]: @@ -170,7 +170,7 @@ async def get_last_receipt_event_id_for_user( allow_none=True, ) - @cached(num_args=2) + @cached() async def get_receipts_for_user( self, user_id: str, receipt_type: str ) -> Dict[str, str]: @@ -283,7 +283,7 @@ async def get_linearized_receipts_for_room( return await self._get_linearized_receipts_for_room(room_id, to_key, from_key) - @cached(num_args=3, tree=True) + @cached(tree=True) async def _get_linearized_receipts_for_room( self, room_id: str, to_key: int, from_key: Optional[int] = None ) -> List[JsonDict]: From fb58d671758c7b19b78981079a92fe5150d0e4b4 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 28 Apr 2022 13:00:43 -0400 Subject: [PATCH 3/8] Clarify comments. Co-authored-by: David Robertson --- synapse/storage/databases/main/receipts.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/synapse/storage/databases/main/receipts.py b/synapse/storage/databases/main/receipts.py index 6d7afd86bcdc..90ed6f1d8335 100644 --- a/synapse/storage/databases/main/receipts.py +++ b/synapse/storage/databases/main/receipts.py @@ -156,7 +156,7 @@ async def get_last_receipt_event_id_for_user( receipt_type: The receipt type to fetch. Returns: - The event ID of the latest receipt, if one exists. + The event ID of the latest receipt, if one exists; otherwise `None`. """ return await self.db_pool.simple_select_one_onecol( table="receipts_linearized", @@ -197,7 +197,7 @@ async def get_receipts_for_user_with_orderings( self, user_id: str, receipt_type: str ) -> JsonDict: """ - Fetch receipts in all rooms for a user. +Fetch receipts for all rooms that the given user is joined to. Args: user_id: The user to fetch receipts for. From 6d1d8651bc36a5efb721c43179a6227aa67343c0 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 28 Apr 2022 13:10:23 -0400 Subject: [PATCH 4/8] More clarifications. --- synapse/storage/databases/main/receipts.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/synapse/storage/databases/main/receipts.py b/synapse/storage/databases/main/receipts.py index 90ed6f1d8335..a649bd8e6fdb 100644 --- a/synapse/storage/databases/main/receipts.py +++ b/synapse/storage/databases/main/receipts.py @@ -134,7 +134,8 @@ async def get_receipts_for_room( receipt_type: The receipt type to fetch. Returns: - A list of dictionaries of the user ID and event ID of the latest receipt for each user. + A list of dictionaries, one for each user ID. Each dictionary + contains a user ID and the event ID of that user's latest receipt. """ return await self.db_pool.simple_select_list( table="receipts_linearized", From 0501bbc002d8d3391c3f335aa15286f4d59a6d5a Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 28 Apr 2022 13:13:00 -0400 Subject: [PATCH 5/8] Attempt to clarify docstring for get_receipts_for_user. --- synapse/storage/databases/main/receipts.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/synapse/storage/databases/main/receipts.py b/synapse/storage/databases/main/receipts.py index a649bd8e6fdb..322d99b921f7 100644 --- a/synapse/storage/databases/main/receipts.py +++ b/synapse/storage/databases/main/receipts.py @@ -176,7 +176,7 @@ async def get_receipts_for_user( self, user_id: str, receipt_type: str ) -> Dict[str, str]: """ - Fetch the event IDs for the latest receipt in all rooms with the given receipt type. + Fetch the event IDs for the latest receipt sent by the given user. Args: user_id: The user to fetch receipts for. @@ -184,6 +184,9 @@ async def get_receipts_for_user( Returns: A map of room ID to the event ID of the latest receipt for that room. + + If the user has not sent a receipt to a room then it will not appear + in the returned dictionary. """ rows = await self.db_pool.simple_select_list( table="receipts_linearized", From 008a7f4f6187188389a2f4ce2922f31a152ef9e8 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 28 Apr 2022 13:14:19 -0400 Subject: [PATCH 6/8] Fix formatting. --- synapse/storage/databases/main/receipts.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/synapse/storage/databases/main/receipts.py b/synapse/storage/databases/main/receipts.py index 322d99b921f7..9f14807bd197 100644 --- a/synapse/storage/databases/main/receipts.py +++ b/synapse/storage/databases/main/receipts.py @@ -201,7 +201,7 @@ async def get_receipts_for_user_with_orderings( self, user_id: str, receipt_type: str ) -> JsonDict: """ -Fetch receipts for all rooms that the given user is joined to. + Fetch receipts for all rooms that the given user is joined to. Args: user_id: The user to fetch receipts for. From 7a15edc7c0cbe6bea51d549530c8ed0fe71b4042 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 28 Apr 2022 13:31:18 -0400 Subject: [PATCH 7/8] Fix typo. --- synapse/storage/databases/main/receipts.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/synapse/storage/databases/main/receipts.py b/synapse/storage/databases/main/receipts.py index 9f14807bd197..64ff0fe83e37 100644 --- a/synapse/storage/databases/main/receipts.py +++ b/synapse/storage/databases/main/receipts.py @@ -180,7 +180,7 @@ async def get_receipts_for_user( Args: user_id: The user to fetch receipts for. - receipt_type: The receipt types to fetch. + receipt_type: The receipt type to fetch. Returns: A map of room ID to the event ID of the latest receipt for that room. From 9db3a2d70b944729fb0c6a4c7581a93c5f833a13 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 28 Apr 2022 13:32:07 -0400 Subject: [PATCH 8/8] Fix pluralization. Co-authored-by: David Robertson --- synapse/storage/databases/main/receipts.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/synapse/storage/databases/main/receipts.py b/synapse/storage/databases/main/receipts.py index 64ff0fe83e37..7d96f4fedabf 100644 --- a/synapse/storage/databases/main/receipts.py +++ b/synapse/storage/databases/main/receipts.py @@ -176,7 +176,7 @@ async def get_receipts_for_user( self, user_id: str, receipt_type: str ) -> Dict[str, str]: """ - Fetch the event IDs for the latest receipt sent by the given user. + Fetch the event IDs for the latest receipts sent by the given user. Args: user_id: The user to fetch receipts for.