roboto.domain.comments#

Comments module for the Roboto SDK.

This module provides functionality for creating, retrieving, updating, and deleting comments on various Roboto platform entities such as datasets, files, actions, invocations, triggers, and collections.

Comments support @mention syntax to notify users and can be queried by entity, entity type, user, or organization. The module includes both the high-level Comment domain entity and supporting data structures for API operations.

Submodules#

Package Contents#

class roboto.domain.comments.Comment(record, roboto_client=None)#

A comment attached to a Roboto platform entity.

Comments provide a way to add contextual information, feedback, or discussion to various Roboto platform resources including datasets, files, actions, invocations, triggers, and collections. Comments support @mention syntax using the format @[display_name](user_id) to notify specific users.

Comments are created through the create() class method and cannot be instantiated directly. They can be retrieved by entity, entity type, user, or organization using the various class methods provided.

Each comment tracks creation and modification metadata, including timestamps and user information. Comments can be updated or deleted by authorized users.

Note

Comments cannot be instantiated directly through the constructor. Use create() to create new comments or the various retrieval methods to access existing comments.

Parameters:
property comment_id: str#

Unique identifier for this comment.

Return type:

str

classmethod create(comment_text, entity_id, entity_type, roboto_client=None, caller_org_id=None)#

Create a new comment on a Roboto platform entity.

Creates a comment attached to the specified entity. The comment text can include @mention syntax to notify users using the format @[display_name](user_id).

Parameters:

  • comment_text (str) – The text content of the comment. May include @mention syntax to notify users.

  • entity_id (str) – Unique identifier of the entity to attach the comment to.

  • entity_type (roboto.domain.comments.record.CommentEntityType) – Type of entity being commented on.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional Roboto client instance. If not provided, uses the default client.

  • caller_org_id (Optional[str]) – Optional organization ID of the caller. If not provided, uses the organization from the client context.

Returns:

A new Comment instance representing the created comment.

Raises:
Return type:

Comment

Examples

>>> from roboto.domain import comments
>>> # Create a comment on a dataset
>>> comment = comments.Comment.create(
...     comment_text="This dataset looks good!",
...     entity_id="ds_1234567890abcdef",
...     entity_type=comments.CommentEntityType.Dataset
... )
>>> print(comment.comment_id)
cm_abcdef1234567890

>>> # Create a comment with user mentions
>>> comment = comments.Comment.create(
...     comment_text="@[John Doe](john.doe@example.com) please review this",
...     entity_id="fl_9876543210fedcba",
...     entity_type=comments.CommentEntityType.File
... )
property created: datetime.datetime#

Timestamp when the comment was created.

Return type:

datetime.datetime

property created_by: str#

User ID of the comment author.

Return type:

str

delete_comment()#

Delete this comment permanently.

Removes the comment from the platform. This action cannot be undone. Only the comment author or users with appropriate permissions can delete a comment.

Raises:
Return type:

None

Examples

>>> from roboto.domain import comments
>>> comment = comments.Comment.from_id("cm_1234567890abcdef")
>>> comment.delete_comment()
# Comment is now permanently deleted
classmethod for_entity(entity_type, entity_id, owner_org_id=None, page_token=None, roboto_client=None)#

Retrieve all comments for a specific entity.

Fetches all comments attached to a particular entity, such as a dataset, file, action, invocation, trigger, or collection. Results are paginated and returned in chronological order.

Parameters:

  • entity_type (roboto.domain.comments.record.CommentEntityType) – Type of entity to retrieve comments for.

  • entity_id (str) – Unique identifier of the entity.

  • owner_org_id (Optional[str]) – Optional organization ID that owns the entity. If not provided, uses the organization from the client context.

  • page_token (Optional[str]) – Optional pagination token to retrieve the next page of results. Use None to start from the beginning.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional Roboto client instance. If not provided, uses the default client.

Returns:

  • A sequence of Comment instances for the entity

  • An optional pagination token for the next page, or None if no more pages are available

Return type:

A tuple containing

Raises:

Examples

>>> from roboto.domain import comments
>>> # Get all comments for a dataset
>>> comments_list, next_token = comments.Comment.for_entity(
...     entity_type=comments.CommentEntityType.Dataset,
...     entity_id="ds_1234567890abcdef"
... )
>>> print(f"Found {len(comments_list)} comments")
Found 5 comments

