fiftyone.operators#

Module contents#

FiftyOne operators.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

`Operator`([_builtin])	A FiftyOne operator.
`OperatorConfig`(name[, label, description, ...])	A configuration for an operator.
`OperatorRegistry`([enabled])	Operator registry.
`EvaluationMetricConfig`(name[, label, ...])	Configuration class for evaluation metrics.
`EvaluationMetric`([_builtin])	Base class for evaluation metric operators.
`ExecutionContext`([request_params, executor, ...])	Represents the execution context of an operator.
`ExecutionOptions`([...])	Represents the execution options of an operation.
`ProgressHandler`(ctx[, logger, level])	A logging handler that reports all logging messages issued while the handler's context manager is active to the provided execution context's `set_progress()` method.
`Panel`([_builtin])	A panel.
`PanelConfig`(name, label[, help_markdown, ...])	Configuration for a panel.
`ExecutionStore`(store_name, store_service[, ...])	Execution store.
`Categories`(value[, names, module, qualname, ...])

Functions:

`get_operator`(operator_uri[, enabled])	Gets the operator with the given URI.
`list_operators`([enabled, builtin, type])	Returns all available operators.
`operator_exists`(operator_uri[, enabled])	Checks if the given operator exists.
`execute_operator`(operator_uri[, ctx])	Executes the operator with the given name.
`is_new`(release_date[, days])	Determines if a feature is considered "new" based on its release date.
`execution_cache`([_func, residency, ...])	Decorator for caching function results in an `ExecutionStore`.

class fiftyone.operators.Operator(_builtin=False)#

Bases: object

A FiftyOne operator.

Operators represent an operation and the details of how to execute it.

FiftyOne operators contain enough information for a user interface to render a form or button allowing a user to execute the operation.

Attributes:

`name`
`uri`	The unique identifier of the operator: `plugin_name/operator_name`.
`builtin`	Whether the operator is builtin.
`config`	The `OperatorConfig` for the operator.

Methods:

`resolve_delegation`(ctx)	Returns the resolved forced delegation flag.
`resolve_execution_options`(ctx)	Returns the resolved execution options.
`execute`(ctx)	Executes the operator.
`resolve_type`(ctx, type)	Returns the resolved input or output property.
`resolve_input`(ctx)	Returns the resolved input property.
`resolve_output`(ctx)	Returns the resolved output property.
`resolve_placement`(ctx)	Returns the resolved placement of the operator.
`resolve_run_name`(ctx)	Returns the resolved run name of the operator.
`method_to_uri`(method_name)	Converts a method name to a URI.
`to_json`()	Returns a JSON representation of the operator.
`add_secrets`(secrets)	Adds secrets to the operator.

property name#

property uri#: The unique identifier of the operator: plugin_name/operator_name.

property builtin#: Whether the operator is builtin.

property config#: The OperatorConfig for the operator.

resolve_delegation(ctx)#

Returns the resolved forced delegation flag.

Subclasses can implement this method to decide if delegated execution should be forced for the given operation.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: whether the operation should be delegated (True), run immediately (False), or None to defer to resolve_execution_options() to specify the available options

resolve_execution_options(ctx)#

Returns the resolved execution options.

Subclasses can implement this method to define the execution options available for the operation.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.executor.ExecutionOptions instance

execute(ctx)#

Executes the operator.

Subclasses must implement this method.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: JSON serializable data, or None

resolve_type(ctx, type)#

Returns the resolved input or output property.

Parameters:

ctx – the fiftyone.operators.executor.ExecutionContext
type – the type of property to resolve, either "inputs" or "outputs"

Returns:

a fiftyone.operators.types.Property, or None

resolve_input(ctx)#

Returns the resolved input property.

Subclasses can implement this method to define the inputs to the operator. This method should never be called directly. Instead use resolve_type().

By default, this method is called once when the operator is created. If the operator is dynamic, this method is called each time the input changes.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.types.Property, or None

resolve_output(ctx)#

Returns the resolved output property.

Subclasses can implement this method to define the outputs of the operator.

By default, this method is called once when the operator is created. If the operator is dynamic, this method is called after the operator is executed.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.types.Property, or None

resolve_placement(ctx)#

Returns the resolved placement of the operator.

Subclasses can implement this method to define the placement of the operator.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.types.Placement, or None

resolve_run_name(ctx)#

Returns the resolved run name of the operator.

Subclasses can implement this method to define the run name of the operator.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a string, or None

method_to_uri(method_name)#

Converts a method name to a URI.

Parameters:: method_name – the method name
Returns:: a URI

to_json()#

Returns a JSON representation of the operator.

Returns:: a JSON dict

add_secrets(secrets)#

Adds secrets to the operator.

Parameters:: secrets – a list of secrets

class fiftyone.operators.OperatorConfig(name, label=None, description=None, dynamic=False, execute_as_generator=False, unlisted=False, on_startup=False, on_dataset_open=False, disable_schema_validation=False, delegation_target=None, icon=None, light_icon=None, dark_icon=None, allow_immediate_execution=True, allow_delegated_execution=False, default_choice_to_delegated=False, resolve_execution_options_on_change=None, allow_distributed_execution=False, **kwargs)#

