Component API¶

Protocols for components and component managers.

Typing¶

disnake_compass.api.component.ComponentT = ~ComponentT¶

A type hint for a (subclass of) a disnake-compass component.

In practice, this will be any implementation of the RichButton, or RichSelect protocols.

Classes¶

Methods

asyncas_ui_component
asynccallback
clsget_factory
clsget_manager
clsset_factory
clsset_manager

class disnake_compass.api.component.RichComponent(*args, **kwargs)[source]¶

Bases: Protocol

The baseline protocol for any kind of component.

Any and all components must implement this protocol in order to be properly handled by disnake-compass.

Methods¶

await as_ui_component(manager=None, /)[source]¶

Convert this component into a component that can be sent by disnake.

Returns:: A component that can be sent by disnake, maintaining the parameters and custom id set on this rich component.
Return type:: WrappedComponent

await callback(interaction, /)[source]¶

Run the component callback.

This should be implemented by the user in each concrete component type.

Parameters:: interaction (Interaction[Client]) – The interaction that caused this button to fire.

classmethod get_factory()[source]¶: Get the factory that built this component instance.

classmethod get_manager()[source]¶: Get the manager that was responsible for parsing this component instance.

classmethod set_factory(factory)[source]¶: Set the factory that built this component instance.

classmethod set_manager(manager, /)[source]¶: Set the manager that was responsible for parsing this component instance.

Attributes

disabled
emoji
label
style

Methods

asyncas_ui_component

class disnake_compass.api.component.RichButton(*args, **kwargs)[source]¶

Bases: RichComponent, Protocol

Baseline protocol for Button-like components.

Attributes¶

disabled: bool¶

Whether or not this button is disabled.

A disabled button is greyed out on discord, and cannot be pressed. Disabled buttons can therefore not cause any interactions, either.

emoji: str | PartialEmoji | Emoji | None¶

The emoji that is to be displayed on this button.

Either or both this field or the emoji field must be set.

label: str | None¶

The label of the component.

Either or both this field or the emoji field must be set.

style: ButtonStyle¶

The style of the component.

This dictates how the button is displayed on discord.

Methods¶

await as_ui_component(manager=None, /)[source]¶

Convert this component into a component that can be sent by disnake.

Returns:: A component that can be sent by disnake, maintaining the parameters and custom id set on this rich component.
Return type:: WrappedComponent

Attributes

disabled
max_values
min_values
placeholder

Methods

asyncas_ui_component

class disnake_compass.api.component.RichSelect(*args, **kwargs)[source]¶

Bases: RichComponent, Protocol

Baseline protocol for Select-like components.

Attributes¶

disabled: bool¶

Whether or not this button is disabled.

A disabled select is greyed out on discord, and cannot be used. Disabled selects can therefore not cause any interactions, either.

max_values: int¶

The maximum number of values the user may select.

This must lie between 1 and 25, inclusive.

min_values: int¶

The minimum number of values the user must select.

This must lie between 1 and 25, inclusive.

placeholder: str | None¶

The placeholder of the component.

This shows when nothing is selected, or shows nothing if set to None.

Methods¶

await as_ui_component(manager=None, /)[source]¶

Convert this component into a component that can be sent by disnake.

Returns:: A component that can be sent by disnake, maintaining the parameters and custom id set on this rich component.
Return type:: WrappedComponent

Attributes

children
components
name
parent

Methods

defadd_to_client
defderegister_component
defget_identifier
asyncinvoke_component
deflookup_identifier
asyncmake_custom_id
defmake_identifier
defregister_component
defremove_from_client

class disnake_compass.api.component.ComponentManager(*args, **kwargs)[source]¶

Bases: Protocol

The baseline protocol for component managers.

Component managers keep track of disnake-compass’ special components and ensure they smoothly communicate with disnake’s bots. Since this relies on listener functionality, component managers are incompatible with disnake.Client-classes.

To register a component to a component manager, use register_component(). Without registering your components, they will remain unresponsive.

Attributes¶

property children: Collection[ComponentManager][source]¶: The children of this component manager.

property components: Mapping[str, type[RichComponent]][source]¶

The components registered to this manager or any of its children.

In case a custom implementation is made, special care must be taken to ensure that these do not desync when a child’s components are updated.

property name: str[source]¶

The name of this manager.

Used in get_manager(). This functions similar to loggers, where a parent-child relationship is denoted with a “.”. For example, a manager “foo.bar” has parent “foo”, which has the root manager as parent.

