See also

Please visit our docs for more information on Segments.ai and visit the setup page to learn how to install and setup the Segments.ai Python SDK.

Client#

Users#

Get a user#

SegmentsClient.get_user(user=None)[source]#

Get a user.

user = client.get_user()
print(user)
Parameters

user (Optional[str]) – The username for which to get the user details. Leave empty to get the authenticated user. Defaults to None.

Raises
Return type

User

Datasets#

List datasets#

SegmentsClient.get_datasets(user=None, per_page=1000, page=1)[source]#

Get a list of datasets.

datasets = client.get_datasets()
for dataset in datasets:
    print(dataset.name, dataset.description)
Parameters

  • user (Optional[str]) – The user for which to get the datasets. Leave empty to get datasets of current user. Defaults to None.

  • per_page (int) – Pagination parameter indicating the maximum number of datasets to return. Defaults to 1000.

  • page (int) – Pagination parameter indicating the page to return. Defaults to 1.

Raises
Return type

List[Dataset]

Get a dataset#

SegmentsClient.get_dataset(dataset_identifier)[source]#

Get a dataset.

dataset_identifier = 'jane/flowers'
dataset = client.get_dataset(dataset_identifier)
print(dataset)
Parameters

dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

Raises
Return type

Dataset

Create a dataset#

SegmentsClient.add_dataset(name, description='', task_type=TaskType.SEGMENTATION_BITMAP, task_attributes=None, category=Category.OTHER, public=False, readme='', metadata=None, labeling_inactivity_timeout_seconds=300, enable_skip_labeling=True, enable_skip_reviewing=False, enable_ratings=False, enable_interpolation=True, enable_same_dimensions_track_constraint=False, enable_save_button=False, enable_label_status_verified=False, enable_3d_cuboid_rotation=False, organization=None)[source]#

Add a dataset.

dataset_name = 'flowers'
description = 'A dataset containing flowers of all kinds.'
task_type = 'segmentation-bitmap'
dataset = client.add_dataset(dataset_name, description, task_type)
print(dataset)

Task type

Value

Image segmentation labels (bitmap)

segmentation-bitmap

Image segmentation labels (bitmap)

segmentation-bitmap-highres

Image segmentation labels (sequence)

image-segmentation-sequence

Image bounding box labels

bboxes

Image vector labels

vector

Image vector labels (sequence)

image-vector-sequence

Point cloud cuboid labels

pointcloud-cuboid

Point cloud cuboid labels (sequence)

pointcloud-cuboid-sequence

Point cloud segmentation labels

pointcloud-segmentation

Point cloud segmentation labels (sequence)

pointcloud-segmentation-sequence

Point cloud vector labels

pointcloud-vector

Point cloud vector labels (sequence)

pointcloud-vector-sequence

Multisensor labels (sequence)

multisensor-sequence
Parameters

  • name (str) – The dataset name. Example: flowers.

  • description (str) – The dataset description. Defaults to ''.

  • task_type (TaskType) – The dataset’s task type. Defaults to segmentation-bitmap.

  • task_attributes (Union[Dict[str, Any], TaskAttributes, None]) – The dataset’s task attributes. Please refer to the online documentation. Defaults to {'format_version': '0.1', 'categories': [{'id': 1, 'name': 'object'}]}.

  • category (Category) – The dataset category. Defaults to other.

  • public (bool) – The dataset visibility. Defaults to False.

  • readme (str) – The dataset readme. Defaults to ''.

  • metadata (Optional[Dict[str, Any]]) – Any dataset metadata. Example: {'day': 'sunday', 'robot_id': 3}.

  • labeling_inactivity_timeout_seconds (int) – The number of seconds after which a user is considered inactive during labeling. Only impacts label timing metrics. Defaults to 300.

  • enable_skip_labeling (bool) – Enable the skip button in the labeling workflow. Defaults to True.

  • enable_skip_reviewing (bool) – Enable the skip button in the reviewing workflow. Defaults to False.

  • enable_ratings (bool) – Enable star-ratings for labeled images. Defaults to False.

  • enable_interpolation (bool) – Enable label interpolation in sequence datasets. Ignored for non-sequence datasets. Defaults to True.

  • enable_same_dimensions_track_constraint (bool) – Enable constraint to keep same cuboid dimensions for the entire object track in point cloud cuboid datasets. Ignored for non-cuboid datasets. Defaults to False.

  • enable_save_button (bool) – Enable a save button in the labeling and reviewing workflow, to save unfinished work. Defaults to False.

  • enable_label_status_verified (bool) – Enable an additional label status “Verified”. Defaults to False.

  • enable_3d_cuboid_rotation (bool) – Enable 3D cuboid rotation (i.e., yaw, pitch and roll). Defaults to False.

  • organization (Optional[str]) – The username of the organization for which this dataset should be created. None will create a dataset for the current user. Defaults to None.

