chancy.plugin module

class chancy.plugin.Plugin

Bases: ABC

Base class for all plugins.

Plugins are used to extend the functionality of the worker. When a worker starts, it will call run() on all plugins that have a scope that matches the worker’s scope.

api_plugin()

If this plugin has an associated API component, returns the import string for the plugin.

Return type:

str | None

async cleanup(chancy)

Clean up any resources used by the plugin.

Should return either None, if no work was done, or the number of rows cleaned up.

Note

Normally, you don’t need to call this yourself. The Pruner plugin will call the cleanup method of all other registered plugins.

Parameters:

chancy (Chancy)

Return type:

int | None

static get_dependencies()

Get the identifiers of all plugins this plugin depends on, if any.

Plugins that depend on the presence of other plugins will refuse to start if those dependencies are not met.

Return type:

list[str]

abstractmethod static get_identifier()

Returns a unique identifier for this plugin.

This identifier should be unique across all active plugins. If a custom plugin provides compatible functionality to a built-in plugin, it may use the same identifier as the built-in plugin.

Return type:

str

classmethod get_scope()

Get the scope of this plugin. Scopes control when and where the plugin will be run.

By default, plugins are scoped to the worker.

Return type:

PluginScope

get_tables()

Get the names of all tables this plugin is responsible for.

By default, returns an empty list.

Return type:

list[str]

async migrate(chancy, *, to_version=None)

Migrate the database to the latest schema version.

If to_version is provided, the database will be migrated to that specific version, up or down as necessary.

Parameters:

• chancy (Chancy)

• to_version (int | None)

migrate_key()

Get the migration key for this plugin, if it has any.

Return type:

str | None

migrate_package()

Get the package name that contains the migration scripts for this plugin, if it has any.

Return type:

str | None

migrator(chancy)

Get a migrator for this plugin, if it has any migration scripts.

Parameters:

chancy (Chancy)

Return type:

Migrator | None

async on_job_completed(*, worker, job, exc=None, result=None)

Called after a job is completed (successfully or otherwise) and before the QueuedJob is updated in the database.

If an exception occurred during the job, exc will be the exception instance instead of None.

The passed job is immutable - to modify it, return a new QueuedJob object with the desired changes.

Parameters:

• worker (Worker) – The worker that is running the job.

• job (QueuedJob) – The job that was completed.

• exc (Exception | None) – The exception that was raised, if any.

• result (Any | None) – The result of the job, if any.

Returns:

The job to update in the database.

Return type:

QueuedJob

async on_job_starting(*, job, worker)

Called when a job has been retrieved from the queue and is about to start.

The passed job is immutable - to modify it, return a new QueuedJob with the desired changes.

Parameters:

• job (QueuedJob)

• worker (Worker)

Return type:

QueuedJob

async on_job_updated(*, worker, job)

Called for each accepted job update after its transaction commits.

This method cannot modify the saved update. Updates rejected because their claims no longer match or their jobs no longer exist do not invoke this hook. Accepted updates retain their original batch order, including repeated updates to the same job.

Parameters:

• worker (Worker) – The worker saving the update.

• job (QueuedJob) – The accepted update that was committed.

async on_jobs_updated_in_transaction(*, worker, jobs, cursor)

Called after a batch’s SQL updates, before its transaction commits.

Use the supplied cursor for database work that must commit atomically with the job updates. Raising an exception rolls back the batch. This hook may run again on retry; avoid external or in-memory side effects. Use on_job_updated() for work that requires committed updates.

Parameters:

• worker (Worker) – The worker saving the updates.

• jobs (Sequence[QueuedJob]) – Only updates whose claims matched and whose database rows were updated, in their original order, including repeated accepted updates to the same job. Rejected updates are omitted; this hook is not called if none were accepted.

• cursor (AsyncCursor[dict[str, Any]]) – The cursor for the current update transaction.

async on_worker_started(*, worker)

Called when a worker starts, before plugin tasks begin running.

Use this hook to register event handlers or prepare resources needed by other plugins. It is called for plugins with worker scope.

Parameters:

worker (Worker) – The worker being started.

async on_worker_stopped(*, worker)

Called during shutdown, after the worker saves its final job updates.

Use this hook to save remaining plugin data and release resources. Background tasks have already stopped. If shutdown fails and is retried, this hook may be called again, so repeated calls must be safe.

Parameters:

worker (Worker) – The worker being stopped.

async run(worker, chancy)

Runs the plugin.

This function can and should run indefinitely, as it will be cancelled when the worker is stopped.

Parameters:

• worker (Worker)

• chancy (Chancy)

async sleep(seconds)

Sleep for a specified number of seconds, but allow the plugin to be woken up early.

Parameters:

seconds (int)

Return type:

bool

async static wait_for_leader(worker)

Wait until the worker running this plugin is the leader.

Parameters:

worker (Worker)

Return type:

None

wake_up()

Wake up the plugin if it’s sleeping.

wakeup_signal

An asyncio.Event that can be used to wake up the plugin if it’s sleeping.

class chancy.plugin.PluginScope(*values)

Bases: Enum

WORKER = 'worker'

The plugin is a general worker plugin.