Teams Management SDK¶

One of FiftyOne’s core design principles is that you should be able to do everything programmatically if you want.

To this end, the fiftyone.management module provides Teams-specific methods for managing users, invitations, dataset permissions, plugins, API keys, and more.

Note

You must use an API connection (not a direct MongoDB connection) in order to use Management SDK methods.

API reference¶

Connections¶

API connection.

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

Functions:

`reload_api_connection`()	Reloads the API connection.
`test_api_connection`()	Tests the API connection.

fiftyone.management.connection.reload_api_connection() → None¶

Reloads the API connection.

This is necessary if the API URI or API key are changed after the first usage of this module.

Note

This should rarely be needed unless a script is working across deployments.

Examples:

import fiftyone.management as fom
import fiftyone as fo

# https://api.dev.mycompany.org
print(fo.config.api_uri)
fom.whoami()

# Change API URI, need to reload cached connection
fo.config.api_uri = "https://api.test.mycompany.org"
fom.reload_api_connection()
fom.whoami()

fiftyone.management.connection.test_api_connection()¶

Tests the API connection.

If the connection succeeds, a message will be printed. If the connection failes, an exception will be raised.

Examples:

import fiftyone.management as fom
fom.test_api_connection() # API connection succeeded

API keys¶

API key management.

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

Classes:

APIKey(id, name, created_at)

API key dataclass.

Functions:

`delete_api_key`(key[, user])	Deletes the API key for the given user (default: current user).
`generate_api_key`(key_name[, user])	Generates an API key for the given user (default: current user).
`list_api_keys`([user])	Lists all API keys for the given user (default: current user).

class fiftyone.management.api_key.APIKey(id: str, name: str, created_at: datetime.datetime)¶

API key dataclass.

Attributes:

`fiftyone.management.api_key.APIKey.created_at`
`fiftyone.management.api_key.APIKey.id`
`fiftyone.management.api_key.APIKey.name`

id: str = None¶

name: str = None¶

created_at: datetime.datetime = None¶

fiftyone.management.api_key.delete_api_key(key: str, user: Union[str, fiftyone.management.users.User, None] = None) → None¶

Deletes the API key for the given user (default: current user).

Note

Only admins can delete keys for other users.

Examples:

import fiftyone.management as fom

# Delete all keys from a user
email = "user@company.com"
for key in fom.list_api_keys(email):
    fom.delete_api_key(key.id, email)

Parameters

key – the ID of the key to delete
user (None) – an optional user ID, email string, or User instance. Defaults to the current user.

fiftyone.management.api_key.generate_api_key(key_name: str, user: Union[str, fiftyone.management.users.User, None] = None) → str¶

Generates an API key for the given user (default: current user).

Note

Only admins can generate keys for other users.

Warning

Once generated, this key cannot be recovered! If it’s lost, you must generate a new key.

Examples:

import fiftyone.management as fom

# 1. Generate key for myself
fom.generate_api_key("my-key")

# 2.a Generate key for user@example.com
fom.generate_api_key("your-key", "user@example.com")

# 2.b Generate key for user@example.com
user = fom.get_user("user@example.com")
fom.generate_api_key("your-key", user)

Parameters

key_name – a descriptive name for the key
user (None) – an optional user ID, email string, or User instance. Defaults to the current user.

Returns

the API key string

fiftyone.management.api_key.list_api_keys(user: Union[str, fiftyone.management.users.User, None] = None)¶

Lists all API keys for the given user (default: current user).

The returned key objects only have their name and IDs populated; the raw key is only available at time of generation.

Note

Only admins can request keys for other users.

Examples:

import fiftyone.management as fom

# 1. List my keys
fom.list_api_keys() # list my keys

# 2.a List keys for user@example.com
fom.list_api_keys("user@example.com")

# 2.b List keys for user@example.com
user = fom.get_user("user@example.com")
fom.list_api_keys(user)

Parameters: user (None) – an optional user ID, email string, or User instance. Defaults to the current user.
Returns: a list of APIKey instances

Dataset permissions¶

Dataset management.

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

Classes:

DatasetPermission

Dataset permission enum.

Functions:

`delete_dataset_user_permission`(dataset_name, …)	Removes the given user’s specific access to the given dataset.
`get_dataset_creator`(dataset_name)	Gets creator of a dataset, if known.
`get_permissions`(*[, dataset_name, user])	Gets the specified dataset or user permissions.
`get_permissions_for_dataset`(dataset_name)	Gets the list of users that have access to the given dataset.
`get_permissions_for_dataset_user`(…)	Gets the access permission (if any) that a given user has to a given dataset.
`get_permissions_for_user`(user)	Gets a list of datasets a given user has access to.
`set_dataset_default_permission`(dataset_name, …)	Sets the default member access level for the given dataset.
`set_dataset_user_permission`(dataset_name, …)	Grants the given user specific access to the given dataset at the specified permission level.

class fiftyone.management.dataset.DatasetPermission¶

Dataset permission enum.

Attributes:

`COMMENT`
`EDIT`
`MANAGE`
`NO_ACCESS`
`VIEW`

NO_ACCESS = 'NO_ACCESS'¶

VIEW = 'VIEW'¶

COMMENT = 'COMMENT'¶

EDIT = 'EDIT'¶

MANAGE = 'MANAGE'¶

fiftyone.management.dataset.delete_dataset_user_permission(dataset_name: str, user: Union[str, fiftyone.management.users.User]) → None¶

Removes the given user’s specific access to the given dataset.

Note

The caller must have Can Manage permissions on the dataset.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
user = "guest@company.com"

fom.set_dataset_user_permission(dataset_name, user, fom.VIEW)

fom.delete_dataset_user_permission(dataset_name, user)

assert fom.get_permissions(dataset_name=dataset_name, user=user) == fom.NO_ACCESS

Parameters

dataset_name – the dataset name
user – a user ID, email string, or User instance.

fiftyone.management.dataset.get_dataset_creator(dataset_name: str) → Optional[fiftyone.management.users.User]¶

Gets creator of a dataset, if known.

Examples:

import fiftyone.management as fom

user = fom.get_dataset_creator("dataset")

Parameters: dataset_name – the dataset name
Raises: ValueError – if dataset_name does not exist or calling user does not have access to it.
Returns: User instance, or None if dataset has no recorded creator.

fiftyone.management.dataset.get_permissions(*, dataset_name: str = None, user: str = None)¶

Gets the specified dataset or user permissions.

This method is a convenience wrapper around the methods below based on which arguments you provide:

dataset_name: get_permissions_for_dataset()
user: get_permissions_for_user()
dataset_name and user: get_permissions_for_dataset_user()

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
user = "guest@company.com"

# Get permissions for user
assert (
    fom.get_permissions(user=user) ==
    fom.get_permissions_for_user(user)
)

# Get permissions for dataset
assert (
    fom.get_permissions(dataset_name=dataset_name) ==
    fom.get_permissions_for_dataset(dataset_name)
)

# Get permissions for user-dataset combination
assert (
    fom.get_permissions(dataset_name=dataset_name, user=user) ==
    fom.get_permissions_for_dataset_user(dataset_name, user)
)

Parameters

dataset_name (None) – a dataset name
user (None) – a user ID, email string, or User instance

Returns

the requested user/dataset permissions

fiftyone.management.dataset.get_permissions_for_dataset(dataset_name: str) → List[Dict]¶

Gets the list of users that have access to the given dataset.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"

fom.get_permissions_for_dataset(dataset_name)

Example output:

[
    {'name': 'A. User', 'email': 'a@company.com', 'id': '12345', 'permission': 'MANAGE'},
    {'name': 'B. User', 'email': 'b@company.com', 'id': '67890', 'permission': 'EDIT'},
]

Parameters: dataset_name – the dataset name
Returns: a list of user info dicts

fiftyone.management.dataset.get_permissions_for_dataset_user(dataset_name: str, user: str) → fiftyone.management.dataset.DatasetPermission¶

Gets the access permission (if any) that a given user has to a given dataset.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
user = "guest@company.com"

fom.get_permissions_for_dataset_user(dataset_name, user)

Parameters

dataset_name – the dataset name
user – a user ID, email string, or User instance

Returns

DatasetPermission

fiftyone.management.dataset.get_permissions_for_user(user: str)¶

Gets a list of datasets a given user has access to.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

user = "guest@company.com"

fom.get_permissions_for_user(user)

Example output:

[
    {'name': 'datasetA', 'permission': 'EDIT'},
    {'name': 'datasetB', 'permission': 'VIEW'},
]

