Define a Python Handler
This section describes how to define a handler for Python-runtime functions. A handler is a Python function declared with the standard def keyword. Handlers can be simple or accept platform-provided objects and inputs. The runtime injects reserved arguments and provides helpers to map inputs and outputs.
Example
from digitalhub_runtime_python import handler
@handler(outputs=["my-sdk-output", "my-primitive-output"])
def func(project, run, context, event, input_1, parameter_1):
project.log_artifact(source="some-file.ext", name="my-artifact")
run.log_metric("my-metric", -14.6)
context.logger.info("log-some-string")
body = event.body
# Process the event body
df = input_1.as_df(sep=";")
df.head(70)
parameter_1.pop("some-key")
return df, 19.45
The function you define becomes the entrypoint when referenced as the handler in the run configuration.
There are 4 components to know when defining a Python function for the runtime:
For runtime-specific handler behavior, see the OpenInference handler definition or the Guardrail handler definition.
Reserved arguments
The runtime injects a small set of reserved arguments when it invokes your handler. Commonly injected values are:
project— the currentProjectobject.run— the activeRunobject.context— the Nuclio runtime context object (see Nuclio Python runtime docs) — only available in remote execution.event— the Nuclio event object — only available in remote execution.
Local execution: Nuclio context and event
When running locally, context and event are not provided automatically; if your handler expects them you must pass them explicitly through function.run().
Inputs and parameters
Inputs and parameters map function argument names to values provided at run time. They are passed to the run via the inputs and parameters arguments of function.run() and are stored in the Run spec.
- Inputs must reference platform entities (for example
Dataitem,Artifact, orModel) by their keys. - Parameters may be plain Python values (strings, numbers, dicts, lists, etc.).
- The argument names in the two maps must match the handler signature. Reserved names (
project,run,context, andevent) are supplied by the runtime when they appear in the signature.
Example
# Function signature: di is a Dataitem, param1 is a string
def func(di: Dataitem, param1: str):
# do something
...
# Create or obtain the dataitem
sdk_dataitem = sdk.new_dataitem(...)
# Run the function, mapping the argument name to the dataitem key
sdk_function.run(inputs={"di": sdk_dataitem.key},
parameters={"param1": "some value"})
Inputs vs parameters
Passing a parameter where an input is expected can produce an error stating the SDK cannot parse an entity_key. If you see that error, double-check which values you provided in inputs vs parameters.
Handler and outputs
Decorating a function with @handler (from digitalhub_runtime_python) allows you to name and collect outputs from the run. The decorator maps returned values to outputs and results on the resulting Run object.
Example
from digitalhub_runtime_python import handler
@handler(outputs=["data", "string"])
def func(di: Dataitem, param1: str):
# produce a Dataitem and a primitive
return pd.DataFrame, "some value"
run = sdk_function.run(inputs={"di": sdk_dataitem.key},
parameters={"param1": "some value"},
...)
# After the run completes
run.output("data") # returns a Dataitem object
run.result("string") # returns "some value"
The outputs list can contain names or descriptors. A descriptor explicitly
selects the entity kind to log and can pass kind-specific specification fields:
Example with descriptor
Returned values are classified as follows:
Dataitem,Artifact, orModelobjects are recorded as entity outputs.- Supported dataframe objects are logged as table dataitems.
- Other objects are serialized and logged as artifacts.
- Strings, numbers, booleans, and bytes are stored as primitive results.
Noneproduces no result. A tuple or list is treated as multiple positional results.
Entity outputs are available through run.output(name); primitive values are
available through run.result(name). If the decorator is omitted, returned
values receive default names such as output_0. If the number of declared
names differs from the number of returned values, missing names also use this
default pattern and extra names are ignored.
Init function
When executing remotely, the Nuclio wrapper calls an init function (if present) before invoking your handler. The runtime injects the Nuclio context into init at invocation time. Additional parameters may be supplied via init_parameters in function.run().