EncordUserClient
EncordUserClient Objects
class EncordUserClient()
get_dataset
def get_dataset(
dataset_hash: Union[str, UUID],
dataset_access_settings:
DatasetAccessSettings = DEFAULT_DATASET_ACCESS_SETTINGS
) -> Dataset
Get the Dataset class to access dataset fields and manipulate a dataset.
You only have access to this project if you are one of the following
-
Dataset admin
-
Organisation admin of the project
Arguments:
dataset_hash
- The Dataset IDdataset_access_settings
- Set the dataset_access_settings if you would like to change the defaults.
get_project
def get_project(project_hash: str) -> Project
Get the Project class to access project fields and manipulate a project.
You will only have access to this project if you are one of the following
-
Project admin
-
Project team manager
-
Organisation admin of the project
Arguments:
project_hash
- The Project ID
create_private_dataset
@deprecated("0.1.104", alternative=".create_dataset")
def create_private_dataset(
dataset_title: str,
dataset_type: StorageLocation,
dataset_description: Optional[str] = None) -> CreateDatasetResponse
DEPRECATED - please use create_dataset
instead.
create_dataset
def create_dataset(
dataset_title: str,
dataset_type: StorageLocation,
dataset_description: Optional[str] = None,
create_backing_folder: bool = True) -> CreateDatasetResponse
Arguments:
dataset_title: Title of dataset. dataset_type: StorageLocation type where data will be stored. dataset_description: Optional description of the dataset.
Returns:
CreateDatasetResponse
get_datasets
def get_datasets(
title_eq: Optional[str] = None,
title_like: Optional[str] = None,
desc_eq: Optional[str] = None,
desc_like: Optional[str] = None,
created_before: Optional[Union[str, datetime]] = None,
created_after: Optional[Union[str, datetime]] = None,
edited_before: Optional[Union[str, datetime]] = None,
edited_after: Optional[Union[str,
datetime]] = None) -> List[Dict[str, Any]]
List either all (if called with no arguments) or matching datasets the user has access to.
Arguments:
title_eq
- optional exact title filtertitle_like
- optional fuzzy title filter; SQL syntaxdesc_eq
- optional exact description filterdesc_like
- optional fuzzy description filter; SQL syntaxcreated_before
- optional creation date filter, ‘less’created_after
- optional creation date filter, ‘greater’edited_before
- optional last modification date filter, ‘less’edited_after
- optional last modification date filter, ‘greater’
Returns:
list of (role, dataset) pairs for datasets matching filter conditions.
create_with_ssh_private_key
@staticmethod
def create_with_ssh_private_key(
ssh_private_key: Optional[str] = None,
password: Optional[str] = None,
requests_settings: RequestsSettings = DEFAULT_REQUESTS_SETTINGS,
ssh_private_key_path: Optional[str | Path] = None,
**kwargs) -> EncordUserClient
Creates an instance of EncordUserClient authenticated with private SSH key. Accepts the private key content, path to key file, that can be provided as method parameters or as following environment variables:
- ENCORD_SSH_KEY: environment variable with the private key content
- ENCORD_SSH_KEY_FILE: environment variable with the path to the key file
Arguments:
ssh_private_key
- the private key contentssh_private_key_path
- the pah to the private key filepassword
- private key password
get_projects
def get_projects(
title_eq: Optional[str] = None,
title_like: Optional[str] = None,
desc_eq: Optional[str] = None,
desc_like: Optional[str] = None,
created_before: Optional[Union[str, datetime]] = None,
created_after: Optional[Union[str, datetime]] = None,
edited_before: Optional[Union[str, datetime]] = None,
edited_after: Optional[Union[str, datetime]] = None) -> List[Dict]
List either all (if called with no arguments) or matching projects the user has access to.
Arguments:
title_eq
- optional exact title filtertitle_like
- optional fuzzy title filter; SQL syntaxdesc_eq
- optional exact description filterdesc_like
- optional fuzzy description filter; SQL syntaxcreated_before
- optional creation date filter, ‘less’created_after
- optional creation date filter, ‘greater’edited_before
- optional last modification date filter, ‘less’edited_after
- optional last modification date filter, ‘greater’
Returns:
list of (role, projects) pairs for project matching filter conditions.
create_project
def create_project(project_title: str,
dataset_hashes: List[str],
project_description: str = "",
ontology_hash: str = "",
workflow_settings:
ProjectWorkflowSettings = ManualReviewWorkflowSettings(),
workflow_template_hash: Optional[str] = None) -> str
Creates a new project and returns its uid (‘project_hash’)
Arguments:
project_title
- the title of the projectdataset_hashes
- a list of the dataset uids that the project will useproject_description
- the optional description of the projectontology_hash
- the uid of an ontology to be used. If omitted, a new empty ontology will be createdworkflow_settings
- selects and configures the type of the quality control workflow to use, See :class:encord.orm.project.ProjectWorkflowSettings
for details. If omitted, :class:~encord.orm.project.ManualReviewWorkflowSettings
is used.workflow_template_hash
- project will be created using a workflow based on the template provided.
Returns:
the uid of the project.
create_project_api_key
def create_project_api_key(project_hash: str, api_key_title: str,
scopes: List[APIKeyScopes]) -> str
Returns:
The created project API key.
get_dataset_client
@deprecated("0.1.98", ".get_dataset()")
def get_dataset_client(dataset_hash: str,
dataset_access_settings:
DatasetAccessSettings = DEFAULT_DATASET_ACCESS_SETTINGS,
**kwargs) -> EncordClientDataset
DEPRECATED - prefer using :meth:get_dataset()
instead.
get_project_client
@deprecated("0.1.98", ".get_project()")
def get_project_client(
project_hash: str,
**kwargs) -> Union[EncordClientProject, EncordClientDataset]
DEPRECATED - prefer using :meth:get_project()
instead.
create_project_from_cvat
def create_project_from_cvat(
import_method: ImportMethod,
dataset_name: str,
review_mode: ReviewMode = ReviewMode.LABELLED,
max_workers: Optional[int] = None,
*,
transform_bounding_boxes_to_polygons=False
) -> Union[CvatImporterSuccess, CvatImporterError]
Export your CVAT project with the “CVAT for images 1.1” option and use this function to import your images and annotations into encord. Ensure that during you have the “Save images” checkbox enabled when exporting from CVAT.
Arguments:
import_method:
The chosen import method. See the ImportMethod
class for details.
dataset_name:
The name of the dataset that will be created.
review_mode:
Set how much interaction is needed from the labeler and from the reviewer for the CVAT labels.
See the ReviewMode
documentation for more details.
max_workers:
DEPRECATED
- This argument will be ignored transform_bounding_boxes_to_polygons: All instances of CVAT bounding boxes will be converted to polygons in the final Encord project.
Returns:
CvatImporterSuccess
- If the project was successfully imported.CvatImporterError
- If the project could not be imported.
Raises:
ValueError: If the CVAT directory has an invalid format.
get_ontologies
def get_ontologies(
title_eq: Optional[str] = None,
title_like: Optional[str] = None,
desc_eq: Optional[str] = None,
desc_like: Optional[str] = None,
created_before: Optional[Union[str, datetime]] = None,
created_after: Optional[Union[str, datetime]] = None,
edited_before: Optional[Union[str, datetime]] = None,
edited_after: Optional[Union[str, datetime]] = None) -> List[Dict]
List either all (if called with no arguments) or matching ontologies the user has access to.
Arguments:
title_eq
- optional exact title filtertitle_like
- optional fuzzy title filter; SQL syntaxdesc_eq
- optional exact description filterdesc_like
- optional fuzzy description filter; SQL syntaxcreated_before
- optional creation date filter, ‘less’created_after
- optional creation date filter, ‘greater’edited_before
- optional last modification date filter, ‘less’edited_after
- optional last modification date filter, ‘greater’
Returns:
list of (role, projects) pairs for ontologies matching filter conditions.
list_groups
def list_groups() -> Iterable[OrmGroup]
List all groups belonging to the user’s current organization.
deidentify_dicom_files
def deidentify_dicom_files(
dicom_urls: List[str],
integration_hash: str,
redact_dicom_tags: bool = True,
redact_pixels_mode: DeidentifyRedactTextMode = DeidentifyRedactTextMode
.REDACT_NO_TEXT,
save_conditions: Optional[List[SaveDeidentifiedDicomCondition]] = None,
upload_dir: Optional[str] = None) -> List[str]
Deidentify DICOM files in external storage. Given links to DICOM files pointing to AWS, GCP, AZURE or OTC, for example: [ ”https://s3.region-code.amazonaws.com/bucket-name/dicom-file-input.dcm” ] Function executes deidentification on those files, it removes all DICOM tags (https://dicom.nema.org/medical/Dicom/2017e/output/chtml/part06/chapter_6.html) from metadata except for:
- x00080018 SOPInstanceUID
- x00100010 PatientName
- x00180050 SliceThickness
- x00180088 SpacingBetweenSlices
- x0020000d StudyInstanceUID
- x0020000e SeriesInstanceUID
- x00200032 ImagePositionPatient
- x00200037 ImageOrientationPatient
- x00280008 NumberOfFrames
- x00281050 WindowCenter
- x00281051 WindowWidth
- x00520014 ALinePixelSpacing
Arguments:
self
- Encord client object.dicom_urls
- a list of urls to DICOM files, e.g.[ "https://s3.region-code.amazonaws.com/bucket-name/dicom-file-input.dcm" ]
integration_hash: integration_hash parameter of Encord platform external storage integration redact_dicom_tags: Specifies if DICOM tags redaction should be enabled. redact_pixels_mode: Specifies which text redaction policy should be applied to pixel data. save_conditions: Specifies a list of conditions which all have to be true for DICOM deidentified file to be saved. upload_dir: Specifies a directory that files will be uploaded to. By default, set to None, deidentified files will be uploaded to the same directory as source files.
Returns:
Function returns list of links pointing to deidentified DICOM files,
those will be saved to the same bucket and the same directory
as original files with prefix ( deid__ ).
Example output:
[ "https://s3.region-code.amazonaws.com/bucket-name/deid_167294769118005312_dicom-file-input.dcm" ]
create_storage_folder
def create_storage_folder(
name: str,
description: Optional[str] = None,
client_metadata: Optional[Dict[str, Any]] = None,
parent_folder: Optional[Union[StorageFolder,
UUID]] = None) -> StorageFolder
Create a new storage folder.
Arguments:
name
- The name of the folder.description
- The description of the folder.client_metadata
- Optional arbitrary metadata to be associated with the folder. Should be a dictionary that is JSON-serializable.parent_folder
- The parent folder of the folder; orNone
if the folder is to be created at the root level.
Returns:
The created storage folder. See :class:encord.storage.StorageFolder
for details.
get_storage_folder
def get_storage_folder(folder_uuid: UUID) -> StorageFolder
Get a storage folder by its UUID.
Arguments:
folder_uuid
- The UUID of the folder to retrieve.
Returns:
The storage folder. See :class:encord.storage.StorageFolder
for details.
Raises:
:class:encord.exceptions.AuthorizationError
: If the folder with the given UUID does not exist or
the user does not have access to it.
get_storage_item
def get_storage_item(item_uuid: UUID, sign_url: bool = False) -> StorageItem
Get a storage item by its UUID.
Arguments:
item_uuid
- The UUID of the item to retrieve.sign_url
- IfTrue
, pre-fetch a signed URL for the item (otherwise the URL will be signed on demand).
Returns:
The storage item. See :class:encord.storage.StorageItem
for details.
Raises:
:class:encord.exceptions.AuthorizationError
: If the item with the given UUID does not exist or
the user does not have access to it.
get_storage_items
def get_storage_items(item_uuids: List[UUID],
sign_url: bool = False) -> List[StorageItem]
Get storage items by their UUIDs, in bulk. Useful for retrieving multiple items at once, e.g. when getting
items pointed to by :attr:encord.orm.dataset.DataRow.backing_item_uuid
for all data rows of a dataset.
Arguments:
item_uuids
- list of UUIDs of items to retrieve.sign_url
- IfTrue
, pre-fetch a signed URLs for the items (otherwise the URLs will be signed on demand).
Returns:
A list of storage items. See :class:encord.storage.StorageItem
for details.
Raises:
:class:encord.exceptions.AuthorizationError
: If some of the items with the given UUIDs do not exist or
the user does not have access to them.
list_storage_folders
def list_storage_folders(*,
search: Optional[str] = None,
dataset_synced: Optional[bool] = None,
org_access: Optional[bool] = None,
order: FoldersSortBy = FoldersSortBy.NAME,
desc: bool = False,
page_size: int = 100) -> Iterable[StorageFolder]
List top-level storage folders.
Arguments:
search
- Search string to filter folders by name (optional)dataset_synced
- Include or exclude folders that are mirrored by a dataset. Optional; ifNone
, no filtering is applied.org_access
- IfTrue
, and if the caller isADMIN
of their organization, the results contain the folders belonging to the organization, instead of those accessible to the user. If enabled but the user is not an organization admin, theAuthorisationError
is raised. Default value isFalse
.order
- Sort order for the folders. See :class:encord.storage.FoldersSortBy
for available options.desc
- If True, sort in descending order.page_size
- Number of folders to return per page. Default if not specified is 100. Maximum value is 1000.
Returns:
Iterable of :class:encord.StorageFolder
objects.
find_storage_folders
def find_storage_folders(*,
search: Optional[str] = None,
dataset_synced: Optional[bool] = None,
org_access: Optional[bool] = None,
order: FoldersSortBy = FoldersSortBy.NAME,
desc: bool = False,
page_size: int = 100) -> Iterable[StorageFolder]
Recursively search for storage folders, starting from the top level.
Arguments:
search
- Search string to filter folders by name (optional)dataset_synced
- Include or exclude folders that are mirrored by a dataset. Optional; ifNone
, no filtering is applied.org_access
- IfTrue
, and if the caller isADMIN
of their organization, the results contain the folders belonging to the organization, instead of those accessible to the user. If enabled but the user is not an organization admin, theAuthorisationError
is raised. Default value isFalse
.order
- Sort order for the folders. See :class:encord.storage.FoldersSortBy
for available options.desc
- If True, sort in descending order.page_size
- Number of folders to return per page. Default if not specified is 100. Maximum value is 1000.
Returns:
Iterable of :class:encord.StorageFolder
objects.
find_storage_items
def find_storage_items(*,
search: Optional[str] = None,
is_in_dataset: Optional[bool] = None,
item_types: Optional[List[StorageItemType]] = None,
org_access: Optional[bool] = None,
order: FoldersSortBy = FoldersSortBy.NAME,
desc: bool = False,
get_signed_urls: bool = False,
page_size: int = 100) -> Iterable[StorageItem]
Recursively search for storage items, starting from the root level.
Arguments:
-
search
- Search string to filter items by name. -
is_in_dataset
- Filter items by whether they are linked to any dataset.True
andFalse
select only linked and only unlinked items, respectively.None
includes all items regardless of their dataset links. -
item_types
- Filter items by type. -
org_access
- IfTrue
, and if the caller isADMIN
of their organization, the results contain the items belonging to the organization, instead of those accessible to the user. If enabled but the user is not an organization admin, theAuthorisationError
is raised. Default value isFalse
. -
order
- Sort order. -
desc
- Sort in descending order. -
get_signed_urls
- If True, return signed URLs for the items. -
page_size
- Number of items to return per page. Default if not specified is 100. Maximum value is 1000.At least one of
search
oritem_types
must be provided.
Returns:
Iterable of items in the folder.
get_collection
def get_collection(collection_uuid: Union[str, UUID]) -> Collection
Get collection by unique identifier (UUID).
Arguments:
collection_uuid
- The unique identifier of the collection to retrieve.
Returns:
The collection. See :class:encord.collection.Collection
for details.
Raises:
:class:encord.exceptions.AuthorizationError
: If the item with the given UUID does not exist or
the user does not have access to it.
list_collections
def list_collections(top_level_folder_uuid: Union[str, UUID, None] = None,
collection_uuids: List[str | UUID] | None = None,
page_size: Optional[int] = None) -> Generator[Collection]
Get collections by top level folder or list of collection IDs. If both top_level_folder_uuid and collection_uuid_list are preset then the intersection of the two conditions is returned.
Arguments:
top_level_folder_uuid
- The unique identifier of the top level folder.collection_uuids
- The unique identifiers (UUIDs) of the collections to retrieve.page_size
int - Number of items to return per page. Default if not specified is 100. Maximum value is 1000.
Returns:
The list of collections which match the given criteria.
Raises:
:class:encord.exceptions.AuthorizationError
: If the user does not have access to it.
delete_collection
def delete_collection(collection_uuid: Union[str, UUID]) -> None
Delete a collection by its UUID if it exists.
Arguments:
collection_uuid
- The unique identifier (UUID) of the collection to delete.
Returns:
None
Raises:
:class:encord.exceptions.AuthorizationError
: If the user does not have access to it.
create_collection
def create_collection(top_level_folder_uuid: Union[str, UUID],
name: str,
description: str = "") -> Collection
Create a collection.
Arguments:
top_level_folder_uuid
- The unique identifier (UUID) of the folder that the collection is created in.name
- The name of the collection.description
- The description of the collection.
Returns:
Collection
- Newly created collection.
Raises:
:class:encord.exceptions.AuthorizationError
: If the user does not have access to the folder.
get_filter_preset
def get_filter_preset(preset_uuid: Union[str, UUID]) -> FilterPreset
Get a preset by its unique identifier (UUID).
Arguments:
preset_uuid
- The unique identifier of the preset to retrieve.
Returns:
The preset. See :class:encord.preset.Preset
for details.
Raises:
:class:encord.exceptions.AuthorizationError
: If the item with the given UUID does not exist or
the user does not have access to it.
get_filter_presets
def get_filter_presets(
preset_uuids: List[Union[str, UUID]] = [],
page_size: Optional[int] = None) -> Generator[FilterPreset]
Get presets by list of preset unique identifiers (UUIDs).
Arguments:
preset_uuids
- The list of unique identifiers (UUIDs) to be retrieved.page_size
int - Number of items to return per page. Default if not specified is 100. Maximum value is 1000.
Returns:
The list of presets which match the given criteria.
Raises:
:class:encord.exceptions.AuthorizationError
: If the user does not have access to it.
list_presets
def list_presets(top_level_folder_uuid: Union[str, UUID, None] = None,
page_size: Optional[int] = None) -> Generator[FilterPreset]
Get presets by top level folder.
Arguments:
top_level_folder_uuid
- The unique identifier of the top level folder.page_size
int - Number of items to return per page. Default if not specified is 100. Maximum value is 1000.
Returns:
The list of presets which match the given criteria.
Raises:
:class:encord.exceptions.AuthorizationError
: If the user does not have access to it.
delete_preset
def delete_preset(preset_uuid: Union[str, UUID]) -> None
Delete a preset by its unique identifier (UUID) if it exists.
Arguments:
preset_uuid
- The uuid/id of the preset to delete.
Returns:
None
Raises:
:class:encord.exceptions.AuthorizationError
: If the user does not have access to it.
Was this page helpful?