Bases: object

A configuration for an operator.

Parameters:

name – the name of the operator
label (name) – a label for the operator
description (None) – a description of the operator
dynamic (False) – whether the operator inputs and outputs should be resolved when the input/output changes
execute_as_generator (False) – whether the operator should be executed as a generator
unlisted (False) – whether the operator should be hidden from the Operator Browser
on_startup (False) – whether the operator should be executed on startup
on_dataset_open (False) – whether the operator should be executed on opening a dataset
disable_schema_validation (False) – whether the operator built-in schema validation should be disabled
icon (None) – icon to show for the operator in the Operator Browser
light_icon (None) – icon to show for the operator in the Operator Browser when the App is in the light mode
dark_icon (None) – icon to show for the operator in the Operator Browser when the App is in the dark mode
allow_immediate_execution (True) – whether the operator should allow immediate execution
allow_delegated_execution (False) – whether the operator should allow delegated execution
default_choice_to_delegated (False) – whether to default to delegated execution, if allowed
resolve_execution_options_on_change (None) – whether to resolve execution options dynamically when inputs change. By default, this behavior will match the dynamic setting
allow_distributed_execution (False) – whether the operator supports distributing delegated execution across parallel workers.

Methods:

to_json()

to_json()#

class fiftyone.operators.OperatorRegistry(enabled=True)#

Bases: object

Operator registry.

enabled (True): whether to include only enabled operators (True) or: only disabled operators (False) or all operators (“all”)

Methods:

`list_operators`([builtin, type])	Lists the available FiftyOne operators.
`list_errors`()	Lists the errors that occurred during operator loading.
`operator_exists`(operator_uri)	Checks if the operator exists.
`can_execute`(operator_uri)	Whether the operator can be executed.
`get_operator`(operator_uri)	Retrieves an operator by its URI.

list_operators(builtin=None, type=None)#

Lists the available FiftyOne operators.

Parameters:

builtin (None) – whether to include only builtin operators (True) or only non-builtin operators (False)
type (None) – whether to include only "panel" or "operator" type operators, or a specific fiftyone.operators.Operator subclass to restrict to

Returns:

a list of fiftyone.operators.Operator instances

list_errors()#

Lists the errors that occurred during operator loading.

Returns:: a list of errors

operator_exists(operator_uri)#

Checks if the operator exists.

Parameters:: operator_uri – the URI of the operator
Returns:: True/False

can_execute(operator_uri)#

Whether the operator can be executed.

Parameters:: operator_uri – the URI of the operator
Returns:: True/False

get_operator(operator_uri)#

Retrieves an operator by its URI.

Parameters:: operator_uri – the URI of an operator
Returns:: an fiftyone.operators.Operator, or None

fiftyone.operators.get_operator(operator_uri, enabled=True)#

Gets the operator with the given URI.

Parameters:

operator_uri – the operator URI
enabled (True) – whether to include only enabled operators (True) or only disabled operators (False) or all operators (“all”)

Returns:

an fiftyone.operators.Operator

Raises:

ValueError – if the operator is not found

fiftyone.operators.list_operators(enabled=True, builtin='all', type=None)#

Returns all available operators.

Parameters:

enabled (True) – whether to include only enabled operators (True) or only disabled operators (False) or all operators (“all”)
builtin ("all") – whether to include only builtin operators (True) or only non-builtin operators (False) or all operators (“all”)
type (None) – whether to include only "panel" or "operator" type operators, or a specific fiftyone.operators.Operator subclass to restrict to

Returns:

a list of fiftyone.operators.Operator instances

fiftyone.operators.operator_exists(operator_uri, enabled=True)#

Checks if the given operator exists.

Parameters:

operator_uri – the operator URI
enabled (True) – whether to include only enabled operators (True) or only disabled operators (False) or all operators (“all”)

Returns:

True/False

class fiftyone.operators.EvaluationMetricConfig(name, label=None, description=None, eval_types=None, aggregate_key=None, lower_is_better=True, **kwargs)#

Bases: OperatorConfig

Configuration class for evaluation metrics.

Parameters:

name – the name of the evaluation metric
label (name) – a label for the evaluation metric
description (None) – a description of the evaluation metric
eval_types (None) – an optional list of evaluation method types that this metric supports
aggregate_key (None) – an optional key under which to store the metric’s aggregate value. This is used, for example, by metrics(). By default, the metric’s name is used as its key
lower_is_better (True) – whether lower values of the metric are better
**kwargs – other kwargs for fiftyone.operators.OperatorConfig

Methods:

to_json()

to_json()#

class fiftyone.operators.EvaluationMetric(_builtin=False)#

Bases: Operator

Base class for evaluation metric operators.

Methods:

`resolve_input`(ctx)	Defines any necessary properties to collect this evaluation metric's parameters from a user during prompting.
`parse_parameters`(ctx, params)	Performs any necessary execution-time formatting to this evaluation metric's parameters.
`compute`(samples, results, **kwargs)	Computes the evaluation metric for the given collection.
`get_fields`(samples, config, eval_key)	Lists the fields that were populated by the evaluation metric with the given key, if any.
`rename`(samples, config, eval_key, new_eval_key)	Performs any necessary operations required to rename this evaluation metric's key.
`cleanup`(samples, config, eval_key)	Cleans up the results of the evaluation metric with the given key from the collection.
`add_secrets`(secrets)	Adds secrets to the operator.
`execute`(ctx)	Executes the operator.
`method_to_uri`(method_name)	Converts a method name to a URI.
`resolve_delegation`(ctx)	Returns the resolved forced delegation flag.
`resolve_execution_options`(ctx)	Returns the resolved execution options.
`resolve_output`(ctx)	Returns the resolved output property.
`resolve_placement`(ctx)	Returns the resolved placement of the operator.
`resolve_run_name`(ctx)	Returns the resolved run name of the operator.
`resolve_type`(ctx, type)	Returns the resolved input or output property.
`to_json`()	Returns a JSON representation of the operator.

Attributes:

`builtin`	Whether the operator is builtin.
`config`	The `OperatorConfig` for the operator.
`name`
`uri`	The unique identifier of the operator: `plugin_name/operator_name`.

resolve_input(ctx)#

Defines any necessary properties to collect this evaluation metric’s parameters from a user during prompting.

Parameters:: ctx – an fiftyone.operators.ExecutionContext
Returns:: a fiftyone.operators.types.Property, or None

parse_parameters(ctx, params)#

Performs any necessary execution-time formatting to this evaluation metric’s parameters.

Parameters:

ctx – an fiftyone.operators.ExecutionContext
params – a params dict

compute(samples, results, **kwargs)#

Computes the evaluation metric for the given collection.

Parameters:

samples – a fiftyone.core.collections.SampleCollection
results – an fiftyone.core.evaluation.EvaluationResults
**kwargs – arbitrary metric-specific parameters

Returns:

an optional aggregate metric value to store on the results

get_fields(samples, config, eval_key)#

Lists the fields that were populated by the evaluation metric with the given key, if any.

Parameters:

samples – a fiftyone.core.collections.SampleCollection
config – an fiftyone.core.evaluation.EvaluationMethodConfig
eval_key – an evaluation key

Returns:

a list of fields

rename(samples, config, eval_key, new_eval_key)#

Performs any necessary operations required to rename this evaluation metric’s key.

Parameters:

samples – a fiftyone.core.collections.SampleCollection
config – an fiftyone.core.evaluation.EvaluationMethodConfig
eval_key – an evaluation key
new_eval_key – a new evaluation key

cleanup(samples, config, eval_key)#

Cleans up the results of the evaluation metric with the given key from the collection.

Parameters:

samples – a fiftyone.core.collections.SampleCollection
config – an fiftyone.core.evaluation.EvaluationMethodConfig
eval_key – an evaluation key

add_secrets(secrets)#

Adds secrets to the operator.

Parameters:: secrets – a list of secrets

property builtin#: Whether the operator is builtin.

property config#: The OperatorConfig for the operator.

execute(ctx)#

Executes the operator.

Subclasses must implement this method.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: JSON serializable data, or None

method_to_uri(method_name)#

Converts a method name to a URI.

Parameters:: method_name – the method name
Returns:: a URI

property name#

resolve_delegation(ctx)#

Returns the resolved forced delegation flag.

Subclasses can implement this method to decide if delegated execution should be forced for the given operation.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: whether the operation should be delegated (True), run immediately (False), or None to defer to resolve_execution_options() to specify the available options

resolve_execution_options(ctx)#

Returns the resolved execution options.

Subclasses can implement this method to define the execution options available for the operation.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.executor.ExecutionOptions instance

resolve_output(ctx)#

Returns the resolved output property.

Subclasses can implement this method to define the outputs of the operator.

By default, this method is called once when the operator is created. If the operator is dynamic, this method is called after the operator is executed.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.types.Property, or None

resolve_placement(ctx)#

Returns the resolved placement of the operator.

Subclasses can implement this method to define the placement of the operator.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.types.Placement, or None

resolve_run_name(ctx)#

Returns the resolved run name of the operator.

Subclasses can implement this method to define the run name of the operator.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a string, or None

resolve_type(ctx, type)#

Returns the resolved input or output property.

Parameters:

ctx – the fiftyone.operators.executor.ExecutionContext
type – the type of property to resolve, either "inputs" or "outputs"

Returns:

a fiftyone.operators.types.Property, or None

to_json()#

Returns a JSON representation of the operator.

Returns:: a JSON dict

property uri#: The unique identifier of the operator: plugin_name/operator_name.

fiftyone.operators.execute_operator(operator_uri, ctx=None, **kwargs)#

Executes the operator with the given name.

Parameters:

operator_uri – the URI of the operator
ctx (None) –
a dictionary of parameters defining the execution context. The supported keys are:
- dataset: a fiftyone.core.dataset.Dataset or the name of a dataset to process. This is required unless a view is provided
- view (None): an optional fiftyone.core.view.DatasetView to process
- selected ([]): an optional list of selected sample IDs
- selected_labels ([]): an optional list of selected labels in the format returned by fiftyone.core.session.Session.selected_labels
- current_sample (None): an optional ID of the current sample being processed
- extended_selection (None): an optional extended selection of the view.
- params: a dictionary of parameters for the operator. Consult the operator’s documentation for details
- request_delegation (False): whether to request delegated execution, if supported by the operator
- delegation_target (None): an optional orchestrator on which to schedule the operation, if it is delegated
- active_fields ([]): a list of active field names
- workspace_name (None): an optional name of the workspace to use for the operation
- spaces (None): an optional dictionary defining spaces to use for the operation
- group_slice (None): an optional group slice to use for the operation’s view. This is only applicable to group datasets
- query_performance (None): whether to enable query performance
- num_distributed_tasks (None): the number of tasks to split
the operation into, if it is delegated.
**kwargs – you can optionally provide any of the supported ctx keys as keyword arguments rather than including them in ctx

Returns:

an ExecutionResult, or an asyncio.Task if you run this method in a notebook context

Raises:

ExecutionError – if an error occurred while immediately executing an operation or scheduling a delegated operation

class fiftyone.operators.ExecutionContext(request_params=None, executor=None, set_progress=None, delegated_operation_id=None, operator_uri=None, required_secrets=None)#

Bases: object

Represents the execution context of an operator.

Operators can use the execution context to access the view, dataset, and selected samples, as well as to trigger other operators.

Parameters:

request_params (None) – a optional dictionary of request parameters
executor (None) – an optional Executor instance
set_progress (None) – an optional function to set the progress of the current operation
delegated_operation_id (None) – an optional ID of the delegated operation
operator_uri (None) – the unique id of the operator
required_secrets (None) – the list of required secrets from the plugin’s definition

Attributes:

`dataset`	The `fiftyone.core.dataset.Dataset` being operated on.
`dataset_name`	The name of the `fiftyone.core.dataset.Dataset` being operated on.
`dataset_id`	The ID of the `fiftyone.core.dataset.Dataset` being operated on.
`view`	The `fiftyone.core.view.DatasetView` being operated on.
`has_custom_view`	Whether the operator has a custom view.
`spaces`	The current spaces layout in the FiftyOne App.
`selected`	The list of selected sample IDs (if any).
`selected_labels`	A list of selected labels (if any).
`extended_selection`	The extended selection of the view (if any).
`current_sample`	The ID of the current sample being processed (if any).
`active_fields`	The list of currently active fields in the FiftyOne App sidebar.
`user_id`	The ID of the user executing the operation, if known.
`user_request_token`	The request token authenticating the user executing the operation, if known.
`panel_id`	The ID of the panel that invoked the operator, if any.
`panel_state`	The current panel state.
`panel`	A `fiftyone.operators.panel.PanelRef` instance that you can use to read and write the state and data of the current panel.
`delegated`	Whether the operation was delegated.
`requesting_delegated_execution`	Whether delegated execution was requested for the operation.
`delegation_target`	The orchestrator to which the operation was delegated (if any).
`results`	A `dict` of results for the current operation.
`secrets`	A read-only mapping of keys to their resolved values.
`ops`	A `fiftyone.operators.operations.Operations` instance that you can use to trigger builtin operations on the current context.
`group_slice`	The current group slice of the view (if any).
`num_distributed_tasks`	The number of tasks this job should be split into.
`query_performance`	Whether query performance is enabled.
`prompt_id`	An identifier for the prompt, unique to each instance of a user opening a prompt in the FiftyOne App.
`operator_uri`	The URI of the target operator.

Methods:

`target_view`([param_name])	The target `fiftyone.core.view.DatasetView` for the operator being executed.
`prompt`(operator_uri[, params, on_success, ...])	Prompts the user to execute the operator with the given URI.
`secret`(key)	Retrieves the secret with the given key.
`resolve_secret_values`(keys, **kwargs)	Resolves the values of the given secrets keys.
`trigger`(operator_name[, params])	Triggers an invocation of the operator with the given name.
`log`(message)	Logs a message to the browser console.
`set_progress`([progress, label])	Sets the progress of the current operation.
`store`(store_name)	Retrieves the execution store with the given name.
`serialize`()	Serializes the execution context.
`to_dict`()	Returns the properties of the execution context as a dict.

property dataset#: The fiftyone.core.dataset.Dataset being operated on.

property dataset_name#: The name of the fiftyone.core.dataset.Dataset being operated on.

property dataset_id#: The ID of the fiftyone.core.dataset.Dataset being operated on.

property view#: The fiftyone.core.view.DatasetView being operated on.

target_view(param_name='view_target')#

The target fiftyone.core.view.DatasetView for the operator being executed.

Parameters:: param_name ("view_target") – the name of the enum parameter defining the target view choice
Returns:: a fiftyone.core.collections.SampleCollection

property has_custom_view#: Whether the operator has a custom view.

property spaces#: The current spaces layout in the FiftyOne App.

property selected#: The list of selected sample IDs (if any).

property selected_labels#

A list of selected labels (if any).

Items are dictionaries with the following keys:

label_id: the ID of the label
sample_id: the ID of the sample containing the label
field: the field name containing the label
frame_number: the frame number containing the label (only applicable to video samples)

property extended_selection#: The extended selection of the view (if any).

property current_sample#

The ID of the current sample being processed (if any).

When executed via the FiftyOne App, this is set when the user opens a sample in the modal.

