Data Models

class pyryver.objects.Object(ryver: Ryver, data: dict)

Base class for all Ryver objects.

Parameters:

ryver – The parent Ryver instance.
data – The object’s data.

get_ryver() → Ryver

Get the Ryver session this object was retrieved from.

Returns:: The Ryver session associated with this object.

get_id() → int | str

Get the ID of this object.

For a ChatMessage this is a string. For all other types, it is an int.

Returns:: The ID of this object.

get_entity_type() → str

Get the entity type of this object.

Returns:: The entity type of this object, or if no entity of such type exists, <unknown>.

get_raw_data() → dict

Get the raw data of this object.

The raw data is a dictionary directly obtained from parsing the JSON response.

Returns:: The raw data of this object.

get_api_url(*args, **kwargs) → str

Uses Ryver.get_api_url() to get a URL for working with the Ryver API.

Warning

This method is intended for internal use only.

This is equivalent to calling Ryver.get_api_url(), but with the first two parameters set to self.get_type() and self.get_id().

Returns:: The formatted URL for performing requests.

get_create_date() → str | None

Get the date this object was created as an ISO 8601 timestamp.

Note

This method does not work for all objects. For some objects, it will return None.

Tip

You can use pyryver.util.iso8601_to_datetime() to convert the timestamps returned by this method into a datetime.

Returns:: The creation date of this object, or None if not supported.

get_modify_date() → str | None

Get the date this object was last modified as an ISO 8601 timestamp.

Note

This method does not work for all objects. For some objects, it will return None.

Tip

You can use pyryver.util.iso8601_to_datetime() to convert the timestamps returned by this method into a datetime.

Returns:: The modification date of this object, or None if not supported.

get_app_link() → str

Get a link to this object that opens the app to this object.

Note

This method does not work for some types such as messages and topic/task replies. Additionally, only types with Object.is_instantiable() true can be linked to. Calling this method on an object of an invalid type will result in a TypeError.

Raises:: TypeError – If this object cannot be linked to.
Returns:: The in-app link for this object.

get_creator() → Creator | None

Get the Creator of this object.

Note that this is different from the author. Creators are used to override the display name and avatar of a user. If the username and avatar were not overridden, this will return None.

Not all objects support this operation. If not supported, this will return None.

Returns:: The overridden creator of this message.

await get_deferred_field(field: str, field_type: str) → Type[Object] | List[Type[Object]]

Get the value of a field of this object that exists, but is not included (“__deferred” in the Ryver API).

Warning

This function is intended for internal use only.

This function will automatically infer from the result’s contents whether to return a single object or a list of objects.

If the field cannot be retrieved, a ValueError will be raised.

Parameters:

field – The name of the field.
field_type – The type of the field, must be a TYPE_ constant.

Returns:

The expanded value of this field as an object or a list of objects.

Raises:

ValueError – When the field cannot be expanded.

await get_create_user() → User | None

Get the user that created this object.

Note

This method does not work for all objects. If not supported, it will return None.

Returns:: The user that created this object, or None if not supported.

await get_modify_user() → User | None

Get the user that modified this object.

Note

This method does not work for all objects. If not supported, it will return None.

Returns:: The user that last modified this object, or None if not supported.

classmethod get_type() → str

Get the type of this object.

Returns:: The type of this object.

classmethod is_instantiable() → bool

Get whether this object type is instantiable.

Some types of objects cannot be instantiated, as they are actually not a part of the REST API, such as Message, Chat, and other abstract types. If the type can be instantiated, this class method will return True.

Note that even though a type may not be instantiable, its derived types could still be. For example, Chat is not instantiable, but one of its derived types, User, is instantiable.

Returns:: Whether this type is instantiable.

classmethod await get_by_id(ryver: Ryver, obj_id: int) → Type[Object]

Retrieve an object of this type by ID.

Parameters:

ryver – The Ryver session to retrieve the object from.
obj_id – The ID of the object to retrieve.

Raises:

TypeError – If this type is not instantiable.

Returns:

The object requested.

Chats

class pyryver.objects.Chat(ryver: Ryver, data: dict)

Bases: Object

Any Ryver chat you can send messages to.

E.g. Teams, forums, user DMs, etc.

get_jid() → str

Get the JID (JabberID) of this chat.

The JID is used in the websockets interface.

Returns:: The JID of this chat.

abstractmethod get_name() → str

Get the name of this chat.

Returns:: The name of this chat.

get_task_tags() → List[TaskTag]

Get a list of task tags defined in this chat, as TaskTag objects.

Returns:: The defined task tags of this chat.

await set_task_tags(tags: Iterable[TaskTag])

Set the task tags defined in this chat.

Note

This will erase any existing tags.

This method also updates the task tags property of this object.

Parameters:: tags – The new tags as a list of TaskTag s.

await send_message(message: str, creator: Creator | None = None, attachment: Storage | File | None = None, from_user: User | None = None) → str

Send a message to this chat.

Specify a creator to override the username and profile of the message creator.

Tip

To attach a file to the message, use pyryver.ryver.Ryver.upload_file() to upload the file you wish to attach. Alternatively, use pyryver.ryver.Ryver.create_link() for a link attachment.

Warning

from_user must be set when using attachments with private messages. Otherwise, a ValueError will be raised. It should be set to the user that is sending the message (the user currently logged in).

It is not required to be set if the message is being sent to a forum/team.

Returns the ID of the chat message sent (not the message object itself). Note that message IDs are strings.

Parameters:

message – The message contents.
creator – The overridden creator; optional, if unset uses the logged-in user’s profile.
attachment – An attachment for this message, e.g. a file or a link (optional). Can be either a Storage or a File object.
from_user – The user that is sending this message (the user currently logged in); must be set when using attachments in private messages (optional).

Raises:

ValueError – If a from_user is not provided for a private message attachment.

Returns:

The ID of the chat message that was sent.

async for ... in get_topics(archived: bool = False, top: int = -1, skip: int = 0) → AsyncIterator[Topic]

Get all the topics in this chat.

Parameters:

archived – If True, only include archived topics in the results, otherwise, only include non-archived topics.
top – Maximum number of results; optional, if unspecified return all results.
skip – Skip this many results.

