From bad8860ea4e982d981953f64cf6146b234c68269 Mon Sep 17 00:00:00 2001 From: dgw Date: Sun, 10 Nov 2024 18:00:14 -0600 Subject: [PATCH 1/2] irc: annotate some newer AbstractBot methods with `versionadded` --- sopel/irc/__init__.py | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/sopel/irc/__init__.py b/sopel/irc/__init__.py index 7658c4ac7..f73a061eb 100644 --- a/sopel/irc/__init__.py +++ b/sopel/irc/__init__.py @@ -78,9 +78,12 @@ def __init__(self, settings: Config): 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() @@ -136,7 +139,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 @@ -201,7 +207,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 @@ -288,6 +297,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`, @@ -512,6 +523,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 +532,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) From 0b85704e921ccf0072f9418d40a8a71c81808963 Mon Sep 17 00:00:00 2001 From: dgw Date: Sun, 10 Nov 2024 18:03:49 -0600 Subject: [PATCH 2/2] irc: begin migrating `Optional[type]` to `type | None` Might as well migrate as we touch things. I just updated some docstring stuff in `irc/__init__.py`, and as long as I'm in the file let's get rid of the `typing.Optional` import, too. --- sopel/irc/__init__.py | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/sopel/irc/__init__.py b/sopel/irc/__init__.py index f73a061eb..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,7 +70,7 @@ 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) @@ -87,7 +86,7 @@ def __init__(self, settings: Config): # 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 @@ -180,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``, @@ -225,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 @@ -343,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. @@ -579,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 @@ -626,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 @@ -646,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``. @@ -674,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 @@ -685,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!") @@ -704,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!")