search

sopel-irc / sopel

:robot::speech_balloon: An easy-to-use and highly extensible IRC Bot framework. Formerly Willie.
https://sopel.chat
Other
951 stars 405 forks source link

bot: add deprecation notice to SopelWrapper #2521

Closed SnoopJ closed 8 months ago

SnoopJ commented 8 months ago

Description

This changeset adds a deprecation notice to SopelWrapper as the first part of #2460.

Checklist

dgw commented 8 months ago

This is… not the right approach. It's too early to warn on every creation of a SopelWrapper object, and doing it this way doesn't show anything in the docs either. This approach also removes SopelWrapper from the docs entirely.

I wrote up the detailed explanation below first, but then decided to summarize it as above in case you're short on spoons.

The Long Version You can't see it when testing this patch as written, because `master`'s version is `8.0.0.dev0` and prerelease versions are "less than" the same stable version—but this warning will make logs unusable. A _lot_ of `SopelWrapper`s get created during normal bot operation—at least one every time a rule matches and the bot dispatches a callback. Try changing `version` and `warning_in` to `7.1`, then start the bot. A normally peaceful startup sequence (one without `DEBUG` logs enabled, that is) turns into: ``` $ sopel Sopel 8.0.0.dev0 (running on Python 3.10.12) https://sopel.chat/ Loaded config file: /home/dgw/.sopel/default.cfg [2023-10-13 18:38:58,661] sopel.bot INFO - Loading plugins... [2023-10-13 18:38:58,674] sopel.bot INFO - Plugin loaded: calc [2023-10-13 18:38:58,734] sopel.bot INFO - Plugin loaded: search [2023-10-13 18:38:58,736] sopel.bot INFO - Plugin loaded: currency [2023-10-13 18:38:58,738] sopel.bot INFO - Plugin loaded: reload [2023-10-13 18:38:58,740] sopel.bot INFO - Plugin loaded: flipper [2023-10-13 18:38:58,907] sopel.bot INFO - Plugin loaded: twitter [2023-10-13 18:38:58,911] sopel.bot INFO - Plugin loaded: coretasks [2023-10-13 18:38:58,911] sopel.bot INFO - Registered 6 plugins, 0 failed, 33 disabled [2023-10-13 18:38:58,912] asyncio DEBUG - Using selector: EpollSelector [2023-10-13 18:38:59,047] sopel.irc INFO - Connected, initiating setup sequence [2023-10-13 18:39:00,983] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:00,983] sopel.bot INFO - Client capability negotiation list: away-notify, chghost, invite-notify, multi-prefix, sasl, userhost-in-names [2023-10-13 18:39:01,015] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,017] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,018] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,019] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,020] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,020] sopel.coretasks INFO - Capability negotiation ended successfuly. [2023-10-13 18:39:01,085] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,086] sopel.coretasks INFO - Enabled client capabilities: userhost-in-names, away-notify, sasl, chghost, multi-prefix [2023-10-13 18:39:01,086] sopel.coretasks INFO - No custom command to execute. [2023-10-13 18:39:01,087] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,088] sopel.coretasks INFO - Received RPL_MYINFO from server: SopelTest, irc.rizon.io, plexus-4(hybrid-8.1.20) [2023-10-13 18:39:01,088] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,090] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,091] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,118] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,119] sopel.coretasks INFO - Joining 1 channels (with JOIN throttle OFF); this may take a moment. [2023-10-13 18:39:01,120] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,153] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,154] sopel.coretasks INFO - Channel joined: #dgw [2023-10-13 18:39:01,158] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,158] sopel.coretasks INFO - Channel's topic updated: #dgw [2023-10-13 18:39:01,159] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,192] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,192] sopel.coretasks INFO - Updated mode for channel: #dgw [2023-10-13 18:39:01,193] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,195] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,196] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,197] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,198] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( [2023-10-13 18:39:01,199] sopel.bot WARNING - Deprecated since 7.1, will be removed in 9.0: SopelWrapper will soon be replaced with contextvars. See https://github.com/sopel-irc/sopel/issues/2460 File "/home/dgw/github/sopel-irc/sopel/sopel/bot.py", line 869, in dispatch wrapper = SopelWrapper( ``` Even better, the `@lifecycle.deprecated` decorator doesn't appear in documentation anywhere; Sphinx doesn't know about it. That's why we also have to add `.. deprecated::` blocks to the relevant docstrings when we mark stuff. (In short, docstring warns against _future_ use while the decorator warns about _existing_ use.) Finally, the above is moot anyway right now because decorating `class SopelWrapper` makes it disappear from the documentation. The decorator wraps the class in an undocumented function, which is skipped when Sphinx scans the module for members to document. ([`:undoc-members:`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-option-automodule-undoc-members) isn't included in the autodoc directives for `package/bot`.) The `deprecated` decorator would need to be used on `SopelWrapper.__init__()`, not the class itself. See how the old `sopel.tools.OutputRedirect` type is marked: https://github.com/sopel-irc/sopel/blob/ec9691b3bf3c00ade012b89335193181ace819e2/sopel/tools/__init__.py#L115-L127 (This example also demonstrates that `warning_in` needn't be specified if the desired value is equal to `version`.)