>>> # Paginate through comments
>>> all_comments = []
>>> page_token = None
>>> while True:
...     comments_page, page_token = comments.Comment.for_entity(
...         entity_type=comments.CommentEntityType.File,
...         entity_id="fl_9876543210fedcba",
...         page_token=page_token
...     )
...     all_comments.extend(comments_page)
...     if page_token is None:
...         break
classmethod for_entity_type(entity_type, owner_org_id=None, page_token=None, roboto_client=None)#

Retrieve all comments for a specific entity type.

Fetches all comments attached to entities of a particular type within an organization. For example, retrieve all comments on datasets or all comments on files. Results are paginated and returned in chronological order.

Parameters:

  • entity_type (roboto.domain.comments.record.CommentEntityType) – Type of entities to retrieve comments for.

  • owner_org_id (Optional[str]) – Optional organization ID to scope the search to. If not provided, uses the organization from the client context.

  • page_token (Optional[str]) – Optional pagination token to retrieve the next page of results. Use None to start from the beginning.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional Roboto client instance. If not provided, uses the default client.

Returns:

  • A sequence of Comment instances for the entity type

  • An optional pagination token for the next page, or None if no more pages are available

Return type:

A tuple containing

Raises:

RobotoUnauthorizedException – If the user lacks permission to access comments for the specified entity type.

Examples

>>> from roboto.domain import comments
>>> # Get all comments on datasets in the organization
>>> dataset_comments, next_token = comments.Comment.for_entity_type(
...     entity_type=comments.CommentEntityType.Dataset
... )
>>> print(f"Found {len(dataset_comments)} dataset comments")
Found 12 dataset comments

>>> # Get all comments on action invocations
>>> invocation_comments, _ = comments.Comment.for_entity_type(
...     entity_type=comments.CommentEntityType.Invocation,
...     owner_org_id="og_1234567890abcdef"
... )
classmethod for_user(user_id, owner_org_id=None, page_token=None, roboto_client=None)#

Retrieve all comments created by a specific user.

Fetches all comments authored by the specified user within an organization. Results are paginated and returned in chronological order.

Parameters:

  • user_id (str) – Unique identifier of the user whose comments to retrieve.

  • owner_org_id (Optional[str]) – Optional organization ID to scope the search to. If not provided, uses the organization from the client context.

  • page_token (Optional[str]) – Optional pagination token to retrieve the next page of results. Use None to start from the beginning.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional Roboto client instance. If not provided, uses the default client.

Returns:

  • A sequence of Comment instances created by the user

  • An optional pagination token for the next page, or None if no more pages are available

Return type:

A tuple containing

Raises:

RobotoUnauthorizedException – If the user lacks permission to access comments by the specified user.

Examples

>>> from roboto.domain import comments
>>> # Get all comments by a specific user
>>> user_comments, next_token = comments.Comment.for_user(
...     user_id="john.doe@example.com"
... )
>>> print(f"User has created {len(user_comments)} comments")
User has created 8 comments

>>> # Get comments by user in a specific organization
>>> org_user_comments, _ = comments.Comment.for_user(
...     user_id="jane.smith@example.com",
...     owner_org_id="og_1234567890abcdef"
... )
classmethod from_id(comment_id, owner_org_id=None, roboto_client=None)#

Retrieve a comment by its unique identifier.

Fetches a specific comment using its comment ID. The caller must have permission to access the comment and its associated entity.

Parameters:

  • comment_id (str) – Unique identifier of the comment to retrieve.

  • owner_org_id (Optional[str]) – Optional organization ID that owns the comment. If not provided, uses the organization from the client context.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional Roboto client instance. If not provided, uses the default client.

Returns:

A Comment instance representing the retrieved comment.

Raises:
Return type:

Comment

Examples

>>> from roboto.domain import comments
>>> # Retrieve a specific comment
>>> comment = comments.Comment.from_id("cm_1234567890abcdef")
>>> print(comment.record.comment_text)
This is the comment text

>>> # Retrieve a comment from a specific organization
>>> comment = comments.Comment.from_id(
...     comment_id="cm_abcdef1234567890",
...     owner_org_id="og_fedcba0987654321"
... )
property modified: datetime.datetime#

Timestamp when the comment was last modified.

Return type:

datetime.datetime

property modified_by: str#

User ID of the user who last modified this comment.

Return type:

str

classmethod recent_for_org(owner_org_id=None, page_token=None, roboto_client=None)#

Retrieve recent comments for an organization.

Fetches the most recently created or modified comments within an organization, across all entity types. Results are paginated and returned in reverse chronological order (most recent first).

Parameters:

  • owner_org_id (Optional[str]) – Optional organization ID to retrieve comments for. If not provided, uses the organization from the client context.

  • page_token (Optional[str]) – Optional pagination token to retrieve the next page of results. Use None to start from the beginning.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional Roboto client instance. If not provided, uses the default client.

Returns:

  • A sequence of Comment instances ordered by recency

  • An optional pagination token for the next page, or None if no more pages are available

Return type:

A tuple containing

Raises:

RobotoUnauthorizedException – If the user lacks permission to access comments in the organization.

Examples

>>> from roboto.domain import comments
>>> # Get recent comments in the organization
>>> recent_comments, next_token = comments.Comment.recent_for_org()
>>> print(f"Found {len(recent_comments)} recent comments")
Found 10 recent comments

>>> # Get recent comments for a specific organization
>>> org_comments, _ = comments.Comment.recent_for_org(
...     owner_org_id="og_1234567890abcdef"
... )
>>> if org_comments:
...     print(f"Most recent comment: {org_comments[0].record.comment_text}")
property record: roboto.domain.comments.record.CommentRecord#

The underlying CommentRecord data structure.

Return type:

roboto.domain.comments.record.CommentRecord

update_comment(comment_text)#

Update the text content of this comment.

Modifies the comment text and updates the modification timestamp. The updated comment text can include @mention syntax to notify users. Only the comment author or users with appropriate permissions can update a comment.

Parameters:

comment_text (str) – New text content for the comment. May include @mention syntax to notify users.

Returns:

This Comment instance with updated content.

Raises:
Return type:

Comment

Examples

>>> from roboto.domain import comments
>>> comment = comments.Comment.from_id("cm_1234567890abcdef")
>>> updated_comment = comment.update_comment("Updated text content")
>>> print(updated_comment.record.comment_text)
Updated text content

>>> # Update with mentions
>>> comment.update_comment("@[Jane Doe](jane.doe@example.com) please check this")
class roboto.domain.comments.CommentEntityType#

Bases: str, enum.Enum

Enumeration of Roboto platform entities that support comments.

This enum defines the types of resources in the Roboto platform that can have comments attached to them. Each value corresponds to a specific domain entity type.

Action = 'action'#

Actions that can be executed on the platform.

Collection = 'collection'#

Collections of related datasets or resources.

Dataset = 'dataset'#

Datasets containing uploaded data files.

File = 'file'#

Individual files within datasets.

Invocation = 'invocation'#

Executions of actions with specific inputs.

Trigger = 'trigger'#

Automated triggers for action execution.

class roboto.domain.comments.CommentRecord(/, **data)#

Bases: pydantic.BaseModel

A wire-transmissible representation of a comment.

This model represents the complete data structure of a comment as stored and transmitted by the Roboto platform API. It includes all metadata about the comment including creation/modification timestamps, user mentions, and the associated entity information.

Parameters:

data (Any)

comment_id: str#

Unique identifier for this comment.

comment_text: str#

The text content of the comment, may include @mention syntax.

created: datetime.datetime#

Timestamp when the comment was created.

Stored as datetime.datetime in Python but serialized as ISO 8601 string in UTC when transmitted over the API.

created_by: str#

User ID of the comment author.

entity_id: str#

Unique identifier of the entity this comment is attached to.

entity_type: CommentEntityType#

Type of entity this comment is attached to.

mentions: list[str] = None#

List of user IDs mentioned in this comment using @mention syntax.

modified: datetime.datetime#

Timestamp when the comment was last modified.

Stored as datetime.datetime in Python but serialized as ISO 8601 string in UTC when transmitted over the API.

modified_by: str#

User ID of the user who last modified this comment.

org_id: str#

Organization ID that owns this comment (partition key).

class roboto.domain.comments.CreateCommentRequest(/, **data)#

Bases: pydantic.BaseModel

Request payload for creating a new comment.

This model defines the required information to create a comment on a Roboto platform entity.

Parameters:

data (Any)

comment_text: str#

Text content of the comment, may include @mention syntax.

entity_id: str#

Unique identifier of the entity to attach the comment to.

entity_type: roboto.domain.comments.record.CommentEntityType#

Type of entity to attach the comment to.

class roboto.domain.comments.UpdateCommentRequest(/, **data)#

Bases: pydantic.BaseModel

Request payload for updating an existing comment.

This model defines the information that can be modified when updating a comment.

Parameters:

data (Any)

comment_text: str#

Updated text content of the comment, may include @mention syntax.

On this page