sopel: reduce and reorganize imports for critical modules

[Exirel]

Description

Sopel has critical modules (sopel.bot, sopel.coretasks, etc.) and I wasn't really happy with their dependencies, starting with a dependency to sopel.loader. This is where I started: I tried to remove dependencies to loader when possible or necessary, and I followed that by reducing imports when possible, with few reorganization here and there.

This is not much, and some may argue that this isn't necessary. However, I'd rather take preventive action now against circular imports or dependency hell now than facing these issues later.

Also I had to extract privilege constants from sopel.plugin into their own module, which lead me to write some proper documentation about privileges.

Checklist

• I have read CONTRIBUTING.md
• I can and do license this contribution under the EFLv2
• No issues are reported by make qa (runs make quality and make test)
• I have tested the functionality of the things this change touches

[dgw]

OK, I pulled together a full review. Only took (I think) three sessions—which is shamefully inefficient on my part, but there has been a lot going on IRL and it's been hard to find time to focus on this stuff. Should be more or less caught up on unreviewed PRs after this, though. 🥳

[Exirel]

Alright so, 2 topics to discuss that needs an action:

• I like sopel.plugin as a shortcut and I think it makes sense to present that to plugin authors and to document it as such (i.e. keep using sopel.plugin in the doc). Action: keep or switch to sopel.privileges in the doc?
• Plugin, handler, and name conflict: I wanted to prevent a conflict between from sopel import plugins, plugin and using the words plugins and plugin for variable name that would conflict with that (specifically in loops). Action: see below.

Name conflict resolutions

Before even talking about semantics, there is still a name conflict to deal with. There are 3 options:

• keep it that way (handler, handlers for variable, plugin, plugins for module)
• replace handler by plugin_handler, and handlers by plugin_handlers, no more conflict
• use aliases from sopel import plugin as plugin_, plugins as plugins_ which I honestly hate but it exists

Semantics

There is a question behind this, which is "what is a Plugin Handler?", and with it, "what does it do?". I argue that a Plugin Handler is not a plugin, it's a handler: it's a proxy between Sopel and its plugins. I argue that its actions are to load, setup, configure, and shutdown the plugin that it handles, and that "plugin" is its action's target. When I read handler.load() I read it as "handler, load your plugin", and not "handler, load yourself". So, for me, there is no confusion, however it looks like it is for others.

"Hold up!" said @dgw "why is PyModulePlugin named like that, and not PyModulePluginHandler?" AH AH. Great question my friend: it's because they are internal names, and their "handlerness" comes from their module: handler.PyModulePlugin already tells me that it's a Handler, not a "plugin". I tend not to do repetition too much, like sopel.plugins.handlers.SopelPyModulePluginHandlerClass (I know, cheeky me!).

However... nothing is that simple, because I know there are functions that call handlers "plugins", which create inconsistency in Sopel's codebase. That's not new, but that's not great either.

[Exirel]

@dgw before I rebase to fix conflict, would you consider my first question?

I like sopel.plugin as a shortcut and I think it makes sense to present that to plugin authors and to document it as such (i.e. keep using sopel.plugin in the doc). Action: keep or switch to sopel.privileges in the doc?

That would close a lot of comment, as I would either apply the changes or mark as resolved!

[dgw]

I like sopel.plugin as a shortcut and I think it makes sense to present that to plugin authors and to document it as such (i.e. keep using sopel.plugin in the doc). Action: keep or switch to sopel.privileges in the doc?

I like the shortcut, too, but it seems to me that we should always document things as they appear in the docs—and these constants don't appear in the documentation for plugin any more after this change.

---

Marked up a couple little things that I noticed while idly scrolling around, thinking about the answer above.

[Exirel]

I like the shortcut, too, but it seems to me that we should always document things as they appear in the docs—and these constants don't appear in the documentation for plugin any more after this change.

Alright, so I've to find a way to properly convey that information. Thanks!

[Exirel]

• changed "plugin" and "handler" to "plugin_handler" so it's less confusing for, hopefully, everyone
• plugins.jobs and tools.jobs will be handled in a separate PR (in an undefined future time)
• didn't rebase yet but there is a conflict to fix

ping @dgw for the follow up :)

[dgw]

Turns out I had more thoughts left than expected—and that was after writing (then deleting) a whole thing about the plugin_jobs/tools_jobs thing that will be addressed in a separate patch.

[dgw]

I say if any typo or other mistake has eluded both of us for this long, it deserves to make it into master and then get patched out in X months when we finally notice. 😁