fiftyone.operators.executor

FiftyOne operator execution.

Copyright 2017-2023, Voxel51, Inc.

voxel51.com

Classes:

ExecutionContext([request_params, executor])	Represents the execution context of an operator.
ExecutionResult([result, executor, error, …])	Represents the result of an operator execution.
ExecutionRunState	Enumeration of the available operator run states.
Executor([requests, logs])	Handles the execution phase of the operator lifecycle.
InvocationRequest(operator_uri[, params])	Represents a request to invoke an operator.
ValidationContext(ctx, inputs_property, operator)	Represents the validation context of an operator.
ValidationError(reason, property, path[, custom])	A validation error.

Exceptions:

ExecutionError

An error that occurs while executing an operator.

Functions:

execute_operator(operator_uri, ctx[, params])	Executes the operator with the given name.
execute_or_delegate_operator(operator_uri, …)	Executes the operator with the given name.
prepare_operator_executor(operator_uri, …)
resolve_placement(operator, request_params)	Resolves the placement of the operator with the given name.
resolve_type(registry, operator_uri, …)	Resolves the inputs property type of the operator with the given name.

class fiftyone.operators.executor.ExecutionRunState

Bases: object

Enumeration of the available operator run states.

Attributes:

COMPLETED
FAILED
QUEUED
RUNNING

QUEUED = 'queued'

RUNNING = 'running'

COMPLETED = 'completed'

FAILED = 'failed'

class fiftyone.operators.executor.InvocationRequest(operator_uri, params=None)

Bases: object

Represents a request to invoke an operator.

Parameters

• operator_uri – the URI of the operator to invoke

• params (None) – an optional dictionary of parameters

Methods:

to_json()

to_json()

class fiftyone.operators.executor.Executor(requests=None, logs=None)

Bases: object

Handles the execution phase of the operator lifecycle.

Parameters

• requests (None) – an optional list of InvocationRequest objects

• logs (None) – an optional list of log messages

Methods:

log(message)	Logs a message.
to_json()
trigger(operator_name[, params])	Triggers an invocation of the operator with the given name.

trigger(operator_name, params=None)

Triggers an invocation of the operator with the given name.

Parameters

• operator_name – the name of the operator

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

Returns

a fiftyone.operators.message.GeneratedMessage containing the result of the invocation

log(message)

Logs a message.

to_json()

fiftyone.operators.executor.execute_operator(operator_uri, ctx, params=None)

Executes the operator with the given name.

Parameters

• operator_uri – the URI of the operator

• ctx –

  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: 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

  • params: a dictionary of parameters for the operator. Consult the operator’s documentation for details

• params (None) – you can optionally provide the ctx.params dict as a separate argument

Returns

an ExecutionResult

async fiftyone.operators.executor.execute_or_delegate_operator(operator_uri, request_params)

Executes the operator with the given name.

Parameters

• operator_uri – the URI of the operator

• request_params – a dictionary of parameters for the operator

Returns

an ExecutionResult

async fiftyone.operators.executor.prepare_operator_executor(operator_uri, request_params)

fiftyone.operators.executor.resolve_type(registry, operator_uri, request_params)

Resolves the inputs property type of the operator with the given name.

Parameters

• registry – an fiftyone.operators.registry.OperatorRegistry

• operator_uri – the URI of the operator

• request_params – a dictionary of request parameters

Returns

the type of the inputs fiftyone.operators.types.Property of the operator, or None

fiftyone.operators.executor.resolve_placement(operator, request_params)

Resolves the placement of the operator with the given name.

Parameters

• operator – the fiftyone.operators.operator.Operator

• request_params – a dictionary of request parameters

Returns

the placement of the operator or None

