hikari.embeds

Application and entities that are used to describe message embeds on Discord.

Embed

Embed(
    *,
    title: Optional[str] = None,
    description: Optional[str] = None,
    url: Optional[str] = None,
    color: Optional[Colorish] = None,
    colour: Optional[Colorish] = None,
    timestamp: Optional[datetime] = None
)

Represents an embed.

author property

author: Optional[EmbedAuthor]

Return the author to show in the embed.

Will be None if not set.

Note

Use hikari.embeds.Embed.set_author to update this value.

color property writable

color: Optional[Color]

Return the colour of the embed.

This will be None if not set.

colour property writable

colour: Optional[Color]

Alias of hikari.colors.Color.

description property writable

description: Optional[str]

Return the description of the embed.

This will be None if not set.

fields property

fields: Sequence[EmbedField]

Return the sequence of fields in the embed.

Note

Use hikari.embeds.Embed.add_field to add a new field, hikari.embeds.Embed.edit_field to edit an existing field, or hikari.embeds.Embed.remove_field to remove a field.

footer property

footer: Optional[EmbedFooter]

Return the footer of the embed.

Will be None if not set.

image property

image: Optional[EmbedImage]

Return the image set in the embed.

Will be None if not set.

Note

Use hikari.embeds.Embed.set_image to update this value.

provider property

provider: Optional[EmbedProvider]

Return the provider to show in the embed.

Will be None if not set.

Note

This object cannot be set by bots or webhooks while sending an embed and will be ignored during serialization. Expect this to be populated on any received embed attached to a message event with a custom provider set.

thumbnail property

thumbnail: Optional[EmbedImage]

Return the thumbnail set in the embed.

Will be None if not set.

Note

Use hikari.embeds.Embed.set_thumbnail to update this value.

timestamp property writable

timestamp: Optional[datetime]

Return the timestamp of the embed.

This will be None if not set.

Warning

Setting a non-timezone-aware datetime will result in a warning being raised. This is done due to potential confusion caused by Discord requiring a UTC timestamp for this field. Any non-timezone aware timestamp is interpreted as using the system's current timezone instead. Thus, using datetime.datetime.utcnow will result in a potentially incorrect timezone being set.

To generate a timezone aware timestamp, use one of the following snippets:

    # Use UTC.
    >>> datetime.datetime.now(tz=datetime.timezone.utc)
    datetime.datetime(2020, 6, 5, 18, 29, 56, 424744, tzinfo=datetime.timezone.utc)

    # Use your current timezone.
    >>> datetime.datetime.now().astimezone()
    datetime.datetime(2020, 7, 7, 8, 57, 9, 775328, tzinfo=..., 'BST'))

By specifying a timezone, Hikari can automatically adjust the given time to UTC without you needing to think about it.

You can generate a timezone-aware timestamp instead of a timezone-naive one by specifying a timezone. Hikari will detect any difference in timezone if the timestamp is non timezone-naive and fix it for you:

    # I am British, and it is June, so we are in daylight saving
    # (UTC+1 or GMT+1, specifically).
    >>> import datetime

    # This is timezone naive, notice no timezone in the repr that
    # gets printed. This is no good to us, as Discord will interpret it
    # as being in the future!
    >>> datetime.datetime.now()
    datetime.datetime(2020, 6, 5, 19, 29, 48, 281716)

    # Instead, this is a timezone-aware timestamp, and we can use this
    # correctly. This will always return the current time in UTC.
    >>> datetime.datetime.now(tz=datetime.timezone.utc)
    datetime.datetime(2020, 6, 5, 18, 29, 56, 424744, tzinfo=datetime.timezone.utc)

    # We could instead use a custom timezone. Since the timezone is
    # explicitly specified, Hikari will convert it to UTC for you when
    # you send the embed.
    >>> ...

A library on PyPI called tzlocal also exists that may be useful to you if you need to get your local timezone for any reason:

    >>> import datetime
    >>> import tzlocal

    # Naive datetime that will show the wrong time on Discord.
    >>> datetime.datetime.now()
    datetime.datetime(2020, 6, 5, 19, 33, 21, 329950)

    # Timezone-aware datetime that uses my local timezone correctly.
    >>> datetime.datetime.now(tz=tzlocal.get_localzone())
    datetime.datetime(2020, 6, 5, 19, 33, 40, 967939, tzinfo=<DstTzInfo 'Europe/London' BST+1:00:00 DST>)

    # Changing timezones.
    >>> dt = datetime.datetime.now(tz=datetime.timezone.utc)
    >>> print(dt)
    datetime.datetime(2020, 6, 5, 18, 38, 27, 863990, tzinfo=datetime.timezone.utc)
    >>> dt.astimezone(tzlocal.get_localzone())
    datetime.datetime(2020, 6, 5, 19, 38, 27, 863990, tzinfo=<DstTzInfo 'Europe/London' BST+1:00:00 DST>)