Parameters: user – a user ID, email string, or User instance
Returns: a list of permission dicts

fiftyone.management.dataset.set_dataset_default_permission(dataset_name: str, permission: fiftyone.management.dataset.DatasetPermission) → None¶

Sets the default member access level for the given dataset.

Note

The caller must have Can Manage permissions on the dataset.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"

# Give every Member Edit access by default
fom.set_dataset_default_permission(dataset_name, fom.EDIT)

Parameters

dataset_name – the dataset name
permission – the DatasetPermission to set

fiftyone.management.dataset.set_dataset_user_permission(dataset_name: str, user: Union[str, fiftyone.management.users.User], permission: fiftyone.management.dataset.DatasetPermission, invite: bool = False) → None¶

Grants the given user specific access to the given dataset at the specified permission level.

Note

The caller must have Can Manage permissions on the dataset.

Warning

If an unknown email is passed to this function and invite is True, an invitation to join the organization will be sent to the email. The user will be created and have access to the dataset on invitation acceptance. Please double-check the email correctness before running.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
guest = "guest@company.com"
new_guest = "new-guest@company.com"

# Existing user
fom.set_dataset_user_permission(dataset_name, guest, fom.VIEW)

assert fom.get_permissions(dataset_name=dataset_name, user=guest) == fom.VIEW

# Nonexisting user
fom.set_dataset_user_permission(dataset_name, new_guest, invite=True)
assert guest in [i.invitee_email for i in fom.list_pending_invitations()]

Parameters

dataset_name – the dataset name
user – a user ID, email string, or User instance
permission – the DatasetPermission to grant
invite (False) – if True and user is an email, an invitation will be sent to join the organization.

Organization settings¶

Organization settings management.

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

Classes:

OrganizationSettings(default_user_role, …)

Functions:

`get_organization_settings`()	Gets organization-wide settings for the Teams deployment.
`set_organization_settings`(*[, …])	Sets organization-wide settings for the Teams deployment

class fiftyone.management.organization.OrganizationSettings(default_user_role: fiftyone.management.users.UserRole, default_dataset_permission: fiftyone.management.dataset.DatasetPermission, default_operator_minimum_role: fiftyone.management.users.UserRole, default_operator_minimum_dataset_permission: fiftyone.management.dataset.DatasetPermission)¶

Attributes:

`fiftyone.management.organization.OrganizationSettings.default_dataset_permission`
`fiftyone.management.organization.OrganizationSettings.default_operator_minimum_dataset_permission`
`fiftyone.management.organization.OrganizationSettings.default_operator_minimum_role`
`fiftyone.management.organization.OrganizationSettings.default_user_role`

default_user_role: users.UserRole = None¶

default_dataset_permission: dataset.DatasetPermission = None¶

default_operator_minimum_role: users.UserRole = None¶

default_operator_minimum_dataset_permission: dataset.DatasetPermission = None¶

fiftyone.management.organization.get_organization_settings() → fiftyone.management.organization.OrganizationSettings¶

Gets organization-wide settings for the Teams deployment.

Note

Only admins can retrieve this information

Examples:

import fiftyone.management as fom

fom.get_organization_settings()

Returns: OrganizationSettings

fiftyone.management.organization.set_organization_settings(*, default_user_role: Optional[fiftyone.management.users.UserRole] = None, default_dataset_permission: Optional[fiftyone.management.dataset.DatasetPermission] = None, default_operator_minimum_role: Optional[fiftyone.management.users.UserRole] = None, default_operator_minimum_dataset_permission: Optional[fiftyone.management.dataset.DatasetPermission] = None) → fiftyone.management.organization.OrganizationSettings¶

Sets organization-wide settings for the Teams deployment

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

user_role = fom.MEMBER
dataset_perm = fom.EDIT

# Set only default user role
fom.set_organization_settings(default_user_role=user_role)

# Set only default dataset permission
fom.set_organization_settings(default_dataset_permission=dataset_perm)

# Set multiple settings at once
fom.set_organization_settings(
    default_user_role=user_role,
    default_dataset_permission=dataset_perm,
    default_operator_minimum_role=user_role,
    default_operator_minimum_dataset_permission=dataset_perm,
)

Parameters

