Session¶
-
class
pyryver.ryver.
Ryver
(org: Optional[str] = None, user: Optional[str] = None, password: Optional[str] = None, token: Optional[str] = None, cache: Optional[Type[pyryver.cache_storage.AbstractCacheStorage]] = 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) → pyryver.ryver_ws.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) → Optional[pyryver.objects.Chat]¶ 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) → Optional[pyryver.objects.User]¶ 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) → Optional[pyryver.objects.Forum]¶ 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) → Optional[pyryver.objects.Forum]¶ 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) → Optional[pyryver.objects.GroupChat]¶ 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
andteams
.- 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: Union[str, type], obj_id: Optional[int] = None, **kwargs) → Union[Type[pyryver.objects.Object], List[Type[pyryver.objects.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[pyryver.objects.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: Optional[str] = None) → pyryver.objects.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 typeStorage.TYPE_FILE
. UseStorage.get_file()
to obtain the actualFile
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.
-
await
create_link
(name: str, link_url: str) → pyryver.objects.Storage¶ Create a link on Ryver (for attaching to messages).
Note
The returned object is an instance of
Storage
with typeStorage.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: Optional[str] = None, display_name: Optional[str] = None) → pyryver.objects.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: Optional[str] = None, about: Optional[str] = None, description: Optional[str] = None) → pyryver.objects.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: Optional[str] = None, about: Optional[str] = None, description: Optional[str] = None) → pyryver.objects.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.