Usage

Initialization

__init__

Initialize the client.

Parameters:

Name	Type	Description	Default
base_url	str	The base url of the Doccano instance	required
verify	str | bool	Either a boolean, in which case it controls whether we verify the server's TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True. When set to False, requests will accept any TLS certificate presented by the server, and will ignore hostname mismatches and/or expired certificates, which will make your application vulnerable to man-in-the-middle (MitM) attacks. Setting verify to False may be useful during local development or testing.	None

Authentication

login

Login to a session with the Doccano instance related to the base url.

Parameters:

Name	Type	Description	Default
username	str	The username of the user.	required
password	str	The password of the user.	required

logout

Logout from the session.

User

search_users

Search users by name.

Parameters:

Name	Type	Description	Default
name	str	The name of the user to search for.	''

Returns:

Type	Description
List[User]	List[User]: The list of the users.

find_user_by_name

Find a user by name.

Parameters:

Name	Type	Description	Default
name	str	The name of the user.	required

Returns:

Name	Type	Description
User	User	The found user.

create_user

Create new user.

Parameters:

Name	Type	Description	Default
username	str	the username of the user to be created	required
password	str	the password to set for the new user	required

Returns:

Name	Type	Description
User	User	the newly created user info

User Details

get_profile

Return the profile of the logged in user.

Returns:

Name	Type	Description
User	User	The profile of the logged in user.

change_current_user_password

Change the current user's password

Parameters:

Name	Type	Description	Default
password	str	the new password to set for the current user	required
confirm_password	str	confirm the new password to set for the current user	required

Returns:

Name	Type	Description
PasswordUpdated	PasswordUpdated	Message confirming password change.

update_current_user_details

Update either username, first name or last name of the current user. If any args are left as None the current info will be kept

Parameters:

Name	Type	Description	Default
username	str	The username to change the current user to.	None
first_name	str	The first name to change the current user to.	None
last_name	str	The last name to change the current user to	None

Returns:

Name	Type	Description
UserDetails	UserDetails	the updated user login info

Role

list_roles

Return all roles.

Returns:

Type	Description
List[Role]	List[Role]: The list of roles.

Project

find_project_by_id

Find a project by id.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project to find.	required

Returns:

Name	Type	Description
Project	Project	The found project.

list_projects

Return all projects in which you are a member.

Yields:

Name	Type	Description
Project	Iterator[Project]	The next project.

create_project

Create a new project. ProjectType is one of the DocumentClassification, SequenceLabeling, Seq2seq, Speech2text, ImageClassification, BoundingBox, Segmentation, ImageCaptioning, and IntentDetectionAndSlotFilling.

Parameters:

Name	Type	Description	Default
name	str	The name of the project.	required
project_type	ProjectType	The type of the project.	required
description	str	The description of the project.	required
guideline	str	The annotation guideline. Defaults to "".	''
random_order	bool	Whether to shuffle the uploaded data. Defaults to False.	False
collaborative_annotation	bool	If True, a data can be annotated by multiple users. Defaults to False.	False
single_class_classification	bool	If True, only one label can apply a data. Defaults to False.	False
allow_overlapping	bool	If True, span overlapping is allowed. Defaults to False.	False
grapheme_mode	bool	If True, count multi-byte characters as one character. Defaults to False.	False
use_relation	bool	If True, relation labeling is allowed. Defaults to False.	False
tags	Optional[List[str]]	The tags of the project. Defaults to None.	None

Returns:

Name	Type	Description
Project	Project	The created project.

update_project

Update a project. ProjectType is one of the DocumentClassification, SequenceLabeling, Seq2seq, Speech2text, ImageClassification, BoundingBox, Segmentation, ImageCaptioning, and IntentDetectionAndSlotFilling.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
name	str	The name of the project.	None
project_type	ProjectType	The type of the project.	None
description	str	The description of the project. Defaults to None.	None
guideline	str	The annotation guideline. Defaults to None.	None
random_order	bool	Whether to shuffle the uploaded data. Defaults to None.	None
collaborative_annotation	bool	If True, a data can be annotated by multiple users. Defaults to None.	None
single_class_classification	bool	If True, only one label can apply a data. Defaults to None.	None
allow_overlapping	bool	If True, span overlapping is allowed. Defaults to None.	None
grapheme_mode	bool	If True, count multi-byte characters as one character. Defaults to None.	None
use_relation	bool	If True, relation labeling is allowed. Defaults to None.	None
tags	Optional[List[str]]	The tags of the project. Defaults to None.	None