property parent: ComponentManager | None[source]¶

The parent of this manager.

Returns None in case this is the root manager.

Methods¶

add_to_client(client, /)[source]¶

This is required to make components registered to this manager responsive.

This method registers the invoke() callback as an event to the client for the disnake.on_message_interaction and disnake.on_modal_submit events.

Note

There is no need to separately register every manager you make. In general, it is sufficient to only register the root manager as the root manager will contain all components of its children. That is, the root manager contains all registered components, as every other manager is a child of the root manager.

Parameters:: client (Client) – The client to which to register this manager.
Raises:: RuntimeError – This manager has already been registered to the provided client.

deregister_component(identifier, /)[source]¶

Deregister a component from this component manager.

After deregistration, the component will no be tracked, and its callbacks can no longer fire until it is re-registered.

Parameters:: identifier (str) – The identifier of the component class to deregister.
Returns:: The component class that was just deregistered.
Return type:: type[RichComponent]

get_identifier(custom_id, /)[source]¶

Extract the identifier and parameters from a custom id.

This is used to check whether the identifier is registered in components.

Parameters:: custom_id (str) – The custom id from which to extract the identifier.

await invoke_component(interaction, /)[source]¶

Try to invoke a component with the given interaction.

If this manager has no registered component that matches the interaction, it is silently ignored. Otherwise, the interaction will be parsed into a fully fledged component, and its callback will then be invoked.

Parameters:: interaction (MessageInteraction[Client]) – The interaction with which to try to invoke a component callback.

lookup_identifier(component_type, /)[source]¶

Look up the identifier of an already registered component type.

Parameters:: component_type (type[RichComponent]) – The component type for which to look up the registered identifier.

await make_custom_id(component, /)[source]¶

Make a custom id from the provided component.

This can then be used later to reconstruct the component without any state or data loss.

Parameters:: component (RichComponent) – The component for which to create a custom id.
Returns:: A custom id that fully represents the provided component.
Return type:: str

make_identifier(component_type, /)[source]¶

Make an identifier for the provided component class.

This is used to store the component in components, and to determine which component’s callback should be fired when an interaction is received.

Parameters:: component_type (type[RichComponent]) – The type of component for which to make an identifier.
Returns:: The component type’s identifier.
Return type:: str

register_component(component_type, /, *, identifier)[source]¶

This returns the provided class, such that this method can serve as a decorator.

Parameters:

component_type (type[ComponentT]) – The component class to register.
identifier (str) – The identifier with which to register this component class.

Returns:

The component class that was just registered.

Return type:

type[ComponentT]

remove_from_client(client, /)[source]¶

Deregister this manager from the provided client.

This makes all components registered to this manager unresponsive.

Parameters:: client (Client) – The client from which to deregister this manager.
Raises:: RuntimeError – This manager is not registered to the provided client.

Methods

asyncbuild_component
asyncdump_params
clsfrom_component
asyncload_params

class disnake_compass.api.component.ComponentFactory(*args, **kwargs)[source]¶

Bases: Protocol[ComponentT]

The baseline protocol for any kind of component factory.

Any and all component factories must implement this protocol in order to be properly handled by disnake-compass.

A component factory handles creating a component instance from a custom id by running all individual fields’ parsers and aggregating the result into a component instance.

Methods¶

await build_component(params, component_params)[source]¶

Create a new component instance from the provided interaction.

This requires the custom id to already have been decomposed into individual fields. This is generally done by the component manager.

Parameters:

params (Sequence[str]) – A sequence of to-be-parsed field values.
component_params (Mapping[str, object] | None) – A mapping of parameters that is to be directly passed to the component constructor.

await dump_params(component, /)[source]¶

Dump a component into a new custom id string.

This converts the component’s individual fields back into strings and and uses these strings to build a new custom id. This is generally done using the ComponentManager.get_identifier() method.

Parameters:: component (ComponentT) – The component to dump into a custom id.

classmethod from_component(component, /)[source]¶

Create a component factory from the provided component.

This takes the component’s fields into account and generates the corresponding parser types for each field if a parser was not provided manually for that particular field.

Parameters:: component (type[ComponentT]) – The component for which to create a component factory.

await load_params(params, /)[source]¶

Create a new component instance from the provided custom id.

This requires the custom id to already have been decomposed into individual fields. This is generally done using the ComponentManager.get_identifier() method.

Parameters:: params (Sequence[str]) – A mapping of field name to to-be-parsed field values.