Skip to content

docs: add/adjust docstrings for components #1777

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: unstable
Choose a base branch
from
Open

docs: add/adjust docstrings for components #1777

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 130 additions & 16 deletions interactions/models/discord/components.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,18 @@


class UnfurledMediaItem(DictSerializationMixin):
"""A basic object for making media items."""
"""
A basic object for making media items.

Attributes:
url str: The source url of the media.
proxy_url Optional[str]: A proxied url of the media. Only present when provided by Discord.
height Optional[int]: The height of the media. Only present when provided by Discord.
width Optional[int]: The width of the media. Only present when provided by Discord.
content_type Optional[str]: The content type of the media. Only present when provided by Discord.
loading_state Optional[UnfurledMediaItemLoadingState]: The loading state of the media.

"""

url: str
proxy_url: Optional[str] = None
Expand Down Expand Up @@ -569,12 +580,12 @@ class StringSelectMenu(BaseSelectMenu):

Attributes:
options List[dict]: The choices in the select, max 25.
custom_id str: A developer-defined identifier for the button, max 100 characters.
custom_id str: A developer-defined identifier for the select, max 100 characters.
placeholder str: The custom placeholder text to show if nothing is selected, max 100 characters.
min_values Optional[int]: The minimum number of items that must be chosen. (default 1, min 0, max 25)
max_values Optional[int]: The maximum number of items that can be chosen. (default 1, max 25)
disabled bool: Disable the select and make it not intractable, default false.
type Union[ComponentType, int]: The action role type number defined by discord. This cannot be modified.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

Expand Down Expand Up @@ -630,12 +641,13 @@ class UserSelectMenu(DefaultableSelectMenu):
Represents a user select component.

Attributes:
custom_id str: A developer-defined identifier for the button, max 100 characters.
placeholder str: The custom placeholder text to show if nothing is selected, max 100 characters.
min_values Optional[int]: The minimum number of items that must be chosen. (default 1, min 0, max 25)
max_values Optional[int]: The maximum number of items that can be chosen. (default 1, max 25)
custom_id str: A developer-defined identifier for the select, max 100 characters.
default_values list[BaseUser, Member, SelectDefaultValues]: A list of default values to pre-select in the select.
disabled bool: Disable the select and make it not intractable, default false.
type Union[ComponentType, int]: The action role type number defined by discord. This cannot be modified.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

