hikari.emojis

Application and entities that are used to describe emojis on Discord.

CustomEmoji

Bases: Unique, Emoji

Represents a custom emoji.

This is a custom emoji that is from a guild you might not be part of.

All CustomEmoji objects and their derivatives act as valid hikari.files.Resource objects. This means you can use them as a file when sending a message.

>>> emojis = await bot.rest.fetch_guild_emojis(12345)
>>> picks = random.choices(emojis, 5)
>>> await event.respond(files=picks)

Warning

Discord will not provide information on whether these emojis are animated or not when a reaction is removed and an event is fired. This is problematic if you need to try and determine the emoji that was removed. The side effect of this means that mentions for animated emojis will not be correct.

This will not be changed as stated here: https://github.com/discord/discord-api-docs/issues/1614#issuecomment-628548913

created_at property

created_at: datetime

When the object was created.

extension property

extension: Optional[str]

File extension, if there is one.

filename property

filename: str

Filename of the resource.

id class-attribute instance-attribute

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

is_animated class-attribute instance-attribute

is_animated: bool = field(eq=False, hash=False, repr=True)

Whether the emoji is animated.

mention property

mention: str

Mention string to use to mention the emoji with.

name class-attribute instance-attribute

name: str = field(eq=False, hash=False, repr=True)

The name of the emoji.

url property

url: str

URL of the emoji image to display in clients.

url_name property

url_name: str

Name of the part of the emoji to use in requests.

parse classmethod

parse(string: str) -> CustomEmoji

Parse a given emoji mention string into a custom emoji object.

PARAMETER	DESCRIPTION
string	The emoji mention to parse. TYPE: str

RETURNS	DESCRIPTION
CustomEmoji	The parsed emoji object.

RAISES	DESCRIPTION
ValueError	If a mention is given that has an invalid format.

read async

read(*, executor: Optional[Executor] = None) -> bytes

Read the entire resource at once into memory.

    data = await resource.read(...)
    # ^-- This is a shortcut for the following --v
    async with resource.stream(...) as reader:
        data = await reader.read()

Warning

If you simply wish to re-upload this resource to Discord via any endpoint in Hikari, you should opt to just pass this resource object directly. This way, Hikari can perform byte inception, which significantly reduces the memory usage for your bot as it grows larger.

PARAMETER	DESCRIPTION
executor	The executor to run in for blocking operations. If None, then the default executor is used for the current event loop. TYPE: Optional[Executor] DEFAULT: None

RETURNS	DESCRIPTION
bytes	The entire resource.

save async

save(
    path: Pathish, *, executor: Optional[Executor] = None, force: bool = False
) -> None

Save this resource to disk.

This writes the resource file in chunks, and so does not load the entire resource into memory.

PARAMETER	DESCRIPTION
path	The path to save this resource to. If this is a string, the path will be relative to the current working directory. TYPE: Pathish
executor	The executor to run in for blocking operations. If None, then the default executor is used for the current event loop. TYPE: Optional[Executor] DEFAULT: None
force	Whether to overwrite an existing file. TYPE: bool DEFAULT: False

stream

stream(
    *, executor: Optional[Executor] = None, head_only: bool = False
) -> AsyncReaderContextManager[WebReader]

Start streaming the content into memory by downloading it.

You can use this to fetch the entire resource, parts of the resource, or just to view any metadata that may be provided.

PARAMETER	DESCRIPTION
executor	Not used. Provided only to match the underlying interface. TYPE: Optional[Executor] DEFAULT: None
head_only	If True, then the implementation may only retrieve HEAD information if supported. This currently only has any effect for web requests. TYPE: bool DEFAULT: False

Examples:

Downloading an entire resource at once into memory:

    async with obj.stream() as stream:
        data = await stream.read()

Checking the metadata:

    async with obj.stream() as stream:
        mimetype = stream.mimetype

    if mimetype is None:
        ...
    elif mimetype not in whitelisted_mimetypes:
        ...
    else:
        ...

Fetching the data-uri of a resource:

    async with obj.stream() as stream:
        data_uri = await stream.data_uri()

RETURNS	DESCRIPTION
AsyncReaderContextManager[WebReader]	An async context manager that when entered, produces the data stream.

RAISES	DESCRIPTION
BadRequestError	If a 400 is returned.
UnauthorizedError	If a 401 is returned.
ForbiddenError	If a 403 is returned.
NotFoundError	If a 404 is returned.
ClientHTTPResponseError	If any other 4xx is returned.
InternalServerError	If any other 5xx is returned.
HTTPResponseError	If any other unexpected response code is returned.

Emoji

Bases: WebResource, ABC

Base class for all emojis.

