fiftyone.plugins#

Module contents#

FiftyOne plugins.

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

Functions:

`enable_plugin`(plugin_name[, _allow_missing])	Enables the given plugin.
`disable_plugin`(plugin_name[, _allow_missing])	Disables the given plugin.
`delete_plugin`(plugin_name)	Deletes the given plugin from local disk.
`list_plugins`([enabled, builtin, shadowed])	Lists available plugins.
`list_disabled_plugins`()	Returns a list of all disabled plugin names.
`list_downloaded_plugins`()	Returns a list of all downloaded plugin names.
`list_enabled_plugins`()	Returns a list of all enabled plugin names.
`get_plugin`([name, plugin_dir])	Gets the definition for the given plugin.
`find_plugin`(name)	Returns the path to the plugin on local disk.
`download_plugin`(url_or_gh_repo[, ...])	Downloads the plugin(s) from the given location to your local plugins directory (`fo.config.plugins_dir`).
`create_plugin`(plugin_name[, from_files, ...])	Creates a plugin with the given name.
`load_plugin_requirements`(plugin_name)	Loads the Python package requirements associated with the given plugin, if any.
`install_plugin_requirements`(plugin_name[, ...])	Installs any Python package requirements associated with the given plugin.
`ensure_plugin_requirements`(plugin_name[, ...])	Ensures that any Python package requirements associated with the given plugin are installed.
`ensure_plugin_compatibility`(plugin_name[, ...])	Ensures that the given plugin is compatible with your current FiftyOne package version.

Classes:

`PluginDefinition`(directory, metadata[, ...])	A plugin definition.
`PluginContext`(plugin_definition)	Context that represents a plugin and the Python objects it creates.
`PluginSecretsResolver`()	Injects secrets from environmental variables into the execution context.

fiftyone.plugins.enable_plugin(plugin_name, _allow_missing=False)#

Enables the given plugin.

Parameters:: plugin_name – the plugin name

fiftyone.plugins.disable_plugin(plugin_name, _allow_missing=False)#

Disables the given plugin.

Parameters:: plugin_name – the plugin name

fiftyone.plugins.delete_plugin(plugin_name)#

Deletes the given plugin from local disk.

Parameters:: plugin_name – the plugin name

fiftyone.plugins.list_plugins(enabled=True, builtin=False, shadowed=False)#

Lists available plugins.

Parameters:

enabled (True) – whether to include only enabled plugins (True) or only disabled plugins (False) or all plugins (“all”)
builtin (False) – whether to include only builtin plugins (True) or only non-builtin plugins (False) or all plugins (“all”)
shadowed (False) – whether to include only “shadowed” duplicate plugins (True) or only usable plugins (False) or all plugins (“all”)

Returns:

a list of PluginDefinition instances

fiftyone.plugins.list_disabled_plugins()#

Returns a list of all disabled plugin names.

Returns:: a list of plugin names

fiftyone.plugins.list_downloaded_plugins()#

Returns a list of all downloaded plugin names.

Returns:: a list of plugin names

fiftyone.plugins.list_enabled_plugins()#

Returns a list of all enabled plugin names.

Returns:: a list of plugin names

fiftyone.plugins.get_plugin(name=None, plugin_dir=None)#

Gets the definition for the given plugin.

Parameters:

name (None) – the plugin name
plugin_dir (None) – a directory containing the plugin

Returns:

a PluginDefinition

fiftyone.plugins.find_plugin(name)#

Returns the path to the plugin on local disk.

Parameters:: name – the plugin name
Returns:: the path to the plugin directory

fiftyone.plugins.download_plugin(url_or_gh_repo, plugin_names=None, overwrite=False)#

Downloads the plugin(s) from the given location to your local plugins directory (fo.config.plugins_dir).

Note

To download from a private GitHub repository that you have access to, provide your GitHub personal access token by setting the GITHUB_TOKEN environment variable.

Parameters:

url_or_gh_repo –
the location to download from, which can be:
- a GitHub repo URL like https://github.com/<user>/<repo>
- a GitHub ref like https://github.com/<user>/<repo>/tree/<branch> or https://github.com/<user>/<repo>/commit/<commit>
- a GitHub ref string like <user>/<repo>[/<ref>]
- a GitHub tree path like https://github.com/<user>/<repo>/tree/<branch>/<path>
- a publicly accessible URL of an archive (eg zip or tar) file
plugin_names (None) – a plugin name or iterable of plugin names to download. By default, all found plugins are downloaded
overwrite (False) – whether to overwrite an existing plugin with the same name if it already exists