Expand All @@ -650,8 +662,6 @@ def __init__(
list[
Union[
"interactions.models.discord.BaseUser",
"interactions.models.discord.Role",
"interactions.models.discord.BaseChannel",
"interactions.models.discord.Member",
SelectDefaultValues,
],
Expand All @@ -674,15 +684,16 @@ def __init__(

class RoleSelectMenu(DefaultableSelectMenu):
"""
Represents a user select component.
Represents a role select component.

Attributes:
custom_id str: A developer-defined identifier for the button, max 100 characters.
placeholder str: The custom placeholder text to show if nothing is selected, max 100 characters.
min_values Optional[int]: The minimum number of items that must be chosen. (default 1, min 0, max 25)
max_values Optional[int]: The maximum number of items that can be chosen. (default 1, max 25)
custom_id str: A developer-defined identifier for the select, max 100 characters.
default_values list[Role, SelectDefaultValues]: A list of default values to pre-select in the select.
disabled bool: Disable the select and make it not intractable, default false.
type Union[ComponentType, int]: The action role type number defined by discord. This cannot be modified.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

Expand All @@ -697,10 +708,7 @@ def __init__(
default_values: (
list[
Union[
"interactions.models.discord.BaseUser",
"interactions.models.discord.Role",
"interactions.models.discord.BaseChannel",
"interactions.models.discord.Member",
SelectDefaultValues,
],
]
Expand All @@ -720,6 +728,20 @@ def __init__(


class MentionableSelectMenu(DefaultableSelectMenu):
"""
Represents a mentional select component, which includes users, roles, and channels.

Attributes:
placeholder str: The custom placeholder text to show if nothing is selected, max 100 characters.
min_values Optional[int]: The minimum number of items that must be chosen. (default 1, min 0, max 25)
max_values Optional[int]: The maximum number of items that can be chosen. (default 1, max 25)
custom_id str: A developer-defined identifier for the select, max 100 characters.
default_values list[BaseUser, Role, BaseChannel, Member, SelectDefaultValues]: A list of default values to pre-select in the select.
disabled bool: Disable the select and make it not intractable, default false.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

def __init__(
self,
*,
Expand Down Expand Up @@ -754,6 +776,20 @@ def __init__(


class ChannelSelectMenu(DefaultableSelectMenu):
"""
Represents a chanel select component.

Attributes:
placeholder str: The custom placeholder text to show if nothing is selected, max 100 characters.
min_values Optional[int]: The minimum number of items that must be chosen. (default 1, min 0, max 25)
max_values Optional[int]: The maximum number of items that can be chosen. (default 1, max 25)
custom_id str: A developer-defined identifier for the select, max 100 characters.
default_values list[BaseChannel, SelectDefaultValues]: A list of default values to pre-select in the select.
disabled bool: Disable the select and make it not intractable, default false.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

def __init__(
self,
*,
Expand All @@ -766,10 +802,7 @@ def __init__(
default_values: (
list[
Union[
"interactions.models.discord.BaseUser",
"interactions.models.discord.Role",
"interactions.models.discord.BaseChannel",
"interactions.models.discord.Member",
SelectDefaultValues,
],
]
Expand Down Expand Up @@ -812,6 +845,16 @@ def to_dict(self) -> discord_typings.SelectMenuComponentData:


class SectionComponent(BaseComponent):
"""
A top-level layout component that allows you to join text contextually with an accessory.

Attributes:
components list[TextDisplayComponent]: The text components to include in this section.
accessory Button | ThumbnailComponent: The accessory to include in this section.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

components: "list[TextDisplayComponent]"
accessory: "Button | ThumbnailComponent"

Expand Down Expand Up @@ -840,6 +883,15 @@ def to_dict(self) -> dict:


class TextDisplayComponent(BaseComponent):
"""
A top-level content component that allows you to add text to your message.

Attributes:
content str: Text that will be displayed, similar to a message.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

content: str

def __init__(self, content: str):
Expand All @@ -861,6 +913,17 @@ def to_dict(self) -> dict:


class ThumbnailComponent(BaseComponent):
"""
A content component that is a small image only usable as an accessory in a section.

Attributes:
media UnfurledMediaItem: The media item to display as a thumbnail.
description Optional[str]: An optional description to show below the thumbnail.
spoiler bool: Whether the thumbnail should be marked as a spoiler, default false.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

media: UnfurledMediaItem
description: Optional[str] = None
spoiler: bool = False
Expand Down Expand Up @@ -892,6 +955,17 @@ def to_dict(self) -> dict:


class MediaGalleryItem(DictSerializationMixin):
"""
A basic object for displaying a media attachment.

Attributes:
media UnfurledMediaItem: The media item to display in the gallery.
description Optional[str]: An optional description to show below the media.
spoiler bool: Whether the media should be marked as a spoiler, default false.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

media: UnfurledMediaItem
description: Optional[str] = None
spoiler: bool = False
Expand Down Expand Up @@ -921,6 +995,15 @@ def to_dict(self) -> dict:


class MediaGalleryComponent(BaseComponent):
"""
A top-level content component that allows you to display 1-10 media attachments in an organized gallery format.

Attributes:
items list[MediaGalleryItem]: A list of media gallery items to display, max 10.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

items: list[MediaGalleryItem]

def __init__(self, items: list[MediaGalleryItem] | None = None):
Expand All @@ -942,6 +1025,16 @@ def to_dict(self) -> dict:


class FileComponent(BaseComponent):
"""
A top-level component that allows you to display an uploaded file in a component.

Attributes:
file UnfurledMediaItem: The media item to display as a file.
spoiler bool: Whether the file should be marked as a spoiler, default false.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

file: UnfurledMediaItem
spoiler: bool = False

Expand All @@ -966,6 +1059,16 @@ def to_dict(self) -> dict:


class SeparatorComponent(BaseComponent):
"""
A top-level layout component that adds vertical padding and visual division between other components.

Attributes:
divider bool: Whether this is a divider, which adds a horizontal line, default false.
spacing SeparatorSpacingSize | int: The amount of vertical space to add, default SeparatorSpacingSize.SMALL.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

divider: bool = False
spacing: SeparatorSpacingSize = SeparatorSpacingSize.SMALL

Expand All @@ -990,6 +1093,17 @@ def to_dict(self) -> dict:


class ContainerComponent(BaseComponent):
"""
A top-level layout component. Containers are visually distinct from surrounding components and have an optional customizable color bar.

Attributes:
components list[ActionRow | SectionComponent | TextDisplayComponent | MediaGalleryComponent | FileComponent | SeparatorComponent]: The components to include in this container.
accent_color Optional[int]: The color of the container, as a hex value, default None.
spoiler bool: Whether the container should be marked as a spoiler, default false.
type Union[ComponentType, int]: The type of component, as defined by discord. This cannot be modified.

"""

components: list[
ActionRow | SectionComponent | TextDisplayComponent | MediaGalleryComponent | FileComponent | SeparatorComponent
]
Expand Down
Loading