mirror of
https://github.com/simonw/datasette.git
synced 2026-09-29 05:14:21 +02:00
c6bbcc3298
Fire plugin-visible events from Datasette.add_database() and .remove_database() so plugins can react to databases being attached or detached at runtime. Dispatch is best-effort fire-and-forget: events only fire when startup has completed and an event loop is running, and remove-database fires after close() so queued writes are flushed before listeners run. Motivating consumer is datasette-litestream, which needs to register newly attached databases with its replication daemon. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
25 lines
1.6 KiB
Markdown
25 lines
1.6 KiB
Markdown
(events)=
|
|
# Events
|
|
|
|
Datasette includes a mechanism for tracking events that occur while the software is running. This is primarily intended to be used by plugins, which can both trigger events and listen for events.
|
|
|
|
The core Datasette application triggers events when certain things happen. This page describes those events.
|
|
|
|
Note that these events will *not* fire for changes made to a SQLite database by a process other than Datasette itself.
|
|
|
|
Plugins can listen for events using the {ref}`plugin_hook_track_event` plugin hook, which will be called with instances of the following classes - or additional classes {ref}`registered by other plugins <plugin_hook_register_events>`.
|
|
|
|
## Delivery guarantees for database lifecycle events
|
|
|
|
The ``add-database`` and ``remove-database`` events have some specific delivery characteristics:
|
|
|
|
- Delivery is asynchronous. Listeners run shortly after the change, not before the triggering ``add_database()`` or ``remove_database()`` call returns.
|
|
- These events fire only for changes made at runtime - while an event loop is running, after Datasette's startup has completed. Databases attached while the instance is starting up do not produce events: plugins that need to see those should iterate over ``datasette.databases`` in their own {ref}`plugin_hook_startup` hook.
|
|
- Rapid successive changes involving the same database name may reach listeners interleaved. Listeners should tolerate events arriving out of order.
|
|
- ``event.actor`` is ``None`` for programmatic calls made by Datasette itself or by plugins.
|
|
|
|
```{eval-rst}
|
|
.. automodule:: datasette.events
|
|
:members:
|
|
:exclude-members: Event
|
|
```
|