Any emoji implementation supports being used as a hikari.files.Resource when uploading an attachment to the API. This is achieved in the same way as using a hikari.files.WebResource would achieve this.

extension property

extension: Optional[str]

File extension, if there is one.

filename abstractmethod property

filename: str

Filename of the resource.

mention abstractmethod property

mention: str

Mention string to use to mention the emoji with.

name abstractmethod property

name: str

Return the generic name/representation for this emoji.

url abstractmethod property

url: str

URL of the emoji image to display in clients.

url_name abstractmethod property

url_name: str

Name of the part of the emoji to use in requests.

parse classmethod

parse(string: str) -> Union[UnicodeEmoji, CustomEmoji]

Parse a given string into an emoji object.

PARAMETER	DESCRIPTION
string	The emoji object to parse. TYPE: str

RETURNS	DESCRIPTION
Union[UnicodeEmoji, CustomEmoji]	The parsed emoji object. This will be a hikari.emojis.CustomEmoji if a custom emoji mention, or a hikari.emojis.UnicodeEmoji otherwise.

RAISES	DESCRIPTION
ValueError	If a mention is given that has an invalid format.

read async

read(*, executor: Optional[Executor] = None) -> bytes

Read the entire resource at once into memory.

    data = await resource.read(...)
    # ^-- This is a shortcut for the following --v
    async with resource.stream(...) as reader:
        data = await reader.read()

Warning

If you simply wish to re-upload this resource to Discord via any endpoint in Hikari, you should opt to just pass this resource object directly. This way, Hikari can perform byte inception, which significantly reduces the memory usage for your bot as it grows larger.

PARAMETER	DESCRIPTION
executor	The executor to run in for blocking operations. If None, then the default executor is used for the current event loop. TYPE: Optional[Executor] DEFAULT: None

RETURNS	DESCRIPTION
bytes	The entire resource.

save async

save(
    path: Pathish, *, executor: Optional[Executor] = None, force: bool = False
) -> None

Save this resource to disk.

This writes the resource file in chunks, and so does not load the entire resource into memory.

PARAMETER	DESCRIPTION
path	The path to save this resource to. If this is a string, the path will be relative to the current working directory. TYPE: Pathish
executor	The executor to run in for blocking operations. If None, then the default executor is used for the current event loop. TYPE: Optional[Executor] DEFAULT: None
force	Whether to overwrite an existing file. TYPE: bool DEFAULT: False

stream

stream(
    *, executor: Optional[Executor] = None, head_only: bool = False
) -> AsyncReaderContextManager[WebReader]

Start streaming the content into memory by downloading it.

You can use this to fetch the entire resource, parts of the resource, or just to view any metadata that may be provided.

PARAMETER	DESCRIPTION
executor	Not used. Provided only to match the underlying interface. TYPE: Optional[Executor] DEFAULT: None
head_only	If True, then the implementation may only retrieve HEAD information if supported. This currently only has any effect for web requests. TYPE: bool DEFAULT: False

Examples:

Downloading an entire resource at once into memory:

    async with obj.stream() as stream:
        data = await stream.read()

Checking the metadata:

    async with obj.stream() as stream:
        mimetype = stream.mimetype

    if mimetype is None:
        ...
    elif mimetype not in whitelisted_mimetypes:
        ...
    else:
        ...

Fetching the data-uri of a resource:

    async with obj.stream() as stream:
        data_uri = await stream.data_uri()

RETURNS	DESCRIPTION
AsyncReaderContextManager[WebReader]	An async context manager that when entered, produces the data stream.

RAISES	DESCRIPTION
BadRequestError	If a 400 is returned.
UnauthorizedError	If a 401 is returned.
ForbiddenError	If a 403 is returned.
NotFoundError	If a 404 is returned.
ClientHTTPResponseError	If any other 4xx is returned.
InternalServerError	If any other 5xx is returned.
HTTPResponseError	If any other unexpected response code is returned.

KnownCustomEmoji

Bases: CustomEmoji

Represents an emoji that is known from a guild the bot is in.

This is a specialization of hikari.emojis.CustomEmoji that is from a guild that you are part of. As a result, it contains a lot more information with it.

app class-attribute instance-attribute

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

created_at property

created_at: datetime

When the object was created.

extension property

extension: Optional[str]

File extension, if there is one.

filename property

filename: str

Filename of the resource.

guild_id class-attribute instance-attribute

guild_id: Snowflake = field(eq=False, hash=False, repr=False)

The ID of the guild this emoji belongs to.

id class-attribute instance-attribute

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

is_animated class-attribute instance-attribute

is_animated: bool = field(eq=False, hash=False, repr=True)

Whether the emoji is animated.

is_available class-attribute instance-attribute

is_available: bool = field(eq=False, hash=False, repr=False)

Whether this emoji can currently be used.