default_user_role (None) – an optional UserRole to set.
default_dataset_permission (None) – an optional DatasetPermission to set,
default_operator_minimum_role (None) – an optional UserRole to set
default_operator_minimum_dataset_permission (None) – an optional DatasetPermission to set

Returns

OrganizationSettings

Plugin management¶

Plugin management.

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

Classes:

`OperatorPermission`(minimum_role, …)	Operator permission dataclass.
`Plugin`(name, description, version, …)	Plugin dataclass.
`PluginOperator`(name, enabled, permission)	Plugin operator dataclass.

Functions:

`delete_plugin`(plugin_name)	Deletes the given plugin from central FiftyOne Teams.
`download_plugin`(plugin_name, download_dir)	Downloads a plugin from central FiftyOne Teams.
`get_plugin_info`(plugin_name)	Gets information about the specified plugin in central FiftyOne Teams.
`list_plugins`([include_builtin])	Returns a list of all installed plugins in central FiftyOne Teams.
`set_plugin_enabled`(plugin_name, enabled)	Sets the enabled status of the given plugin in central FiftyOne Teams.
`set_plugin_operator_enabled`(plugin_name, …)	Sets the enabled status of the given plugin operator in central FiftyOne Teams.
`set_plugin_operator_permissions`(plugin_name, …)	Sets permission levels of the given plugin operator in central FiftyOne Teams.
`upload_plugin`(plugin_path[, overwrite, optimize])	Uploads a plugin to central FiftyOne Teams.

class fiftyone.management.plugin.OperatorPermission(minimum_role: fiftyone.management.users.UserRole, minimum_dataset_permission: fiftyone.management.dataset.DatasetPermission)¶

Operator permission dataclass.

Attributes:

`fiftyone.management.plugin.OperatorPermission.minimum_dataset_permission`
`fiftyone.management.plugin.OperatorPermission.minimum_role`

minimum_role: users.UserRole = None¶

minimum_dataset_permission: dataset.DatasetPermission = None¶

class fiftyone.management.plugin.PluginOperator(name: str, enabled: bool, permission: fiftyone.management.plugin.OperatorPermission)¶

Plugin operator dataclass.

Attributes:

`fiftyone.management.plugin.PluginOperator.enabled`
`fiftyone.management.plugin.PluginOperator.name`
`fiftyone.management.plugin.PluginOperator.permission`

name: str = None¶

enabled: bool = None¶

permission: OperatorPermission = None¶

class fiftyone.management.plugin.Plugin(name: str, description: str, version: str, fiftyone_version: str, enabled: bool, operators: List[fiftyone.management.plugin.PluginOperator])¶

Plugin dataclass.

Attributes:

`fiftyone.management.plugin.Plugin.description`
`fiftyone.management.plugin.Plugin.enabled`
`fiftyone.management.plugin.Plugin.fiftyone_version`
`fiftyone.management.plugin.Plugin.name`
`fiftyone.management.plugin.Plugin.operators`
`fiftyone.management.plugin.Plugin.version`

name: str = None¶

description: str = None¶

version: str = None¶

fiftyone_version: str = None¶

enabled: bool = None¶

operators: List[PluginOperator] = None¶

fiftyone.management.plugin.list_plugins(include_builtin: bool = False) → List[fiftyone.management.plugin.Plugin]¶

Returns a list of all installed plugins in central FiftyOne Teams.

Examples:

import fiftyone.management as fom

fom.list_plugins()

Parameters: include_builtin (False) – whether to include builtin plugins
Returns: a list of Plugin instances

fiftyone.management.plugin.get_plugin_info(plugin_name: str) → fiftyone.management.plugin.Plugin¶

Gets information about the specified plugin in central FiftyOne Teams.

Examples:

import fiftyone.management as fom

fom.get_plugin_info("my-plugin")

Parameters: plugin_name – a plugin name
Returns: Plugin, or None if no such plugin is found

fiftyone.management.plugin.upload_plugin(plugin_path: str, overwrite: bool = False, optimize=False) → fiftyone.management.plugin.Plugin¶

Uploads a plugin to central FiftyOne Teams.

The local plugin must be a zip file that contains a single directory with a fiftyone.yml or fiftyone.yaml file. For example:

my_plugin/
    fiftyone.yml
    __init__.py
    data.txt

Note

Only admins can upload plugins.

Examples:

import fiftyone.management as fom

# Upload a raw plugin directory
fom.upload_plugin("/path/to/plugin_dir", overwrite=True)

# Upload a plugin, optimizing the directory before the upload
fom.upload_plugin("/path/to/plugin_dir", overwrite=True, optimize=True)

# Upload a plugin as ZIP file
fom.upload_plugin("/path/to/plugin.zip", overwrite=True)

Parameters

plugin_path – the path to a plugin zip or directory
overwrite (False) – whether to overwrite an existing plugin with same name
optimize (False) – whether to optimize the created zip file before uploading. If a .gitignore file exists, an attempt will first be made to use git archive to create the zip. If not or this doesn’t work, a zip will be created by pruning various known system-generated files and directories such as .git/ and __pycache__/. This argument has no effect if plugin_path does not point to a directory

fiftyone.management.plugin.delete_plugin(plugin_name: str) → None¶

Deletes the given plugin from central FiftyOne Teams.

Examples:

import fiftyone.management as fom

plugin_name = "special-plugin"
fom.delete_plugin(plugin_name)

plugins = fom.list_plugins()
assert not any(plugin.name == plugin_name for plugin in plugins)

Note

Only admins can perform this action.

Parameters: plugin_name – a plugin name

fiftyone.management.plugin.download_plugin(plugin_name: str, download_dir: str) → str¶

Downloads a plugin from central FiftyOne Teams.

Examples:

import fiftyone.management as fom

fom.download_plugin("special-plugin", "/path/to/local/plugins/")

Parameters

plugin_name – a plugin name
download_dir – a directory into which to download the plugin

Returns

the path to the downloaded plugin

fiftyone.management.plugin.set_plugin_enabled(plugin_name: str, enabled: bool) → None¶

Sets the enabled status of the given plugin in central FiftyOne Teams.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

# Disable whole plugin
fom.set_plugin_enabled("special-plugin", False)

Parameters

plugin_name – a plugin name
enabled – a bool specifying what to set enabled status to

fiftyone.management.plugin.set_plugin_operator_enabled(plugin_name: str, operator_name: str, enabled: bool) → None¶

Sets the enabled status of the given plugin operator in central FiftyOne Teams.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

# Disable a particular operator
fom.set_plugin_operator_enabled("special-plugin", "special-operator", False)

Parameters

plugin_name – a plugin name
operator_name – an operator name within the given plugin
enabled – a bool specifying what to set operator enabled status to

fiftyone.management.plugin.set_plugin_operator_permissions(plugin_name: str, operator_name: str, minimum_role: Optional[fiftyone.management.users.UserRole] = None, minimum_dataset_permission: Optional[fiftyone.management.dataset.DatasetPermission] = None)¶

Sets permission levels of the given plugin operator in central FiftyOne Teams.

At least one of minimum_role and minimum_dataset_permission must be set.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

plugin_name = "special-plugin"
operator_name = "special-operator"

# Set minimum role permission only
fom.set_plugin_operator_enabled(
    plugin_name,
    operator_name,
    minimum_role=fom.MEMBER
    )

# Set minimum dataset permission only
fom.set_plugin_operator_enabled(
    plugin_name,
    operator_name,
    minimum_dataset_permission=fom.EDIT
)

# Set both minimum role and minimum dataset permissions
fom.set_plugin_operator_enabled(
    plugin_name,
    operator_name,
    minimum_role=fom.EDIT,
    minimum_dataset_permission=fom.EDIT
)

Parameters

plugin_name – a plugin name
operator_name – an operator name within the given plugin
minimum_role (None) – an optional UserRole to set
minimum_dataset_permission (None) – an optional DatasetPermission to set

Snapshots¶

Dataset snapshot management.

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

Classes:

`DatasetSnapshot`(created_at, NoneType], …)
`DatasetSnapshotStatus`	User role enum.
`SampleChangeSummary`(total_samples, …)

Functions:

`calculate_dataset_latest_changes_summary`(…)	Calculate change summary between recent snapshot and HEAD of dataset.
`create_snapshot`(dataset_name, snapshot_name)	Create and store a snapshot of the current state of `dataset_name`.
`delete_snapshot`(dataset_name, snapshot_name)	Delete snapshot `snapshot_name` from dataset `dataset_name`.
`get_dataset_latest_changes_summary`(dataset_name)	Gets change summary between most recent snapshot and HEAD of dataset
`get_snapshot_info`(dataset_name, snapshot_name)	Gets information about the specified dataset snapshot, or `None`
`list_snapshots`(dataset_name)	Returns a list of all snapshots of a dataset in order of creation.
`revert_dataset_to_snapshot`(dataset_name, …)	Revert dataset to a previous snapshot state.

class fiftyone.management.snapshot.DatasetSnapshotStatus¶

User role enum.

Attributes:

`LOADED`
`LOADING`
`UNLOADED`

UNLOADED = 'UNLOADED'¶

LOADING = 'LOADING'¶

LOADED = 'LOADED'¶

class fiftyone.management.snapshot.SampleChangeSummary(total_samples: int, num_samples_added: int, num_samples_deleted: int, num_samples_changed: int, updated_at: Union[datetime.datetime, NoneType] = None)¶

Attributes:

`fiftyone.management.snapshot.SampleChangeSummary.num_samples_added`
`fiftyone.management.snapshot.SampleChangeSummary.num_samples_changed`
`fiftyone.management.snapshot.SampleChangeSummary.num_samples_deleted`
`fiftyone.management.snapshot.SampleChangeSummary.total_samples`
`updated_at`

total_samples: int = None¶

num_samples_added: int = None¶

num_samples_deleted: int = None¶

num_samples_changed: int = None¶

updated_at: Optional[datetime.datetime] = None¶

class fiftyone.management.snapshot.DatasetSnapshot(created_at: Union[datetime.datetime, NoneType], created_by: str, description: Union[str, NoneType], id: str, linear_change_summary: Union[fiftyone.management.snapshot.SampleChangeSummary, NoneType], load_status: fiftyone.management.snapshot.DatasetSnapshotStatus, name: str, slug: str)¶

Attributes:

`fiftyone.management.snapshot.DatasetSnapshot.created_at`
`fiftyone.management.snapshot.DatasetSnapshot.created_by`
`fiftyone.management.snapshot.DatasetSnapshot.description`
`fiftyone.management.snapshot.DatasetSnapshot.id`
`fiftyone.management.snapshot.DatasetSnapshot.linear_change_summary`
`fiftyone.management.snapshot.DatasetSnapshot.load_status`
`fiftyone.management.snapshot.DatasetSnapshot.name`
`fiftyone.management.snapshot.DatasetSnapshot.slug`

created_at: Optional[datetime.datetime] = None¶

created_by: str = None¶

description: Optional[str] = None¶

id: str = None¶

linear_change_summary: Optional[SampleChangeSummary] = None¶

load_status: DatasetSnapshotStatus = None¶

name: str = None¶

slug: str = None¶

fiftyone.management.snapshot.calculate_dataset_latest_changes_summary(dataset_name: str) → fiftyone.management.snapshot.SampleChangeSummary¶

Calculate change summary between recent snapshot and HEAD of dataset.

Examples:

import fiftyone.management as fom

old = fom.calculate_dataset_latest_changes_summary(dataset.name)
assert old == fom.get_dataset_latest_changes_summary(dataset.name)

dataset.delete_samples(dataset.take(5))

# Cached summary hasn't been updated
assert old == fom.get_dataset_latest_changes_summary(dataset.name)

new = fom.calculate_dataset_latest_changes_summary(dataset.name)
assert new.updated_at > changes.updated_at

Parameters: dataset_name – the dataset name
Returns: Change summary between most recent snapshot and HEAD of this dataset.

fiftyone.management.snapshot.create_snapshot(dataset_name: str, snapshot_name: str, description: Optional[str] = None) → fiftyone.management.snapshot.DatasetSnapshot¶

Create and store a snapshot of the current state of dataset_name.

Snapshot name must be unique for the given dataset.

Note

Only users with MANAGE access can create a snapshot

Examples:

import fiftyone.management as fom

snapshot_name = "v0.1"
description = "Initial dataset snapshot"
fom.create_snapshot(dataset.name, snapshot_name, description)

Parameters

dataset_name – the dataset name
snapshot_name – the name of the snapshot to create
description (None) – Optional description to attach to this snapshot

fiftyone.management.snapshot.delete_snapshot(dataset_name: str, snapshot_name: str)¶

