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() → str | None

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

async cleanup(chancy: Chancy) → int | None

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.

static get_dependencies() → list[str]

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.

abstractmethod static get_identifier() → str

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.

classmethod get_scope() → PluginScope

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

By default, plugins are scoped to the worker.

get_tables() → list[str]

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

By default, returns an empty list.

async migrate(chancy: Chancy, *, to_version: int | None = 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.

migrate_key() → str | None

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

migrate_package() → str | None

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

migrator(chancy: Chancy) → Migrator | None

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

async on_job_completed(*, worker: Worker, job: QueuedJob, exc: Exception | None = None, result: Any | None = None) → QueuedJob

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 – The worker that is running the job.

• job – The job that was completed.

• exc – The exception that was raised, if any.

• result – The result of the job, if any.

Returns:

The job to update in the database.

async on_job_starting(*, job: QueuedJob, worker: Worker) → QueuedJob

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.

async on_job_updated(*, worker: Worker, job: QueuedJob)

Called after a job has been run and saved.

Unlike on_job_completed, this method cannot modify the job, but the job is guaranteed to have been updated in the database by the time it is called.

Parameters:

• worker – The worker that is running the job.

• job – The job that was completed.

async on_worker_started(worker: Worker)

Called when the worker has started.

async run(worker: Worker, chancy: Chancy)

Runs the plugin.

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

async sleep(seconds: int) → bool

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

async static wait_for_leader(worker: Worker) → None

Wait until the worker running this plugin is the leader.

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.