property active_fields#: The list of currently active fields in the FiftyOne App sidebar.

property user_id#: The ID of the user executing the operation, if known.

property user_request_token#: The request token authenticating the user executing the operation, if known.

property panel_id#: The ID of the panel that invoked the operator, if any.

property panel_state#

The current panel state.

Only available when the operator is invoked from a panel.

property panel#

A fiftyone.operators.panel.PanelRef instance that you can use to read and write the state and data of the current panel.

Only available when the operator is invoked from a panel.

property delegated#: Whether the operation was delegated.

property requesting_delegated_execution#: Whether delegated execution was requested for the operation.

property delegation_target#: The orchestrator to which the operation was delegated (if any).

property results#: A dict of results for the current operation.

property secrets#: A read-only mapping of keys to their resolved values.

property ops#: A fiftyone.operators.operations.Operations instance that you can use to trigger builtin operations on the current context.

property group_slice#: The current group slice of the view (if any).

property num_distributed_tasks#: The number of tasks this job should be split into.

property query_performance#: Whether query performance is enabled.

property prompt_id#: An identifier for the prompt, unique to each instance of a user opening a prompt in the FiftyOne App.

property operator_uri#: The URI of the target operator.

prompt(operator_uri, params=None, on_success=None, on_error=None, skip_prompt=False)#

Prompts the user to execute the operator with the given URI.

Parameters:

operator_uri – the URI of the operator
params (None) – a dictionary of parameters for the operator
on_success (None) – a callback to invoke if the user successfully executes the operator
on_error (None) – a callback to invoke if the execution fails
skip_prompt (False) – whether to skip the prompt

Returns:

a fiftyone.operators.message.GeneratedMessage containing instructions for the FiftyOne App to prompt the user

secret(key)#

Retrieves the secret with the given key.

Parameters:: key – a secret key
Returns:: the secret value

async resolve_secret_values(keys, **kwargs)#

Resolves the values of the given secrets keys.

Parameters:

keys – a list of secret keys
**kwargs – additional keyword arguments to pass to the secrets client for authentication if required

trigger(operator_name, params=None)#

Triggers an invocation of the operator with the given name.

This method is only available when the operator is invoked via the FiftyOne App. You can check this via ctx.executor.

Example:

def execute(self, ctx):
    # Trigger the `reload_dataset` operator after this operator
    # finishes executing
    ctx.trigger("reload_dataset")

    # Immediately trigger the `reload_dataset` operator while a
    # generator operator is executing
    yield ctx.trigger("reload_dataset")

Parameters:

operator_name – the name of the operator
params (None) – a dictionary of parameters for the operator

Returns:

a fiftyone.operators.message.GeneratedMessage containing instructions for the FiftyOne App to invoke the operator

log(message)#

Logs a message to the browser console.

Note

This method is only available to non-delegated operators. You can only use this method during the execution of an operator.

Parameters:: message – a message to log
Returns:: a fiftyone.operators.message.GeneratedMessage containing instructions for the FiftyOne App to invoke the operator

set_progress(progress=None, label=None)#

Sets the progress of the current operation.

Parameters:

progress (None) – an optional float between 0 and 1 (0% to 100%)
label (None) – an optional label to display

store(store_name)#

Retrieves the execution store with the given name.

The store is automatically created if necessary.

Parameters:: store_name – the name of the store
Returns:: a fiftyone.operators.store.ExecutionStore

serialize()#

Serializes the execution context.

Returns:: a JSON dict

to_dict()#: Returns the properties of the execution context as a dict.

class fiftyone.operators.ExecutionOptions(allow_immediate_execution=True, allow_delegated_execution=False, default_choice_to_delegated=False, allow_distributed_execution=False, min_distributed_tasks=2, max_distributed_tasks=None, recommended_distributed_tasks=None, **_)#

Bases: object

Represents the execution options of an operation.

Parameters:

allow_immediate_execution (True) – whether the operation can be executed immediately
allow_delegated_execution (False) – whether the operation can be delegated to an orchestrator
default_choice_to_delegated (False) – whether to default to delegated execution, if allowed
allow_distributed_execution (False) – whether the operator supports distributing delegated execution across parallel workers. Only valid for delegated operations.
min_distributed_tasks (2) – the minimum number of tasks that a distributed delegated operation can be split into. None means no limit. Only valid for distributed and delegated operations.
max_distributed_tasks (None) – the maximum number of tasks that a distributed delegated operation can be split into. None means no limit. Only valid for distributed and delegated operations.
recommended_distributed_tasks (None) – the recommended number of tasks that a distributed delegated operation should be split into. None means no recommendation. Only valid for distributed and delegated operations.

Attributes:

`allow_immediate_execution`
`allow_delegated_execution`
`allow_distributed_execution`
`default_choice_to_delegated`
`min_distributed_tasks`
`max_distributed_tasks`
`recommended_distributed_tasks`
`available_orchestrators`
`orchestrator_registration_enabled`

Methods:

`update`([available_orchestrators])
`to_dict`()

property allow_immediate_execution#

property allow_delegated_execution#

property allow_distributed_execution#

property default_choice_to_delegated#

property min_distributed_tasks#

