In this tutorial you will learn how to work with projects using Encord's Python SDK.
Note
Make sure that you have a public-private key pair that you've authenticated with Encord before you start.
Creating projects
New projects are created using the create_project() method. create_project() returns a unique ID known as the <project_hash> of the created project, and the user that calls this method automatically becomes the admin of the project.
Note
Projects cannot be deleted using the SDK or the API. Use the web-app to delete projects.
# Import dependencies
from encord.user_client import EncordUserClient
#Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path='<private_key_path>')
# Create a project my specifying a title, the hashes of the datasets you'd like to attach, and a description
project_hash = user_client.create_project(
"Example project title",
["<dataset_hash_1>", "<dataset_hash_2>"],
"Example project description",
)
# Prints the hash of the project you've just created
print(project_hash)
# The <project_hash>
"046550d1-13fe-4052-ac99-e6a2d84f9b72"
Copying projects
Copying a project creates another project with the same ontology and settings. You also have the option to copy over the same users, datasets and models (which are not copied over by default).
The copy_project() method takes the following parameters, all of which are optional:
-
Copydatasets: when set to _True, the datasets from the original project will be copied over and new tasks will be created from them.
-
Copycollaborators: when set to _True, the collaborators from the original project will be copied over with their existing roles.
-
Copymodels: when set to _True, the models and their training data from the original project will be copied over.
The parameters above are set to False by default, which means that they don't need to be included if a given feature shouldn't be copied to the new project.
The copy_project() method returns the <project_hash> of the new project.
Caution
If collaborators are not copied, reviewer and label mapping settings are not copied over either.
Tip
The project hash can be found within the URL once a project has been selected:
app.encord.com/projects/view/<project_hash>/summary
The sample code below demonstrates how to copy a project in the most simple way.
# Import dependencies
from encord import EncordUserClient, Project
#Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")
# Specify the project you'd like to copy using its project hash
project = user_client.get_project("<project_hash>")
# Copy the project with attached datasets and collaborators, but without models
new_project_hash = project.copy_project(
copy_datasets=True,
copy_collaborators=True,
copy_models=False, # Not strictly needed
)
# Print the new project's hash
print(new_project_hash)
"aaaaaaaa-bbbb-cccc-eeee-ffffffffffff" # the new project's <project_hash>
The sample code below demonstrates how to copy a project in a more advanced way.
# Import dependencies
from encord import EncordUserClient
from encord.orm.project import (
CopyDatasetAction,
CopyDatasetOptions,
CopyLabelsOptions,
ReviewApprovalState
)
#Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")
# Specify the project to be copied
project = user_client.get_project("<project_hash>")
# Copy the project
project.copy_project(
new_title="foo", #specify the new project's title
new_description="bar", #specify the new project's description
copy_collaborators=True, # specify whether project collaborators should be copied to the new project
copy_datasets=CopyDatasetOptions(
action=CopyDatasetAction.CLONE, # This will also create a new dataset
dataset_title="baz", #specify the new dataset's title
dataset_description="quz", # Specify the new dataset's description
datasets_to_data_hashes_map={
"<dataset_hash>": ["<data_hash_1", "<data_hash_2"]
},
),
copy_labels=CopyLabelsOptions(
accepted_label_statuses=[ReviewApprovalState.APPROVED], # Copy over all labels in the 'Approved' state.
accepted_label_hashes=["<label_hash_1>", "<label_hash_2>"], # Copy over labels with the listed hashes.
),
)
"aaaaaaaa-bbbb-cccc-eeee-ffffffffffff" # the new project's <project_hash>
Listing existing projects
You can query and list all the available projects for a given user. In the example below, a user authenticates with Encord and then fetches all projects available using the get_projects() method.
# Import dependencies
from encord.user_client import EncordUserClient
#Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")
# List existing projects
projects = user_client.get_projects()
print(projects)
[
{
"project": {
"created_at": datetime.datetime(...),
"description": "Example description",
"last_edited_at": datetime.datetime(...),
"project_hash": "<project_hash>",
"title": "Example title"
},
"user_role": <ProjectUserRole.ADMIN: 0>
},
...
]
Tip
The get_projects() method has multiple optional arguments that allow you to perform a filtered search when querying projects. For example, if you only want projects with titles starting with “Validation”, you could use userclient.get_project(title_like="Validation%"). Other keyword arguments such as _created_before or edited_after may also be of interest.
Adding users to projects
Users can be added to an existing project using their emails. You can specify the role of the users being added using the ProjectUserRole enum. You can find more details of the different roles here.
Tip
The project hash can be found within the URL once a project has been selected:
app.encord.com/projects/view/<project_hash>/summary
Tip
For collaborative teams using our SDK, we recommend creating shared service accounts and creating SSH keys for those shared accounts. For example, to have several people create ontologies, datasets, and projects programmatically, create an email account for use with Encord (for example, [email protected]) and generate an SSH for that email account.
Below is an example of how to add two new annotators to the project. Note how all users get assigned the same role.
# Import dependencies
from encord import EncordUserClient, Project
from encord.utilities.project_user import ProjectUserRole
#Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")
# Specify the project you'd like to add users to
project = user_client.get_project("<project_hash>")
# Add users by specifying their email addresses, as well as the role these users should have.
added_users = project.add_users(
["[email protected]", "[email protected]"],
ProjectUserRole.ANNOTATOR,
)
# Print the new users added to the project
print(added_users)
View project details
To obtain details about your project:
- Complete the User authentication and
- Create a ‘project’ object. The code snippet below shows how to do this using the project hash / id.
Tip
The project hash can be found within the URL once a project has been selected:
app.encord.com/projects/view/<project_hash>/summary
# Import dependencies
from encord import EncordUserClient
# Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")
# Get project details using the "<project_hash>" as an identifier
project = user_client.get_project("<project_hash>")
View Collaborator session information
Use the list_collaborator_timers() method on a ‘project’ object to obtain session information for each collaborator that has worked on the project within a specified range of dates.
import datetime
from encord import EncordUserClient, Project
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
"<your_private_key>"
)
project: Project = user_client.get_project("<project_hash>")
for timer in project.list_collaborator_timers(
after=datetime.datetime.now(datetime.timezone.utc)
- datetime.timedelta(weeks=1)
):
print(f"Collaborator session: {timer}")