Returns:

a dict mapping plugin names to plugin directories on disk

fiftyone.plugins.create_plugin(plugin_name, from_files=None, outdir=None, description=None, version=None, overwrite=False, **kwargs)#

Creates a plugin with the given name.

If no from_files are provided, a directory containing only the plugin’s metadata file will be created.

If no outdir is specified, the plugin is created within your local plugins directory (fo.config.plugins_dir).

Parameters:

plugin_name – the name of the plugin
from_files (None) – a directory or list of explicit filepaths to include in the plugin
outdir (None) – the path at which to create the plugin directory. If not provided, the plugin is created within your fo_config.plugins_dir
description (None) – a description for the plugin
version (None) – an optional FiftyOne version requirement string
overwrite (False) – whether to overwrite a local plugin with the same name if one exists
**kwargs – additional keyword arguments to include in the plugin definition

Returns:

the directory containing the created plugin

fiftyone.plugins.load_plugin_requirements(plugin_name)#

Loads the Python package requirements associated with the given plugin, if any.

Parameters:: plugin_name – the plugin name
Returns:: a list of requirement strings, or None

fiftyone.plugins.install_plugin_requirements(plugin_name, error_level=None)#

Installs any Python package requirements associated with the given plugin.

Parameters:

plugin_name – the plugin name
error_level (None) –
the error level to use, defined as:
- 0: raise error if the install fails
- 1: log warning if the install fails
- 2: ignore install fails
By default, fiftyone.config.requirement_error_level is used

fiftyone.plugins.ensure_plugin_requirements(plugin_name, error_level=None, log_success=False)#

Ensures that any Python package requirements associated with the given plugin are installed.

Parameters:

plugin_name – the plugin name
error_level (None) –
the error level to use, defined as:
- 0: raise error if requirement is not satisfied
- 1: log warning if requirement is not satisfied
- 2: ignore unsatisifed requirements
By default, fiftyone.config.requirement_error_level is used
log_success (False) – whether to generate a log message if a requirement is satisfied

fiftyone.plugins.ensure_plugin_compatibility(plugin_name, error_level=None, log_success=False)#

Ensures that the given plugin is compatible with your current FiftyOne package version.

Parameters:

plugin_name – the plugin name
error_level (None) –
the error level to use, defined as:
- 0: raise error if plugin is not compatible
- 1: log warning if plugin is not satisfied
- 2: ignore fiftyone compatibility requirements
By default, fiftyone.config.requirement_error_level is used
log_success (False) – whether to generate a log message if the plugin is compatible

class fiftyone.plugins.PluginDefinition(directory, metadata, shadow_paths=None)#

Bases: object

A plugin definition.

Parameters:

directory – the directory containing the plugin
metadata – a plugin metadata dict
shadow_paths (None) – a list of plugin directories that this plugin shadows

Attributes:

`name`	The name of the plugin.
`directory`	The directory containing the plugin.
`builtin`	Whether the plugin is a builtin plugin.
`shadow_paths`	A list of plugin directories that this plugin shadows.
`author`	The author of the plugin.
`version`	The version of the plugin.
`url`	The URL of the plugin.
`license`	The license of the plugin.
`description`	The description of the plugin.
`fiftyone_compatibility`	The FiftyOne compatibility version.
`fiftyone_requirement`	The FiftyOne requirement as a string like `fiftyone>=0.21`.
`operators`	The operators of the plugin.
`package_json_path`	The absolute path to the package.json file.
`has_package_json`	Whether the plugin has a package.json file.
`js_bundle`	The relative path to the JS bundle file.
`js_bundle_path`
`py_entry`
`py_entry_path`	The absolute path to the Python entry file.
`server_path`	The default server path to the plugin.
`js_bundle_server_path`	The default server path to the JS bundle.
`js_bundle_hash`	A hash of the plugin's JS bundle file.
`has_py`	Whether the plugin has a Python entry file.
`has_js`	Whether the plugin has a JS bundle file.
`secrets`	A list of required secrets for the plugin.

Methods:

`can_register_operator`(name)	Whether the plugin can register the given operator.
`to_dict`()	Returns a JSON dict representation of the plugin metadata.
`from_disk`(metadata_path[, shadow_paths])	Creates a `PluginDefinition` for the given metadata file.