May be False due to a loss of Sever Boosts on the emoji's guild.

is_colons_required class-attribute instance-attribute

is_colons_required: bool = field(eq=False, hash=False, repr=False)

Whether this emoji must be wrapped in colons.

is_managed class-attribute instance-attribute

is_managed: bool = field(eq=False, hash=False, repr=False)

Whether the emoji is managed by an integration.

mention property

mention: str

Mention string to use to mention the emoji with.

name class-attribute instance-attribute

name: str = field(eq=False, hash=False, repr=True)

The name of the emoji.

role_ids class-attribute instance-attribute

role_ids: Sequence[Snowflake] = field(eq=False, hash=False, repr=False)

The IDs of the roles that are whitelisted to use this emoji.

If this is empty then any user can use this emoji regardless of their roles.

url property

url: str

URL of the emoji image to display in clients.

url_name property

url_name: str

Name of the part of the emoji to use in requests.

user class-attribute instance-attribute

user: Optional[User] = field(eq=False, hash=False, repr=False)

The user that created the emoji.

Note

This will be None if you are missing the hikari.permissions.Permissions.MANAGE_GUILD_EXPRESSIONS permission in the server the emoji is from.

parse classmethod

parse(string: str) -> CustomEmoji

Parse a given emoji mention string into a custom emoji object.

PARAMETER	DESCRIPTION
string	The emoji mention to parse. TYPE: str

RETURNS	DESCRIPTION
CustomEmoji	The parsed emoji object.

RAISES	DESCRIPTION
ValueError	If a mention is given that has an invalid format.

read async

read(*, executor: Optional[Executor] = None) -> bytes

Read the entire resource at once into memory.

    data = await resource.read(...)
    # ^-- This is a shortcut for the following --v
    async with resource.stream(...) as reader:
        data = await reader.read()

Warning

If you simply wish to re-upload this resource to Discord via any endpoint in Hikari, you should opt to just pass this resource object directly. This way, Hikari can perform byte inception, which significantly reduces the memory usage for your bot as it grows larger.

PARAMETER	DESCRIPTION
executor	The executor to run in for blocking operations. If None, then the default executor is used for the current event loop. TYPE: Optional[Executor] DEFAULT: None

RETURNS	DESCRIPTION
bytes	The entire resource.

save async

save(
    path: Pathish, *, executor: Optional[Executor] = None, force: bool = False
) -> None

Save this resource to disk.

This writes the resource file in chunks, and so does not load the entire resource into memory.

PARAMETER	DESCRIPTION
path	The path to save this resource to. If this is a string, the path will be relative to the current working directory. TYPE: Pathish
executor	The executor to run in for blocking operations. If None, then the default executor is used for the current event loop. TYPE: Optional[Executor] DEFAULT: None
force	Whether to overwrite an existing file. TYPE: bool DEFAULT: False

stream

stream(
    *, executor: Optional[Executor] = None, head_only: bool = False
) -> AsyncReaderContextManager[WebReader]

Start streaming the content into memory by downloading it.

You can use this to fetch the entire resource, parts of the resource, or just to view any metadata that may be provided.

PARAMETER	DESCRIPTION
executor	Not used. Provided only to match the underlying interface. TYPE: Optional[Executor] DEFAULT: None
head_only	If True, then the implementation may only retrieve HEAD information if supported. This currently only has any effect for web requests. TYPE: bool DEFAULT: False

Examples:

Downloading an entire resource at once into memory:

    async with obj.stream() as stream:
        data = await stream.read()

Checking the metadata:

    async with obj.stream() as stream:
        mimetype = stream.mimetype

    if mimetype is None:
        ...
    elif mimetype not in whitelisted_mimetypes:
        ...
    else:
        ...

Fetching the data-uri of a resource:

    async with obj.stream() as stream:
        data_uri = await stream.data_uri()

RETURNS	DESCRIPTION
AsyncReaderContextManager[WebReader]	An async context manager that when entered, produces the data stream.

RAISES	DESCRIPTION
BadRequestError	If a 400 is returned.
UnauthorizedError	If a 401 is returned.
ForbiddenError	If a 403 is returned.
NotFoundError	If a 404 is returned.
ClientHTTPResponseError	If any other 4xx is returned.
InternalServerError	If any other 5xx is returned.
HTTPResponseError	If any other unexpected response code is returned.

UnicodeEmoji

Bases: str, Emoji

Represents a unicode emoji.

Warning

A word of warning if you try to upload this emoji as a file attachment.

While this emoji type can be used to upload the Twemoji representations of this emoji as a PNG, this is NOT foolproof. The mapping between Discord's implementation and official Twemoji bindings is very flaky. Responsible implementations relying on this behaviour will be implemented to expect this behaviour in the form of hikari.errors.NotFoundError exceptions being raised when a mismatch may occur. It is also likely that this will change in the future without notice, so you will likely be relying on flaky behaviour.

