Embed
attrs
class
EmbedField (DictSerializationMixin)
¶
Representation of an embed field.
Attributes:
Name | Type | Description |
---|---|---|
name |
str |
Field name |
value |
str |
Field value |
inline |
bool |
If the field should be inline |
Attr attributes:
Name | Type | Description |
---|
Source code in naff/models/discord/embed.py
@define(kw_only=False)
class EmbedField(DictSerializationMixin):
"""
Representation of an embed field.
Attributes:
name: Field name
value: Field value
inline: If the field should be inline
"""
name: str = field()
value: str = field()
inline: bool = field(default=False)
@name.validator
def _name_validation(self, attribute: str, value: Any) -> None:
if len(value) > EMBED_MAX_NAME_LENGTH:
raise ValueError(f"Field name cannot exceed {EMBED_MAX_NAME_LENGTH} characters")
@value.validator
def _value_validation(self, attribute: str, value: Any) -> None:
if len(value) > EMBED_FIELD_VALUE_LENGTH:
raise ValueError(f"Field value cannot exceed {EMBED_FIELD_VALUE_LENGTH} characters")
def __len__(self) -> int:
return len(self.name) + len(self.value)
inherited
method
update_from_dict(self, data)
¶
Updates object attribute(s) with new json data received from discord api.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data |
Dict[str, Any] |
The json data received from discord api. |
required |
Returns:
Type | Description |
---|---|
~T |
The updated object class instance. |
Source code in naff/models/discord/embed.py
def update_from_dict(self: Type[const.T], data: Dict[str, Any]) -> const.T:
"""
Updates object attribute(s) with new json data received from discord api.
Args:
data: The json data received from discord api.
Returns:
The updated object class instance.
"""
data = self._process_dict(data)
for key, value in self._filter_kwargs(data, self._get_keys()).items():
# todo improve
setattr(self, key, value)
return self
inherited
method
to_dict(self)
¶
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
Type | Description |
---|---|
Dict[str, Any] |
The exported dictionary. |
Source code in naff/models/discord/embed.py
def to_dict(self) -> Dict[str, Any]:
"""
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
The exported dictionary.
"""
self._check_object()
return serializer.to_dict(self)
attrs
class
EmbedAuthor (DictSerializationMixin)
¶
Representation of an embed author.
Attributes:
Name | Type | Description |
---|---|---|
name |
Optional[str] |
Name to show on embed |
url |
Optional[str] |
Url to go to when name is clicked |
icon_url |
Optional[str] |
Icon to show next to name |
proxy_icon_url |
Optional[str] |
Proxy icon url |
Attr attributes:
Name | Type | Description |
---|
Source code in naff/models/discord/embed.py
@define(kw_only=False)
class EmbedAuthor(DictSerializationMixin):
"""
Representation of an embed author.
Attributes:
name: Name to show on embed
url: Url to go to when name is clicked
icon_url: Icon to show next to name
proxy_icon_url: Proxy icon url
"""
name: Optional[str] = field(default=None)
url: Optional[str] = field(default=None)
icon_url: Optional[str] = field(default=None)
proxy_icon_url: Optional[str] = field(default=None, metadata=no_export_meta)
@name.validator
def _name_validation(self, attribute: str, value: Any) -> None:
if len(value) > EMBED_MAX_NAME_LENGTH:
raise ValueError(f"Field name cannot exceed {EMBED_MAX_NAME_LENGTH} characters")
def __len__(self) -> int:
return len(self.name)
inherited
method
update_from_dict(self, data)
¶
Updates object attribute(s) with new json data received from discord api.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data |
Dict[str, Any] |
The json data received from discord api. |
required |
Returns:
Type | Description |
---|---|
~T |
The updated object class instance. |
Source code in naff/models/discord/embed.py
def update_from_dict(self: Type[const.T], data: Dict[str, Any]) -> const.T:
"""
Updates object attribute(s) with new json data received from discord api.
Args:
data: The json data received from discord api.
Returns:
The updated object class instance.
"""
data = self._process_dict(data)
for key, value in self._filter_kwargs(data, self._get_keys()).items():
# todo improve
setattr(self, key, value)
return self
inherited
method
to_dict(self)
¶
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
Type | Description |
---|---|
Dict[str, Any] |
The exported dictionary. |
Source code in naff/models/discord/embed.py
def to_dict(self) -> Dict[str, Any]:
"""
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
The exported dictionary.
"""
self._check_object()
return serializer.to_dict(self)
attrs
class
EmbedAttachment (DictSerializationMixin)
¶
Representation of an attachment.
Attributes:
Name | Type | Description |
---|---|---|
url |
Optional[str] |
Attachment url |
proxy_url |
Optional[str] |
Proxy url |
height |
Optional[int] |
Attachment height |
width |
Optional[int] |
Attachment width |
Attr attributes:
Name | Type | Description |
---|
Source code in naff/models/discord/embed.py
@define(kw_only=False)
class EmbedAttachment(DictSerializationMixin): # thumbnail or image or video
"""
Representation of an attachment.
Attributes:
url: Attachment url
proxy_url: Proxy url
height: Attachment height
width: Attachment width
"""
url: Optional[str] = field(default=None)
proxy_url: Optional[str] = field(default=None, metadata=no_export_meta)
height: Optional[int] = field(default=None, metadata=no_export_meta)
width: Optional[int] = field(default=None, metadata=no_export_meta)
@classmethod
def _process_dict(cls, data: Dict[str, Any]) -> Dict[str, Any]:
if isinstance(data, str):
return {"url": data}
return data
@property
def size(self) -> tuple[Optional[int], Optional[int]]:
return self.height, self.width
inherited
method
update_from_dict(self, data)
¶
Updates object attribute(s) with new json data received from discord api.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data |
Dict[str, Any] |
The json data received from discord api. |
required |
Returns:
Type | Description |
---|---|
~T |
The updated object class instance. |
Source code in naff/models/discord/embed.py
def update_from_dict(self: Type[const.T], data: Dict[str, Any]) -> const.T:
"""
Updates object attribute(s) with new json data received from discord api.
Args:
data: The json data received from discord api.
Returns:
The updated object class instance.
"""
data = self._process_dict(data)
for key, value in self._filter_kwargs(data, self._get_keys()).items():
# todo improve
setattr(self, key, value)
return self
inherited
method
to_dict(self)
¶
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
Type | Description |
---|---|
Dict[str, Any] |
The exported dictionary. |
Source code in naff/models/discord/embed.py
def to_dict(self) -> Dict[str, Any]:
"""
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
The exported dictionary.
"""
self._check_object()
return serializer.to_dict(self)
attrs
class
EmbedFooter (DictSerializationMixin)
¶
Representation of an Embed Footer.
Attributes:
Name | Type | Description |
---|---|---|
text |
str |
Footer text |
icon_url |
Optional[str] |
Footer icon url |
proxy_icon_url |
Optional[str] |
Proxy icon url |
Attr attributes:
Name | Type | Description |
---|
Source code in naff/models/discord/embed.py
@define(kw_only=False)
class EmbedFooter(DictSerializationMixin):
"""
Representation of an Embed Footer.
Attributes:
text: Footer text
icon_url: Footer icon url
proxy_icon_url: Proxy icon url
"""
text: str = field()
icon_url: Optional[str] = field(default=None)
proxy_icon_url: Optional[str] = field(default=None, metadata=no_export_meta)
@classmethod
def converter(cls, ingest: Union[dict, str, "EmbedFooter"]) -> "EmbedFooter":
"""
A converter to handle users passing raw strings or dictionaries as footers to the Embed object.
Args:
ingest: The data to convert
Returns:
An EmbedFooter object
"""
if isinstance(ingest, str):
return cls(text=ingest)
else:
return cls.from_dict(ingest)
def __len__(self) -> int:
return len(self.text)
inherited
method
update_from_dict(self, data)
¶
Updates object attribute(s) with new json data received from discord api.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data |
Dict[str, Any] |
The json data received from discord api. |
required |
Returns:
Type | Description |
---|---|
~T |
The updated object class instance. |
Source code in naff/models/discord/embed.py
def update_from_dict(self: Type[const.T], data: Dict[str, Any]) -> const.T:
"""
Updates object attribute(s) with new json data received from discord api.
Args:
data: The json data received from discord api.
Returns:
The updated object class instance.
"""
data = self._process_dict(data)
for key, value in self._filter_kwargs(data, self._get_keys()).items():
# todo improve
setattr(self, key, value)
return self
inherited
method
to_dict(self)
¶
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
Type | Description |
---|---|
Dict[str, Any] |
The exported dictionary. |
Source code in naff/models/discord/embed.py
def to_dict(self) -> Dict[str, Any]:
"""
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
The exported dictionary.
"""
self._check_object()
return serializer.to_dict(self)
classmethod
method
converter(ingest)
¶
A converter to handle users passing raw strings or dictionaries as footers to the Embed object.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
ingest |
Union[dict, str, EmbedFooter] |
The data to convert |
required |
Returns:
Type | Description |
---|---|
EmbedFooter |
An EmbedFooter object |
Source code in naff/models/discord/embed.py
@classmethod
def converter(cls, ingest: Union[dict, str, "EmbedFooter"]) -> "EmbedFooter":
"""
A converter to handle users passing raw strings or dictionaries as footers to the Embed object.
Args:
ingest: The data to convert
Returns:
An EmbedFooter object
"""
if isinstance(ingest, str):
return cls(text=ingest)
else:
return cls.from_dict(ingest)
attrs
class
EmbedProvider (DictSerializationMixin)
¶
Represents an embed's provider.
Note
Only used by system embeds, not bots
Attributes:
Name | Type | Description |
---|---|---|
name |
Optional[str] |
Provider name |
url |
Optional[str] |
Provider url |
Attr attributes:
Name | Type | Description |
---|
Source code in naff/models/discord/embed.py
@define(kw_only=False)
class EmbedProvider(DictSerializationMixin):
"""
Represents an embed's provider.
Note:
Only used by system embeds, not bots
Attributes:
name: Provider name
url: Provider url
"""
name: Optional[str] = field(default=None)
url: Optional[str] = field(default=None)
inherited
method
update_from_dict(self, data)
¶
Updates object attribute(s) with new json data received from discord api.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data |
Dict[str, Any] |
The json data received from discord api. |
required |
Returns:
Type | Description |
---|---|
~T |
The updated object class instance. |
Source code in naff/models/discord/embed.py
def update_from_dict(self: Type[const.T], data: Dict[str, Any]) -> const.T:
"""
Updates object attribute(s) with new json data received from discord api.
Args:
data: The json data received from discord api.
Returns:
The updated object class instance.
"""
data = self._process_dict(data)
for key, value in self._filter_kwargs(data, self._get_keys()).items():
# todo improve
setattr(self, key, value)
return self
inherited
method
to_dict(self)
¶
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
Type | Description |
---|---|
Dict[str, Any] |
The exported dictionary. |
Source code in naff/models/discord/embed.py
def to_dict(self) -> Dict[str, Any]:
"""
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
The exported dictionary.
"""
self._check_object()
return serializer.to_dict(self)
attrs
class
Embed (DictSerializationMixin)
¶
Represents a discord embed object.
Attr attributes:
Name | Type | Description |
---|---|---|
title |
Optional[str] |
The title of the embed |
description |
Optional[str] |
The description of the embed |
color |
Union[naff.models.discord.color.Color, dict, tuple, list, str, int] |
The colour of the embed |
url |
Optional[str] |
The url the embed should direct to when clicked |
timestamp |
Optional[naff.models.discord.timestamp.Timestamp] |
Timestamp of embed content |
fields |
List[naff.models.discord.embed.EmbedField] |
A list of fields to go in the embed |
author |
Optional[naff.models.discord.embed.EmbedAuthor] |
The author of the embed |
thumbnail |
Optional[naff.models.discord.embed.EmbedAttachment] |
The thumbnail of the embed |
image |
Optional[naff.models.discord.embed.EmbedAttachment] |
The image of the embed |
video |
Optional[naff.models.discord.embed.EmbedAttachment] |
The video of the embed, only used by system embeds |
footer |
Optional[naff.models.discord.embed.EmbedFooter] |
The footer of the embed |
provider |
Optional[naff.models.discord.embed.EmbedProvider] |
The provider of the embed, only used for system embeds |
Source code in naff/models/discord/embed.py
@define(kw_only=False)
class Embed(DictSerializationMixin):
"""Represents a discord embed object."""
title: Optional[str] = field(default=None, repr=True)
"""The title of the embed"""
description: Optional[str] = field(default=None, repr=True)
"""The description of the embed"""
color: Optional[Union[Color, dict, tuple, list, str, int]] = field(
default=None, repr=True, metadata=export_converter(process_color)
)
"""The colour of the embed"""
url: Optional[str] = field(default=None, validator=v_optional(instance_of(str)), repr=True)
"""The url the embed should direct to when clicked"""
timestamp: Optional[Timestamp] = field(
default=None,
converter=c_optional(timestamp_converter),
validator=v_optional(instance_of((datetime, float, int))),
repr=True,
)
"""Timestamp of embed content"""
fields: List[EmbedField] = field(factory=list, converter=EmbedField.from_list, repr=True)
"""A list of [fields][naff.models.discord.embed.EmbedField] to go in the embed"""
author: Optional[EmbedAuthor] = field(default=None, converter=c_optional(EmbedAuthor.from_dict))
"""The author of the embed"""
thumbnail: Optional[EmbedAttachment] = field(default=None, converter=c_optional(EmbedAttachment.from_dict))
"""The thumbnail of the embed"""
image: Optional[EmbedAttachment] = field(default=None, converter=c_optional(EmbedAttachment.from_dict))
"""The image of the embed"""
video: Optional[EmbedAttachment] = field(
default=None, converter=c_optional(EmbedAttachment.from_dict), metadata=no_export_meta
)
"""The video of the embed, only used by system embeds"""
footer: Optional[EmbedFooter] = field(default=None, converter=c_optional(EmbedFooter.converter))
"""The footer of the embed"""
provider: Optional[EmbedProvider] = field(
default=None, converter=c_optional(EmbedProvider.from_dict), metadata=no_export_meta
)
"""The provider of the embed, only used for system embeds"""
type: EmbedTypes = field(default=EmbedTypes.RICH, converter=c_optional(EmbedTypes), metadata=no_export_meta)
@title.validator
def _name_validation(self, attribute: str, value: Any) -> None:
"""Validate the embed title."""
if value is not None:
if isinstance(value, str):
if len(value) > EMBED_MAX_NAME_LENGTH:
raise ValueError(f"Title cannot exceed {EMBED_MAX_NAME_LENGTH} characters")
return
raise TypeError("Title must be of type String")
@description.validator
def _description_validation(self, attribute: str, value: Any) -> None:
"""Validate the description."""
if value is not None:
if isinstance(value, str):
if len(value) > EMBED_MAX_DESC_LENGTH:
raise ValueError(f"Description cannot exceed {EMBED_MAX_DESC_LENGTH} characters")
return
raise TypeError("Description must be of type String")
@fields.validator
def _fields_validation(self, attribute: str, value: Any) -> None:
"""Validate the fields."""
if isinstance(value, list):
if len(value) > EMBED_MAX_FIELDS:
raise ValueError(f"Embeds can only hold {EMBED_MAX_FIELDS} fields")
def _check_object(self) -> None:
self._name_validation("title", self.title)
self._description_validation("description", self.description)
self._fields_validation("fields", self.fields)
if len(self) > EMBED_TOTAL_MAX:
raise ValueError(
"Your embed is too large, more info at https://discord.com/developers/docs/resources/channel#embed-limits"
)
def __len__(self) -> int:
# yes i know there are far more optimal ways to write this
# its written like this for readability
total: int = 0
if self.title:
total += len(self.title)
if self.description:
total += len(self.description)
if self.footer:
total += len(self.footer)
if self.author:
total += len(self.author)
if self.fields:
total += sum(map(len, self.fields))
return total
def __bool__(self) -> bool:
return any(
(
self.title,
self.description,
self.fields,
self.author,
self.thumbnail,
self.footer,
self.image,
self.video,
)
)
def set_author(
self,
name: str,
url: Optional[str] = None,
icon_url: Optional[str] = None,
) -> None:
"""
Set the author field of the embed.
Args:
name: The text to go in the title section
url: A url link to the author
icon_url: A url of an image to use as the icon
"""
self.author = EmbedAuthor(name=name, url=url, icon_url=icon_url)
def set_thumbnail(self, url: str) -> None:
"""
Set the thumbnail of the embed.
Args:
url: the url of the image to use
"""
self.thumbnail = EmbedAttachment(url=url)
def set_image(self, url: str) -> None:
"""
Set the image of the embed.
Args:
url: the url of the image to use
"""
self.image = EmbedAttachment(url=url)
def set_footer(self, text: str, icon_url: Optional[str] = None) -> None:
"""
Set the footer field of the embed.
Args:
text: The text to go in the title section
icon_url: A url of an image to use as the icon
"""
self.footer = EmbedFooter(text=text, icon_url=icon_url)
def add_field(self, name: str, value: Any, inline: bool = False) -> None:
"""
Add a field to the embed.
Args:
name: The title of this field
value: The value in this field
inline: Should this field be inline with other fields?
"""
self.fields.append(EmbedField(name, str(value), inline))
self._fields_validation("fields", self.fields)
inherited
method
update_from_dict(self, data)
¶
Updates object attribute(s) with new json data received from discord api.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data |
Dict[str, Any] |
The json data received from discord api. |
required |
Returns:
Type | Description |
---|---|
~T |
The updated object class instance. |
Source code in naff/models/discord/embed.py
def update_from_dict(self: Type[const.T], data: Dict[str, Any]) -> const.T:
"""
Updates object attribute(s) with new json data received from discord api.
Args:
data: The json data received from discord api.
Returns:
The updated object class instance.
"""
data = self._process_dict(data)
for key, value in self._filter_kwargs(data, self._get_keys()).items():
# todo improve
setattr(self, key, value)
return self
inherited
method
to_dict(self)
¶
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
Type | Description |
---|---|
Dict[str, Any] |
The exported dictionary. |
Source code in naff/models/discord/embed.py
def to_dict(self) -> Dict[str, Any]:
"""
Exports object into dictionary representation, ready to be sent to discord api.
Returns:
The exported dictionary.
"""
self._check_object()
return serializer.to_dict(self)
method
set_author(self, name, url, icon_url)
¶
Set the author field of the embed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name |
str |
The text to go in the title section |
required |
url |
Optional[str] |
A url link to the author |
None |
icon_url |
Optional[str] |
A url of an image to use as the icon |
None |
Source code in naff/models/discord/embed.py
def set_author(
self,
name: str,
url: Optional[str] = None,
icon_url: Optional[str] = None,
) -> None:
"""
Set the author field of the embed.
Args:
name: The text to go in the title section
url: A url link to the author
icon_url: A url of an image to use as the icon
"""
self.author = EmbedAuthor(name=name, url=url, icon_url=icon_url)
method
set_thumbnail(self, url)
¶
Set the thumbnail of the embed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
url |
str |
the url of the image to use |
required |
Source code in naff/models/discord/embed.py
def set_thumbnail(self, url: str) -> None:
"""
Set the thumbnail of the embed.
Args:
url: the url of the image to use
"""
self.thumbnail = EmbedAttachment(url=url)
method
set_image(self, url)
¶
Set the image of the embed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
url |
str |
the url of the image to use |
required |
Source code in naff/models/discord/embed.py
def set_image(self, url: str) -> None:
"""
Set the image of the embed.
Args:
url: the url of the image to use
"""
self.image = EmbedAttachment(url=url)
method
set_footer(self, text, icon_url)
¶
Set the footer field of the embed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
text |
str |
The text to go in the title section |
required |
icon_url |
Optional[str] |
A url of an image to use as the icon |
None |
Source code in naff/models/discord/embed.py
def set_footer(self, text: str, icon_url: Optional[str] = None) -> None:
"""
Set the footer field of the embed.
Args:
text: The text to go in the title section
icon_url: A url of an image to use as the icon
"""
self.footer = EmbedFooter(text=text, icon_url=icon_url)
method
add_field(self, name, value, inline)
¶
Add a field to the embed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name |
str |
The title of this field |
required |
value |
Any |
The value in this field |
required |
inline |
bool |
Should this field be inline with other fields? |
False |
Source code in naff/models/discord/embed.py
def add_field(self, name: str, value: Any, inline: bool = False) -> None:
"""
Add a field to the embed.
Args:
name: The title of this field
value: The value in this field
inline: Should this field be inline with other fields?
"""
self.fields.append(EmbedField(name, str(value), inline))
self._fields_validation("fields", self.fields)
function
process_embeds(embeds)
¶
Process the passed embeds into a format discord will understand.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
embeds |
Union[List[Union[naff.models.discord.embed.Embed, Dict]], naff.models.discord.embed.Embed, Dict] |
List of dict / embeds to process |
required |
Returns:
Type | Description |
---|---|
Optional[List[dict]] |
formatted list for discord |
Source code in naff/models/discord/embed.py
def process_embeds(embeds: Optional[Union[List[Union[Embed, Dict]], Union[Embed, Dict]]]) -> Optional[List[dict]]:
"""
Process the passed embeds into a format discord will understand.
Args:
embeds: List of dict / embeds to process
Returns:
formatted list for discord
"""
if embeds is None:
# Its just empty, so nothing to process.
return embeds
if isinstance(embeds, Embed):
# Single embed, convert it to dict and wrap it into a list for discord.
return [embeds.to_dict()]
if isinstance(embeds, dict):
# We assume the dict correctly represents a single discord embed and just send it blindly
# after wrapping it in a list for discord
return [embeds]
if isinstance(embeds, list):
# A list of embeds, convert Embed to dict representation if needed.
return [embed.to_dict() if isinstance(embed, Embed) else embed for embed in embeds]
raise ValueError(f"Invalid embeds: {embeds}")