Utilities¶
Cache Data Storage¶
Cache storages are used by Ryver
to cache organization data locally.
In large organizations with lots of data, caching can be used to make the program load some organization data locally instead of fetching them from Ryver. This can significantly improve program startup times.
Currently, the lists of all users, forums, and teams can be cached.
See also
The Ryver
class
-
class
pyryver.cache_storage.
AbstractCacheStorage
¶ Bases:
abc.ABC
An abstract class defining the requirements for cache storages.
A cache storage is used by the Ryver class to cache chats data to improve performance.
-
abstractmethod
load
(ryver: Ryver, obj_type: str) → List[pyryver.objects.Object]¶ Load all saved objects of a specific type.
If no objects were saved, this method returns an empty list.
- Parameters
ryver – The Ryver session to associate the objects with.
obj_type – The type of the objects to load.
- Returns
A list of saved objects of that type.
-
abstractmethod
save
(obj_type: str, data: Iterable[pyryver.objects.Object]) → None¶ Save all objects of a specific type.
- Parameters
obj_type – The type of the objects to save.
data – The objects to save.
-
abstractmethod
-
class
pyryver.cache_storage.
FileCacheStorage
(root_dir: str = '.', prefix: str = '')¶ Bases:
pyryver.cache_storage.AbstractCacheStorage
A cache storage implementation using files.
-
load
(ryver: Ryver, obj_type: str) → List[pyryver.objects.Object]¶ Load all saved objects of a specific type.
If no objects were saved, this method returns an empty list.
- Parameters
ryver – The Ryver session to associate the objects with.
obj_type – The type of the objects to load.
- Returns
A list of saved objects of that type.
-
save
(obj_type: str, data: Iterable[pyryver.objects.Object]) → None¶ Save all objects of a specific type.
- Parameters
obj_type – The type of the objects to save.
data – The objects to save.
-
API Helpers¶
This module contains various contants and utilities for both internal and external use.
-
pyryver.util.
NO_CHANGE
= NO_CHANGE¶ This constant is used in the various
edit()
methods. It’s used to indicate that there should be no change to the value of a field, in the cases whereNone
is a valid value.
-
pyryver.util.
get_type_from_entity
(entity_type: str) → Optional[str]¶ Gets the object type from the entity type.
Note that it doesn’t actually return a class, just the string.
Warning
This function is intended for internal use only.
- Parameters
entity_type – The entity type of the object.
- Returns
The regular type of the object, or None if an invalid type.
-
await
pyryver.util.
retry_until_available
(action: Callable[[…], Awaitable[T]], *args, timeout: Optional[float] = None, retry_delay: float = 0.5, **kwargs) → T¶ Repeatedly tries to do some action (usually getting a resource) until the resource becomes available or a timeout elapses.
This function will try to run the given coroutine once every
retry_delay
seconds. If it results in a 404, the function tries again. Otherwise, the exception is raised.If it times out, an
asyncio.TimeoutError
will be raised.args
andkwargs
are passed to the coroutine.For example, this snippet will try to get a message from a chat by ID with a timeout of 5 seconds, retrying after 1 second if a 404 occurs:
message = await pyryver.retry_until_available(chat.get_message, message_id, timeout=5.0, retry_delay=1.0)
Note
Do not “call” the coro first and pass a future to this function; instead, pass a reference to the coro directly, as seen in the example. This is done because a single future cannot be awaited multiple times, so a new one is created each time the function retries.
- Parameters
action – The coroutine to run.
timeout – The timeout in seconds, or None for no timeout (optional).
retry_delay – The duration in seconds to wait before trying again (optional).
- Returns
The return value of the coroutine.
-
pyryver.util.
iso8601_to_datetime
(timestamp: str) → datetime.datetime¶ Convert an ISO 8601 timestamp as returned by the Ryver API into a datetime.
Warning
This function does not handle all valid ISO 8601 timestamps; it only tries to handle the ones returned by the Ryver API. It uses the simple format string
"%Y-%m-%dT%H:%M:%S%z"
to parse the timestamp.Therefore, this function should not be used for parsing any ISO timestamp; to do that, consider using
dateutil.parser
, or some alternative method.- Parameters
timestamp – The ISO 8601 timestamp.
-
pyryver.util.
datetime_to_iso8601
(timestamp: datetime.datetime) → str¶ Convert a datetime into an ISO 8601 timestamp as used by the Ryver API.
- Parameters
timestamp – The datetime to convert.
-
pyryver.objects.
get_obj_by_field
(objs: Iterable[pyryver.objects.Object], field: str, value: Any, case_sensitive: str = True) → Optional[pyryver.objects.Object]¶ Gets an object from a list of objects by a field.
For example, this function can find a chat with a specific nickname in a list of chats.
- Parameters
objs – List of objects to search in.
field – The field’s name (usually a constant beginning with
FIELD_
in pyryver.util) within the object’s JSON data.value – The value to look for.
case_sensitive – Whether the search should be case-sensitive. Can be useful for fields such as username or nickname, which are case-insensitive. Defaults to True. If the field value is not a string, it will be ignored.
- Returns
The object with the matching field, or None if not found.
Entity Types¶
-
pyryver.util.
TYPE_USER
¶ Corresponds to
pyryver.objects.User
.
-
pyryver.util.
TYPE_FORUM
¶ Corresponds to
pyryver.objects.Forum
.
-
pyryver.util.
TYPE_TEAM
¶ Corresponds to
pyryver.objects.Team
.
-
pyryver.util.
TYPE_GROUPCHAT_MEMBER
¶ Corresponds to
pyryver.objects.GroupChatMember
.
-
pyryver.util.
TYPE_TOPIC
¶ Corresponds to
pyryver.objects.Topic
.
-
pyryver.util.
TYPE_TOPIC_REPLY
¶ Corresponds to
pyryver.objects.TopicReply
.
-
pyryver.util.
TYPE_NOTIFICATION
¶ Corresponds to
pyryver.objects.Notification
.
-
pyryver.util.
TYPE_STORAGE
¶ Corresponds to
pyryver.objects.Storage
.
-
pyryver.util.
TYPE_FILE
¶ Corresponds to
pyryver.objects.File
.
Common Field Names¶
-
pyryver.util.
FIELD_USERNAME
¶
-
pyryver.util.
FIELD_EMAIL_ADDR
¶
-
pyryver.util.
FIELD_DISPLAY_NAME
¶ The object’s display name (friendly name)
-
pyryver.util.
FIELD_NAME
¶
-
pyryver.util.
FIELD_NICKNAME
¶
-
pyryver.util.
FIELD_ID
¶ The object’s ID, sometimes an
int
, sometimes astr
depending on the object type.
-
pyryver.util.
FIELD_JID
¶ The object’s JID, or JabberID. Used in the live socket interface for referring to chats.