Returns:

An async iterator for the topics of this chat.

await get_messages(count: int, skip: int = 0) → List[ChatMessage]

Get a number of messages (most recent first) in this chat.

Parameters:

count – Maximum number of results.
skip – The number of results to skip (optional).

Returns:

A list of messages.

await get_message(msg_id: str) → ChatMessage

Get a single message from this chat by its ID.

Note

There is a chance that this method might result in a 404 Not Found for messages that were sent recently (such as when using the realtime websocket API (pyryver.ryver_ws.RyverWS) to respond to messages), as those messages have not been fully added to Ryver’s database yet.

You can use pyryver.util.retry_until_available() to wrap around this coroutine to get around this.

Parameters:: msg_id – The ID of the chat message to get.
Returns:: The message object.

await get_messages_surrounding(msg_id: str, before: int = 0, after: int = 0) → List[ChatMessage]

Get a range of messages (most recent last) before and after a chat message (given by ID).

Warning

Before and after cannot exceed 25 messages, otherwise a aiohttp.ClientResponseError will be raised with the code 400 Bad Request.

Note

There is a chance that this method might result in a 404 Not Found for messages that were sent recently (such as when using the realtime websocket API (pyryver.ryver_ws.RyverWS) to respond to messages), as those messages have not been fully added to Ryver’s database yet.

You can use pyryver.util.retry_until_available() to wrap around this coroutine to get around this.

The message with the given ID is also included as a part of the result.

Parameters:

msg_id – The ID of the message to use as the reference point.
before – How many messages to retrieve before the specified one (optional).
after – How many messages to retrieve after the specified one (optional).

Returns:

The messages requested, including the reference point message.

await get_task_board() → TaskBoard | None

Get the task board of this chat.

If tasks are not set up for this chat, this will return None.

This method works on users too. If used on a user, it will get their personal task board.

Returns:: The task board of this chat.

await delete_task_board() → bool

Delete (or “reset”, according to the UI) the task board of this chat.

This method will not yield an error even if there is no task board set up. In those cases, it will simply return false.

Returns:: Whether the task board was deleted.

await create_task_board(board_type: str, prefix: str | None = None, categories: List[str | Tuple[str, str]] | None = None, uncategorized_name: str | None = None) → TaskBoard

Create the task board for this chat if it has not yet been set up.

The board type should be one of the TaskBoard BOARD_TYPE_ constants; it specified whether this task board should be a simple list or a board with categories.

You can also specify a list of category names and optional category types to pre-populate the task board with categories. Each entry in the list should either be a string, which specifies the category name, or a tuple of the name and the type of the category (a CATEGORY_TYPE_ constant). The default category type is TaskCategory.CATEGORY_TYPE_OTHER.

An “uncategorized” category is always automatically added. Therefore, the type TaskCategory.CATEGORY_TYPE_UNCATEGORIZED cannot be used in the list. You can, however, change the name of the default “Uncategorized” category by specifying uncategorized_name.

Categories should not be specified if the type of the task board is TaskBoard.BOARD_TYPE_LIST.

Parameters:

board_type – The type of the task board.
prefix – The task prefix (optional).
categories – A list of categories and optional types to pre-populate the task board with (see above) (optional).
uncategorized_name – The name for the default “Uncategorized” category.

await delete_avatar() → None: Delete the avatar of this chat.

await set_avatar(filename: str, filedata: Any, filetype: str | None = None) → None

Set the avatar of this chat.

A wrapper for Storage.make_avatar_of() and Ryver.upload_file().

Parameters:

filename – The filename of the image.
filedata – The image’s raw data, sent directly to aiohttp.FormData.add_field().
filetype – The MIME type of the file.

class pyryver.objects.GroupChat(ryver: Ryver, data: dict)

Bases: Chat

A Ryver team or forum.

get_name() → str

Get the name of this chat.

Returns:: The name of this forum/team.

get_nickname() → str

Get the nickname of this chat.

The nickname is a unique identifier that can be used to refer to the chat across Ryver.

Returns:: The nickname of this forum/team.

has_chat() → bool

Get whether this forum/team has a chat tab.

Returns:: Whether there is a chat tab for this forum/team.

has_topics() → bool

Get whether this forum/team has a topics tab.

Returns:: Whether there is a topics tab for this forum/team.

has_tasks() → bool

Get whether this forum/team has a tasks tab.

Returns:: Whether there is a tasks tab for this forum/team.

does_announce_topics() → bool

Get whether new topics are announced with a chat message.

Returns:: Whether new topics are announced with a chat message.

does_announce_tasks() → bool

Get whether new tasks are announced with a chat message.

Returns:: Whether new tasks are announced with a chat message.

is_archived() → bool

Get whether this team/forum is archived.

Returns:: Whether the team/forum is archived.

async for ... in get_members(top: int = -1, skip: int = 0) → AsyncIterator[GroupChatMember]

Get all the members of this chat.

Note

This gets the members as GroupChatMember objects, which contain additional info such as whether the user is an admin of this chat.

To get the User object, use GroupChatMember.as_user().

Parameters:

top – Maximum number of results; optional, if unspecified return all results.
skip – Skip this many results.

Returns:

An async iterator for the members of this chat.

await get_member(user: int | User) → GroupChatMember | None

Get a member using either a User object or user ID.

Note

This gets the member as a GroupChatMember object, which contain additional info such as whether the user is an admin of this chat.

Note

If an ID is provided, it should be the user ID of this member, not the groupchat member ID.

If the user is not found, this method will return None.

Parameters:: user – The user, or the ID of the user.
Returns:: The member, or None if not found.

await add_member(user: User, role: str = None) → None

Add a member to this forum or team.

This is a wrapper for User.add_to_chat().

The role should be either GroupChatMember.ROLE_MEMBER or GroupChatMember.ROLE_ADMIN. By default, new members are invited as normal members.

Parameters:

user – The user to add.
role – The role to invite the user as (member or admin) (optional).

await remove_member(user: int | User) → None

Remove a user from this forum/team.

Either a user ID or a user object can be used.

If the user is not in this forum/team, this method will do nothing.

Parameters:: user – The user or the ID of the user to remove.