...this is not required, but you may find it more useful if using the timestamps in debug logs, for example.

title property writable

title: Optional[str]

Return the title of the embed.

This will be None if not set.

url property writable

url: Optional[str]

Return the URL of the embed title.

This will be None if not set.

video property

video: Optional[EmbedVideo]

Return the video to show in the embed.

Will be None if not set.

Note

This object cannot be set by bots or webhooks while sending an embed and will be ignored during serialization. Expect this to be populated on any received embed attached to a message event with a video attached.

add_field

add_field(name: str, value: str, *, inline: bool = False) -> Embed

Add a new field to this embed.

PARAMETER	DESCRIPTION
name	The mandatory non-empty field name. This must contain at least one non-whitespace character to be valid. TYPE: str
value	The mandatory non-empty field value. This must contain at least one non-whitespace character to be valid. TYPE: str

PARAMETER	DESCRIPTION
inline	If True, the embed field may be shown "inline" on some Discord clients with other fields. If False, it is always placed on a separate line. This will default to False. TYPE: bool

RETURNS	DESCRIPTION
Embed	This embed. Allows for call chaining.

edit_field

edit_field(
    index: int,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    value: UndefinedOr[str] = undefined.UNDEFINED,
    /,
    *,
    inline: UndefinedOr[bool] = undefined.UNDEFINED,
) -> Embed

Edit an existing field on this embed.

PARAMETER	DESCRIPTION
index	The index of the field to edit. TYPE: int

PARAMETER	DESCRIPTION
name	The new field name to use. If left to the default (hikari.undefined.UNDEFINED), then it will not be changed. TYPE: UndefinedOr[str]
value	The new field value to use. If left to the default (hikari.undefined.UNDEFINED), then it will not be changed. TYPE: UndefinedOr[str]
inline	True to inline the field, or False to force it to be on a separate line. If left to the default (hikari.undefined.UNDEFINED), then it will not be changed. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
Embed	This embed. Allows for call chaining.

RAISES	DESCRIPTION
IndexError	Raised if the index is greater than len(embed.fields) - 1 or less than -len(embed.fields)

from_received_embed classmethod

from_received_embed(
    *,
    title: Optional[str],
    description: Optional[str],
    url: Optional[str],
    color: Optional[Color],
    timestamp: Optional[datetime],
    image: Optional[EmbedImage],
    thumbnail: Optional[EmbedImage],
    video: Optional[EmbedVideo],
    author: Optional[EmbedAuthor],
    provider: Optional[EmbedProvider],
    footer: Optional[EmbedFooter],
    fields: Optional[MutableSequence[EmbedField]]
) -> Embed

Generate an embed from the given attributes.

Warning

This function is for internal use only!

remove_field

remove_field(index: int) -> Embed

Remove an existing field from this embed.

PARAMETER	DESCRIPTION
index	The index of the embed field to remove. TYPE: int

RETURNS	DESCRIPTION
Embed	This embed. Allows for call chaining.

RAISES	DESCRIPTION
IndexError	Raised if the index is greater than len(embed.fields) - 1 or less than -len(embed.fields)

set_author

set_author(
    *,
    name: Optional[str] = None,
    url: Optional[str] = None,
    icon: Optional[Resourceish] = None
) -> Embed

Set the author of this embed.

PARAMETER	DESCRIPTION
name	The optional name of the author. TYPE: Optional[str] DEFAULT: None
url	The optional URL of the author. TYPE: Optional[str] DEFAULT: None
icon	The optional image to show next to the embed author. This can be many different things, to aid in convenience. If None, nothing is set. If a pathlib.PurePath or str to a valid URL, the URL is linked to directly. Subclasses of hikari.files.WebResource such as hikari.files.URL, hikari.messages.Attachment, hikari.emojis.Emoji, hikari.embeds.EmbedResource, etc will have their URL linked to directly. this field. If a hikari.files.Bytes is passed, or a str that contains a valid data URI is passed, then this is uploaded as an attachment and linked into the embed. If a hikari.files.File, pathlib.PurePath or str that is an absolute or relative path to a file on your file system is passed, then this resource is uploaded as an attachment using non-blocking code internally and linked into the embed. TYPE: Optional[Resourceish] DEFAULT: None

RETURNS	DESCRIPTION
Embed	This embed. Allows for call chaining.

set_footer