Raises
Return type

Dataset

Update a dataset#

SegmentsClient.update_dataset(dataset_identifier, description=None, task_type=None, task_attributes=None, category=None, public=None, readme=None, metadata=None, labeling_inactivity_timeout_seconds=None, enable_skip_labeling=None, enable_skip_reviewing=None, enable_ratings=None, enable_interpolation=None, enable_same_dimensions_track_constraint=None, enable_save_button=None, enable_label_status_verified=None, enable_3d_cuboid_rotation=None)[source]#

Update a dataset.

dataset_identifier = 'jane/flowers'
description = 'A dataset containing flowers of all kinds.'
dataset = client.update_dataset(dataset_identifier, description)
print(dataset)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • description (Optional[str]) – The dataset description. Defaults to None.

  • task_type (Optional[TaskType]) – The dataset’s task type. Defaults to None.

  • task_attributes (Union[Dict[str, Any], TaskAttributes, None]) – The dataset’s task attributes. Please refer to the online documentation. Defaults to None.

  • category (Optional[Category]) – The dataset category. Defaults to None.

  • public (Optional[bool]) – The dataset visibility. Defaults to None.

  • readme (Optional[str]) – The dataset readme. Defaults to None.

  • metadata (Optional[Dict[str, Any]]) – Any dataset metadata. Example: {'day': 'sunday', 'robot_id': 3}.

  • labeling_inactivity_timeout_seconds (Optional[int]) – The number of seconds after which a user is considered inactive during labeling. Only impacts label timing metrics. Defaults to None.

  • enable_skip_labeling (Optional[bool]) – Enable the skip button in the labeling workflow. Defaults to None.

  • enable_skip_reviewing (Optional[bool]) – Enable the skip button in the reviewing workflow. Defaults to None.

  • enable_ratings (Optional[bool]) – Enable star-ratings for labeled images. Defaults to None.

  • enable_interpolation (Optional[bool]) – Enable label interpolation in sequence datasets. Ignored for non-sequence datasets. Defaults to None.

  • enable_same_dimensions_track_constraint (Optional[bool]) – Enable constraint to keep same cuboid dimensions for the entire object track in point cloud cuboid datasets. Ignored for non-cuboid datasets. Defaults to None.

  • enable_save_button (Optional[bool]) – Enable a save button in the labeling and reviewing workflow, to save unfinished work. Defaults to False.

  • enable_label_status_verified (Optional[bool]) – Enable an additional label status “Verified”. Defaults to False.

  • enable_3d_cuboid_rotation (Optional[bool]) – Enable 3D cuboid rotation (i.e., yaw, pitch and roll). Defaults to False.

Raises
Return type

Dataset

Delete a dataset#

SegmentsClient.delete_dataset(dataset_identifier)[source]#

Delete a dataset.

dataset_identifier = 'jane/flowers'
client.delete_dataset(dataset_identifier)
Parameters

dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

Raises
Return type

None

Clone a dataset#

SegmentsClient.clone_dataset(dataset_identifier, new_name=None, new_task_type=None, new_public=None, organization=None, clone_labels=False)[source]#

Clone a dataset.

dataset_identifier = 'jane/flowers'
new_name = 'flowers-vector'
new_task_type = 'vector'
new_public = False
client.clone_dataset(
    dataset_identifier,
    new_name=new_name,
    new_task_type=new_task_type,
    new_public=new_public,
)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • new_name (Optional[str]) – The dataset name for the clone. Defaults to f'{old_dataset_name}-clone'.

  • new_task_type (Optional[TaskType]) – The task type for the clone. Defaults to the task type of the original dataset.

  • new_public (Optional[bool]) – The visibility for the clone. Defaults to the visibility of the original dataset.

  • organization (Optional[str]) – The username of the organization for which this dataset should be created. None will create a dataset for the current user. Defaults to None.

  • clone_labels (bool) – Whether to clone the labels of the original dataset. Defaults to False.

Raises
Return type