await create_topic(subject: str, body: str, stickied: bool = False, attachments: Iterable[Storage | File] | None = None, creator: Creator | None = None) → Topic

Create a topic in this chat.

Returns the topic created.

Tip

To attach files to the topic, use pyryver.ryver.Ryver.upload_file() to upload the files you wish to attach. Alternatively, use pyryver.ryver.Ryver.create_link() for link attachments.

Changed in version 0.4.0: Switched the order of attachments and creator for consistency.

Parameters:

subject – The subject (or title) of the new topic.
body – The contents of the new topic.
stickied – Whether to sticky (pin) this topic to the top of the list (optional, default False).
attachments – A number of attachments for this topic (optional).
creator – The overridden creator; optional, if unset uses the logged-in user’s profile.

Returns:

The created topic.

Change the settings of this forum/team.

Note

The settings here contain only the settings in the “Settings” tab in the UI.

This method also updates these properties in this object.

If any parameters are unspecified, NO_CHANGE, or None, they will be left as-is.

Parameters:

chat – Whether there should be a chat tab for this forum/team (optional).
topics – Whether there should be a topics tab for this forum/team (optional).
tasks – Whether there should be a tasks tab for this form/team (optional).
announce_topics – Whether new topics should be announced in the chat (optional).
announce_tasks – Whether new tasks should be announced in the chat (optional).

await set_archived(archived: bool) → None

Set whether this team/forum is archived.

Note

This method also updates the archived property of this object.

Parameters:: archived – Whether this team/forum should be archived.

await delete() → None

Delete this forum/team.

As with most things, once it’s deleted, there’s no way to go back!

await join() → None: Join this forum/team as the current logged in user.

await leave() → None: Leave this forum/team as the current logged in user.

Note

This is not the same as selecting “Close and keep closed” in the UI. With this, the user will no longer show up in the members list of the forum/team, whereas “Close and keep closed” will still keep the user in the forum/team and only update the notification settings.

class pyryver.objects.Forum(ryver: Ryver, data: dict)

Bases: GroupChat

A Ryver forum.

class pyryver.objects.Team(ryver: Ryver, data: dict)

Bases: GroupChat

A Ryver team.

Users

class pyryver.objects.User(ryver: Ryver, data: dict)

Bases: Chat

A Ryver user.

Variables:

ROLE_USER – Regular organization member. Admins also have this role in addition to ROLE_ADMIN.
ROLE_ADMIN – An org admin.
ROLE_GUEST – A guest.
USER_TYPE_MEMBER – A member.
USER_TYPE_GUEST – A guest.

ROLE_USER = 'ROLE_USER'

ROLE_ADMIN = 'ROLE_ADMIN'

ROLE_GUEST = 'ROLE_GUEST'

USER_TYPE_MEMBER = 'member'

USER_TYPE_GUEST = 'guest'

get_username() → str

Get the username of this user.

Returns:: The username of this user.

get_display_name() → str

Get the display name of this user.

Returns:: The display name of this user.

get_name() → str

Get the display name of this user (same as the display name).

Returns:: The name of this user.

get_role() → str

Get this user’s role in their profile.

Note

This is different from get_roles(). While this one gets the “Role” of the user from the profile, get_roles() gets the user’s roles in the organization (user, guest, admin).

Returns:: The user’s “Role” as described in their profile.

get_about() → str

Get this user’s About.

Returns:: The user’s “About” as described in their profile.

get_time_zone() → str

Get this user’s Time Zone.

Returns:: The user’s time zone.

get_email_address() → str

Get this user’s Email Address.

Returns:: The user’s email address.

get_activated() → bool

Get whether this user’s account is activated.

Returns:: Whether this user’s account is activated (enabled).

get_roles() → List[str]

Get this user’s role in the organization.

Note

This is different from get_role(). While this one gets the user’s roles in the organization (user, guest, admin), get_role() gets the user’s role from their profile.

Returns:: The user’s roles in the organization.

get_user_type() → str

Get the type of this user (member or guest).

The returned value will be either User.USER_TYPE_MEMBER or User.USER_TYPE_GUEST.

Returns:: The type of the user.

is_admin() → bool

Get whether this user is an org admin.

Returns:: Whether the user is an org admin.

accepted_invite() → bool

Get whether this user has accepted their user invite.

Returns:: Whether the user has accepted their invite.

await set_profile(display_name: str | None = None, role: str | None = None, about: str | None = None) → None

Update this user’s profile.

If any of the arguments are None, they will not be changed.

Note

This also updates these properties in this object.

Parameters:

display_name – The user’s new display_name.
role – The user’s new role, as described in get_role().
about – The user’s new “about me” blurb.

await set_activated(activated: bool) → None: Activate or deactivate the user. Requires admin.

Note

This also updates these properties in this object.

await set_org_role(role: str) → None

Set a user’s role in this organization, as described in get_roles().

This can be either ROLE_USER, ROLE_ADMIN or ROLE_GUEST.

Note

Although for org admins, get_roles() will return both ROLE_USER and ROLE_ADMIN, to make someone an org admin you only need to pass ROLE_ADMIN into this method.

Note

This also updates these properties in this object.

await add_to_chat(chat: GroupChat, role: str | None = None) → None

Add a user to a forum/team.

The role should be either GroupChatMember.ROLE_MEMBER or GroupChatMember.ROLE_ADMIN. By default, new members are invited as normal members.

Parameters:

chat – The forum/team to add to.
role – The role to invite the user as (member or admin) (optional, defaults to member).

await create_topic(from_user: User, subject: str, body: str, stickied: bool = False, attachments: Iterable[Storage | File] | None = None, creator: Creator | None = None) → Topic

Create a topic in this user’s DMs.

Returns the topic created.

Tip

To attach files to the topic, use pyryver.ryver.Ryver.upload_file() to upload the files you wish to attach. Alternatively, use pyryver.ryver.Ryver.create_link() for link attachments.

Parameters:

from_user – The user that will create the topic; must be the same as the logged-in user.
subject – The subject (or title) of the new topic.
body – The contents of the new topic.
stickied – Whether to sticky (pin) this topic to the top of the list (optional, default False).
attachments – A number of attachments for this topic (optional).
creator – The overridden creator; optional, if unset uses the logged-in user’s profile.

