The get utility method#

New in version 4.3.0.

interactions.utils.get.get(client, obj, **kwargs)[source]#

Helper method to get an object.

This method can do the following:
  • Get a list of specific objects

    • purely from cache

    • purely from HTTP

    • from cache and additionally from HTTP for every ID that was not found in cache

  • Get a single specific object

    • purely from cache

    • purely from HTTP

    • from HTTP if not found in cache else from cache

The method has to be awaited when:

  • You don’t force anything

  • You force HTTP

The method doesn’t have to be awaited when:

  • You force cache

Note

Technically, there is no need for an await if there is an object found in the cache. Because of the fact, that, as long as you don’t enforce the cache, the function will get the object from HTTP, if it is not in the cache, you still have to await it. This has been done to reduce confusion on whether the object origins from an HTTP call or a cache result and to remove the extra step for you to check if the returned object is an awaitable or not.

Forcing:
Forcing can be done via the force keyword argument.
  • force="cache" or force=interactions.Force.CACHE:

    This forces the method to only return from cache (if the object is not found it will return None). If you use this, you don’t need to await the method.

  • force="http" or force=interactions.Force.HTTP:

    This forces the method to make an HTTP request to the discord API and return the result of it. If you use this, you have to await the method.

    Attention

    If you are a PyCharm user, please be aware of a bug that causes incorrect suggestions to appear if using an enum. Even if PyCharm shows a normal object as result, you have to await the method if you enforce HTTP. To prevent this bug from happening it is suggested using force="http" instead of the enum.

Getting an object:

Here you will see two examples on how to get a single objects and the variations of how the object can be gotten.

  • Example 1/2: Getting a Channel:

    # normally
channel = await get(client, interactions.Channel, object_id=your_channel_id)
# always has a value

# with http force
channel = await get(client, interactions.Channel, object_id=your_channel_id, force="http")
# always has a value

# with cache force
channel = get(client, interactions.Channel, object_id=your_channel_id, force="cache")
# because of cache only, this can be None

  • Example 2/2: Getting a Member:

    # normally
member = await get(
    client, interactions.Member, parent_id=your_guild_id, object_id=your_member_id
)
# always has a value

# with http force
member = await get(
    client, interactions.Member, parent_id=your_guild_id, object_id=your_member_id, force="http",
)
# always has a value

# with cache force
member = get(
    client, interactions.Member, parent_id=your_guild_id, object_id=your_member_id, force="cache",
)
# because of cache only, this can be None

Both examples should have given you a basic overview on how to get a single object. Now we will move on with lists of objects.

Important

The parent_id represents the channel or guild id that belongs to the objects you want to get. It is called parent_id because guild_or_channel_id would be horrible to type out every time.

Getting a list of an object:

Here you will see 1 example of how to get a list of objects. The possibilities on how to force (and their results) are the same as in the examples above.

  • Example 1/1: Getting a list of members:

    from typing import List

# you can also use `list[interactions.Member]` if you have python >= 3.9

members = await get(
    client,
    List[interactions.Member],
    parent_id=your_guild_id,
    object_ids=[your_member_id1, your_member_id2, ...],
)

If you enforce cache when getting a list of objects, found objets will be placed into the list and not found objects will be placed as None into the list.

Return type:

Optional[_T]

enum interactions.utils.get.Force(value)[source]#

An enumerable object representing the force types for the get method.

Variables:

  • CACHE (str) – Enforce the usage of cache and block the usage of http

  • HTTP (str) – Enforce the usage of http and block the usage of cache

Member Type:

str

Valid values are as follows:

CACHE = <Force.CACHE: 'cache'>#
HTTP = <Force.HTTP: 'http'>#