Dataset

Dataset collaborators#

Get a dataset collaborator#

SegmentsClient.get_dataset_collaborator(dataset_identifier, username)[source]#

Get a dataset collaborator.

dataset_identifier = 'jane/flowers'
username = 'john'
client.get_dataset_collaborator(dataset_identifier, username)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • username (str) – The username of the collaborator to be added.

Raises

  • ValidationError – If validation of the collaborator fails.

  • APILimitError – If the API limit is exceeded.

  • NotFoundError – If the dataset or dataset collaborator is not found.

  • NetworkError – If the request is not valid (e.g., if the dataset collaborator does not exist) or if the server experienced an error.

  • TimeoutError – If the request times out.

Return type

Collaborator

Add a dataset collaborator#

SegmentsClient.add_dataset_collaborator(dataset_identifier, username, role=Role.LABELER)[source]#

Add a dataset collaborator.

dataset_identifier = 'jane/flowers'
username = 'john'
role = 'reviewer'
client.add_dataset_collaborator(dataset_identifier, username, role)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • username (str) – The username of the collaborator to be added.

  • role (Role) – The role of the collaborator to be added. One of labeler, reviewer, manager, admin. Defaults to labeler.

Raises
Return type

Collaborator

Update a dataset collaborator#

SegmentsClient.update_dataset_collaborator(dataset_identifier, username, role)[source]#

Update a dataset collaborator.

dataset_identifier = 'jane/flowers'
username = 'john'
role = 'admin'
client.update_dataset_collaborator(dataset_identifier, username, role)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • username (str) – The username of the collaborator to be added.

  • role (Role) – The role of the collaborator to be added. Defaults to labeler.

Raises
Return type

Collaborator

Delete a dataset collaborator#

SegmentsClient.delete_dataset_collaborator(dataset_identifier, username)[source]#

Delete a dataset collaborator.

dataset_identifier = 'jane/flowers'
username = 'john'
client.delete_dataset_collaborator(dataset_identifier, username)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • username (str) – The username of the collaborator to be deleted.

Raises
Return type

None

Samples#

List samples#

SegmentsClient.get_samples(dataset_identifier, labelset=None, name=None, label_status=None, metadata=None, sort='name', direction='asc', per_page=1000, page=1, include_full_label=False)[source]#

Get the samples in a dataset.

dataset_identifier = 'jane/flowers'
samples = client.get_samples(dataset_identifier)
for sample in samples:
    print(sample.name, sample.uuid)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • labelset (Optional[str]) – If defined, this additionally returns for each sample a label summary or full label (depending on include_full_label) for the given labelset. Defaults to None.

  • name (Optional[str]) – Name to filter by. Defaults to None (no filtering).

  • label_status (Union[LabelStatus, List[LabelStatus], None]) – Sequence of label statuses to filter by. Defaults to None (no filtering).

  • metadata (Union[str, List[str], None]) – Sequence of ‘key:value’ metadata attributes to filter by. Defaults to None (no filtering).

  • sort (Literal[‘name’, ‘created’, ‘priority’, ‘updated_at’, ‘gt_label__updated_at’]) – What to sort results by. One of name, created, priority, updated_at, gt_label__updated_at. Defaults to name.

  • direction (Literal[‘asc’, ‘desc’]) – Sorting direction. One of asc (ascending) or desc (descending). Defaults to asc.

  • per_page (int) – Pagination parameter indicating the maximum number of samples to return. Defaults to 1000.

  • page (int) – Pagination parameter indicating the page to return. Defaults to 1.

  • include_full_label (bool) – Whether to include the full label in the response, or only a summary. Ignored if labelset is None. Defaults to False.

Raises
Return type

List[Sample]

Get a sample#

SegmentsClient.get_sample(uuid, labelset=None, include_signed_url=False)[source]#

Get a sample.

uuid = '602a3eec-a61c-4a77-9fcc-3037ce5e9606'
sample = client.get_sample(uuid)
print(sample)
Parameters

  • uuid (str) – The sample uuid.

  • labelset (Optional[str]) – If defined, this additionally returns the label for the given labelset. Defaults to None.

  • include_signed_url (bool) – Whether to return the pre-signed URL in case of private S3 buckets. Defaults to False.

Raises
Return type

Sample

Create a sample#

SegmentsClient.add_sample(dataset_identifier, name, attributes, metadata=None, priority=0, assigned_labeler=None, assigned_reviewer=None)[source]#