Returns:

The created topic.

Group Chat Members

class pyryver.objects.GroupChatMember(ryver: Ryver, data: dict)

Bases: Object

A member in a forum or team.

This class can be used to tell whether a user is an admin of their forum/team.

Variables:

ROLE_MEMBER – Regular chat member. Note: This member could also be an org admin.
ROLE_ADMIN – Forum/team admin.

ROLE_MEMBER = 'ROLE_TEAM_MEMBER'

ROLE_ADMIN = 'ROLE_TEAM_ADMIN'

get_role() → str

Get the role of this member.

This will be one of the ROLE_ constants in this class.

Returns:: The role of this member.

await as_user() → User

Get this member as a User object.

Returns:: The member as a User object.

get_name() → str: Get the display name of this member.

is_admin() → bool

Get whether this member is an admin of their forum/team.

Warning

This method does not check for org admins.

Returns:: Whether this user is a forum admin/team admin.

await remove() → None: Remove this member from the forum/team.

await set_role(role: str) → None

Set the role of this member (regular member or admin).

The role should be one of the ROLE_ constants in this class.

Note

This will also update the role stored in this object.

Parameters:: role – The new role of the member.

Messages (Including Topics)

class pyryver.objects.Message(ryver: Ryver, data: dict)

Bases: Object

Any generic Ryver message, with an author, body, and reactions.

get_body() → str

Get the body of this message.

Note that this may be None in some circumstances.

Returns:: The body of this message.

await get_author() → User

Get the author of this message, as a User object.

Returns:: The author of this message.

await react(emoji: str) → None

React to this message with an emoji.

Note

This method does not update the reactions property of this object.

Parameters:: emoji – The string name of the reaction (e.g. “thumbsup”).

await unreact(emoji: str) → None

Unreact with an emoji.

Note

This method does not update the reactions property of this object.

Parameters:: emoji – The string name of the reaction (e.g. “thumbsup”).

get_reactions() → dict

Get the reactions on this message.

Returns a dict of {emoji: [users]}.

Returns:: A dict matching each emoji to the users that reacted with that emoji.

get_reaction_counts() → dict

Count the number of reactions for each emoji on a message.

Returns a dict of {emoji: number_of_reacts}.

Returns:: A dict matching each emoji to the number of users that reacted with that emoji.

await delete() → None: Delete this message.

class pyryver.objects.ChatMessage(ryver: Ryver, data: dict)

Bases: Message

A message that was sent to a chat.

Note

Chat message are actually not a part of the Ryver REST APIs, since they aren’t standalone objects (a chat is required to obtain one). As a result, they are a bit different from the other objects. Their IDs are strings rather than ints, and they are not instantiable (and therefore cannot be obtained from Ryver.get_object() or Object.get_by_id().)

Variables:

MSG_TYPE_PRIVATE – A private message between users.
MSG_TYPE_GROUPCHAT – A message sent to a group chat (team or forum).
SUBTYPE_CHAT_MESSAGE – A regular chat message sent by a user.
SUBTYPE_TOPIC_ANNOUNCEMENT – An automatic chat message that announces the creation of a new topic.
SUBTYPE_TASK_ANNOUNCEMENT – An automatic chat message that announces the creation of a new task.

MSG_TYPE_PRIVATE = 'chat'

MSG_TYPE_GROUPCHAT = 'groupchat'

SUBTYPE_CHAT_MESSAGE = 'chat'

SUBTYPE_TOPIC_ANNOUNCEMENT = 'topic_share'

SUBTYPE_TASK_ANNOUNCEMENT = 'task_share'

get_msg_type() → str

Get the type of this message (private message or group chat message).

The returned value will be one of the MSG_TYPE_ constants in this class.

Returns:: The type of this message.

get_subtype() → str

Get the subtype of this message (regular message or topic/task announcement).

The returned value will be one of the SUBTYPE_ constants in this class.

Returns:: The subtype of this message.

get_time() → str

Get the time this message was sent, as an ISO 8601 timestamp.

Tip

You can use pyryver.util.iso8601_to_datetime() to convert the timestamps returned by this method into a datetime.

Returns:: The time this message was sent, as an ISO 8601 timestamp.

get_author_id() → int

Get the ID of the author of this message.

Returns:: The author ID of the message.

get_chat_type() → str

Gets the type of chat that this message was sent to, as a string.

Returns:: The type of the chat this message was sent to.

get_chat_id() → int

Get the id of the chat that this message was sent to, as an integer.

Note that this is different from get_chat() as the id is stored in the message data and is good for most API purposes while get_chat() returns an entire Chat object, which might not be necessary depending on what you’re trying to do.

Returns:: The ID of the chat this message was sent to.

get_attached_file() → File | None

Get the file attached to this message, if there is one.

Note

Files obtained from this only have a limited amount of information, including the ID, name, URL, size and type. Attempting to get any other info will result in a KeyError. To obtain the full file info, use Ryver.get_object() with TYPE_FILE and the ID.

Note

Even if the attachment was a link and not a file, it will still be returned as a File object, as there seems to be no way of telling the type of the attachment just from the info provided in the message object.

Returns None otherwise.

Returns:: The attached file or link.

get_announced_topic_id() → int | None

Get the ID of the topic this message is announcing.

This is only a valid operation for messages that announce a new topic. In other words, ChatMessage.get_subtype() must return ChatMessage.SUBTYPE_TOPIC_ANNOUNCEMENT. If this message does not announce a topic, this method will return None.

Returns:: The ID of the topic that is announced by this message, or None.

get_announced_task_id() → int | None

Get the ID of the task this message is announcing.

This is only a valid operation for messages that announce a new task. In other words, ChatMessage.get_subtype() must return ChatMessage.SUBTYPE_TASK_ANNOUNCEMENT. If this message does not announce a topic, this method will return None.

Returns:: The ID of the task that is announced by this message, or None.

await get_author() → User

Get the author of this message, as a User object.

Tip

For chat messages, you can get the author ID without sending any requests, with ChatMessage.get_author_id().

Returns:: The author of this message.

await get_chat() → Chat

Get the chat that this message was sent to, as a Chat object.