property max_distributed_tasks#

property recommended_distributed_tasks#

property available_orchestrators#

property orchestrator_registration_enabled#

update(available_orchestrators=None)#

to_dict()#

class fiftyone.operators.ProgressHandler(ctx, logger=None, level=None)#

Bases: Handler

A logging handler that reports all logging messages issued while the handler’s context manager is active to the provided execution context’s set_progress() method.

Parameters:

ctx – an fiftyone.operators.executor.ExecutionContext
logger (None) – a specific logging.Logger for which to report records. By default, the root logger is used
level (None) – an optional logging level above which to report records. By default, the logger’s effective level is used

Methods:

`emit`(record)	Do whatever it takes to actually log the specified logging record.
`acquire`()	Acquire the I/O thread lock.
`addFilter`(filter)	Add the specified filter to this handler.
`close`()	Tidy up any resources used by the handler.
`createLock`()	Acquire a thread lock for serializing access to the underlying I/O.
`filter`(record)	Determine if a record is loggable by consulting all the filters.
`flush`()	Ensure all logging output has been flushed.
`format`(record)	Format the specified record.
`get_name`()
`handle`(record)	Conditionally emit the specified logging record.
`handleError`(record)	Handle errors which occur during an emit() call.
`release`()	Release the I/O thread lock.
`removeFilter`(filter)	Remove the specified filter from this handler.
`setFormatter`(fmt)	Set the formatter for this handler.
`setLevel`(level)	Set the logging level of this handler.
`set_name`(name)

Attributes:

name

emit(record)#

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

acquire()#: Acquire the I/O thread lock.

addFilter(filter)#: Add the specified filter to this handler.

close()#

Tidy up any resources used by the handler.

This version removes the handler from an internal map of handlers, _handlers, which is used for handler lookup by name. Subclasses should ensure that this gets called from overridden close() methods.

createLock()#: Acquire a thread lock for serializing access to the underlying I/O.

filter(record)#

Determine if a record is loggable by consulting all the filters.

The default is to allow the record to be logged; any filter can veto this and the record is then dropped. Returns a zero value if a record is to be dropped, else non-zero.

Changed in version 3.2: Allow filters to be just callables.

flush()#

Ensure all logging output has been flushed.

This version does nothing and is intended to be implemented by subclasses.

format(record)#

Format the specified record.

If a formatter is set, use it. Otherwise, use the default formatter for the module.

get_name()#

handle(record)#

Conditionally emit the specified logging record.

Emission depends on filters which may have been added to the handler. Wrap the actual emission of the record with acquisition/release of the I/O thread lock. Returns whether the filter passed the record for emission.

handleError(record)#

Handle errors which occur during an emit() call.

This method should be called from handlers when an exception is encountered during an emit() call. If raiseExceptions is false, exceptions get silently ignored. This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors. You could, however, replace this with a custom handler if you wish. The record which was being processed is passed in to this method.

property name#

release()#: Release the I/O thread lock.

removeFilter(filter)#: Remove the specified filter from this handler.

setFormatter(fmt)#: Set the formatter for this handler.

setLevel(level)#: Set the logging level of this handler. level must be an int or a str.

set_name(name)#

fiftyone.operators.is_new(release_date, days=30)#

Determines if a feature is considered “new” based on its release date.

A feature is considered new if its release date is within the specified number of days.

Examples:

is_new("2024-11-09")
# True if today's date is within 30 days after 2024-11-09

is_new(datetime(2024, 11, 9), days=15)
# True if today's date is within 15 days after November 9, 2024

is_new("2024-10-01", days=45)
# False if today's date is more than 45 days after October 1, 2024

Parameters:

release_date –
the release date of the feature, in one of the following formats:
- a string in the format "%Y-%m-%d", e.g., "2024-11-09"
- a datetime instance
days (30) – the number of days for which the feature is considered new

Returns:

True/False whether the release date is within the specified number of days

class fiftyone.operators.Panel(_builtin=False)#

Bases: Operator

A panel.

Methods:

`render`(ctx)	Defines the panel's layout and events.
`resolve_input`(ctx)	Returns the resolved input property.
`on_startup`(ctx)
`on_load`(ctx)
`execute`(ctx)	Executes the operator.
`add_secrets`(secrets)	Adds secrets to the operator.
`method_to_uri`(method_name)	Converts a method name to a URI.
`resolve_delegation`(ctx)	Returns the resolved forced delegation flag.
`resolve_execution_options`(ctx)	Returns the resolved execution options.
`resolve_output`(ctx)	Returns the resolved output property.
`resolve_placement`(ctx)	Returns the resolved placement of the operator.
`resolve_run_name`(ctx)	Returns the resolved run name of the operator.
`resolve_type`(ctx, type)	Returns the resolved input or output property.
`to_json`()	Returns a JSON representation of the operator.

Attributes:

`builtin`	Whether the operator is builtin.
`config`	The `OperatorConfig` for the operator.
`name`
`uri`	The unique identifier of the operator: `plugin_name/operator_name`.

render(ctx)#

Defines the panel’s layout and events.

This method is called after every panel event is called (on load, button callback, context change event, etc).

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.types.Property

resolve_input(ctx)#

