How to properly specify the return type of the Blender operator execute function

When using typing in code that calls the Blender Python API, we usually don’t encounter any problems. However, specifying the return type for the execute() function of the Blender operator is not entirely obvious.

.py file on Patreon

We know that the execute() function, the main executable function of any Blender operator, always returns a set consisting of a single string element.

It can be:

{"FINISHED"}
{"RUNNING_MODAL"}
{"CANCELLED"}
{"PASS_THROUGH"}
{"INTERFACE"}

{"FINISHED"}

{"RUNNING_MODAL"}

{"CANCELLED"}

{"PASS_THROUGH"}

{"INTERFACE"}

In general, we can specify the return type of the execute() function as set[‘str’]

def execute(self, context) -> set[str]:
    # some code

1 2	def execute(self, context) -> set[str]: # some code

This will work. However, we can improve our code typing a bit by using a reference to rna_enums.OperatorReturnItems if we use fake-bpy-module for autocompletion.

The description of the type of the operator returned by the execute() function is described in fake-bpy-module in the bpy\_typing\rna_enums module

type OperatorReturnItems = typing.Literal[
    "RUNNING_MODAL",  # Running Modal.Keep the operator running with blender.
    "CANCELLED",  # Cancelled.The operator exited without doing anything, so no undo entry should be pushed.
    "FINISHED",  # Finished.The operator exited after completing its action.
    "PASS_THROUGH",  # Pass Through.Do nothing and pass the event on.
    "INTERFACE",  # Interface.Handled but not executed (popup menus).
]

type OperatorReturnItems = typing.Literal[

"RUNNING_MODAL", # Running Modal.Keep the operator running with blender.

"CANCELLED", # Cancelled.The operator exited without doing anything, so no undo entry should be pushed.

"FINISHED", # Finished.The operator exited after completing its action.

"PASS_THROUGH", # Pass Through.Do nothing and pass the event on.

"INTERFACE", # Interface.Handled but not executed (popup menus).

]

Further information provided by Andrej (Andrej730)

Basically, bpy._typing is even more fake than fake-bpy-modules themselves and doesn’t exist at all in real Blender.

So we need to ensure it’s never used at runtime.

Import it only inside TYPE_CHECKING block.

Refer to it only using quotes, so it won’t be evaluated.

The reason why those shenanigans needed – it’s a compromise between blender realities and Python typing system.

fake-bpy-module is providing exact possible enum values for the stuff like possible return values, but it requires those static-time-only things

Example code with formatting of the return value of the execute() operator function:

import bpy
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import bpy._typing.rna_enums as rna_enums

class SimpleOperator(bpy.types.Operator):
    bl_idname = "wm.simple_operator"
    bl_label = "Simple Operator"

    def execute(self, context) -> set["rna_enums.OperatorReturnItems"]:
        print("Hello from the simplest operator!")
        return {"FINISHED"}

# Register the operator
bpy.utils.register_class(SimpleOperator)

import bpy

from typing import TYPE_CHECKING

if TYPE_CHECKING:

import bpy._typing.rna_enums as rna_enums

class SimpleOperator(bpy.types.Operator):

bl_idname = "wm.simple_operator"

bl_label = "Simple Operator"

def execute(self, context) -> set["rna_enums.OperatorReturnItems"]:

print("Hello from the simplest operator!")

return {"FINISHED"}

# Register the operator

bpy.utils.register_class(SimpleOperator)

Update (04.06.2025) by Andrej (Andrej730)

In the latest version of fake-bpy-module, the bpy._typing module has been replaced with еру bpy.stub_internal.

For autocomplete to work correctly, we now need to specify bpy.stub_internal instead of bpy._typing. In the example above, it would look like this:

Instead of:

import bpy._typing.rna_enums as rna_enums

1	import bpy._typing.rna_enums as rna_enums

We need to write:

import bpy.stub_internal.rna_enums as rna_enums

1	import bpy.stub_internal.rna_enums as rna_enums

All other code remains unchanged.