Returns:: The chat this message was sent to.

await react(emoji: str) → None

React to this task with an emoji.

Note

This method does not update the reactions property of this object.

Parameters:: emoji – The string name of the reaction (e.g. “thumbsup”).

await unreact(emoji: str) → None

Unreact with an emoji.

Note

This method does not update the reactions property of this object.

Parameters:: emoji – The string name of the reaction (e.g. “thumbsup”).

await delete() → None: Deletes the message.

Edit this message.

Note

You can only edit a message if it was sent by you (even if you are an admin). Attempting to edit another user’s message will result in a aiohttp.ClientResponseError.

This also updates these properties in this object.

Tip

To attach a file to the message, use pyryver.ryver.Ryver.upload_file() to upload the file you wish to attach. Alternatively, use pyryver.ryver.Ryver.create_link() for a link attachment.

Warning

from_user must be set when using attachments with private messages. Otherwise, a ValueError will be raised. It should be set to the user that is sending the message (the user currently logged in).

It is not required to be set if the message is being sent to a forum/team.

If any parameters are unspecified or NO_CHANGE, they will be left as-is. Passing None for parameters for which None is not a valid value will also result in the value being unchanged.

Parameters:

message – The new message contents (optional).
creator – The new creator (optional).
attachment – An attachment for this message, e.g. a file or a link (optional). Can be either a Storage or a File object.
from_user – The user that is sending this message (the user currently logged in); must be set when using attachments in private messages (optional).

Raises:

ValueError – If a from_user is not provided for a private message attachment.

class pyryver.objects.Topic(ryver: Ryver, data: dict)

Bases: PostedMessage

A Ryver topic in a chat.

get_subject() → str

Get the subject of this topic.

Returns:: The subject of this topic.

is_stickied() → bool

Return whether this topic is stickied (pinned) to the top of the list.

Returns:: Whether this topic is stickied.

is_archived() → bool

Return whether this topic is archived.

Returns:: Whether this topic is archived.

await archive(archived: bool = True) → None

Archive or un-archive this topic.

Parameters:: archived – Whether the topic should be archived.

await unarchive() → None

Un-archive this topic.

This is the same as calling Topic.archive() with False.

await reply(message: str, creator: Creator | None = None, attachments: Iterable[Storage | File] | None = None) → TopicReply

Reply to the topic.

Note

For unknown reasons, overriding the creator does not seem to work for this method.

Tip

To attach files to the reply, use pyryver.ryver.Ryver.upload_file() to upload the files you wish to attach. Alternatively, use pyryver.ryver.Ryver.create_link() for link attachments.

Parameters:

message – The reply content
creator – The overridden creator (optional). Does not work.
attachments – A number of attachments for this reply (optional).

Returns:

The created reply.

async for ... in get_replies(top: int = -1, skip: int = 0) → AsyncIterator[TopicReply]

Get all the replies to this topic.

Parameters:

top – Maximum number of results; optional, if unspecified return all results.
skip – Skip this many results (optional).

Returns:

An async iterator for the replies of this topic.

Edit this topic.

Note

Unlike editing topic replies and chat messages, admins have permission to edit any topic regardless of whether they created it.

The file attachments (if specified) will replace all existing attachments.

Additionally, this method also updates these properties in this object.

If any parameters are unspecified or NO_CHANGE, they will be left as-is. Passing None for parameters for which None is not a valid value will also result in the value being unchanged.

Parameters:

subject – The subject (or title) of the topic (optional).
body – The contents of the topic (optional).
stickied – Whether to sticky (pin) this topic to the top of the list (optional).
creator – The overridden creator (optional).
attachments – A number of attachments for this topic (optional).

class pyryver.objects.TopicReply(ryver: Ryver, data: dict)

Bases: PostedComment

A reply on a topic.

await get_topic() → Topic

Get the topic this reply was sent to.

Returns:: The topic associated with this reply.

Tasks

class pyryver.objects.TaskBoard(ryver: Ryver, data: dict)

Bases: Object

A Ryver task board.

Variables:

BOARD_TYPE_BOARD – A task board with categories.
BOARD_TYPE_LIST – A task list (i.e. a task board without categories).

BOARD_TYPE_BOARD = 'board'

BOARD_TYPE_LIST = 'list'

get_name() → str

Get the name of this task board.

This will be the same as the name of the forum/team/user the task board is associated with.

Returns:: The name of the task board.

get_board_type() → str

Get the type of this task board.

Returns one of the BOARD_TYPE_ constants in this class.

BOARD_TYPE_BOARD is a task board with categories, while BOARD_TYPE_LIST is a task list without categories.

Not to be confused with Object.get_type().

Returns:: The type of this task board.

get_prefix() → str

Get the prefix for this task board.

The prefix can be used to reference tasks across Ryver using the #PREFIX-ID syntax.

If a task board does not have task IDs set up, this will return None.

Returns:: The task prefix for this task board.

async for ... in get_categories(top: int = -1, skip: int = 0) → AsyncIterator[TaskCategory]

Get all the categories in this task board.

Even if this task board has no categories (a list), this method will still return a single category, “Uncategorized”.

Parameters:

top – Maximum number of results; optional, if unspecified return all results.
skip – Skip this many results (optional).

Returns:

An async iterator for the categories in this task board.

await create_category(name: str, done: bool = False) → TaskCategory

Create a new task category in this task board.

Parameters:

name – The name of this category.
done – Whether tasks moved to this category should be marked as done.

Returns:

The created category.

async for ... in get_tasks(archived: bool | None = None, top: int = -1, skip: int = 0) → AsyncIterator[Task]

Get all the tasks in this task board.

If archived is unspecified or None, all tasks will be retrieved. If archived is either True or False, only tasks that are archived or unarchived are retrieved, respectively.

This will not retrieve sub-tasks (checklist items).

Parameters:

archived – If True or False, only retrieve tasks that are archived or unarchived; if None, retrieve all tasks (optional).
top – Maximum number of results; optional, if unspecified return all results.
skip – Skip this many results (optional).

Returns:

An async iterator for the tasks in this task board.

Create a task in this task board.

If the category is None, this task will be put in the “Uncategorized” category. For list type task boards, the category can be left as None.

