Top-level imports

Everything below is importable from fastapi_crons. The SQL backends are the exception — see SQL backends.

from fastapi_crons import (
    # Core
    Crons,
    CronJob,
    CronConfig,
    cron_job,
    get_cron_router,
    # Retry and timeout
    RetryConfig,
    retry_on_failure,
    execute_with_retry,
    JobTimeoutError,
    # State
    SQLiteStateBackend,
    RedisStateBackend,
    # Locking
    DistributedLockManager,
    LocalLockBackend,
    RedisLockBackend,
    # Hooks
    log_job_start,
    log_job_success,
    log_job_error,
    alert_on_failure,
    alert_on_long_duration,
    webhook_notification,
    metrics_collector,
    # OpenTelemetry
    OpenTelemetryHooks,
    is_otel_available,
)

Crons

The scheduler. Constructing it registers the FastAPI lifecycle handlers.

Crons(
    app=None,
    state_backend=None,
    lock_manager=None,
    config=None,
)

app

FastAPI | None

Your application. Can be omitted and supplied later with init_app().

state_backend

StateBackend | None

Defaults to SQLiteStateBackend using the configured path.

lock_manager

DistributedLockManager | None

Built from config when distributed locking is enabled.

config

CronConfig | None

Defaults to CronConfig().

Methods

Method	Returns	Description
`init_app(app)`	`None`	Attach to an app constructed later.
`cron(expr, **kwargs)`	decorator	Register a job. See Defining Jobs.
`get_jobs()`	`list[CronJob]`	Every registered job.
`get_job(name)`	`CronJob \| None`	One job by name.
`add_before_run_hook(hook, job_name=None)`	`Crons`	Register a before-run hook.
`add_after_run_hook(hook, job_name=None)`	`Crons`	Register an after-run hook.
`add_on_error_hook(hook, job_name=None)`	`Crons`	Register an error hook.
`start()`	coroutine	Start the loops. Called on startup.
`stop()`	coroutine	Stop the loops. Called on shutdown.

CronJob

A single registered job. Retrieve one with crons.get_job(name).

func

Callable

The function to run.

expr

str

The cron expression.

name

str

Unique job name.

CronConfig

Settings, read from the environment at construction. See Configuration for the full variable list and defaults.

Retry helpers

Name	Kind	Description
`RetryConfig`	dataclass	Fields: `max_retries`, `retry_delay`, `backoff_multiplier`, `max_delay`, `jitter`, `retry_on`, `on_retry`.
`retry_on_failure(...)`	decorator	Apply retries to any callable.
`execute_with_retry(...)`	coroutine	Run a callable under a retry policy.
`JobTimeoutError`	exception	Raised when a job exceeds its timeout.

SQL backends

These live in submodules because they need the optional SQLAlchemy dependency. Importing them without the extra raises an ImportError naming the extra to install.

Class	Import from
`SQLAlchemyStateBackend`	`fastapi_crons.state.sqlalchemy`
`SQLModelStateBackend`	`fastapi_crons.state.sqlalchemy` (alias of the above)
`SQLAlchemyLockBackend`	`fastapi_crons.locking.sqlalchemy`
`PostgreSQLAdvisoryLockBackend`	`fastapi_crons.locking.sqlalchemy`

get_cron_router()

Returns the management APIRouter. See HTTP Endpoints.

Method	Description
`update_next_run()`	Recompute `next_run`.
`add_before_run_hook(hook)`	Attach a hook to this job only.
`add_after_run_hook(hook)`	Attach a hook to this job only.
`add_on_error_hook(hook)`	Attach a hook to this job only.