Backport doc/type-hint housekeeping from #2642 to 8.0.1

sopel/irc/__init__.py

@@ -39,7 +39,6 @@
 import time
 from typing import (
     Any,
-    Optional,
     TYPE_CHECKING,
 )
 
@@ -71,20 +70,23 @@ def __init__(self, settings: Config):
         self._name: str = settings.core.name
         self._isupport = ISupport()
         self._capabilities = Capabilities()
-        self._myinfo: Optional[MyInfo] = None
+        self._myinfo: MyInfo | None = None
         self._nick: identifiers.Identifier = self.make_identifier(
             settings.core.nick)
 
         self.backend: AbstractIRCBackend = UninitializedBackend(self)
         """IRC Connection Backend."""
         self._connection_registered = threading.Event()
-        """Flag stating whether the IRC Connection is registered yet."""
+        """Flag stating whether the IRC connection is registered yet."""
         self.settings = settings
-        """Bot settings."""
+        """The bot's settings.
+
+        .. versionadded:: 7.0
+        """
 
         # internal machinery
         self.sending = threading.RLock()
-        self.last_error_timestamp: Optional[datetime] = None
+        self.last_error_timestamp: datetime | None = None
         self.error_count = 0
         self.stack: dict[identifiers.Identifier, dict[str, Any]] = {}
         self.hasquit = False
@@ -136,7 +138,10 @@ def config(self) -> Config:
 
     @property
     def capabilities(self) -> Capabilities:
-        """Capabilities negotiated with the server."""
+        """Capabilities negotiated with the server.
+
+        .. versionadded:: 8.0
+        """
         return self._capabilities
 
     @property
@@ -174,7 +179,7 @@ def enabled_capabilities(self) -> set[str]:
         warning_in='8.1',
         removed_in='9.0',
     )
-    def server_capabilities(self) -> dict[str, Optional[str]]:
+    def server_capabilities(self) -> dict[str, str | None]:
         """A dict mapping supported IRCv3 capabilities to their options.
 
         For example, if the server specifies the capability ``sasl=EXTERNAL``,
@@ -201,7 +206,10 @@ def server_capabilities(self) -> dict[str, Optional[str]]:
 
     @property
     def isupport(self) -> ISupport:
-        """Features advertised by the server."""
+        """Features advertised by the server.
+
+        .. versionadded:: 7.0
+        """
         return self._isupport
 
     @property
@@ -216,7 +224,7 @@ def myinfo(self) -> MyInfo:
 
     @property
     @abc.abstractmethod
-    def hostmask(self) -> Optional[str]:
+    def hostmask(self) -> str | None:
         """The bot's hostmask."""
 
     # Utility
@@ -288,6 +296,8 @@ def safe_text_length(self, recipient: str) -> int:
         can be sent using ``PRIVMSG`` or ``NOTICE`` by subtracting the size
         required by the server to convey the bot's message.
 
+        .. versionadded:: 8.0
+
         .. seealso::
 
             This method is useful when sending a message using :meth:`say`,
@@ -332,7 +342,7 @@ def get_irc_backend(
         self,
         host: str,
         port: int,
-        source_address: Optional[tuple[str, int]],
+        source_address: tuple[str, int] | None,
     ) -> AbstractIRCBackend:
         """Set up the IRC backend based on the bot's settings.
 
@@ -512,13 +522,17 @@ def rebuild_nick(self) -> None:
         This method exists to update the casemapping rules for the
         :class:`~sopel.tools.identifiers.Identifier` that represents the bot's
         nick, e.g. after ISUPPORT info is received.
+
+        .. versionadded:: 8.0
         """
         self._nick = self.make_identifier(str(self._nick))
 
     def change_current_nick(self, new_nick: str) -> None:
         """Change the current nick without configuration modification.
 
         :param new_nick: new nick to be used by the bot
+
+        .. versionadded:: 7.1
         """
         if self.backend is None:
             raise RuntimeError(ERR_BACKEND_NOT_INITIALIZED)
@@ -564,7 +578,7 @@ def log_raw(self, line: str, prefix: str) -> None:
         logger = logging.getLogger('sopel.raw')
         logger.info("%s\t%r", prefix, line)
 
-    def write(self, args: Iterable[str], text: Optional[str] = None) -> None:
+    def write(self, args: Iterable[str], text: str | None = None) -> None:
         """Send a command to the server.
 
         :param args: an iterable of strings, which will be joined by spaces
@@ -611,7 +625,7 @@ def action(self, text: str, dest: str) -> None:
         """
         self.say('\001ACTION {}\001'.format(text), dest)
 
-    def join(self, channel: str, password: Optional[str] = None) -> None:
+    def join(self, channel: str, password: str | None = None) -> None:
         """Join a ``channel``.
 
         :param channel: the channel to join
@@ -631,7 +645,7 @@ def kick(
         self,
         nick: str,
         channel: str,
-        text: Optional[str] = None,
+        text: str | None = None,
     ) -> None:
         """Kick a ``nick`` from a ``channel``.
 
@@ -659,7 +673,7 @@ def notice(self, text: str, dest: str) -> None:
 
         self.backend.send_notice(dest, text)
 
-    def part(self, channel: str, msg: Optional[str] = None) -> None:
+    def part(self, channel: str, msg: str | None = None) -> None:
         """Leave a channel.
 
         :param channel: the channel to leave
@@ -670,7 +684,7 @@ def part(self, channel: str, msg: Optional[str] = None) -> None:
 
         self.backend.send_part(channel, reason=msg)
 
-    def quit(self, message: Optional[str] = None) -> None:
+    def quit(self, message: str | None = None) -> None:
         """Disconnect from IRC and close the bot.
 
         :param message: optional QUIT message to send (e.g. "Bye!")
@@ -689,7 +703,7 @@ def quit(self, message: Optional[str] = None) -> None:
         # problematic because whomever called quit might still want to do
         # something before the main thread quits.
 
-    def restart(self, message: Optional[str] = None) -> None:
+    def restart(self, message: str | None = None) -> None:
         """Disconnect from IRC and restart the bot.
 
         :param message: optional QUIT message to send (e.g. "Be right back!")