Tip

To attach files to the task, use pyryver.ryver.Ryver.upload_file() to upload the files you wish to attach. Alternatively, use pyryver.ryver.Ryver.create_link() for link attachments.

Tip

You can use pyryver.util.datetime_to_iso8601() to turn datetime objects into timestamps that Ryver will accept.

Note that timezone info must be present in the timestamp. Otherwise, this will result in a 400 Bad Request.

Parameters:

subject – The subject, or title of the task.
body – The body, or description of the task (optional).
category – The category of the task; if None, the task will be uncategorized (optional).
assignees – A list of users to assign for this task (optional).
due_date – The due date, as an ISO 8601 formatted string with a timezone offset (optional).
tags – A list of tags of this task (optional). Can either be a list of strings or a list of TaskTag s.
checklist – A list of strings which are used as the item names for the checklist of this task (optional).
attachments – A list of attachments for this task (optional).

Returns:

The created task.

await get_chat() → Chat

Get the chat this task board is in.

If this task board is a public task board in a forum or team, a GroupChat object will be returned. If this task board is a personal (user) task board, a User object will be returned.

Note

API Detail: Although public task boards can be in either a forum or a team, GroupChat objects returned by this method will always be instances of Team, even if the task board exists in a forum. There seems to be no way of determining whether the returned chat is actually a forum or a team. However, as both forums/teams have the exact same methods, this detail shouldn’t matter.

Returns:: The forum/team/user this task board is in.

class pyryver.objects.TaskCategory(ryver: Ryver, data: dict)

Bases: Object

A category in a task board.

Variables:

CATEGORY_TYPE_UNCATEGORIZED – The “Uncategorized” category, created by the system (present in all task boards regardless of whether it is shown).
CATEGORY_TYPE_DONE – A user-created category in which all tasks are marked as done.
CATEGORY_TYPE_OTHER – Other categories (user-created and not marked as done).

CATEGORY_TYPE_UNCATEGORIZED = 'uncategorized'

CATEGORY_TYPE_DONE = 'done'

CATEGORY_TYPE_OTHER = 'user'

get_name() → str

Get the name of this category.

Returns:: The name of this category.

get_position() → int

Get the position of this category in this task board.

Positions are numbered from left to right.

Note

The first user-created category that is shown in the UI has a position of 1. This is because the “Uncategorized” category, which is present in all task boards, always has a position of 0, even when it’s not shown (when there are no uncategorized tasks).

Returns:: The position of this category.

get_category_type() → str

Get the type of this task category.

Returns one of the CATEGORY_TYPE_ constants in this class.

Returns:: The type of this category.

await get_task_board() → TaskBoard

Get the task board that contains this category.

Returns:: The task board.

await edit(name: str | None = NO_CHANGE, done: bool | None = NO_CHANGE) → None

Edit this category.

Note

This method also updates these properties in this object.

Warning

done should never be set for the “Uncategorized” category, as its type cannot be modified. If set, a ValueError will be raised.

If any parameters are unspecified or NO_CHANGE, they will be left as-is. Passing None for parameters for which None is not a valid value will also result in the value being unchanged.

Parameters:

name – The name of this category (optional).
done – Whether tasks moved to this category should be marked as done (optional).

Raises:

ValueError – If attempting to modify the type of the “Uncategorized” category.

await delete(move_to: TaskCategory | None = None) → None

Delete this category.

If move_to is specified, the tasks that are in this category will be moved into the specified category and not archived. Otherwise, the tasks will be archived.

Parameters:: move_to – Another category to move the tasks in this category to (optional).

await archive(completed_only: bool = False) → None

Archive either all or only completed tasks in this category.

Deprecated since version 0.4.0: Use TaskCategory.archive_tasks() instead. The functionality is unchanged but the name is less misleading.

Note

This archives the tasks in this category, not the category itself.

Parameters:: completed_only – Whether to only archive completed tasks (optional).

await archive_tasks(completed_only: bool = False) → None

Archive either all or only completed tasks in this category.

Parameters:: completed_only – Whether to only archive completed tasks (optional).

await move_position(position: int) → None

Move this category’s display position in the UI.

Note

This also updates the position property of this object.

The first user-created category that is shown in the UI has a position of 1. This is because the “Uncategorized” category, which is present in all task boards, always has a position of 0, even when it’s not shown (when there are no uncategorized tasks).

Therefore, no user-created task category can ever be moved to position 0, and the “Uncategorized” category should never be moved.

Parameters:: position – The new display position.

await move_tasks(category: TaskCategory, completed_only: bool = False) → None

Move either all or only completed tasks in this category to another category.

Parameters:

category – The category to move to.
completed_only – Whether to only move completed tasks (optional).

async for ... in get_tasks(archived: bool | None = None, top: int = -1, skip: int = 0) → AsyncIterator[Task]

Get all the tasks in this category.

If archived is unspecified or None, all tasks will be retrieved. If archived is either True or False, only tasks that are archived or unarchived are retrieved, respectively.

This will not retrieve sub-tasks (checklist items).

Parameters:

archived – If True or False, only retrieve tasks that are archived or unarchived; if None, retrieve all tasks (optional).
top – Maximum number of results; optional, if unspecified return all results.
skip – Skip this many results (optional).

Returns:

An async iterator for the tasks in this category.

class pyryver.objects.Task(ryver: Ryver, data: dict)

Bases: PostedMessage

A Ryver task.

is_archived() → bool

Get whether this task has been archived.

Returns:: Whether this task has been archived.

get_subject() → str

Get the subject (title) of this task.

Returns:: The subject of this task.

get_due_date() → str | None

Get the due date as an ISO 8601 timestamp.

If there is no due date, this method will return None.

Tip

You can use pyryver.util.iso8601_to_datetime() to convert the timestamps returned by this method into a datetime.

Returns:: The due date of this task.

get_complete_date() → str | None

Get the complete date as an ISO 8601 timestamp.

If the task has not been completed, this method will return None.

Tip

You can use pyryver.util.iso8601_to_datetime() to convert the timestamps returned by this method into a datetime.

Returns:: The completion date of this task.

is_completed() → bool

Get whether this task has been completed.

Returns:: Whether this task has been completed.

