API/Dashboard

class chancy.plugins.api.Api(*, port: int = 8000, host: str = '127.0.0.1', debug: bool = False, allow_origins: list[str] | None = None)

Bases: Plugin

Provides an API and a dashboard for viewing the state of the Chancy cluster.

Running this plugin requires a few additional dependencies, you can install them with:

pip install chancy[web]

Then add the API plugin to your Chancy instance:

from chancy.plugins.api import Api

async with Chancy(..., plugins=[
    Api(),
]) as chancy:
    ...

Note

The API is still mostly undocumented, as its development is driven by the needs of the dashboard and may change significantly before it becomes stable.

Warning

The api interface is not secure and should not be exposed to the public internet. It is intended for use in a secure environment, such as a private network or a VPN where only trusted users have access.

Screenshots

CLI

Since it’s very common to only want the dashboard temporarily, you can start it with the CLI:

pip install chancy[cli,web]
chancy --app worker.chancy worker web

This will run the API and dashboard on port 8000 by default (you can change this with the --port and --host flags).

param port:

The port to listen on.

param host:

The host to listen on.

param debug:

Whether to run the server in debug mode.

param allow_origins:

A list of origins that are allowed to access the API.

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.

async run(worker: Worker, chancy: Chancy)

Start the web server.

class chancy.plugins.api.plugin.ApiPlugin

Bases: ABC

A plugin that provides additional API endpoints.

abstract name() → str

Get the name of the plugin.

routes() → list[RouteT]

Get a list of routes to add to the API.

class chancy.plugins.api.plugin.RouteT

Bases: TypedDict

A type hint for a route.

endpoint: Callable

methods: str | None

name: str | None

path: str

class chancy.plugins.api.core.CoreApiPlugin

Bases: ApiPlugin

Core API plugin which implements the endpoints for jobs, queues, workers, etc…

async static get_configuration(request, *, chancy, worker)

Get the configuration of the Chancy instance.

async static get_job(request, *, chancy, worker)

Get a single job by ID.

async static get_jobs(request, *, chancy, worker)

Get a list of all the jobs in the system.

Allows ID-based pagination and basic filtering.

async static get_queues(request, *, chancy, worker)

Get a list of all the queues.

async static get_workers(request, *, chancy, worker)

Get a list of all the workers.

name()

Get the name of the plugin.

routes()

Get a list of routes to add to the API.