From 7162a09909a93c4045ec9b6c315c6ffedc47efbe Mon Sep 17 00:00:00 2001 From: dgw Date: Wed, 13 Nov 2024 11:52:14 -0600 Subject: [PATCH] Backport doc/type-hint housekeeping from #2642 to 8.0.1 --- sopel/irc/__init__.py | 46 ++++++++++++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/sopel/irc/__init__.py b/sopel/irc/__init__.py index 7658c4ac7..181940db9 100644 --- a/sopel/irc/__init__.py +++ b/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,6 +522,8 @@ 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)) @@ -519,6 +531,8 @@ 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!")