Add a sample to a dataset.

Note

  • The content of the attributes field depends on the sample type.

  • If the image is on your local computer, you should first upload it to a cloud storage service like Amazon S3, Google Cloud Storage, Imgur, or to our asset storage service using upload_asset().

  • If you create a sample with a URL from a public S3 bucket and you see an error on the platform, make sure to properly configure your bucket’s CORS settings.

dataset_identifier = 'jane/flowers'
name = 'violet.jpg'
attributes = {
    'image': {
        'url': 'https://example.com/violet.jpg'
    }
}
# Metadata and priority are optional fields.
metadata = {
    'city': 'London',
    'weather': 'cloudy',
    'robot_id': 3
}
priority = 10 # Samples with higher priority value will be labeled first. Default is 0.
sample = client.add_sample(dataset_identifier, name, attributes, metadata, priority)
print(sample)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • name (str) – The name of the sample.

  • attributes (Union[Dict[str, Any], ImageSampleAttributes, ImageSequenceSampleAttributes, PointcloudSampleAttributes, PointcloudSequenceSampleAttributes, MultiSensorSampleAttributes]) – The sample attributes. Please refer to the online documentation.

  • metadata (Optional[Dict[str, Any]]) – Any sample metadata. Example: {'weather': 'sunny', 'camera_id': 3}.

  • priority (float) – Priority in the labeling queue. Samples with higher values will be labeled first. Defaults to 0.

  • assigned_labeler (Optional[str]) – The username of the user who should label this sample. Leave empty to not assign a specific labeler. Defaults to None.

  • assigned_reviewer (Optional[str]) – The username of the user who should review this sample. Leave empty to not assign a specific reviewer. Defaults to None.

Raises
Return type

Sample

Create samples in bulk#

SegmentsClient.add_samples(dataset_identifier, samples)[source]#

Add samples to a dataset in bulk. When attempting to add samples which already exist, no error is thrown but the existing samples are returned without changes.

Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • samples (List[Union[Dict[str, Any], Sample]]) – A list of dicts with required name, attributes fields and optional metadata, priority fields. See add_sample() for details.

Raises
Return type

List[Sample]

Update a sample#

SegmentsClient.update_sample(uuid, name=None, attributes=None, metadata=None, priority=None, assigned_labeler=None, assigned_reviewer=None)[source]#

Update a sample.

uuid = '602a3eec-a61c-4a77-9fcc-3037ce5e9606'
metadata = {
    'city': 'London',
    'weather': 'cloudy',
    'robot_id': 3
}
priority = 10 # Samples with higher priority value will be labeled first. Default is 0.
sample = client.update_sample(uuid, metadata=metadata, priority=priority)
print(sample)
Parameters

  • uuid (str) – The sample uuid.

  • name (Optional[str]) – The name of the sample.

  • attributes (Union[Dict[str, Any], ImageSampleAttributes, ImageSequenceSampleAttributes, PointcloudSampleAttributes, PointcloudSequenceSampleAttributes, MultiSensorSampleAttributes, None]) – The sample attributes. Please refer to the online documentation.

  • metadata (Optional[Dict[str, Any]]) – Any sample metadata. Example: {'weather': 'sunny', 'camera_id': 3}.

  • priority (Optional[float]) – Priority in the labeling queue. Samples with higher values will be labeled first.

  • assigned_labeler (Optional[str]) – The username of the user who should label this sample. Leave empty to not assign a specific labeler.

  • assigned_reviewer (Optional[str]) – The username of the user who should review this sample. Leave empty to not assign a specific reviewer.

Raises
Return type

Sample

Delete a sample#

SegmentsClient.delete_sample(uuid)[source]#

Delete a sample.

uuid = '602a3eec-a61c-4a77-9fcc-3037ce5e9606'
client.delete_sample(uuid)
Parameters

uuid (str) – The sample uuid.

Raises
Return type

None

Labels#

Get a label#

SegmentsClient.get_label(sample_uuid, labelset='ground-truth')[source]#

Get a label.

Note

If the sample is unlabeled, a NotFoundError will be raised.

sample_uuid = '602a3eec-a61c-4a77-9fcc-3037ce5e9606'
label = client.get_label(sample_uuid)
print(label)
Parameters

  • sample_uuid (str) – The sample uuid.

  • labelset (str) – The labelset this label belongs to. Defaults to ground-truth.

