hikari.embeds#
Application and entities that are used to describe message embeds on Discord.
Module Contents#
- class hikari.embeds.Embed(*, title=None, description=None, url=None, color=None, colour=None, timestamp=None)[source]#
Represents an embed.
- property author: EmbedAuthor | None[source]#
Return the author to show in the embed.
Will be
None
if not set.Note
Use
set_author
to update this value.
- property color: hikari.colors.Color | None[source]#
Return the colour of the embed.
This will be
None
if not set.
- property colour: hikari.colors.Color | None[source]#
Alias of
color
.
- property description: str | None[source]#
Return the description of the embed.
This will be
None
if not set.
- property fields: Sequence[EmbedField][source]#
Return the sequence of fields in the embed.
Note
Use
add_field
to add a new field,edit_field
to edit an existing field, orremove_field
to remove a field.
Return the footer of the embed.
Will be
None
if not set.
- property image: EmbedImage | None[source]#
Return the image set in the embed.
Will be
None
if not set.Note
Use
set_image
to update this value.
- property provider: EmbedProvider | None[source]#
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: EmbedImage | None[source]#
Return the thumbnail set in the embed.
Will be
None
if not set.Note
Use
set_thumbnail
to update this value.
- property timestamp: datetime.datetime | None[source]#
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: EmbedVideo | None[source]#
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(name, value, *, inline=False)[source]#
Add a new field to this embed.
- Parameters:
- Other Parameters:
- Returns:
Embed
This embed. Allows for call chaining.
- edit_field(index, name=undefined.UNDEFINED, value=undefined.UNDEFINED, /, *, inline=undefined.UNDEFINED)[source]#
Edit an existing field on this embed.
- Parameters:
- index
int
The index of the field to edit.
- index
- Other Parameters:
- name
hikari.undefined.UndefinedOr
[str
] The new field name to use. If left to the default (
undefined
), then it will not be changed.- value
hikari.undefined.UndefinedOr
[str
] The new field value to use. If left to the default (
undefined
), then it will not be changed.- inline
hikari.undefined.UndefinedOr
[bool] True
to inline the field, orFalse
to force it to be on a separate line. If left to the default (undefined
), then it will not be changed.
- name
- Returns:
Embed
This embed. Allows for call chaining.
- Raises:
IndexError
Raised if the index is greater than
len(embed.fields) - 1
or less than-len(embed.fields)
- classmethod from_received_embed(*, title, description, url, color, timestamp, image, thumbnail, video, author, provider, footer, fields)[source]#
Generate an embed from the given attributes.
Warning
This function is for internal use only!
- remove_field(index, /)[source]#
Remove an existing field from this embed.
- Parameters:
- index
int
The index of the embed field to remove.
- index
- Returns:
Embed
This embed. Allows for call chaining.
- Raises:
IndexError
Raised if the index is greater than
len(embed.fields) - 1
or less than-len(embed.fields)
- set_author(*, name=None, url=None, icon=None)[source]#
Set the author of this embed.
- Parameters:
- name
typing.Optional
[str
] The optional name of the author.
- url
typing.Optional
[str
] The optional URL of the author.
- icon
typing.Optional
[hikari.files.Resourceish
] 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
orstr
to a valid URL, the URL is linked to directly.
- If a
- Subclasses of
hikari.files.WebResource
such as hikari.files.URL
,hikari.messages.Attachment
,hikari.emojis.Emoji
,EmbedResource
, etc will have their URL linked to directly. this field.
- Subclasses of
- If a
hikari.files.Bytes
is passed, or astr
that contains a valid data URI is passed, then this is uploaded as an attachment and linked into the embed.
- If a
- 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.
- If a
- name
- Returns:
Embed
This embed. Allows for call chaining.
Set the footer of this embed.
- Parameters:
- text
typing.Optional
[str
] The mandatory text string to set in the footer. If
None
, the footer is removed.- icon
typing.Optional
[hikari.files.Resourceish
] 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
orstr
to a valid URL, the URL is linked to directly.
- If a
- Subclasses of
hikari.files.WebResource
such as hikari.files.URL
,hikari.messages.Attachment
,hikari.emojis.Emoji
,EmbedResource
, etc will have their URL linked to directly. this field.
- Subclasses of
- If a
hikari.files.Bytes
is passed, or astr
that contains a valid data URI is passed, then this is uploaded as an attachment and linked into the embed.
- If a
- 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.
- If a
- text
- Returns:
Embed
This embed. Allows for call chaining.
- set_image(image=None, /)[source]#
Set the image on this embed.
- Parameters:
- image
typing.Optional
[hikari.files.Resourceish
] 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
orstr
to a valid URL, the URL is linked to directly.
- If a
- Subclasses of
hikari.files.WebResource
such as hikari.files.URL
,hikari.messages.Attachment
,hikari.emojis.Emoji
,EmbedResource
, etc will have their URL linked to directly. this field.
- Subclasses of
- If a
hikari.files.Bytes
is passed, or astr
that contains a valid data URI is passed, then this is uploaded as an attachment and linked into the embed.
- If a
- 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.
- If a
- image
- Returns:
Embed
This embed. Allows for call chaining.
- set_thumbnail(image=None, /)[source]#
Set the image on this embed.
- Parameters:
- image
typing.Optional
[hikari.files.Resourceish
] 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
orstr
to a valid URL, the URL is linked to directly.
- If a
- Subclasses of
hikari.files.WebResource
such as hikari.files.URL
,hikari.messages.Attachment
,hikari.emojis.Emoji
,EmbedResource
, etc will have their URL linked to directly.
- Subclasses of
- If a
hikari.files.Bytes
is passed, or astr
that contains a valid data URI is passed, then this is uploaded as an attachment and linked into the embed.
- If a
- 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.
- If a
- image
- Returns:
Embed
This embed. Allows for call chaining.
- class hikari.embeds.EmbedAuthor[source]#
Represents an author of an embed.
- icon: EmbedResourceWithProxy | None[source]#
The author’s icon, or
None
if not present.
- class hikari.embeds.EmbedField[source]#
Represents a field in a embed.
Represents an embed footer.
The URL of the footer icon, or
None
if not present.
The footer text, or
None
if not present.
- class hikari.embeds.EmbedImage[source]#
Bases:
EmbedResourceWithProxy
Represents an embed image.
- class hikari.embeds.EmbedProvider[source]#
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.
- class hikari.embeds.EmbedResource[source]#
Bases:
hikari.files.Resource
[hikari.files.AsyncReader
]A base type for any resource provided in an embed.
Resources can be downloaded and uploaded.
- resource: hikari.files.Resource[hikari.files.AsyncReader][source]#
The resource this object wraps around.
- stream(*, executor=None, head_only=False)[source]#
Produce a stream of data for the resource.
- Parameters:
- executor
typing.Optional
[concurrent.futures.Executor
] The executor to run in for blocking operations. If
None
, then the default executor is used for the current event loop.- head_onlybool
Defaults to
False
. IfTrue
, then the implementation may only retrieve HEAD information if supported. This currently only has any effect for web requests.
- executor
- class hikari.embeds.EmbedResourceWithProxy[source]#
Bases:
EmbedResource
Resource with a corresponding proxied element.
- property proxy_filename: str | None[source]#
File name of the proxied version of this embed resource if applicable, else
None
.
- property proxy_url: str | None[source]#
Proxied URL of this embed resource if applicable, else
None
.
- proxy_resource: hikari.files.Resource[hikari.files.AsyncReader] | None[source]#
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.
- class hikari.embeds.EmbedVideo[source]#
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.