set_footer(text: Optional[str], *, icon: Optional[Resourceish] = None) -> Embed

Set the footer of this embed.

PARAMETER	DESCRIPTION
text	The mandatory text string to set in the footer. If None, the footer is removed. TYPE: Optional[str]
icon	The optional image to show next to the embed footer. This can be many different things, to aid in convenience. If None, nothing is set. If a pathlib.PurePath or str to a valid URL, the URL is linked to directly. Subclasses of hikari.files.WebResource such as hikari.files.URL, hikari.messages.Attachment, hikari.emojis.Emoji, hikari.embeds.EmbedResource, etc. will have their URL linked to directly. this field. If a hikari.files.Bytes is passed, or a str that contains a valid data URI is passed, then this is uploaded as an attachment and linked into the embed. If a hikari.files.File, pathlib.PurePath or str that is an absolute or relative path to a file on your file system is passed, then this resource is uploaded as an attachment using non-blocking code internally and linked into the embed. TYPE: Optional[Resourceish] DEFAULT: None

RETURNS	DESCRIPTION
Embed	This embed. Allows for call chaining.

set_image

set_image(image: Optional[Resourceish] = None) -> Embed

Set the image on this embed.

PARAMETER

DESCRIPTION

image

The optional resource to show for the embed image. This can be many different things, to aid in convenience. If None, nothing is set. If a pathlib.PurePath or str to a valid URL, the URL is linked to directly. Subclasses of hikari.files.WebResource such as hikari.files.URL, hikari.messages.Attachment, hikari.emojis.Emoji, hikari.embeds.EmbedResource, etc will have their URL linked to directly. this field. If a hikari.files.Bytes is passed, or a str that contains a valid data URI is passed, then this is uploaded as an attachment and linked into the embed. If a hikari.files.File, pathlib.PurePath or str that is an absolute or relative path to a file on your file system is passed, then this resource is uploaded as an attachment using non-blocking code internally and linked into the embed. TYPE: Optional[Resourceish] DEFAULT: None

RETURNS	DESCRIPTION
Embed	This embed. Allows for call chaining.

set_thumbnail

set_thumbnail(image: Optional[Resourceish] = None) -> Embed

Set the image on this embed.

PARAMETER

DESCRIPTION

image

The optional resource to show for the embed thumbnail. This can be many different things, to aid in convenience. If None, nothing is set. If a pathlib.PurePath or str to a valid URL, the URL is linked to directly. Subclasses of hikari.files.WebResource such as hikari.files.URL, hikari.messages.Attachment, hikari.emojis.Emoji, hikari.embeds.EmbedResource, etc will have their URL linked to directly. If a hikari.files.Bytes is passed, or a str that contains a valid data URI is passed, then this is uploaded as an attachment and linked into the embed. If a hikari.files.File, pathlib.PurePath or str that is an absolute or relative path to a file on your file system is passed, then this resource is uploaded as an attachment using non-blocking code internally and linked into the embed. TYPE: Optional[Resourceish] DEFAULT: None

RETURNS	DESCRIPTION
Embed	This embed. Allows for call chaining.

total_length

total_length() -> int

Get the total character count of the embed.

RETURNS	DESCRIPTION
int	The total character count of this embed, including title, description, fields, footer, and author combined.

EmbedAuthor

Represents an author of an embed.

icon class-attribute instance-attribute

icon: Optional[EmbedResourceWithProxy] = field(default=None, repr=False)

The author's icon, or None if not present.

name class-attribute instance-attribute

name: Optional[str] = field(default=None, repr=True)

The name of the author, or None if not specified.

url class-attribute instance-attribute

url: Optional[str] = field(default=None, repr=True)

The URL that the author's name should act as a hyperlink to.

This may be None if no hyperlink on the author's name is specified.

EmbedField

Represents a field in a embed.

is_inline property writable

is_inline: bool

Whether the field should display inline.

Defaults to False.

name class-attribute instance-attribute

name: str = field(repr=True)

The name of the field.

value class-attribute instance-attribute

value: str = field(repr=True)

The value of the field.

EmbedFooter

Represents an embed footer.

icon class-attribute instance-attribute

icon: Optional[EmbedResourceWithProxy] = field(default=None, repr=True)

The URL of the footer icon, or None if not present.

text class-attribute instance-attribute

text: Optional[str] = field(default=None, repr=True)

The footer text, or None if not present.

EmbedImage

Bases: EmbedResourceWithProxy

Represents an embed image.

extension property

extension: Optional[str]

File extension, if there is one.

filename property

filename: str

File name of this embed resource.

height class-attribute instance-attribute