Delete snapshot snapshot_name from dataset dataset_name.

Note

Only users with MANAGE access can delete a snapshot.

Examples:

import fiftyone.management as fom

snapshot_name = "v0.1"
description = "Initial dataset snapshot"
fom.create_snapshot(dataset.name, snapshot_name, description)

# Some time later ...

fom.delete_snapshot(dataset, snapshot_name)

Parameters

dataset_name – the dataset name
snapshot_name – the snapshot name

fiftyone.management.snapshot.get_dataset_latest_changes_summary(dataset_name: str) → fiftyone.management.snapshot.SampleChangeSummary¶

Gets change summary between most recent snapshot and HEAD of dataset

Note

This summary is not continuously computed, the result of this function may be stale. Use calculate_dataset_latest_changes_summary() to recalculate.

Examples:

import fiftyone.management as fom

fom.get_dataset_latest_changes_summary(dataset.name)

Parameters

dataset_name – the dataset name

Returns

Change summary between most recent snapshot and HEAD of this dataset.: Or None if no summary has been calculated yet.

Raises

ValueError – if dataset doesn’t exist or no access

fiftyone.management.snapshot.get_snapshot_info(dataset_name: str, snapshot_name: str) → Optional[fiftyone.management.snapshot.DatasetSnapshot]¶

Gets information about the specified dataset snapshot, or None: if snapshot_name doesn’t exist.

Examples:

import fiftyone.management as fom

dataset = "quickstart"
snapshot_name = "v0.1"

fom.get_snapshot_info(dataset.name, snapshot_name)

Parameters

dataset_name – the dataset name
snapshot_name – the snapshot name

Raises

ValueError – if dataset doesn’t exist or no access

fiftyone.management.snapshot.list_snapshots(dataset_name: str) → List[str]¶

Returns a list of all snapshots of a dataset in order of creation.

Examples:

import fiftyone.management as fom

fom.list_snapshots(dataset.name)

Parameters: dataset_name – the dataset name
Raises: ValueError – if dataset doesn’t exist or no access
Returns: a list of DatasetSnapshot instances

fiftyone.management.snapshot.revert_dataset_to_snapshot(dataset_name: str, snapshot_name: str)¶

Revert dataset to a previous snapshot state.

Reverts the current (HEAD) state of dataset_name to a previous state encapsulated by the snapshot snapshot_name. All changes since then are lost. All snapshots created after this one will be deleted as well.

If you are attempting to view the dataset at the point of a snapshot but not completely revert, you can do so with:

snapshot = fo.load_dataset(dataset_name, snapshot=snapshot_name)

Note

Only users with MANAGE access can revert a dataset

Warning

This action is very destructive! All changes between snapshot_name and the current HEAD state of dataset_name will be destroyed! Including all snapshots created after snapshot_name.

Examples:

import fiftyone.management as fom

snapshot_name = "v0.1"
description = "Initial dataset snapshot"
fom.create_snapshot(dataset.name, snapshot_name, description)

# Oops we deleted everything!
dataset.delete_samples(dataset.values("id"))

# Phew!
fom.revert_dataset_to_snapshot(dataset.name, snapshot_name)
dataset.reload()
assert len(dataset) > 0

Parameters

dataset_name – the dataset name
snapshot_name – the snapshot name

User management¶

User management.

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

Classes:

`Invitation`(id, created_at, expires_at, …)	Invitation dataclass.
`User`(id, name, email, role)	User information dataclass.
`UserRole`	User role enum.

Functions:

`delete_user`(user)	Deletes the given user.
`delete_user_invitation`(invitation)	Deletes/revokes a previously-sent invitation if it has not been accepted.
`get_user`(user)	Gets information about the specified user (if any).
`list_pending_invitations`()	Returns a list of pending user invitations.
`list_users`()	Returns a list of all users.
`send_user_invitation`(email, role)	Sends an email invitation to join your FiftyOne Teams organization.
`set_user_role`(user, role)	Sets the role of the given user.
`whoami`()	Returns information about the calling user.

class fiftyone.management.users.UserRole¶

User role enum.

Attributes:

`ADMIN`
`COLLABORATOR`
`GUEST`
`MEMBER`

ADMIN = 'ADMIN'¶

MEMBER = 'MEMBER'¶

COLLABORATOR = 'COLLABORATOR'¶