property name#: The name of the plugin.

property directory#: The directory containing the plugin.

property builtin#: Whether the plugin is a builtin plugin.

property shadow_paths#: A list of plugin directories that this plugin shadows.

property author#: The author of the plugin.

property version#: The version of the plugin.

property url#: The URL of the plugin.

property license#: The license of the plugin.

property description#: The description of the plugin.

property fiftyone_compatibility#: The FiftyOne compatibility version.

property fiftyone_requirement#: The FiftyOne requirement as a string like fiftyone>=0.21.

property operators#: The operators of the plugin.

property package_json_path#: The absolute path to the package.json file.

property has_package_json#: Whether the plugin has a package.json file.

property js_bundle#: The relative path to the JS bundle file.

property js_bundle_path#

property py_entry#

property py_entry_path#: The absolute path to the Python entry file.

property server_path#: The default server path to the plugin.

property js_bundle_server_path#: The default server path to the JS bundle.

property js_bundle_hash#: A hash of the plugin’s JS bundle file.

can_register_operator(name)#

Whether the plugin can register the given operator.

Parameters:: name – the operator name
Returns:: True/False

property has_py#: Whether the plugin has a Python entry file.

property has_js#: Whether the plugin has a JS bundle file.

property secrets#: A list of required secrets for the plugin.

to_dict()#

Returns a JSON dict representation of the plugin metadata.

Returns:: a JSON dict

classmethod from_disk(metadata_path, shadow_paths=None)#

Creates a PluginDefinition for the given metadata file.

Parameters:

metadata_path – the path to a plugin .yaml file
shadow_paths (None) – a list of plugin directories that this plugin shadows

Returns:

a PluginDefinition

class fiftyone.plugins.PluginContext(plugin_definition)#

Bases: object

Context that represents a plugin and the Python objects it creates.

Parameters:: plugin_definition – the fiftyone.plugins.PluginDefinition for the plugin

Attributes:

`name`	The plugin name.
`secrets`	List of keys for required secrets as specified in the plugin definition.

Methods:

`has_errors`()	Determines whether the plugin has errors.
`can_register`(instance)	Determines whether the given operator can be registered.
`register`(cls)	Registers the given operator on the plugin.
`register_all`()	Registers all operators defined by the plugin on this context.
`dispose_all`()	Disposes all operators from this context.

property name#: The plugin name.

property secrets#: List of keys for required secrets as specified in the plugin definition.

has_errors()#

Determines whether the plugin has errors.

Returns:: True/False

can_register(instance)#

Determines whether the given operator can be registered.

Parameters:: instance – an fiftyone.operators.operator.Operator
Returns:: True/False

register(cls)#

Registers the given operator on the plugin.

Note

Any errors are logged rather than being raised.

Parameters:: cls – an fiftyone.operators.operator.Operator or fiftyone.operators.panel.Panel class

register_all()#: Registers all operators defined by the plugin on this context.

Note

Any errors are logged rather than being raised.

dispose_all()#: Disposes all operators from this context.

class fiftyone.plugins.PluginSecretsResolver#

Bases: object

Injects secrets from environmental variables into the execution context.

Methods:

`register_operator`(operator_uri, required_secrets)
`client`()
`get_multiple`(keys, operator_uri, **kwargs)	Get the value of multiple secrets.
`get_secret`(key, operator_uri, **kwargs)	Get the value of a secret.
`get_secret_sync`(key, operator_uri, **kwargs)	Get the value of a secret.

register_operator(operator_uri: str, required_secrets: List[str]) → None#

client() → ISecretProvider#

async get_multiple(keys: List[str], operator_uri: str, **kwargs) → Dict[str, ISecret | None]#

Get the value of multiple secrets. :param keys: list of secret keys :param operator_uri: the operator URI :param kwargs: additional keyword arguments to pass to the secrets :param client for authentication if required:

Returns:: A dictionary of secret keys and their values

async get_secret(key: str, operator_uri: str, **kwargs) → ISecret | None#

Get the value of a secret.

Parameters:

key (str) – unique secret identifier
kwargs – additional keyword arguments to pass to the secrets
required (client for authentication if)

get_secret_sync(key: str, operator_uri: str, **kwargs) → ISecret | None#

Get the value of a secret.

Parameters:

key (str) – unique secret identifier
kwargs – additional keyword arguments to pass to the secrets
required (client for authentication if)