Returns:

Name	Type	Description
Project	Project	The updated project.

delete_project

Delete a project.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required

Member

find_member_by_id

Find a member by id.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project to find.	required
member_id	int	The id of the member to find.	required

Returns:

Name	Type	Description
Member	Member	The found member.

list_members

Return all members.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required

Returns:

Type	Description
List[Member]	List[Member]: The members in the project.

add_member

Create a new member.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
username	str	The username of the future member.	required
role_name	str	The role of the future member.	required

Returns:

Name	Type	Description
Member	Member	The created member.

update_member

Update a member role.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
member_id	int	The id of the member.	required
role_name	str	The role of the member.	required

Returns:

Name	Type	Description
Member	Member	The updated member.

delete_member

Delete a member.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
member_id	int	The id of the member.	required

bulk_delete_members

Delete multiple members.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
member_ids	List[int]	The ids of the members.	required

Label Type

find_label_type_by_id

Find a label type by id.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
label_type_id	int	The label type id.	required
type	Literal['category', 'span', 'relation']	The type of the label type.	required

Returns:

Name	Type	Description
LabelType	LabelType	The found label type.

list_label_types

Return all label types in a project.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
type	Literal['category', 'span', 'relation']	The type of the label type.	required

Returns:

Type	Description
List[LabelType]	List[LabelType]: The list of label types.

create_label_type

Create a new label type.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
type	Literal['category', 'span', 'relation']	The type of the label type.	required
text	str	The name of the label type.	required
prefix_key	PREFIX_KEY	The prefix key of the label type.	None
suffix_key	SUFFIX_KEY	The suffix key of the label type.	None
color	str	The color of the label type. Defaults to None.	None

Returns:

Name	Type	Description
LabelType	LabelType	The created label type.

update_label_type

Update a label type.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
label_type_id	int	The label type id.	required
type	Literal['category', 'span', 'relation']	The type of the label type.	required
text	str	The name of the label type.	None
prefix_key	PREFIX_KEY	The prefix key of the label type.	-1
suffix_key	SUFFIX_KEY	The suffix key of the label type.	-1
color	str	The color of the label type. Defaults to None.	None

Returns:

Name	Type	Description
LabelType	LabelType	The updated label type.

delete_label_type

Delete a label type.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
label_type_id	int	The label type id.	required
type	Literal['category', 'span', 'relation']	The type of the label type.	required

bulk_delete_label_types

Delete multiple label types.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
label_type_ids	List[int]	The label type ids.	required
type	Literal['category', 'span', 'relation']	The type of the label type.	required

upload_label_type

Upload a label type.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
file_path	str	The path to the file to upload.	required
type	Literal['category', 'span', 'relation']	The type of the label type.	required

Example

find_example_by_id

Find an example by id.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Returns:

Name	Type	Description
Example	Example	The found example.

list_examples

Return all examples.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
is_confirmed	bool	Filter by confirmed state. Defaults to None.	None

Yields:

Name	Type	Description
Example	Iterator[Example]	The examples in the project.

create_example

Create a new example.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
text	str	The text of the example.	required
score	float	The confidence score of the example. Defaults to 100.	100.0
meta	Dict[str, Any]	The meta data of the example.	None

Returns:

Name	Type	Description
Example	Example	The created example.

update_example

Update an example.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
text	str	The text of the example.	None
score	float	The confidence score of the example.	None
meta	Dict[str, Any]	The meta data of the example.	None

Returns:

Name	Type	Description
Example	Example	The updated example.

delete_example

Delete an example.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

bulk_delete_examples

Delete multiple examples.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_ids	List[int]	The ids of the examples.	required

delete_all_examples

Delete all examples.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required

update_example_state

Update the state of an example.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Comment

find_comment_by_id

Find a comment by id.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
comment_id	int	The id of the comment.	required

Returns:

Name	Type	Description
Comment	Comment	The found comment.

list_comments

Return all comments.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
query	str	The query string to filter comments.	''

Yields:

Name	Type	Description
Comment	Iterator[Comment]	The comments in the project.

create_comment

Create a new comment.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
text	str	The text of the comment.	required

Returns:

Name	Type	Description
Comment	Comment	The created comment.

update_comment

Update a comment.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
comment_id	int	The id of the comment.	required
text	str	The text of the comment.	required

Returns:

Name	Type	Description
Comment	Comment	The updated comment.

delete_comment

Delete a comment.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
comment_id	int	The id of the comment.	required

bulk_delete_comments

Delete multiple comments.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
comment_ids	List[int]	The ids of the comments.	required

Data Upload

list_upload_options

Return all upload options.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required

Returns:

Type	Description
List[DataImportOption]	List[Option]: The list of the upload options.

upload

Upload a file. task is one of the DocumentClassification, SequenceLabeling, Seq2seq, Speech2text, ImageClassification, BoundingBox, Segmentation, ImageCaptioning, , IntentDetectionAndSlotFilling, and RelationExtraction.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
file_paths	List[str]	The list of the file paths.	required
task	Task	The task of the upload.	required
format	str	The format of the upload.	required
column_data	str	The column name of the data.	'text'
column_label	str	The column name of the label.	'label'

Returns:

Name	Type	Description
TaskStatus	TaskStatus	The status of the upload task.

Data Download

list_download_options

Return all download options.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required

Returns:

Type	Description
List[DataExportOption]	List[Option]: The list of the download options.

download

Download a file.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
format	str	The format of the download.	required
only_approved	bool	Whether to export approved data only.	False
dir_name	str	The directory to save the file.	'.'

Returns:

Type	Description
pathlib.Path	pathlib.Path: The path to the downloaded file.

Metrics

get_progress

Get the authenticated user's progress.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required

Returns:

Name	Type	Description
Progress	Progress	The user's progress.

get_members_progress

Return all metricss in which you are a member.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required

Returns:

Type	Description
List[MemberProgress]	List[MemberProgress]: The list of the member progress.

get_label_distribution

Return label distribution.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
type	Literal['category', 'span', 'relation']	The type of the label.	required

Returns:

Name	Type	Description
LabelDistribution	List[LabelDistribution]	The label distribution.

Raises:

Type	Description
ValueError	If the type is invalid.

Category

find_category_by_id

Find a category by id.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project to find.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label to find.	required

Returns:

Name	Type	Description
Category	Category	The found category.

list_categories

Return all categories.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Returns:

Type	Description
List[Category]	List[Category]: The categories in the project.

create_category

Create a new category label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
label	int | str	The label to create.	required
human_annotated	bool	Whether the label is human annotated. Defaults to False.	False
confidence	float	The confidence of the label. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
Category	Category	The created category label.

update_category

Update a category label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required
label	int | str	The label to create.	None
human_annotated	bool	Whether the label is human annotated. Defaults to None.	None
confidence	float	The confidence of the label. Defaults to None.	None

Returns:

Name	Type	Description
Category	Category	The updated category label.

delete_category

Delete a category.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
example_id	int	The id of the example.	required
label_id	int	The label id.	required

delete_all_categories

Delete all categories.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Span

find_span_by_id

Find a span by id.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project to find.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required

Returns:

Name	Type	Description
Span	Span	The found span.

list_spans

Return all spans.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Returns:

Type	Description
List[Span]	List[Span]: The spans in the project.

create_span

Create a new span label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
start_offset	int	The start offset of the span.	required
end_offset	int	The end offset of the span.	required
label	int | str	The label to create.	required
human_annotated	bool	Whether the label is human annotated. Defaults to False.	False
confidence	float	The confidence of the label. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
Span	Span	The created span label.

update_span

Update a span label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required
start_offset	int	The start offset of the span.	None
end_offset	int	The end offset of the span.	None
label	int | str	The label to create.	None
human_annotated	bool	Whether the label is human annotated. Defaults to None.	None
confidence	float	The confidence of the label. Defaults to None.	None

Returns:

Name	Type	Description
Span	Span	The updated span label.

delete_span

Delete a span.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
example_id	int	The id of the example.	required
label_id	int	The label id.	required

delete_all_spans

Delete all spans.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Relation

find_relation_by_id

Find a relation by id.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project to find.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required

Returns:

Name	Type	Description
Relation	Relation	The found relation.

list_relations

Return all relations.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Returns:

Type	Description
List[Relation]	List[Relation]: The relations in the project.

create_relation