GUEST = 'GUEST'¶

class fiftyone.management.users.User(id: str, name: str, email: str, role: fiftyone.management.users.UserRole)¶

User information dataclass.

Attributes:

`fiftyone.management.users.User.email`
`fiftyone.management.users.User.id`
`fiftyone.management.users.User.name`
`fiftyone.management.users.User.role`

id: str = None¶

name: str = None¶

email: str = None¶

role: UserRole = None¶

class fiftyone.management.users.Invitation(id: str, created_at: datetime.datetime, expires_at: datetime.datetime, invitee_email: str, invitee_role: fiftyone.management.users.UserRole, url: str)¶

Invitation dataclass.

Attributes:

`fiftyone.management.users.Invitation.created_at`
`fiftyone.management.users.Invitation.expires_at`
`fiftyone.management.users.Invitation.id`
`fiftyone.management.users.Invitation.invitee_email`
`fiftyone.management.users.Invitation.invitee_role`
`fiftyone.management.users.Invitation.url`

id: str = None¶

created_at: datetime.datetime = None¶

expires_at: datetime.datetime = None¶

invitee_email: str = None¶

invitee_role: UserRole = None¶

url: str = None¶

fiftyone.management.users.delete_user(user: Union[str, fiftyone.management.users.User]) → None¶

Deletes the given user.

Note

Only admins can perform this action.

Warning

This action is irreversible! Once deleted, the user will have to be re-invited to the organization to have access again.

Examples:

import fiftyone.management as fom

delete_user = "guest@company.com"

fom.delete_user(delete_user)

assert fom.get_user(delete_user) is None

Parameters: user – a user ID, email string, or User instance

fiftyone.management.users.delete_user_invitation(invitation: str) → None¶

Deletes/revokes a previously-sent invitation if it has not been accepted.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

new_guest = "guest@company.com"

invite_id = fom.send_user_invitation(new_guest, fom.GUEST)

# Delete by invitation ID
fom.delete_user_invitation(invite_id)

# Delete by user email
fom.delete_user_invitation(new_guest)

pending = fom.list_pending_invitations()
assert not any(p.id == invite_id for p in pending)

Parameters: invitation – an invitation ID as returned by send_user_invitation(), or email address

fiftyone.management.users.get_user(user: str) → Optional[fiftyone.management.users.User]¶

Gets information about the specified user (if any).

Note

Only admins can retrieve information about other users.

Examples:

import fiftyone.management as fom

known_user = "member@company.com"
user = fom.get_user(known_user)
assert user.email == known_user

unknown_user = "unknown@company.com"
assert fom.get_user(unknown_user) is None

Parameters: user – a user ID or email string
Returns: User, or None if no such user is found

fiftyone.management.users.list_pending_invitations() → List[fiftyone.management.users.Invitation]¶

Returns a list of pending user invitations.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

fom.list_pending_invitations()

Returns: a list of Invitation instances

fiftyone.management.users.list_users() → List[fiftyone.management.users.User]¶

Returns a list of all users.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

fom.list_users()

Returns: a list of User instances

fiftyone.management.users.send_user_invitation(email: str, role: fiftyone.management.users.UserRole) → str¶

Sends an email invitation to join your FiftyOne Teams organization.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

new_guest = "guest@company.com"

invite_id = fom.send_user_invitation(new_guest, fom.GUEST)

pending = fom.list_pending_invitations()
assert any(p.invitee_email == new_guest for p in pending)

Parameters

email – the email address
role – the UserRole to grant the new user

Returns

the invitation ID string

fiftyone.management.users.set_user_role(user: Union[str, fiftyone.management.users.User], role: fiftyone.management.users.UserRole) → None¶

Sets the role of the given user.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

user = "user@company.com"

#1.a set role from email
fom.set_user_role(user, fom.MEMBER)

#1.b set role from user instance
user_obj = fom.get_user(user_obj)
fom.set_user_role(user_obj, fom.MEMBER)

assert fom.get_user(user).role == fom.MEMBER

Parameters

user – a user ID, email string, or User instance
role – the UserRole to set

fiftyone.management.users.whoami() → fiftyone.management.users.User¶

Returns information about the calling user.

Examples:

import fiftyone.management as fom

me = fom.whoami()

assert fom.get_user(me.id) == me

Returns: User