Apply suggestions from code review (draft)

Co-authored-by: dgw <[email protected]>

Author: Exirel

sopel/irc/__init__.py

@@ -33,7 +33,7 @@
 from typing import Any, Callable, Dict, Iterable, List, Optional, Set, Tuple, TYPE_CHECKING
 
 from sopel import tools, trigger
-from sopel.tools import identifiers
+from sopel.tools.identifiers import Identifier
 from .abstract_backends import AbstractIRCBackend
 from .backends import AsyncioBackend
 from .isupport import ISupport
@@ -58,8 +58,7 @@ def __init__(self, settings: Config):
         self._name: str = settings.core.name
         self._isupport = ISupport()
         self._myinfo: Optional[MyInfo] = None
-        self._nick: identifiers.Identifier = self.make_identifier(
-            settings.core.nick)
+        self._nick: Identifier = self.make_identifier(settings.core.nick)
 
         self.backend: Optional[AbstractIRCBackend] = None
         """IRC Connection Backend."""
@@ -76,13 +75,13 @@ def __init__(self, settings: Config):
         self.sending = threading.RLock()
         self.last_error_timestamp: Optional[datetime] = None
         self.error_count = 0
-        self.stack: Dict[identifiers.Identifier, Dict[str, Any]] = {}
+        self.stack: Dict[Identifier, Dict[str, Any]] = {}
         self.hasquit = False
         self.wantsrestart = False
         self.last_raw_line = ''  # last raw line received
 
     @property
-    def nick(self) -> identifiers.Identifier:
+    def nick(self) -> Identifier:
         """Sopel's current nick.
 
         Changing this while Sopel is running is unsupported.

sopel/irc/abstract_backends.py

@@ -57,8 +57,9 @@ def run_forever(self) -> None:
         and it must call ``bot.on_connect`` once connected, or ``bot.on_close``
         if it fails to connect.
 
-        Then it must run forever, listening to the server, and allowing the
-        bot to use :meth:`~.send_command` in a thread-safe way.
+        Upon successful connection, it must run forever, listening to the
+        server and allowing the bot to use :meth:`~.send_command` in a
+        thread-safe way.
         """
 
     def decode_line(self, line: bytes) -> str:

sopel/irc/backends.py

@@ -37,7 +37,7 @@ class AsyncioBackend(AbstractIRCBackend):
     """IRC Backend implementation using :mod:`asyncio`.
 
     :param bot: an instance of a bot that uses the backend
-    :param host: hostname to connect to
+    :param host: hostname/IP to connect to
     :param port: port to connect to
     :param source_address: optional source address as a tuple of
                            ``(host, port)``
@@ -128,7 +128,7 @@ def _ping_callback(self) -> None:
         self.send_ping(self._host)
 
     def _timeout_callback(self) -> None:
-        # cancel every other tasks
+        # cancel other tasks
         for task in [self._ping_task, self._read_task]:
             if task is not None:
                 task.cancel()
@@ -195,12 +195,12 @@ async def send(self, data: bytes) -> None:
     async def read_forever(self) -> None:
         """Main reading loop of the backend.
 
-        This listens to the reader for IRC line, decodes the line, and pass
-        that to
+        This listens to the reader for an incoming IRC line, decodes the data,
+        and passes it to
         :meth:`bot.on_message(data) <sopel.irc.AbstractBot.on_message>`, until
         the reader reaches the EOF (i.e. connection closed).
 
-        It manages timeout by scheduling two tasks:
+        It manages connection timeouts by scheduling two tasks:
 
         * a PING task, that will send a PING to the server as defined by
           the ping interval (from the configuration)
@@ -239,18 +239,18 @@ async def read_forever(self) -> None:
 
             # connection is active: reset timeout tasks
             self._reset_timeout_tasks()
-            # check content
 
+            # check content
             if not line:
                 LOGGER.debug('No data received.')
                 continue
 
-            # use bot's callback
+            # use bot's callbacks
             data = self.decode_line(line)
             self.bot.log_raw(data, '<<')
             self.bot.on_message(data)
 
-        # cancel timeout tasks
+        # cancel timeout tasks when reading loop ends
         self._cancel_timeout_tasks()
 
     # run & connection
@@ -286,7 +286,7 @@ def get_connection_kwargs(self) -> Dict:
     async def _run_forever(self) -> None:
         self._loop = asyncio.get_running_loop()
 
-        # register signals handlers
+        # register signal handlers
         for quit_signal in QUIT_SIGNALS:
             self._loop.add_signal_handler(quit_signal, self._signal_quit)
         for restart_signal in RESTART_SIGNALS: