Client

encord.client provides a simple Python client that allows you to query project resources through the Encord API.

Here is a simple example for instantiating the client for a project and obtaining project info:

.. test_blurb2.py code::

from encord.client import EncordClient

client = EncordClient.initialize(‘YourProjectID’, ‘YourAPIKey’) client.get_project()

Returns:

• Project - A project record instance. See Project ORM for details.

EncordClient Objects

class EncordClient()

Encord client. Allows you to query db items associated with a project (e.g. label rows, datasets).

EncordClientDataset Objects

class EncordClientDataset(EncordClient)

DEPRECATED - prefer using the Dataset instead

get_dataset

def get_dataset() -> OrmDataset

Retrieve dataset info (pointers to data, labels).

Returns:

• OrmDataset - A dataset record instance.

Raises:

• AuthorisationError - If the dataset API key is invalid.
• ResourceNotFoundError - If no dataset exists by the specified dataset EntityId.
• UnknownError - If an error occurs while retrieving the dataset.

list_data_rows

def list_data_rows(title_eq: Optional[str] = None,
                   title_like: Optional[str] = None,
                   created_before: Optional[Union[str, datetime]] = None,
                   created_after: Optional[Union[str, datetime]] = None,
                   data_types: Optional[List[DataType]] = None,
                   data_hashes: Optional[List[str]] = None) -> List[DataRow]

Retrieve dataset rows (pointers to data, labels).

Arguments:

• title_eq - optional exact title row filter
• title_like - optional fuzzy title row filter; SQL syntax
• created_before - optional datetime row filter
• created_after - optional datetime row filter
• data_types - optional data types row filter
• data_hashes - optional list of individual data unit hashes to include

Returns:

• List[DataRow] - A list of DataRows object that match the filter

Raises:

• AuthorisationError - If the dataset API key is invalid.
• ResourceNotFoundError - If no dataset exists by the specified dataset EntityId.
• UnknownError - If an error occurs while retrieving the dataset.

add_users

def add_users(user_emails: List[str],
              user_role: DatasetUserRole) -> List[DatasetUser]

This function is documented in add_users().

upload_video

def upload_video(
        file_path: Union[str, Path],
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        title: Optional[str] = None,
        folder_uuid: Optional[uuid.UUID] = None) -> Video

This function is documented in upload_video().

create_image_group

def create_image_group(
        file_paths: Iterable[Union[str, Path]],
        max_workers: Optional[int] = None,
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        title: Optional[str] = None,
        *,
        create_video: bool = True,
        folder_uuid: Optional[uuid.UUID] = None) -> List[ImageGroup]

This function is documented in create_image_group().

create_dicom_series

def create_dicom_series(
        file_paths: Union[typing.Collection[str], typing.Collection[Path],
                          typing.Collection[Union[str, Path]]],
        title: Optional[str] = None,
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        folder_uuid: Optional[uuid.UUID] = None) -> Dict

This function is documented in create_dicom_series().

upload_image

def upload_image(
        file_path: Union[Path, str],
        title: Optional[str] = None,
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        folder_uuid: Optional[uuid.UUID] = None) -> Image

This function is documented in upload_image().

link_items

def link_items(
    item_uuids: List[uuid.UUID],
    duplicates_behavior: DataLinkDuplicatesBehavior = DataLinkDuplicatesBehavior
    .SKIP
) -> List[DataRow]

Link storage items to the dataset, creating new data rows.

Arguments:

• item_uuids - List of item UUIDs to link to the dataset
• duplicates_behavior - The behavior to follow when encountering duplicates. Defaults to SKIP. See also DataLinkDuplicatesBehavior

delete_data

def delete_data(data_hashes: Union[List[str], str])

This function is documented in delete_data().

add_private_data_to_dataset

def add_private_data_to_dataset(
        integration_id: str,
        private_files: Union[str, typing.Dict, Path, typing.TextIO],
        ignore_errors: bool = False) -> AddPrivateDataResponse

This function is documented in add_private_data_to_dataset().

add_private_data_to_dataset_start

def add_private_data_to_dataset_start(
        integration_id: str,
        private_files: Union[str, typing.Dict, Path, typing.TextIO],
        ignore_errors: bool = False,
        folder_uuid: Optional[uuid.UUID] = None) -> str

This function is documented in add_private_data_to_dataset_start().

add_private_data_to_dataset_get_result

def add_private_data_to_dataset_get_result(
        upload_job_id: str,
        timeout_seconds: int = 7 * 24 * 60 * 60) -> DatasetDataLongPolling

This function is documented in add_private_data_to_dataset_get_result().

update_data_item

def update_data_item(data_hash: str, new_title: str) -> bool

This function is documented in update_data_item().

re_encode_data

def re_encode_data(data_hashes: List[str])

This function is documented in re_encode_data().

re_encode_data_status

def re_encode_data_status(job_id: int)

This function is documented in re_encode_data_status().

run_ocr

def run_ocr(image_group_id: str) -> List[ImageGroupOCR]

This function is documented in run_ocr().

EncordClientProject Objects

class EncordClientProject(EncordClient)

DEPRECATED - prefer using the Project instead

get_project

def get_project(include_labels_metadata=True) -> OrmProject

Retrieve project info (pointers to data, labels).

Arguments:

• include_labels_metadata - if false, label row metadata information will not be returned.

Returns:

• OrmProject - A project record instance.

Raises:

• AuthorisationError - If the project API key is invalid.
• ResourceNotFoundError - If no project exists by the specified project EntityId.
• UnknownError - If an error occurs while retrieving the project.

get_project_v2

def get_project_v2() -> ProjectOrmV2

This is an internal method, do not use it directly. Use get_project() instead.

list_label_rows

def list_label_rows(
        edited_before: Optional[Union[str, datetime]] = None,
        edited_after: Optional[Union[str, datetime]] = None,
        label_statuses: Optional[List[AnnotationTaskStatus]] = None,
        shadow_data_state: Optional[ShadowDataState] = None,
        *,
        include_uninitialised_labels: bool = False,
        include_workflow_graph_node: bool = True,
        include_client_metadata: bool = False,
        include_images_data: bool = False,
        include_children: bool = False,
        label_hashes: Optional[Union[List[str], List[UUID]]] = None,
        data_hashes: Optional[Union[List[str], List[UUID]]] = None,
        data_title_eq: Optional[str] = None,
        data_title_like: Optional[str] = None,
        workflow_graph_node_title_eq: Optional[str] = None,
        workflow_graph_node_title_like: Optional[str] = None,
        include_all_label_branches: bool = False,
        branch_name: Optional[str] = None,
        client_metadata_as_signed_url: bool = False) -> List[LabelRowMetadata]

This function is documented in list_label_rows().

add_users

def add_users(user_emails: List[str],
              user_role: ProjectUserRole) -> List[ProjectUser]

This function is documented in add_users().

copy_project

def copy_project(copy_datasets: Union[bool, CopyDatasetOptions] = False,
                 copy_collaborators=False,
                 copy_models=False,
                 *,
                 copy_labels: Optional[CopyLabelsOptions] = None,
                 new_title: Optional[str] = None,
                 new_description: Optional[str] = None) -> str

This function is documented in copy_project().

get_label_row

def get_label_row(uid: str,
                  get_signed_url: bool = True,
                  *,
                  include_object_feature_hashes: Optional[
                      typing.Set[str]] = None,
                  include_classification_feature_hashes: Optional[
                      typing.Set[str]] = None,
                  include_reviews: bool = False,
                  include_export_history: bool = False) -> LabelRow

This function is documented in get_label_row().

get_label_rows

def get_label_rows(uids: List[str],
                   get_signed_url: bool = True,
                   *,
                   include_object_feature_hashes: Optional[
                       typing.Set[str]] = None,
                   include_classification_feature_hashes: Optional[
                       typing.Set[str]] = None,
                   include_reviews: bool = False,
                   include_export_history: bool = False,
                   include_archived: bool = False) -> List[LabelRow]

This function is documented in get_label_rows().

save_label_row

def save_label_row(uid, label, validate_before_saving: bool = False)

This function is documented in save_label_row().

save_label_rows

def save_label_rows(uids: List[str],
                    payload: List[LabelRow],
                    validate_before_saving: bool = False)

This function is meant for internal use, please consider using LabelRowV2 class instead

Saves multiple label rows. See save_label_row()

Arguments:

• uids - list of label hashes
• payload - list of LabelRow objects
• validate_before_saving - ????

Returns:

None

create_label_row

def create_label_row(uid, *, get_signed_url=False) -> LabelRow

This function is documented in create_label_row().

create_label_rows

def create_label_rows(uids: List[str],
                      *,
                      get_signed_url: bool = False,
                      branch_name: Optional[str] = None) -> List[LabelRow]

This function is meant for internal use, please consider using LabelRowV2 class instead

Create multiple label rows. See create_label_row()

Arguments:

• uids - list of data uids where label_status is NOT_LABELLED.
• get_signed_url - bool whether to fetch the signed url for the internal label row
• branch_name - Optional[str] which branch name against which to create the label row

Returns:

• List[LabelRow] - A list of created label rows

add_datasets

def add_datasets(dataset_hashes: List[str]) -> bool

This function is documented in add_datasets().

remove_datasets

def remove_datasets(dataset_hashes: List[str]) -> bool

This function is documented in remove_datasets().

add_object

@deprecated("0.1.102", alternative="encord.ontology.Ontology class")
def add_object(name: str, shape: ObjectShape) -> bool

This function is documented in add_object().

add_classification

@deprecated("0.1.102", alternative="encord.ontology.Ontology class")
def add_classification(name: str,
                       classification_type: ClassificationType,
                       required: bool,
                       options: Optional[Iterable[str]] = None)

This function is documented in add_classification().

object_interpolation

def object_interpolation(key_frames, objects_to_interpolate)

This function is documented in object_interpolation().

get_data

def get_data(
    data_hash: str,
    get_signed_url: bool = False
) -> Tuple[Optional[Video], Optional[List[Image]]]

This function is documented in get_data().

get_label_logs

def get_label_logs(user_hash: Optional[str] = None,
                   data_hash: Optional[str] = None,
                   from_unix_seconds: Optional[int] = None,
                   to_unix_seconds: Optional[int] = None,
                   after: Optional[datetime] = None,
                   before: Optional[datetime] = None,
                   user_email: Optional[str] = None) -> List[LabelLog]

This function is documented in get_label_logs().

workflow_reopen

def workflow_reopen(label_hashes: List[str]) -> None

This function is documented in workflow_reopen().

workflow_complete

def workflow_complete(label_hashes: List[str]) -> None

This function is documented in workflow_complete().