Skip to content

tools, plugins: remove tools.jobs and move Job to plugins.jobs #2725

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Exirel wants to merge 3 commits into
base: master
Choose a base branch
from
Open

tools, plugins: remove tools.jobs and move Job to plugins.jobs #2725

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e29812e
bot, plugins, tools: remove sopel.tools.jobs
Exirel Oct 2, 2025
eac025c
docs, plugins, tests: improve doc and tests for plugin jobs
Exirel Feb 21, 2026
1de1381
plugins, tests: improve jobs related docstrings
Exirel Mar 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,7 @@
('py:class', 'callable'),
('py:class', 'depends on subclass'),
('py:class', 'mixed'),
('py:class', 'sopel.tools.jobs.Job'),
('py:class', 'sopel.tools.jobs.JobScheduler'),
('py:class', 'mappingproxy'),
('py:exc', 'plugins.exceptions.PluginNotRegistered'),
]

Expand Down
1 change: 0 additions & 1 deletion docs/source/package/tools.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ these utility features have been collected into submodules for convenience:
tools/calculation
tools/events
tools/identifiers
tools/jobs
tools/memories
tools/target
tools/time
Expand Down
6 changes: 0 additions & 6 deletions docs/source/package/tools/jobs.rst
View file
Open in desktop

This file was deleted.

15 changes: 5 additions & 10 deletions sopel/bot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,14 +34,13 @@
jobs as plugin_jobs,
rules as plugin_rules,
)
from sopel.tools import jobs as tools_jobs
from sopel.trigger import Trigger


if TYPE_CHECKING:
from collections.abc import Iterable, Mapping

from sopel.plugins.callables import PluginCallable
from sopel.plugins.callables import PluginCallable, PluginJob
Comment thread Dismissed
Comment thread Dismissed
from sopel.plugins.handlers import (
AbstractPluginHandler,
PluginMetaDescription,
Expand Down Expand Up @@ -442,7 +441,7 @@
self,
plugin: AbstractPluginHandler,
callables: Sequence[PluginCallable],
jobs: Sequence[Callable],
jobs: Sequence[PluginJob],
shutdowns: Sequence[Callable],
urls: Sequence[PluginCallable],
) -> None:
Expand Down Expand Up @@ -619,15 +618,11 @@
self._rules_manager.register(
plugin_rules.Rule.from_callable(self.settings, callbl))

def register_jobs(self, jobs: Iterable) -> None:
def register_jobs(self, jobs: Iterable[PluginJob]) -> None:
for func in jobs:
job = tools_jobs.Job.from_callable(self.settings, func)
job = plugin_jobs.Job.from_callable(self.settings, func)
self._scheduler.register(job)

def unregister_jobs(self, jobs: Iterable) -> None:
for job in jobs:
self._scheduler.remove_callable_job(job)
Comment on lines -627 to -629
Copy link
Copy Markdown
Member

@dgw dgw Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aaaa, removing something with no deprecation warning in a minor version 🙀

But it's not advertised in the API docs (no docstring), so… it's probably fine? 😅


def register_shutdowns(self, shutdowns: Iterable) -> None:
# Append plugin's shutdown function to the bot's list of functions to
# call on shutdown
Expand Down Expand Up @@ -1104,7 +1099,7 @@
def on_job_error(
self,
scheduler: plugin_jobs.Scheduler,
job: tools_jobs.Job,
job: plugin_jobs.Job,
exc: BaseException,
) -> None:
"""Called when a job from the Job Scheduler fails.
Expand Down
17 changes: 8 additions & 9 deletions sopel/coretasks.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
from sopel import config, plugin
from sopel.irc import isupport, utils
from sopel.plugins import callables
from sopel.tools import events, jobs, SopelMemory, target
from sopel.tools import events, SopelMemory, target


if TYPE_CHECKING:
Expand Down Expand Up @@ -177,15 +177,14 @@ def setup(bot: Sopel) -> None:
# Manage JOIN flood protection
if bot.settings.core.throttle_join:
wait_interval = max(bot.settings.core.throttle_wait, 1)
job = jobs.Job(
[wait_interval],
plugin='coretasks',
label='throttle_join',
handler=_join_event_processing,
threaded=True,
doc=None,

handler = plugin.interval(wait_interval)(
plugin.label('throttle_join')(
_join_event_processing
)
)
bot.scheduler.register(job)
handler.plugin_name = 'coretasks'
bot.register_jobs([handler])
Comment on lines +181 to +187
Copy link
Copy Markdown
Member

@dgw dgw Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I'm honest, this feels a bit too "voodoo" for long-term use, even though conceptually it's just "using decorators without @ syntactic sugar". Can we make a better interface?

Copy link
Copy Markdown
Contributor Author

@Exirel Exirel Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm... on one hand, yes it's just how you can use decorators. And the other hand, the PluginJob new class is not public yet, and I'm not sure it's ready to be, even tho it's probably a very simple interface to use.

So... it's kinda hard to say what's best here.

I also want to point out that, until the PluginJob/PluginCallable rework, you had to use clean_callable to make sure it was possible to register the job: there is now one less step to do so!



def shutdown(bot):
Expand Down
Loading
Loading