Plain Python functions
Event handlers are Python functions accessible frommain.py
. They can be defined in that same file or imported. No decorators or special syntax are required.
_
(underscore).
External handlers
If yourmain.py
file has become cluttered with too many handler functions, you can organize them more effectively using the init_handlers
method. This method allows you to register handler functions from other modules. You can pass a single imported module or a list of modules to the init_handlers method to register multiple handlers simultaneously:
Each function inside a module is attempted to be registered as a handler. Make sure to use
_
prefix as described before to prevent exposing unwanted functions to front-end.init_handlers
within other modules, which allows for a sequence of registrations:
main.py
.
Mutating state
In most cases, event handlers will modify the application state. State can be accessed by including thestate
argument in the handler, which will provide you with a WriterState
object for the session that invoked the handler.
Elements of state can be reached using the square brackets syntax state["my_element"]
. Accessing keys that don’t exist will return None
.
handle_click
, his new counter value will be 5. Other sessions remain unaffected.
Mutation detection
Mutations are detected via assignment.
Make sure you perform an assignment on the state element you’re mutating, for the mutation to be detected.
=
, +=
, etc). This is because Python doesn’t offer a performant, reliable mechanism to detect mutations. See the two examples below.
Mutation event
You can subscribe to mutations on a specific key in the state. This is useful when you want to trigger a function every time a specific key is mutated.subscribe_mutation
is compatible with event handler signature. It will accept all the arguments
of the event handler (context
, payload
, …).Receiving a payload
Several events include additional data, known as the event’s payload. The event handler can receive that data using thepayload
argument.
For example, the wf-change
event in a Text Input component is triggered every time the value changes. As a payload, it includes the new value.
Globals
You can use globals and module attributes, just as you would in a standard Python script. This is very convenient for storing a single copy of resource-intensive object.Middlewares
Middlewares are functions that run before and after every event handler. They can be used to perform tasks such as logging, error handling, session management, or modifying the state.Standard output
The standard output of an app is captured and shown in the code editor’s log. You can use the standardprint
function to output results.
Execution flow
Event handlers run in a thread pool and are non-blocking. Each event is processed independently from each other. State mutations are sent to the front-end after the function has finished executing. The code inhandle_fast
will accumulate all mutations and send to the front-end after the function returns. For long-running tasks, Framework will periodically check state and provide partial updates to the user.
Asynchronous event handlers
Framework supports asynchronous event handlers, allowing for non-blocking I/O operations directly within event handlers. This is particularly useful for tasks such as fetching data from a database, making HTTP requests, or performing any other I/O bound operation that can benefit from asynchronous execution.Defining an asynchronous handler
An asynchronous event handler is defined with the standardasync
keyword syntax.
fetch_data()
is an asynchronous function that retrieves data, potentially from a remote source. The await
keyword is used to wait for the operation to complete without blocking the main thread, allowing other tasks to run concurrently.
Awaitable objects
You can use any awaitable object within an async event handler. This includes the output of any function defined withasync def
, or objects with an __await__
method. This makes it easy to integrate with asynchronous libraries and frameworks.
Context
Thecontext
argument provides additional information about the event.
The context provide the id of component that trigger the event in target
field.
event
field.
keyVariable
and valueVariable
.