hikari.embeds#
Application and entities that are used to describe message embeds on Discord.
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.
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.
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.
property #
footer: Optional[EmbedFooter]
Return the footer of the embed.
Will be None if not set.
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.
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.
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.
property writable #
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.
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 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: |
value | The mandatory non-empty field value. This must contain at least one non-whitespace character to be valid. TYPE: |
inline | If TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Embed | This embed. Allows for call chaining. |
clear_fields() -> Embed
Remove all existing fields from this embed.
| RETURNS | DESCRIPTION |
|---|---|
Embed | This embed. Allows for call chaining. |
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: |
name | The new field name to use. If left to the default ( TYPE: |
value | The new field value to use. If left to the default ( TYPE: |
inline |
TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Embed | This embed. Allows for call chaining. |
| RAISES | DESCRIPTION |
|---|---|
IndexError | Raised if the index is greater than |
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 an existing field from this embed.
| PARAMETER | DESCRIPTION |
|---|---|
index | The index of the embed field to remove. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Embed | This embed. Allows for call chaining. |
| RAISES | DESCRIPTION |
|---|---|
IndexError | Raised if the index is greater than |
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. |
url | The optional URL of the author. |
icon | The optional image to show next to the embed author. This can be many different things, to aid in convenience.
TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Embed | This embed. Allows for call chaining. |
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 |
icon | The optional image to show next to the embed footer. This can be many different things, to aid in convenience.
TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Embed | This embed. Allows for call chaining. |
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.
TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Embed | This embed. Allows for call chaining. |
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.
TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Embed | This embed. Allows for call chaining. |
Represents a field in a embed.
Represents an embed footer.
class-attribute instance-attribute #
icon: Optional[EmbedResourceWithProxy] = field(default=None, repr=True)
The URL of the footer icon, or None if not present.
Bases: EmbedResourceWithProxy
Represents an embed image.
class-attribute instance-attribute #
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.
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.
Bases: Resource[AsyncReader]
A base type for any resource provided in an embed.
Resources can be downloaded and uploaded.
class-attribute instance-attribute #
resource: Resource[AsyncReader] = field(repr=True)
The resource this object wraps around.
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 |
head_only | If TYPE: |
Bases: EmbedResource
Resource with a corresponding proxied element.
property #
File name of the proxied version of this embed resource if applicable, else None.
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.
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.