😡Ruff it up x3

Author: Aluerie

__main__.py

@@ -11,7 +11,7 @@
 from utils.database import create_pool
 
 try:
-    import uvloop  # type: ignore
+    import uvloop  # pyright: ignore[reportMissingImports]
 except ImportError:
     # WINDOWS
     asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

bot/bot.py

@@ -90,7 +90,8 @@ def __init__(
             # TODO: fill in scopes= argument once we figure out what it's used for :x
         )
         self.database: asyncpg.Pool[asyncpg.Record] = pool
-        self.pool: PoolTypedWithAny = pool  # type: ignore # asyncpg typehinting crutch, read `utils.database` for more
+        # asyncpg typehinting crutch, read `utils.database` for more
+        self.pool: PoolTypedWithAny = pool  # pyright: ignore[reportAttributeAccessIssue]
         self.session: ClientSession = session
         self.extensions: tuple[str, ...] = EXTENSIONS
 
@@ -119,6 +120,10 @@ def __init__(
     #     print(auth_url)  # noa: T201
 
     def print_bot_oauth(self) -> None:
+        """Print a link for me (developer) to click and authorize the bot scopes for the bot account.
+
+        Required for proper work of Twitch Eventsub events and API requests.
+        """
         scopes = "%20".join(
             [
                 "user:read:chat",
@@ -135,14 +140,16 @@ def print_bot_oauth(self) -> None:
         print(f"🤖🤖🤖 BOT OAUTH LINK: 🤖🤖🤖\n{link}")  # noqa: T201
 
     def print_broadcaster_oauth(self) -> None:
-        """
+        """Print a link for streamers to click and authorize the scopes for the bot.
+
+        Required for proper work of Twitch Eventsub events and API requests.
 
         Notes
         -----
         * Currently my developer console has localhost as a callback: http://localhost:4343/oauth/callback
             But if we ever switch to multi-streams setup then I already have some things set up with
             * https://parrot-thankful-trivially.ngrok-free.app/oauth/callback (in developer console)
-            * ngrok http --url=parrot-thankful-trivially.ngrok-free.app 80 (in my/vps terminal)
+            * `ngrok http --url=parrot-thankful-trivially.ngrok-free.app 80` (in my/vps terminal)
             Look ngrok dashboard for more.
 
             With it a user needs to go to a link like this:
@@ -172,7 +179,8 @@ async def setup_hook(self) -> None:
         for the first time (or after adding extra scopes):
             1. Uncomment three first lines in this function;
             2. Run the bot;
-            3. Click generated links using proper accounts (i.e. broadcaster = the browser with streamer account logged in);
+            3. Click generated links using proper accounts:
+                (i.e. broadcaster = the browser with streamer account logged in);
             4. The bot will update the tokens in the database automatically;
             5. Comment the lines back. In normal state, they should be commented.
 
@@ -188,10 +196,9 @@ async def setup_hook(self) -> None:
         self.check_if_online.start()
 
     async def create_eventsub_subscriptions(self) -> None:
-        """
-        Subscribe to all EventSub subscriptions that are required for the bot to work.
-        The function also includes (in code) a table showcasing which subscriptions/scopes are required for what.
+        """Subscribe to all EventSub subscriptions that are required for the bot to work.
 
+        The function also includes (in code) a table showcasing which subscriptions/scopes are required for what.
         For more links:
 
         TwitchDev Docs
@@ -261,7 +268,7 @@ async def add_token(self, token: str, refresh: str) -> twitchio.authentication.V
         return resp
 
     @override
-    async def load_tokens(self, path: str | None = None) -> None:
+    async def load_tokens(self, _: str | None = None) -> None:  # _ is `path`
         # We don't need to call this manually, it is called in .login() from .start() internally...
 
         rows: list[LoadTokensQueryRow] = await self.pool.fetch("""SELECT * from ttv_tokens""")
@@ -328,9 +335,9 @@ async def event_command_error(self, payload: commands.CommandErrorPayload) -> No
                 }
                 await ctx.send(guard_mapping.get(error.guard.__qualname__, str(error)))
             case twitchio.HTTPException():
-                # log.error("%s", error.__class__.__name__, exc_info=error)
                 await ctx.send(
-                    f"{error.extra.get('error', 'Error')} {error.extra.get('status', 'XXX')}: "
+                    f"{error.extra.get('error', 'Error')} "
+                    f"{error.extra.get('status', 'XXX')}: "
                     f"{error.extra.get('message', 'Unknown')} {const.STV.dankFix}",
                 )
             case commands.MissingRequiredArgument():
@@ -406,19 +413,26 @@ def error_ping(self) -> str:
         return config.ERROR_PING
 
     async def aluerie_stream(self) -> twitchio.Stream | None:
+        """Shortcut to get @Aluerie's stream."""
         return next(iter(await self.fetch_streams(user_ids=[const.UserID.Aluerie])), None)
 
     @lueloop(count=1)
     async def check_if_online(self) -> None:
+        """Check if aluerie is online - used to make my own (proper) online event instead of twitchio's."""
         await asyncio.sleep(1.0)  # just in case;
         if await self.aluerie_stream():
             self.aluerie_online = True
             self.dispatch("aluerie_online")
 
     async def event_stream_online(self, _: twitchio.StreamOnline) -> None:
+        """Instead of the twitchio event - dispatch my own online event.
+
+        The difference is that my event accounts for the state of my stream when the bot restarts.
+        """
         self.aluerie_online = True
         self.dispatch("aluerie_online")
 
     async def event_stream_offline(self, _: twitchio.StreamOffline) -> None:
+        """Instead of the twitchio event - dispatch my own offline event."""
         self.aluerie_online = False
         self.dispatch("aluerie_offline")

bot/exc_manager.py

@@ -57,9 +57,9 @@ async def register_error(self, error: BaseException, embed: discord.Embed, *, me
                 await asyncio.sleep(total_seconds)
 
             self._most_recent = datetime.datetime.now(datetime.UTC)
-            await self.send_error(traceback_string, embed, mention)
+            await self.send_error(traceback_string, embed, mention=mention)
 
-    async def send_error(self, traceback: str, embed: discord.Embed, mention: bool) -> None:
+    async def send_error(self, traceback: str, embed: discord.Embed, *, mention: bool) -> None:
         """Send an error to the webhook.
 
         It is not recommended to call this yourself, call `register_error` instead.

pyproject.toml

@@ -133,14 +133,14 @@ ignore = [
     # "UP038",
 
     # DOC STRINGS
-    # general doc string exceptions
+    # 1. General doc string exceptions
     "D100",     # Missing docstring in module: no, module level docs aren't always needed
     "D105",     # Missing docstring in magic method: documenting magic methods is often dumb.
     "D107",     # Missing docstring in `__init__`: __init__ is the wrong place to doc this.
     "D401",     # Doc should be starting with an imperative verb: dumb rule, to be honest.
-    # doc string exceptions 
-    # for this bot because it's a bot and it's pointless to document *everything* in one-man project.
+    # 2. Exceptions for this bot because it's pointless to document *everything* in one-man project.
     "DOC201",   # `return` is not documented in docstring
+    "DOC501",   # raised exception is missing from docstring
 
     # "D104",    # Missing docstring in public package. Otherwise spams __init__.py and such.
     # "D417",    # Missing argument description. Otherwise, it keeps asking to document interaction/context args.

utils/formats.py

@@ -33,7 +33,7 @@ def __init__(self, number: int) -> None:
     @override
     def __format__(self, format_spec: str) -> str:
         number = self.number
-        singular, separator, plural = format_spec.partition("|")
+        singular, _, plural = format_spec.partition("|")  # _ is `separator`
         plural = plural or f"{singular}s"
         if abs(number) != 1:
             return f"{number} {plural}"
@@ -60,11 +60,10 @@ def timedelta_to_words(
 
     Example:
     -------
-        ```py
+        ```
         x = datetime.timedelta(seconds=66)
         timedelta_to_words(x)  # "1 minute 6 seconds"
         ```
-
     """
     if delta is not MISSING and seconds is not MISSING:
         msg = "Cannot mix `delta` and `seconds` keyword arguments."
@@ -98,12 +97,13 @@ def timedelta_to_words(
 
 
 def ordinal(n: int | str) -> str:
-    """Convert an integer into its ordinal representation, i.e. 0->'0th', '3'->'3rd'."""
-    # Remember that there is always funny lambda possibility
-    # ```py
-    # ordinal = lambda n: "%d%s" % (n, "tsnrhtdd"[(n // 10 % 10 != 1) * (n % 10 < 4) * n % 10::4])
-    # print([ordinal(n) for n in range(1,32)])
-    # ```
+    """Convert an integer into its ordinal representation, i.e. 0->'0th', '3'->'3rd'.
+
+    Dev Note
+    --------
+    Remember that there is always a funny lambda possibility
+    `ordinal = lambda n: "%d%s" % (n, "tsnrhtdd"[(n // 10 % 10 != 1) * (n % 10 < 4) * n % 10::4])`
+    """
     n = int(n)
     suffix = "th" if 11 <= n % 100 <= 13 else ["th", "st", "nd", "rd", "th"][min(n % 10, 4)]
     return str(n) + suffix

utils/fuzzy.py

@@ -1,13 +1,17 @@
-"""This Source Code Form is subject to the terms of the Mozilla Public
-License, v. 2.0. If a copy of the MPL was not distributed with this
-file, You can obtain one at http://mozilla.org/MPL/2.0/.
+"""Fuzzy wuzzy string matching utilities.
+
+Sources
+-------
+*  `fuzzy.py` file from RoboDanny (license MPL v2 from Rapptz/RoboDanny)
+    https://github.com/Rapptz/RoboDanny/blob/rewrite/cogs/utils/fuzzy.py
+* Helpful article:
+    http://chairnerd.seatgeek.com/fuzzywuzzy-fuzzy-string-matching-in-python/
 """
 
-# help with: http://chairnerd.seatgeek.com/fuzzywuzzy-fuzzy-string-matching-in-python/
-
 from __future__ import annotations
 
 import heapq
+import operator
 import re
 from difflib import SequenceMatcher
 from typing import TYPE_CHECKING, Literal, TypeVar, overload
@@ -20,12 +24,12 @@
 
 def ratio(a: str, b: str) -> int:
     m = SequenceMatcher(None, a, b)
-    return int(round(100 * m.ratio()))
+    return round(100 * m.ratio())
 
 
 def quick_ratio(a: str, b: str) -> int:
     m = SequenceMatcher(None, a, b)
-    return int(round(100 * m.quick_ratio()))
+    return round(100 * m.quick_ratio())
 
 
 def partial_ratio(a: str, b: str) -> int:
@@ -35,7 +39,7 @@ def partial_ratio(a: str, b: str) -> int:
     blocks = m.get_matching_blocks()
 
     scores: list[float] = []
-    for i, j, n in blocks:
+    for i, j, _ in blocks:
         start = max(j - i, 0)
         end = start + len(short)
         o = SequenceMatcher(None, short, long[start:end])
@@ -45,7 +49,7 @@ def partial_ratio(a: str, b: str) -> int:
             return 100
         scores.append(r)
 
-    return int(round(100 * max(scores)))
+    return round(100 * max(scores))
 
 
 _word_regex = re.compile(r"\W", re.IGNORECASE)
@@ -142,8 +146,8 @@ def extract(
 ) -> list[tuple[str, int]] | list[tuple[str, int, T]]:
     it = _extraction_generator(query, choices, scorer, score_cutoff)
     if limit is not None:
-        return heapq.nlargest(limit, it, key=lambda t: t[1])  # pyright: ignore[reportReturnType]
-    return sorted(it, key=lambda t: t[1], reverse=True)  # pyright: ignore[reportReturnType]
+        return heapq.nlargest(limit, it, key=operator.itemgetter(1))  # pyright: ignore[reportReturnType]
+    return sorted(it, key=operator.itemgetter(1), reverse=True)  # pyright: ignore[reportReturnType]
 
 
 @overload
@@ -172,10 +176,10 @@ def extract_one(
     *,
     scorer: Callable[[str, str], int] = quick_ratio,
     score_cutoff: int = 0,
-) -> tuple[str, int] | None | tuple[str, int, T]:
+) -> tuple[str, int] | tuple[str, int, T] | None:
     it = _extraction_generator(query, choices, scorer, score_cutoff)
     try:
-        return max(it, key=lambda t: t[1])
+        return max(it, key=operator.itemgetter(1))
     except:
         # iterator could return nothing
         return None

utils/helpers.py

@@ -7,7 +7,7 @@
 
 import logging
 from time import perf_counter
-from typing import TYPE_CHECKING, Any, Self
+from typing import TYPE_CHECKING, Self
 
 __all__ = ("measure_time",)
 
@@ -48,7 +48,12 @@ async def __aenter__(self) -> Self:
         return self
 
     def measure_time(self) -> None:
-        # PT for Performance Time, maybe there are better ideas for abbreviations.
+        """Record and debug-log measured PT (Performance Time).
+
+        Notes
+        -----
+        * maybe there are better ideas for abbreviations than PT.
+        """
         self.end = end = perf_counter() - self.start
         self.log.debug("%s PT: %.3f secs", self.name, end)