Raises
Return type

Label

Create a label#

SegmentsClient.add_label(sample_uuid, labelset, attributes, label_status=LabelStatus.PRELABELED, score=None)[source]#

Add a label to a sample.

A label is added to a sample in relation to a labelset, such as the default ground-truth labelset, or a newly created labelset for uploading model predictions. You can create a new labelset by clicking the “Add new labelset” link on the Samples tab.

Note

The content of the attributes field depends on the label type.

sample_uuid = '602a3eec-a61c-4a77-9fcc-3037ce5e9606'
attributes = {
    'format_version': '0.1',
    'annotations': [
        {
            'id': 1,
            'category_id': 1,
            'type': 'bbox',
            'points': [
                [12.34, 56.78],
                [90.12, 34.56]
            ]
        },
    ]
}
client.add_label(sample_uuid, attributes)
Parameters
Raises
Return type

Label

Update a label#

SegmentsClient.update_label(sample_uuid, labelset, attributes=None, label_status=None, score=None)[source]#

Update a label.

sample_uuid = '602a3eec-a61c-4a77-9fcc-3037ce5e9606'
attributes = {
    'format_version': '0.1',
    'annotations': [
        {
            'id': 1,
            'category_id': 1,
            'type': 'bbox',
            'points': [
                [12.34, 56.78],
                [90.12, 34.56]
            ]
        },
    ]
}
client.update_label(sample_uuid, attributes)
Parameters
Raises
Return type

Label

Delete a label#

SegmentsClient.delete_label(sample_uuid, labelset)[source]#

Delete a label.

sample_uuid = '602a3eec-a61c-4a77-9fcc-3037ce5e9606'
labelset = 'ground-truth'
client.delete_label(sample_uuid, labelset)
Parameters

  • sample_uuid (str) – The sample uuid.

  • labelset (str) – The labelset this label belongs to.

Raises
Return type

None

Labelsets#

List labelsets#

SegmentsClient.get_labelsets(dataset_identifier)[source]#

Get the labelsets in a dataset.

dataset_identifier = 'jane/flowers'
labelsets = client.get_labelsets(dataset_identifier)
for labelset in labelsets:
    print(labelset.name, labelset.description)
Parameters

dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

Raises
Return type

List[Labelset]

Get a labelset#

SegmentsClient.get_labelset(dataset_identifier, name)[source]#

Get a labelset.

dataset_identifier = 'jane/flowers'
name = 'model-predictions'
labelset = client.get_labelset(dataset_identifier, name)
print(labelset)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • name (str) – The name of the labelset.

Raises

  • ValidationError – If validation of the labelset fails.

  • APILimitError – If the API limit is exceeded.

  • NotFoundError – If the dataset or labelset is not found.

  • NetworkError – If the request is not valid (e.g., if the dataset does not exist) or if the server experienced an error.

  • TimeoutError – If the request times out.

Return type

Labelset

Create a labelset#

SegmentsClient.add_labelset(dataset_identifier, name, description='')[source]#

Add a labelset to a dataset.

dataset_identifier = 'jane/flowers'
name = 'model-predictions-resnet50'
client.add_labelset(dataset_identifier, name)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • name (str) – The name of the labelset.

  • description (str) – The labelset description. Defaults to ''.

Raises
Return type

Labelset

Delete a labelset#

SegmentsClient.delete_labelset(dataset_identifier, name)[source]#

Delete a labelset.

dataset_identifier = 'jane/flowers'
name = 'model-predictions'
client.delete_labelset(dataset_identifier, name)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • name (str) – The name of the labelset.

Raises
Return type

None

Issues#

List issues#

SegmentsClient.get_issues(dataset_identifier)[source]#

Get all issues for a dataset.

dataset_identifier = 'jane/flowers'
issues = client.get_issues(dataset_identifier)
for issue in issues:
    print(issue.uuid, issue.description, issue.status, issue.sample_uuid)
Parameters

dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

Raises
Return type

List[Issue]

Create an issue#

SegmentsClient.add_issue(sample_uuid, description, status=IssueStatus.OPEN)[source]#

Add an issue to a sample.

sample_uuid = '602a3eec-a61c-4a77-9fcc-3037ce5e9606'
description = 'You forgot to label the cars in this image.'

client.add_issue(sample_uuid, description)
Parameters

  • sample_uuid (str) – The sample uuid.

  • description (str) – The issue description.

  • status (IssueStatus) – The issue status. One of OPEN or CLOSED. Defaults to OPEN.

