Improve stats cog documentation & type annotations (#503)

Author: CarrotManMatt

cogs/stats/__init__.py

@@ -8,17 +8,14 @@
 
 from config import settings
 from db.core.models import LeftDiscordMember
-from utils import (
-    CommandChecks,
-    TeXBotBaseCog,
-)
+from utils import CommandChecks, TeXBotBaseCog
 from utils.error_capture_decorators import capture_guild_does_not_exist_error
 
 from .counts import get_channel_message_counts, get_server_message_counts
 from .graphs import amount_of_time_formatter, plot_bar_chart
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterable, Sequence
+    from collections.abc import AsyncIterable, Mapping, Sequence
     from typing import Final
 
     from utils import TeXBotApplicationContext
@@ -115,7 +112,7 @@ async def channel_stats(
 
         await ctx.defer(ephemeral=True)
 
-        message_counts: dict[str, int] = await get_channel_message_counts(channel=channel)
+        message_counts: Mapping[str, int] = await get_channel_message_counts(channel=channel)
 
         if math.ceil(max(message_counts.values()) / 15) < 1:
             await self.command_send_error(
@@ -167,7 +164,7 @@ async def server_stats(self, ctx: "TeXBotApplicationContext") -> None:
 
         await ctx.defer(ephemeral=True)
 
-        message_counts: dict[str, dict[str, int]] = await get_server_message_counts(
+        message_counts: Mapping[str, Mapping[str, int]] = await get_server_message_counts(
             guild=main_guild, guest_role=guest_role
         )
 

cogs/stats/counts.py

@@ -7,13 +7,13 @@
 from config import settings
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterable, Sequence
+    from collections.abc import AsyncIterable, Mapping, Sequence
 
 
 __all__: "Sequence[str]" = ("get_channel_message_counts", "get_server_message_counts")
 
 
-async def get_channel_message_counts(channel: discord.TextChannel) -> dict[str, int]:
+async def get_channel_message_counts(channel: discord.TextChannel) -> "Mapping[str, int]":
     """
     Get the message counts for each role in the given channel.
 
@@ -62,14 +62,14 @@ async def get_channel_message_counts(channel: discord.TextChannel) -> dict[str,
 
 async def get_server_message_counts(
     guild: discord.Guild, *, guest_role: discord.Role
-) -> dict[str, dict[str, int]]:
+) -> "Mapping[str, Mapping[str, int]]":
     """
     Get the message counts for each channel in the given server.
 
-    The message counts are stored in a mapping. It contains a key "roles" which is
+    The message counts are stored in a mapping. It contains a key "roles", which is
     a mapping of role names (prefixed by `@`) to the message counts
     for each role across the entire server.
-    The mapping also contains a key "channels" which is a mapping with the channel
+    The mapping also contains a key "channels", which is a mapping with the channel
     name as a key and the number of messages sent in that channel as the value.
     The "roles" sub-mapping also includes a "Total" key for the total number of messages.
     """

cogs/stats/graphs.py

@@ -9,7 +9,7 @@
 import mplcyberpunk
 
 if TYPE_CHECKING:
-    from collections.abc import Collection, Sequence
+    from collections.abc import Collection, Mapping, Sequence
 
     from matplotlib.text import Text as Plot_Text
 
@@ -37,19 +37,21 @@ def amount_of_time_formatter(value: float, time_scale: str) -> str:
 
 
 def plot_bar_chart(
-    data: dict[str, int],
+    data: "Mapping[str, int]",
     x_label: str,
     y_label: str,
     title: str,
     filename: str,
     description: str,
     extra_text: str = "",
 ) -> discord.File:
-    """Generate an image of a plot bar chart from the given data & format variables."""
+    """Generate an image of a plot bar chart from the given data and format variables."""
     matplotlib.pyplot.style.use("cyberpunk")
 
     max_data_value: int = max(data.values()) + 1
 
+    data = dict(data)
+
     # NOTE: The "extra_values" dictionary represents columns of data that should be formatted differently to the standard data columns
     extra_values: dict[str, int] = {}
     if "Total" in data: