roboto.domain.comments.comment#

Module Contents#

class roboto.domain.comments.comment.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")
On this page