get_short_repr() → str | None

Get the short representation of this task.

This is can be used to reference this task across Ryver. It has the form PREFIX-ID, and is also unique across the entire organization.

If the task board does not have prefixes set up, this will return None.

Returns:: The unique short representation of this task.

get_position() → int

Get the position of this task in its category or the task list.

The first task has a position of 0.

Returns:: The position of this task in its category.

get_comments_count() → int

Get how many comments this task has received.

Returns:: The number of comments this task has received.

get_attachments_count() → int

Get how many attachments this task has.

Returns:: The number of attachments this task has.

get_tags() → List[str]

Get all the tags of this task.

Note

The tags are returned as a list of strings, not a list of TaskTag s.

Returns:: All the tags of this task, as strings.

await get_task_board() → TaskBoard

Get the task board this task is in.

Returns:: The task board containing this task.

await get_task_category() → TaskCategory

Get the category this task is in.

Returns:: The category containing this task.

await get_assignees() → List[User]

Get the assignees of this task.

Returns:: The assignees of this task,.

await set_complete_date(time: str | None = '') → None

Set the complete date of this task, which also marks whether this task is complete.

An optional completion time can be specified in the form of an ISO 8601 timestamp with a timezone offset. If not specified or an empty string, the current time will be used.

Tip

You can use pyryver.util.datetime_to_iso8601() to turn datetime objects into timestamps that Ryver will accept.

Note that timezone info must be present in the timestamp. Otherwise, this will result in a 400 Bad Request.

If None is used as the time, in addition to clearing the complete date, this task will also be un-completed.

Note

This also updates the complete date property in this object.

If a time of None is given, this task will be marked as uncomplete.

Parameters:: time – The completion time (optional).

await set_due_date(time: str | None)

Set the due date of this task.

The time must be specified as an ISO 8601 timestamp with a timezone offset. It can also be None, in which case there will be no due date.

Tip

You can use pyryver.util.datetime_to_iso8601() to turn datetime objects into timestamps that Ryver will accept.

Note that timezone info must be present in the timestamp. Otherwise, this will result in a 400 Bad Request.

Note

This also updates the due date property in this object.

Parameters:: time – The new due date.

await complete() → None: Mark this task as complete.

await uncomplete() → None: Mark this task as uncomplete.

await archive(archived: bool = True) → None

Archive or un-archive this task.

Parameters:: archived – Whether the task should be archived.

await unarchive() → None

Un-archive this task.

This is the same as calling Task.archive() with False.

await move(category: TaskCategory, position: int) → None: Move this task to another category or to a different position in the same category.

Note

This also updates the position property of this object.

async for ... in get_checklist(top: int = -1, skip: int = 0) → AsyncIterator[Task]

Get the checklist items of this task (subtasks).

If this task has no checklist, an empty list will be returned.

The checklist items are Task objects; complete or uncomplete those objects to change the checklist status.

Parameters:

top – Maximum number of results; optional, if unspecified return all results.
skip – Skip this many results (optional).

Returns:

An async iterator for the tasks in the checklist of this task.

await get_parent() → Task | None

Get the parent task of this sub-task (checklist item).

This only works if this task is an item in another task’s checklist. Otherwise, this will return None.

Returns:: The parent of this sub-task (checklist item), or None if this task is not a sub-task.

await add_to_checklist(items: Iterable[str]) → None

Add items to this task’s checklist.

Parameters:: items – The names of the items to add.

await set_checklist(items: Iterable[Task]) → None

Set the contents of this task’s checklist.

This will overwrite existing checklist items.

Note

This method should be used for deleting checklist items only. It cannot be used to add new items as the tasks would have to be created first. To add new items, use Task.add_to_checklist().

Parameters:: items – The items in the checklist.

Edit this task.

Note

Admins can edit any task regardless of whether they created it.

The file attachments (if specified) will replace all existing attachments.

Additionally, this method also updates these properties in this object.

Note

While a value of None for the category in TaskBoard.create_task() will result in the task being placed in the “Uncategorized” category, None is not a valid value for the category in this method, and if used will result in the category being unmodified.

This method does not support editing the checklist. To edit the checklist, use Task.get_checklist(), Task.set_checklist() and Task.add_to_checklist().

If any parameters are unspecified or NO_CHANGE, they will be left as-is. Passing None for parameters for which None is not a valid value will also result in the value being unchanged.

Tip

To attach files to the task, use pyryver.ryver.Ryver.upload_file() to upload the files you wish to attach. Alternatively, use pyryver.ryver.Ryver.create_link() for link attachments.

Tip

You can use pyryver.util.datetime_to_iso8601() to turn datetime objects into timestamps that Ryver will accept.

Note that timezone info must be present in the timestamp. Otherwise, this will result in a 400 Bad Request.

Parameters:

subject – The subject, or title of the task (optional).
body – The body, or description of the task (optional).
category – The category of the task; if None, the task will be uncategorized (optional).
assignees – A list of users to assign for this task (optional).
due_date – The due date, as an ISO 8601 formatted string with a timezone offset (optional).
tags – A list of tags of this task (optional). Can either be a list of strings or a list of TaskTag s.
attachments – A list of attachments for this task (optional).

async for ... in get_comments(top: int = -1, skip: int = 0) → AsyncIterator[TaskComment]

Get all the comments on this task.

Parameters:

top – Maximum number of results; optional, if unspecified return all results.
skip – Skip this many results (optional).

Returns:

An async iterator for the comments of this task.

await comment(message: str, attachments: Iterable[Storage | File] | None = None, creator: Creator | None = None) → TaskComment

Comment on this task.

Note

For unknown reasons, overriding the creator does not seem to work for this method.

Tip

To attach files to the comment, use pyryver.ryver.Ryver.upload_file() to upload the files you wish to attach. Alternatively, use pyryver.ryver.Ryver.create_link() for link attachments.

Changed in version 0.4.0: Switched the order of attachments and creator for consistency.

Parameters:

message – The comment’s contents.
creator – The overridden creator (optional). Does not work.
attachments – A number of attachments for this comment (optional).

Returns:

The created comment.

Files

class pyryver.objects.Storage(ryver: Ryver, data: dict)

