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

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[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[Object]) → None

Save all objects of a specific type.

Parameters:

  • obj_type – The type of the objects to save.

  • data – The objects to save.

class pyryver.cache_storage.FileCacheStorage(root_dir: str = '.', prefix: str = '')

Bases: AbstractCacheStorage

A cache storage implementation using files.

load(ryver: Ryver, obj_type: str) → List[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[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 where None is a valid value.

pyryver.util.get_type_from_entity(entity_type: str) → str | None

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: float | None = 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 and kwargs 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

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) → 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[Object], field: str, value: Any, case_sensitive: str = True) → Object | None

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 a str 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.