Session

class pyryver.ryver.Ryver(org: str | None = None, user: str | None = None, password: str | None = None, token: str | None = None, cache: Type[AbstractCacheStorage] | None = None)

A Ryver session contains login credentials and organization information.

This is the starting point for any application using pyryver.

If the organization, it will be prompted using input(). If the username or password are not provided, and the token is not provided, the username and password will be prompted.

If a token is specified, the username and password will be ignored.

The cache is used to load the chats data. If not provided, no caching will occur.

If a valid cache is provided, the chats data will be loaded in the constructor. Otherwise, it must be loaded through load_forums(), load_teams() and load_users() or load_chats().

Parameters:

  • org – Your organization’s name (optional). (as seen in the URL)

  • user – The username to authenticate with (optional).

  • password – The password to authenticate with (optional).

  • token – The custom integration token to authenticate with (optional).

  • cache – The aforementioned cache (optional).

async with get_live_session(auto_reconnect: bool = False) → RyverWS

Get a live session.

The session is not started unless start() is called or if it is used as a context manager.

Warning

Live sessions do not work when using a custom integration token.

Parameters:

auto_reconnect – Whether to automatically reconnect on connection loss.

Returns:

The live websockets session.

get_chat(**kwargs) → Chat | None

Get a specific forum/team/user.

If no query parameters are supplied, more than one query parameters are supplied or forums/teams/users are not loaded, raises ValueError.

Allowed query parameters are:

  • id

  • jid

Returns None if not found.

Raises:

ValueError – If not all chats are loaded, or zero or multiple query parameters are specified.

Returns:

The chat, or None if not found.

get_user(**kwargs) → User | None

Get a specific user.

If no query parameters are supplied, more than one query parameters are supplied or users are not loaded, raises ValueError.

Allowed query parameters are:

  • id

  • jid

  • username

  • name/display_name

  • email

If using username or email to find the user, the search will be case-insensitive.

Returns None if not found.

Raises:

ValueError – If users are not loaded, or zero or multiple query parameters are specified.

Returns:

The user, or None of not found.

get_forum(**kwargs) → Forum | None

Get a specific forum.

If no query parameters are supplied, more than one query parameters are supplied or forums are not loaded, raises ValueError.

Allowed query parameters are:

  • id

  • jid

  • name

  • nickname

If using nickname to find the chat, the search will be case-insensitive.

Returns None if not found.

Raises:

ValueError – If forums are not loaded, or zero or multiple query parameters are specified.

Returns:

The chat, or None if not found.

get_team(**kwargs) → Forum | None

Get a specific team.

If no query parameters are supplied, more than one query parameters are supplied or teams are not loaded, raises ValueError.

Allowed query parameters are:

  • id

  • jid

  • name

  • nickname

If using nickname to find the chat, the search will be case-insensitive.

Returns None if not found.

Raises:

ValueError – If teams are not loaded, or zero or multiple query parameters are specified.

Returns:

The chat, or None if not found.

get_groupchat(forums: bool = True, teams: bool = True, **kwargs) → GroupChat | None

Get a specific forum/team.

If no query parameters are supplied, more than one query parameters are supplied or the list to search is not loaded, raises ValueError.

Allowed query parameters are:

  • id

  • jid

  • name

  • nickname

If using nickname to find the chat, the search will be case-insensitive.

Returns None if not found.

Changed in version 0.4.0: Added parameters forums and teams.

Parameters:

  • forums – Whether to search the list of forums.

  • teams – Whether to search the list of teams.

Raises:

ValueError – If the list to search is not loaded, or zero or multiple query parameters are specified.

Returns:

The chat, or None if not found.

await get_object(obj_type: str | type, obj_id: int | None = None, **kwargs) → Type[Object] | List[Type[Object]]

Get an object or multiple objects from Ryver with a type and optionally ID.

If extra keyword arguments are supplied, they are appended to the request as additional query parameters. Possible values include top, skip, select, expand and more. The Ryver Developer Docs or OData Specification contains documentation for some of these parameters. (Note: The link is to Odata 2.0 instead of 4.0 because the 2.0 page seems to be much more readable.)

With this method, you can get objects by properties other than ID. The following example gets one or more objects by display name:

# Note that this will return an array, even if there is only 1 result
user = await ryver.get_object(pyryver.User, filter=f"displayName eq '{name}'")
Parameters:

  • obj_type – The type of the object to retrieve, either a string type or the actual object type.

  • obj_id – The object’s ID (optional).

Raises:

TypeError – If the object is not instantiable.

Returns:

The object or list of objects requested.

await get_info() → Dict[str, Any]

Get organization and user info.

This method returns an assortment of info. It is currently the only way to get avatar URLs for users/teams/forums etc. The results (returned mostly verbatim from the Ryver API) include:

  • Basic user info - contains avatar URLs (“me”)

  • User UI preferences (“prefs”)

  • Ryver app info (“app”)

  • Basic info about all users - contains avatar URLs (“users”)

  • Basic info about all teams - contains avatar URLs (“teams”)

  • Basic info about all forums - contains avatar URLs (“forums”)

  • All available commands (“commands”)

  • “messages” and “prefixes”, the purpose of which are currently unknown.

Returns:

The raw org and user info data.

async for notification in get_notifs(unread: bool = False, top: int = -1, skip: int = 0) → AsyncIterator[Notification]

Get the notifications for the logged in user.

Parameters:

  • unread – If True, only return unread notifications.

  • top – Maximum number of results.

  • skip – Skip this many results.

Returns:

An async iterator for the user’s notifications.

await mark_all_notifs_read() → int

Marks all the user’s notifications as read.

Returns:

How many notifications were marked as read.

await mark_all_notifs_seen() → int

Marks all the user’s notifications as seen.

Returns:

How many notifications were marked as seen.

await upload_file(filename: str, filedata: Any, filetype: str | None = None) → Storage

Upload a file to Ryver (for attaching to messages).

Note

Although this method uploads a file, the returned object is an instance of Storage, with type Storage.TYPE_FILE. Use Storage.get_file() to obtain the actual File object.

Parameters:

  • filename – The filename to send to Ryver. (this will show up in the UI if attached as an embed, for example)

  • filedata – The file’s raw data, sent directly to aiohttp.FormData.add_field().

  • filetype – The MIME type of the file.

Returns:

The uploaded file, as a Storage object.

Create a link on Ryver (for attaching to messages).

Note

The returned object is an instance of Storage with type Storage.TYPE_LINK.

Parameters:

  • name – The name of this link (its title).

  • url – The URL of this link.

Returns:

The created link, as a Storage object.

await invite_user(email: str, role: str = 'member', username: str | None = None, display_name: str | None = None) → User

Invite a new user to the organization.

An optional username and display name can be specified to pre-populate those values in the User Profile page that the person is asked to fill out when they accept their invite.

Parameters:

  • email – The email of the user.

  • role – The role of the user (member or guest), one of the User.USER_TYPE_ constants (optional).

  • username – The pre-populated username of this user (optional).

  • display_name – The pre-populated display name of this user (optional).

Returns:

The invited user object.

await create_forum(name: str, nickname: str | None = None, about: str | None = None, description: str | None = None) → Forum

Create a new open forum.

Parameters:

  • name – The name of this forum.

  • nickname – The nickname of this forum (optional).

  • about – The “about” (or “purpose” in the UI) of this forum (optional).

  • description – The description of this forum (optional).

Returns:

The created forum object.

await create_team(name: str, nickname: str | None = None, about: str | None = None, description: str | None = None) → Team

Create a new private team.

Parameters:

  • name – The name of this team.

  • nickname – The nickname of this team (optional).

  • about – The “about” (or “purpose” in the UI) of this team (optional).

  • description – The description of this team (optional).

Returns:

The created team object.

await load_chats() → None

Load the data of all users/teams/forums.

This refreshes the cached data if a cache is supplied.

await load_missing_chats() → None

Load the data of all users/teams/forums if it does not exist.

Unlike load_chats(), this does not update the cache.

This method could send requests.

await load_users() → None

Load the data of all users.

This refreshes the cached data if a cache is supplied.

await load_forums() → None

Load the data of all forums.

This refreshes the cached data if a cache is supplied.

await load_teams() → None

Load the data of all teams.

This refreshes the cached data if a cache is supplied.

await close()

Close this session.