If this is proven to be too unstable, this functionality will be removed in a future release after a deprecation period.

codepoints property

codepoints: Sequence[int]

Integer codepoints that make up this emoji, as UTF-8.

extension property

extension: Optional[str]

File extension, if there is one.

filename property

filename: str

Filename to use if re-uploading this emoji's PNG.

mention property

mention: str

Mention string to use to mention the emoji with.

name property

name: str

Return the code points which form the emoji.

unicode_escape property

unicode_escape: str

Get the unicode escape string for this emoji.

url property

url: str

Get the URL of the PNG rendition of this emoji.

This will use the official Twitter "twemoji" repository to fetch this information, as Discord only stores this in a hashed format that uses SVG files, which is not usually of any use.

Since this uses "twemoji" directly, the emojis may not directly match what is on Discord if Discord have failed to keep their emoji packs up-to-date with this repository.

Examples:

    >>> emoji = hikari.UnicodeEmoji("👌")
    >>> emoji.url
    'https://raw.githubusercontent.com/discord/twemoji/master/assets/72x72/1f44c.png'

url_name property

url_name: str

Name of the part of the emoji to use in requests.

parse classmethod

parse(string: str) -> UnicodeEmoji

Parse a given string into a unicode emoji object.

PARAMETER	DESCRIPTION
string	The emoji object to parse. TYPE: str

RETURNS	DESCRIPTION
UnicodeEmoji	The parsed UnicodeEmoji object.

parse_codepoints classmethod

parse_codepoints(codepoint: int, *codepoints: int) -> UnicodeEmoji

Create a unicode emoji from one or more UTF-32 codepoints.

parse_unicode_escape classmethod

parse_unicode_escape(escape: str) -> UnicodeEmoji

Create a unicode emoji from a unicode escape string.

read async

read(*, executor: Optional[Executor] = None) -> bytes

Read the entire resource at once into memory.

    data = await resource.read(...)
    # ^-- This is a shortcut for the following --v
    async with resource.stream(...) as reader:
        data = await reader.read()

Warning

If you simply wish to re-upload this resource to Discord via any endpoint in Hikari, you should opt to just pass this resource object directly. This way, Hikari can perform byte inception, which significantly reduces the memory usage for your bot as it grows larger.

PARAMETER	DESCRIPTION
executor	The executor to run in for blocking operations. If None, then the default executor is used for the current event loop. TYPE: Optional[Executor] DEFAULT: None

RETURNS	DESCRIPTION
bytes	The entire resource.

save async

save(
    path: Pathish, *, executor: Optional[Executor] = None, force: bool = False
) -> None

Save this resource to disk.

This writes the resource file in chunks, and so does not load the entire resource into memory.

PARAMETER	DESCRIPTION
path	The path to save this resource to. If this is a string, the path will be relative to the current working directory. TYPE: Pathish
executor	The executor to run in for blocking operations. If None, then the default executor is used for the current event loop. TYPE: Optional[Executor] DEFAULT: None
force	Whether to overwrite an existing file. TYPE: bool DEFAULT: False

stream

stream(
    *, executor: Optional[Executor] = None, head_only: bool = False
) -> AsyncReaderContextManager[WebReader]

Start streaming the content into memory by downloading it.

You can use this to fetch the entire resource, parts of the resource, or just to view any metadata that may be provided.

PARAMETER	DESCRIPTION
executor	Not used. Provided only to match the underlying interface. TYPE: Optional[Executor] DEFAULT: None
head_only	If True, then the implementation may only retrieve HEAD information if supported. This currently only has any effect for web requests. TYPE: bool DEFAULT: False

Examples:

Downloading an entire resource at once into memory:

    async with obj.stream() as stream:
        data = await stream.read()

Checking the metadata:

    async with obj.stream() as stream:
        mimetype = stream.mimetype

    if mimetype is None:
        ...
    elif mimetype not in whitelisted_mimetypes:
        ...
    else:
        ...

Fetching the data-uri of a resource:

    async with obj.stream() as stream:
        data_uri = await stream.data_uri()

RETURNS	DESCRIPTION
AsyncReaderContextManager[WebReader]	An async context manager that when entered, produces the data stream.

RAISES	DESCRIPTION
BadRequestError	If a 400 is returned.
UnauthorizedError	If a 401 is returned.
ForbiddenError	If a 403 is returned.
NotFoundError	If a 404 is returned.
ClientHTTPResponseError	If any other 4xx is returned.
InternalServerError	If any other 5xx is returned.
HTTPResponseError	If any other unexpected response code is returned.