Returns the resolved input property.

Subclasses can implement this method to define the inputs to the operator. This method should never be called directly. Instead use resolve_type().

By default, this method is called once when the operator is created. If the operator is dynamic, this method is called each time the input changes.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.types.Property, or None

on_startup(ctx)#

on_load(ctx)#

execute(ctx)#

Executes the operator.

Subclasses must implement this method.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: JSON serializable data, or None

add_secrets(secrets)#

Adds secrets to the operator.

Parameters:: secrets – a list of secrets

property builtin#: Whether the operator is builtin.

property config#: The OperatorConfig for the operator.

method_to_uri(method_name)#

Converts a method name to a URI.

Parameters:: method_name – the method name
Returns:: a URI

property name#

resolve_delegation(ctx)#

Returns the resolved forced delegation flag.

Subclasses can implement this method to decide if delegated execution should be forced for the given operation.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: whether the operation should be delegated (True), run immediately (False), or None to defer to resolve_execution_options() to specify the available options

resolve_execution_options(ctx)#

Returns the resolved execution options.

Subclasses can implement this method to define the execution options available for the operation.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.executor.ExecutionOptions instance

resolve_output(ctx)#

Returns the resolved output property.

Subclasses can implement this method to define the outputs of the operator.

By default, this method is called once when the operator is created. If the operator is dynamic, this method is called after the operator is executed.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.types.Property, or None

resolve_placement(ctx)#

Returns the resolved placement of the operator.

Subclasses can implement this method to define the placement of the operator.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a fiftyone.operators.types.Placement, or None

resolve_run_name(ctx)#

Returns the resolved run name of the operator.

Subclasses can implement this method to define the run name of the operator.

Parameters:: ctx – the fiftyone.operators.executor.ExecutionContext
Returns:: a string, or None

resolve_type(ctx, type)#

Returns the resolved input or output property.

Parameters:

ctx – the fiftyone.operators.executor.ExecutionContext
type – the type of property to resolve, either "inputs" or "outputs"

Returns:

a fiftyone.operators.types.Property, or None

to_json()#

Returns a JSON representation of the operator.

Returns:: a JSON dict

property uri#: The unique identifier of the operator: plugin_name/operator_name.

class fiftyone.operators.PanelConfig(name, label, help_markdown=None, alpha=False, beta=False, is_new=False, category=None, icon=None, light_icon=None, dark_icon=None, allow_multiple=False, surfaces: Literal['grid', 'modal', 'grid modal'] = 'grid', priority=None, **kwargs)#

Bases: OperatorConfig

Configuration for a panel.

Parameters:

name – the name of the panel
label – the display name for the panel
icon (None) – the icon to show in the panel’s tab
light_icon (None) – the icon to show in the panel’s tab when the App is in light mode
dark_icon (None) – the icon to show in the panel’s tab when the App is in dark mode
allow_multiple (False) – whether to allow multiple instances of the panel to be opened
surfaces ("grid") – the surfaces on which the panel can be displayed
help_markdown (None) – a markdown string to display in the panel’s help tooltip
category (Category) – the category id of the panel
priority (None) – the priority of the panel for sorting in the UI

Methods:

to_json()

to_json()#

class fiftyone.operators.ExecutionStore(store_name: str, store_service: ExecutionStoreService, default_policy: str = 'persist')#

Bases: object

Execution store.

Parameters:

store_name – the name of the store
store_service – an fiftyone.operators.store.service.ExecutionStoreService
default_policy ("persist") – the default eviction policy for the store.

Methods:

`create`(store_name[, dataset_id, ...])
`list_stores`()	Lists all stores in the execution store.
`get`(key)	Retrieves a value from the store by its key.
`set`(key, value[, ttl, policy])	Sets the value of a key in the specified store.
`set_cache`(key, value[, ttl])	Sets a value in the store with the eviction policy set to "evict".
`delete`(key)	Deletes a key from the store.
`has`(key)	Checks if the store has a specific key.
`clear`()	Clears all the data in the store.
`clear_cache`()	Clears the cache for the store.
`update_ttl`(key, new_ttl)	Updates the TTL for a specific key.
`update_policy`(key, policy)	Updates the eviction policy for a specific key.
`get_metadata`(key)	Retrieves the metadata for the given key.
`list_keys`()	Lists all keys in the store.

static create(store_name: str, dataset_id: ObjectId | None = None, default_policy: str = 'persist', collection_name: str | None = None) → ExecutionStore#

list_stores() → list[str]#

Lists all stores in the execution store.

Returns:: a list of store names
Return type:: list

get(key: str) → Any | None#

Retrieves a value from the store by its key.

Parameters:: key – the key to retrieve the value for
Returns:: the value stored under the given key, or None if not found

set(key: str, value: Any, ttl: int | None = None, policy=None) → None#

Sets the value of a key in the specified store.

Parameters:

key – the key to set
value – the value to set
ttl (None) – an optional TTL in seconds
policy (persist) – the eviction policy for the key. Can be “persist” or “evict”. If “persist”, the key will never be automatically removed. If “evict”, the key may be removed automatically if a TTL is set, or manually via clear_cache().

Returns:

a fiftyone.store.models.KeyDocument