Create a new relation label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
from_id	int	The id of the from span.	required
to_id	int	The id of the to span.	required
label	int | str	The label to create.	required
human_annotated	bool	Whether the label is human annotated. Defaults to False.	False
confidence	float	The confidence of the label. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
Relation	Relation	The created relation label.

update_relation

Update a relation label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required
from_id	int	The id of the from span.	None
to_id	int	The id of the to span.	None
label	int | str	The label to create.	None
human_annotated	bool	Whether the label is human annotated. Defaults to None.	None
confidence	float	The confidence of the label. Defaults to None.	None

Returns:

Name	Type	Description
Relation	Relation	The updated relation label.

delete_relation

Delete a relation.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
example_id	int	The id of the example.	required
label_id	int	The label id.	required

delete_all_relations

Delete all relations.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Text

find_text_by_id

Find a text by id.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project to find.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required

Returns:

Name	Type	Description
Text	Text	The found text.

list_texts

Return all texts.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Returns:

Type	Description
List[Text]	List[Text]: The texts in the project.

create_text

Create a new text label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
text	str	The text to create.	required
human_annotated	bool	Whether the label is human annotated. Defaults to False.	False
confidence	float	The confidence of the label. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
Text	Text	The created text label.

update_text

Update a text label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required
text	str	The text to update.	None
human_annotated	bool	Whether the label is human annotated. Defaults to None.	None
confidence	float	The confidence of the label. Defaults to None.	None

Returns:

Name	Type	Description
Text	Text	The updated text label.

delete_text

Delete a text.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
example_id	int	The id of the example.	required
label_id	int	The label id.	required

delete_all_texts

Delete all texts.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Bounding Box

find_bounding_box_by_id

Find a bounding box by id.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project to find.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required

Returns:

Name	Type	Description
BoundingBox	BoundingBox	The found bounding box.

list_bounding_boxes

Return all bounding boxes.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Returns:

Type	Description
List[BoundingBox]	List[BoundingBox]: The bounding boxes in the project.

create_bounding_box

Create a new bounding box label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
x	float	The x coordinate of the bounding box.	required
y	float	The y coordinate of the bounding box.	required
width	float	The width of the bounding box.	required
height	float	The height of the bounding box.	required
label	int | str	The label to create.	required
human_annotated	bool	Whether the label is human annotated. Defaults to False.	False
confidence	float	The confidence of the label. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
BoundingBox	BoundingBox	The created bounding box label.

update_bounding_box

Update a bounding box label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required
x	float	The x coordinate of the bounding box.	None
y	float	The y coordinate of the bounding box.	None
width	float	The width of the bounding box.	None
height	float	The height of the bounding box.	None
label	int | str	The label to create.	None
human_annotated	bool	Whether the label is human annotated. Defaults to None.	None
confidence	float	The confidence of the label. Defaults to None.	None

Returns:

Name	Type	Description
BoundingBox	BoundingBox	The updated bounding box label.

delete_bounding_box

Delete a bounding box.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
example_id	int	The id of the example.	required
label_id	int	The label id.	required

delete_all_bounding_boxes

Delete all bounding boxes.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Segment

find_segment_by_id

Find a segment by id.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project to find.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required

Returns:

Name	Type	Description
Segment	Segment	The found segment.

list_segments

Return all segments.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required

Returns:

Type	Description
List[Segment]	List[Segment]: The segments in the project.

create_segment

Create a new segment label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
points	List[float]	The points of the segment.	required
label	int | str	The label to create.	required
human_annotated	bool	Whether the label is human annotated. Defaults to False.	False
confidence	float	The confidence of the label. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
Segment	Segment	The created segment label.

update_segment

Update a segment label.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required
label_id	int	The id of the label.	required
points	List[float]	The points of the segment.	None
label	int | str	The label to create.	None
human_annotated	bool	Whether the label is human annotated. Defaults to None.	None
confidence	float	The confidence of the label. Defaults to None.	None

Returns:

Name	Type	Description
Segment	Segment	The updated segment label.

delete_segment

Delete a segment.

Parameters:

Name	Type	Description	Default
project_id	int	The project id.	required
example_id	int	The id of the example.	required
label_id	int	The label id.	required

delete_all_segments

Delete all segments.

Parameters:

Name	Type	Description	Default
project_id	int	The id of the project.	required
example_id	int	The id of the example.	required