Raises
Return type

Issue

Update an issue#

SegmentsClient.update_issue(uuid, description=None, status=None)[source]#

Add an issue to a sample.

uuid = '602a3eec-a61c-4a77-9fcc-3037ce5e9606'
description = 'You forgot to label the cars in this image.'

client.update_issue(sample_uuid, description)
Parameters

  • uuid (str) – The issue uuid.

  • description (Optional[str]) – The issue description. Defaults to None.

  • status (Optional[IssueStatus]) – The issue status. One of OPEN or CLOSED. Defaults to None.

Raises
Return type

Issue

Delete an issue#

SegmentsClient.delete_issue(uuid)[source]#

Delete an issue.

uuid = '602a3eec-a61c-4a77-9fcc-3037ce5e9606'
client.delete_issue(uuid)
Parameters

uuid (str) – The issue uuid.

Raises
Return type

None

Releases#

List releases#

SegmentsClient.get_releases(dataset_identifier)[source]#

Get the releases in a dataset.

dataset_identifier = 'jane/flowers'
releases = client.get_releases(dataset_identifier)
for release in releases:
    print(release.name, release.description, release.attributes.url)
Parameters

dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

Raises
Return type

List[Release]

Get a release#

SegmentsClient.get_release(dataset_identifier, name)[source]#

Get a release.

dataset_identifier = 'jane/flowers'
name = 'v0.1'
release = client.get_release(dataset_identifier, name)
print(release)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • name (str) – The name of the release.

Raises

  • ValidationError – If validation of the release fails.

  • APILimitError – If the API limit is exceeded.

  • NotFoundError – If the dataset or release is not found.

  • NetworkError – If the request is not valid (e.g., if the dataset does not exist) or if the server experienced an error.

  • TimeoutError – If the request times out.

Return type

Release

Create a release#

SegmentsClient.add_release(dataset_identifier, name, description='')[source]#

Add a release to a dataset.

dataset_identifier = 'jane/flowers'
name = 'v0.1'
description = 'My first release.'
release = client.add_release(dataset_identifier, name, description)
print(release)

# Wait for the release to be created
while release.status == ReleaseStatus.PENDING:
    release = client.get_release(dataset_identifier, name)
    sleep(5)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • name (str) – The name of the release.

  • description (str) – The release description. Defaults to ''.

Raises
Return type

Release

Delete a release#

SegmentsClient.delete_release(dataset_identifier, name)[source]#

Delete a release.

dataset_identifier = 'jane/flowers'
name = 'v0.1'
client.delete_release(dataset_identifier, name)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • name (str) – The name of the release.

Raises
Return type

None

Workunits#

List workunits#

SegmentsClient.get_workunits(dataset_identifier, sort='created_at', direction='desc', start=None, end=None, per_page=1000, page=1)[source]#

Get the workunits in a dataset.

dataset_identifier = 'jane/flowers'
workunits = client.get_workunits(dataset_identifier)
for workunit in workunits:
    print(workunit.created_at)
Parameters

  • dataset_identifier (str) – The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.

  • sort (Literal[‘created_at’]) – What to sort results by. One of created_at. Defaults to created_at.

  • direction (Literal[‘asc’, ‘desc’]) – Sorting direction. One of asc (ascending) or desc (descending). Defaults to desc.

  • start (Optional[str]) – The start datetime for filtering workunits. Must be in the format ‘YYYY-MM-DDTHH:MM:SS’. Defaults to None.

  • end (Optional[str]) – The end datetime for filtering workunits. Must be in the format ‘YYYY-MM-DDTHH:MM:SS’. Defaults to None.

  • per_page (int) – Pagination parameter indicating the maximum number of results to return. Defaults to 1000.

  • page (int) – Pagination parameter indicating the page to return. Defaults to 1.

Raises
Return type

List[Workunit]

Upload an asset to Segments’ S3 bucket#

SegmentsClient.upload_asset(file, filename='label.png')[source]#

Upload an asset.

filename = '/home/jane/flowers/violet.jpg'
with open(filename, 'rb') as f:
    filename = 'violet.jpg'
    asset = client.upload_asset(f, filename)
image_url = asset.url
print(image_url)
Parameters

  • file (Union[TextIO, BinaryIO]) – A file object.

  • filename (str) – The file name. Defaults to label.png.

Raises
Return type

File