Bases: Object

Generic storage (message attachments), e.g. files and links.

Variables:

STORAGE_TYPE_FILE – An uploaded file.
STORAGE_TYPE_LINK – A link.

STORAGE_TYPE_FILE = 'file'

STORAGE_TYPE_LINK = 'link'

get_storage_type() → str

Get the type of this storage object.

Returns one of the STORAGE_TYPE_ constants in this class.

Not to be confused with Object.get_type().

Returns:: The type of this storage object.

get_name() → str

Get the name of this storage object.

Returns:: The name of this storage object.

get_size() → str

Get the size of the object stored.

Returns:: The size of the thing stored.

get_content_id() → int

Get the ID of the contents of this storage object.

If a link is stored, then this will return the same value as get_id(). If a file is stored, then this will return the ID of the file instead.

Returns:: The ID of the contents of this storage object.

get_content_MIME_type() → str

Get the MIME type of the content.

For links, this will be “application/octet-stream”.

Returns:: The MIME type of the contents of this storage object.

get_file() → File

Get the file stored.

Warning

This method will raise a KeyError if the type of this storage is not TYPE_FILE!

Returns:: The file stored.

get_content_url() → str

Get the URL of the contents.

If a link is stored, then this will be the URL of the link. If a file is stored, then this will be the URL of the file contents.

Returns:: The content’s URL.

await delete() → None: Delete this storage object and the file it contains if there is one.

await make_avatar_of(chat: Chat) → None

Make this image an avatar of a chat.

Parameters:: chat – The chat to change the avatar for.
Raises:: ValueError – If the contents of this storage object is not a file.

class pyryver.objects.File(ryver: Ryver, data: dict)

Bases: Object

An uploaded file.

get_title() → str

Get the title of this file.

Returns:: The title of this file.

get_name() → str

Get the name of this file.

Returns:: The name of this file.

get_size() → int

Get the size of this file in bytes.

Returns:: The size of the file in bytes.

get_url() → str

Get the URL of this file.

Returns:: The URL of the file.

get_MIME_type() → str

Get the MIME type of this file.

Returns:: The MIME type of the file.

request_data() → ClientResponse

Get the file data.

Returns an aiohttp request response to the file URL.

Returns:: An aiohttp.ClientResponse object representing a request response for the file contents.

await download_data() → bytes

Download the file data.

Returns:: The downloaded file data, as raw bytes.

await delete() → None: Delete this file.

Notifications

class pyryver.objects.Notification(ryver: Ryver, data: dict)

Bases: Object

A Ryver user notification.

Variables:

PREDICATE_MENTION – The user was directly mentioned with an @mention.
PREDICATE_GROUP_MENTION – The user was mentioned through @team or @here.
PREDICATE_COMMENT – A topic was commented on.
PREDICATE_TASK_COMPLETED – A task was completed.

PREDICATE_MENTION = 'chat_mention'

PREDICATE_GROUP_MENTION = 'group_mention'

PREDICATE_COMMENT = 'commented_on'

PREDICATE_TASK_COMPLETED = 'completed'

get_predicate() → str

Get the “predicate”, or type, of this notification.

This usually returns one of the PREDICATE_ constants in this class. Note that the list currently provided is not exhaustive; this method may return a value that isn’t one of the constants.

Returns:: The predicate of this notification.

get_subject_entity_type() → str

Get the entity type of the “subject” of this notification.

The exact nature of this field is not yet known, but it seems to be the user that did the action which caused this notification.

Returns:: The entity type of this notification’s subject.

get_subject_id() → int

Get the ID of the “subject” of this notification.

The exact nature of this field is not yet known, but it seems to be the user that did the action which caused this notification.

Returns:: The ID of this notification’s subject.

get_subjects() → List[dict]

Get the “subjects” of this notification.

The exact nature of this field is not yet known, but it seems to be the user that did the action which caused this notification. It is also unknown why this is an array, as it seems to only ever contain one element.

Returns:: The subjects of this notification.

get_object_entity_type() → str

Get entity type of the “object” of this notification.

The exact nature of this field is not yet known, but it seems to be the target of an @mention for mentions, the topic for topic comments, or the task for task activities.

Returns:: The entity type of the object of this notification.

get_object_id() → int

Get the ID of the “object” of this notification.

The exact nature of this field is not yet known, but it seems to be the target of an @mention for mentions, the topic for topic comments, or the task for task activities.

Returns:: The ID of the object of this notification.

get_object() → dict

Get the “object” of this notification.

The exact nature of this field is not yet known, but it seems to be the target of an @mention for mentions, the topic for topic comments, or the task for task activities.

Returns:: The object of this notification.

get_via_entity_type() → str

Get the entity type of the “via” of this notification.

The exact nature of this field is not yet known, but it seems to contain information about whatever caused this notification. For example, the chat message of an @mention, the topic reply for a reply, etc. For task completions, there is NO via.

Returns:: The entity type of the via of this notification.

get_via_id() → int

Get the ID of the “via” of this notification.

The exact nature of this field is not yet known, but it seems to contain information about whatever caused this notification. For example, the chat message of an @mention, the topic reply for a reply, etc. For task completions, there is NO via.

Returns:: The ID of the via of this notification.

get_via() → dict

Get the “via” of this notification.

The exact nature of this field is not yet known, but it seems to contain information about whatever caused this notification. For example, the chat message of an @mention, the topic reply for a reply, etc. For task completions, there is NO via.

Returns:: The via of this notification.

get_new() → bool

Get whether this notification is new.

Returns:: Whether this notification is new.

get_unread() → bool

Get whether this notification is unread.

Returns:: Whether this notification is unread.

await set_status(unread: bool, new: bool) → None: Set the read/unread and seen/unseen (new) status of this notification.

Note

This also updates these properties in this object.

Creators

class pyryver.objects.Creator(name: str, avatar: str = '')

A message creator, with a name and an avatar.

This can be used to override the sender’s display name and avatar.

Parameters:

name – The overridden display name
avatar – The overridden avatar (a url to an image)

name

avatar

to_dict() → dict

Convert this Creator object to a dictionary to be used in a request.

Warning

This method is intended for internal use only.

Returns:: The dict representation of this object.