set_cache(key: str, value: Any, ttl: int | None = None) → None#

Sets a value in the store with the eviction policy set to “evict”.

Parameters:

key – the key to store the value under
value – the value to store
ttl (None) – the time-to-live in seconds

delete(key: str) → bool#

Deletes a key from the store.

Parameters:: key – the key to delete.
Returns:: True/False whether the key was deleted

has(key: str) → bool#

Checks if the store has a specific key.

Parameters:: key – the key to check
Returns:: True/False whether the key exists

clear() → None#: Clears all the data in the store.

clear_cache() → None#

Clears the cache for the store.

This will remove all keys that are eligible for eviction.

update_ttl(key: str, new_ttl: int) → None#

Updates the TTL for a specific key.

Parameters:

key – the key to update the TTL for
new_ttl – the new TTL in seconds

update_policy(key: str, policy: str) → None#

Updates the eviction policy for a specific key.

Parameters:

key – the key to update the policy for
policy – the new policy, either “persist” or “evict”

get_metadata(key: str) → dict | None#

Retrieves the metadata for the given key.

Parameters:: key – the key to check
Returns:: a dict of metadata about the key

list_keys() → list[str]#

Lists all keys in the store.

Returns:: a list of keys in the store

class fiftyone.operators.Categories(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Attributes:

`IMPORT`
`CURATE`
`ANALYZE`
`CUSTOM`

IMPORT = 'import'#

CURATE = 'curate'#

ANALYZE = 'analyze'#

CUSTOM = 'custom'#

fiftyone.operators.execution_cache(_func=None, *, residency='hybrid', max_size=None, ttl=None, link_to_dataset=True, key_fn=None, store_name=None, version=None, operator_scoped=False, user_scoped=False, prompt_scoped=False, jwt_scoped=False, collection_name=None, serialize=None, deserialize=None)#

Decorator for caching function results in an ExecutionStore.

The function must:

accept a ctx argument as the first parameter
return a serializable value
should produce the same output for the same input
should have no side effects
have serializable parameters and return values

Parameters:

ttl (None) – Time-to-live for the cached value in seconds.
link_to_dataset (True) – Whether to tie the cache entry to the dataset
key_fn (None) – A custom function to generate cache keys. If not provided, the function arguments are used as the key by serializing them as JSON.
store_name (None) – Custom name for the execution store. Defaults to the function name.
version (None) – Set a version number to prevent cache collisions when the function implementation changes.
operator_scoped (False) – Whether to tie the cache entry to the current operator
user_scoped (False) – Whether to tie the cache entry to the current user
prompt_scoped (False) – Whether to tie the cache entry to the current operator prompt
jwt_scoped (False) – Whether to tie the cache entry to the current user’s JWT
collection_name (None) – Override the default collection name for the execution store used by the execution_cache. The default collection name is “execution_store”.
serialize (None) – Custom serialization function given the original value that returns a JSON-serializable value.
deserialize (None) – Custom deserialization given a JSON-serializable value and returns the original value.
residency ("hybrid") –
The residency of the cache. Can be one of: - “transient”: Cache is stored in the execution store with policy=”evict”. - “ephemeral”: Cache is stored in memory and is cleared when the process ends. - “hybrid”: (default) Combination of transient and ephemeral. Cache is stored in memory

and in the execution store. The memory cache is used first, and if the value is not found, it falls back to the execution store.
max_size (None) – Maximum size of the memory cache. Only applicable for “ephemeral” and “hybrid” residency modes. If not provided, the default size is 1024. The cache will evict the least recently used items when the size exceeds this limit.

note:

When using ``link_to_dataset=True``:
    - the associated store is deleted the dataset is deleted
    - the cache entry is namespaced to the dataset

note:

Return values will be coerced from JSON unsafe types to safe types.
This may yield unexpected return values if the cached function returns
non-serializable types (e.g., NumPy arrays), since they are converted
to a JSON-compatible format.

This behavior can be overridden by providing custom ``serialize`` and/or
``deserialize`` functions.

Example Usage:

# Standalone function with default caching @execution_cache def expensive_query(ctx, path):

return ctx.dataset.count_values(path)

# Instance method with dataset-scoped caching class Processor:

@execution_cache(ttl=60, store_name=”processor_cache”) def expensive_query(self, ctx, path):

return ctx.dataset.count_values(path)

# Using a custom key function def custom_key_fn(ctx, path):

return [path, get_day_of_week()]

# Combines the custom key function with user-scoped caching @execution_cache(ttl=90, key_fn=custom_key_fn, jwt_scoped=True) def user_specific_query(ctx, path):

return ctx.dataset.match(
F(“creator_id”) == ctx.user_id

).count_values(path)

# Bypass the cache result = expensive_query.uncached(ctx, path)

# Set the cache for the given arguments expensive_query.set_cache(ctx, path, value_to_cache)

# Clear the cache for the given arguments expensive_query.clear_cache(ctx, path)

# Remove all cache entries for the function expensive_query.clear_all_caches()

# Clear all cache entries for the function expensive_query.clear_all_caches()

# NOTE: dataset_id is required if link_to_dataset=True expensive_query.clear_all_caches(dataset_id=dataset._doc.id)