height: Optional[int] = field(default=None, repr=False)

The height of the image, if present and known, otherwise None.

Note

This field cannot be set by bots or webhooks while sending an embed and will be ignored during serialization. Expect this to be populated on any received embed attached to a message event.

proxy_filename property

proxy_filename: Optional[str]

File name of the proxied version of this embed resource if applicable, else None.

proxy_resource class-attribute instance-attribute

proxy_resource: Optional[Resource[AsyncReader]] = field(
    default=None, repr=False
)

The proxied version of the resource, or None if not present.

Note

This field cannot be set by bots or webhooks while sending an embed and will be ignored during serialization. Expect this to be populated on any received embed attached to a message event.

proxy_url property

proxy_url: Optional[str]

Proxied URL of this embed resource if applicable, else None.

resource class-attribute instance-attribute

resource: Resource[AsyncReader] = field(repr=True)

The resource this object wraps around.

url property

url: str

URL of this embed resource.

width class-attribute instance-attribute

width: Optional[int] = field(default=None, repr=False)

The width of the image, if present and known, otherwise None.

Note

This field cannot be set by bots or webhooks while sending an embed and will be ignored during serialization. Expect this to be populated on any received embed attached to a message event.

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[AsyncReader]

Produce a stream of data for the resource.

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
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

EmbedProvider

Represents an embed provider.

Note

This object cannot be set by bots or webhooks while sending an embed and will be ignored during serialization. Expect this to be populated on any received embed attached to a message event provided by an external source.

Therefore, you should never need to initialize an instance of this class yourself.

name class-attribute instance-attribute

name: Optional[str] = field(default=None, repr=True)

The name of the provider.

url class-attribute instance-attribute

url: Optional[str] = field(default=None, repr=True)

The URL of the provider.

EmbedResource

Bases: Resource[AsyncReader]

A base type for any resource provided in an embed.

Resources can be downloaded and uploaded.

extension property

extension: Optional[str]

File extension, if there is one.

filename property

filename: str

File name of this embed resource.

resource class-attribute instance-attribute

resource: Resource[AsyncReader] = field(repr=True)

The resource this object wraps around.

url property

url: str

URL of this embed resource.

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[AsyncReader]

Produce a stream of data for the resource.

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
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

EmbedResourceWithProxy

Bases: EmbedResource

Resource with a corresponding proxied element.

extension property

extension: Optional[str]

File extension, if there is one.

filename property

filename: str

File name of this embed resource.

proxy_filename property

proxy_filename: Optional[str]

File name of the proxied version of this embed resource if applicable, else None.

proxy_resource class-attribute instance-attribute

proxy_resource: Optional[Resource[AsyncReader]] = field(
    default=None, repr=False
)

The proxied version of the resource, or None if not present.

Note

This field cannot be set by bots or webhooks while sending an embed and will be ignored during serialization. Expect this to be populated on any received embed attached to a message event.

proxy_url property

proxy_url: Optional[str]

Proxied URL of this embed resource if applicable, else None.

resource class-attribute instance-attribute

resource: Resource[AsyncReader] = field(repr=True)

The resource this object wraps around.

url property

url: str

URL of this embed resource.

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[AsyncReader]

Produce a stream of data for the resource.

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
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

EmbedVideo

Bases: EmbedResourceWithProxy

Represents an embed video.

Note

This object cannot be set by bots or webhooks while sending an embed and will be ignored during serialization. Expect this to be populated on any received embed attached to a message event with a video attached.

Therefore, you should never need to initialize an instance of this class yourself.

extension property

extension: Optional[str]

File extension, if there is one.

filename property

filename: str

File name of this embed resource.

height class-attribute instance-attribute

height: Optional[int] = field(default=None, repr=False)

The height of the video.

proxy_filename property

proxy_filename: Optional[str]

File name of the proxied version of this embed resource if applicable, else None.

proxy_resource class-attribute instance-attribute

proxy_resource: Optional[Resource[AsyncReader]] = field(
    default=None, repr=False
)

The proxied version of the resource, or None if not present.

Note

This field cannot be set by bots or webhooks while sending an embed and will be ignored during serialization. Expect this to be populated on any received embed attached to a message event.

proxy_url property

proxy_url: Optional[str]

Proxied URL of this embed resource if applicable, else None.

resource class-attribute instance-attribute

resource: Resource[AsyncReader] = field(repr=True)

The resource this object wraps around.

url property

url: str

URL of this embed resource.

width class-attribute instance-attribute

width: Optional[int] = field(default=None, repr=False)

The width of the video.

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[AsyncReader]

Produce a stream of data for the resource.

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
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