class fiftyone.operators.executor.ExecutionContext(request_params=None, executor=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

Attributes:

dataset	The fiftyone.core.dataset.Dataset being operated on.
dataset_id	The ID of the fiftyone.core.dataset.Dataset being operated on.
dataset_name	The name of the fiftyone.core.dataset.Dataset being operated on.
delegated	Whether the operation’s execution was delegated to an orchestrator.
results	A dict of results for the current operation.
secrets	The dict of secrets available to the operation (if any).
selected	The list of selected sample IDs (if any).
selected_labels	A list of selected labels (if any).
view	The fiftyone.core.view.DatasetView being operated on.

Methods:

log(message)	Logs a message to the browser console.
resolve_secret_values(keys, **kwargs)	Resolves the values of the given secrets keys.
secret(key)	Retrieves the secret with the given key.
serialize()	Serializes the execution context.
to_dict()	Returns the properties of the execution context as a dict.
trigger(operator_name[, params])	Triggers an invocation of the operator with the given name.

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.

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 delegated

Whether the operation’s execution was delegated to an orchestrator.

This property is only availble for methods that are invoked after an operator is executed, e.g. resolve_output().

property results

A dict of results for the current operation.

This property is only availble for methods that are invoked after an operator is executed, e.g. resolve_output().

property secrets

The dict of secrets available to the operation (if any).

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.

Parameters

• operator_name – the name of the operator

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

Returns

a fiftyone.operators.message.GeneratedMessage containing the result of the invocation

log(message)

Logs a message to the browser console.

Parameters

message – a message to log

serialize()

Serializes the execution context.

Returns

a JSON dict

to_dict()

Returns the properties of the execution context as a dict.

class fiftyone.operators.executor.ExecutionResult(result=None, executor=None, error=None, validation_ctx=None, delegated=False)

Bases: object

Represents the result of an operator execution.

Parameters

• result (None) – the execution result

• executor (None) – an Executor

• error (None) – an error message

• validation_ctx (None) – a ValidationContext

Attributes:

is_generator

Whether the result is a generator or an async generator.

Methods:

to_exception()	Returns an ExecutionError representing a failed execution result.
to_json()	Returns a JSON dict representation of the result.

property is_generator

Whether the result is a generator or an async generator.

to_exception()

Returns an ExecutionError representing a failed execution result.

Returns

a ExecutionError

to_json()

Returns a JSON dict representation of the result.

Returns

a JSON dict

exception fiftyone.operators.executor.ExecutionError

Bases: Exception

An error that occurs while executing an operator.

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class fiftyone.operators.executor.ValidationError(reason, property, path, custom=False)

Bases: object

A validation error.

Parameters

• reason – the reason

• property – the property

• path – the path

Methods:

to_json()

Returns a JSON dict representation of the error.

to_json()

Returns a JSON dict representation of the error.

Returns

a JSON dict

class fiftyone.operators.executor.ValidationContext(ctx, inputs_property, operator)

Bases: object

Represents the validation context of an operator.

Parameters

• ctx – the ExecutionContext

• inputs_property – the fiftyone.operators.types.Property of the operator inputs

Methods:

add_error(error)	Adds a validation error.
exists_or_non_required(property, value)
to_json()	Returns a JSON dict representation of the context.
validate_enum(path, property, value)	Validates an enum value.
validate_list(path, property, value)	Validates a list value.
validate_object(path, property, value)	Validates an object value.
validate_primitive(path, property, value)	Validates a primitive value.
validate_property(path, property, value)	Validates a property value.

to_json()

Returns a JSON dict representation of the context.

Returns

a JSON dict

add_error(error)

Adds a validation error.

Parameters

error – a ValidationError

validate_enum(path, property, value)

Validates an enum value.

Parameters

• path – the path to the property

• property – the fiftyone.operators.types.Property

• value – the value to validate

Returns

a ValidationError, if the value is invalid

validate_list(path, property, value)

Validates a list value.

Parameters

• path – the path to the property

• property – the fiftyone.operators.types.Property

• value – the value to validate

Returns

a ValidationError, if the value is invalid

validate_property(path, property, value)

Validates a property value.

Parameters

• path – the path to the property

• property – the fiftyone.operators.types.Property

• value – the value to validate

Returns

a ValidationError, if the value is invalid

validate_object(path, property, value)

Validates an object value.

Parameters

• path – the path to the property

• property – the fiftyone.operators.types.Property

• value – the value to validate

Returns

a ValidationError, if the value is invalid

validate_primitive(path, property, value)

Validates a primitive value.

Parameters

• path – the path to the property

• property – the fiftyone.operators.types.Property

• value – the value to validate

Returns

a ValidationError, if the value is invalid

exists_or_non_required(property, value)