Context API Reference#

Base#

class lightbulb.context.base.ApplicationContext(app: app_.BotApp, event: hikari.InteractionCreateEvent, command: commands.base.ApplicationCommand)[source]#

get_channel() → GuildChannel | Snowflake | None[source]#: The channel object for the context’s channel ID.

async respond(*args: Any, delete_after: int | float | None = None, **kwargs: Any) → ResponseProxy[source]#

Create a response for this context. The first time this method is called, the initial interaction response will be created by calling create_initial_response with the response type set to MESSAGE_CREATE if not otherwise specified.

Subsequent calls will instead create followup responses to the interaction by calling execute.

Parameters:

*args (Any) – Positional arguments passed to CommandInteraction.create_initial_response or CommandInteraction.execute.
delete_after (Union[int, float, None]) – The number of seconds to wait before deleting this response.
**kwargs – Keyword arguments passed to CommandInteraction.create_initial_response or CommandInteraction.execute.

Returns:

Proxy wrapping the response of the respond call.

Return type:

ResponseProxy

New in version 2.2.0: delete_after kwarg.

async respond_with_modal(title: str, custom_id: str, component: hikari.UndefinedOr[special_endpoints.ComponentBuilder] = UNDEFINED, components: hikari.UndefinedOr[t.Sequence[special_endpoints.ComponentBuilder]] = UNDEFINED) → None[source]#

Create a modal response to this context.

Parameters:

title (str) – The title that will show up in the modal.
custom_id (str) – Developer set custom ID used for identifying interactions with this modal.
component (UndefinedOr[hikari.api.special_endpoints.ComponentBuilder]) – A component builder to send in this modal.
components (UndefinedOr[Sequence[hikari.api.special_endpoints.ComponentBuilder]]) – A sequence of component builders to send in this modal.

Returns:

None

Raises:

ValueError – If both component and components are specified or if neither are specified.

New in version 2.3.1.

property author: User#: The author for the context.

property channel_id: Snowflake#: The channel ID for the context.

abstract property command: commands.base.ApplicationCommand#: The root command object that the context is for.

See also

invoked

property event: InteractionCreateEvent#: The event for the context.

property guild_id: Snowflake | None#: The guild ID for the context.

property interaction: CommandInteraction#: The interaction that triggered this context. Will be None for prefix commands.

property invoked_with: str#: The command name or alias was used in the context.

property member: Member | None#: The member for the context.

property resolved: ResolvedOptionData | None#: The resolved option data for this context. Will be None for prefix commands.

class lightbulb.context.base.Context(app: app_.BotApp)[source]#

Abstract base class for all context types.

Parameters:: app (BotApp) – The BotApp instance that the context is linked to.

async delete_last_response() → None[source]#

Delete the most recently send response. Shortcut for hikari.messages.Message.delete.

Returns:: None

async edit_last_response(*args: Any, **kwargs: Any) → Message | None[source]#

Edit the most recently sent response. Shortcut for hikari.messages.Message.edit.

Parameters:

*args – Args passed to hikari.messages.Message.edit.
**kwargs – Kwargs passed to hikari.messages.Message.edit.

Returns:

New message after edit, or None if no responses have: been sent for the context yet.

Return type:

Optional[Message]

abstract get_channel() → GuildChannel | Snowflake | None[source]#: The channel object for the context’s channel ID.

get_guild() → Guild | None[source]#: The guild object for the context’s guild ID.

async invoke() → None[source]#

Invokes the context’s command under the current context.

Returns:: None

abstract async respond(response_type: ResponseType, content: Any | UndefinedType = hikari.UNDEFINED, delete_after: int | float | None = None, *, attachment: hikari.UndefinedOr[hikari.Resourceish] = hikari.UNDEFINED, attachments: hikari.UndefinedOr[t.Sequence[hikari.Resourceish]] = hikari.UNDEFINED, component: ComponentBuilder | UndefinedType = hikari.UNDEFINED, components: Sequence[ComponentBuilder] | UndefinedType = hikari.UNDEFINED, embed: Embed | UndefinedType = hikari.UNDEFINED, embeds: Sequence[Embed] | UndefinedType = hikari.UNDEFINED, flags: int | MessageFlag | UndefinedType = hikari.UNDEFINED, tts: bool | UndefinedType = hikari.UNDEFINED, nonce: str | UndefinedType = hikari.UNDEFINED, reply: PartialMessage | Snowflake | int | UndefinedType = hikari.UNDEFINED, reply_must_exist: bool | UndefinedType = hikari.UNDEFINED, mentions_everyone: bool | UndefinedType = hikari.UNDEFINED, mentions_reply: bool | UndefinedType = hikari.UNDEFINED, user_mentions: Sequence[PartialUser | Snowflake | int] | bool | UndefinedType = hikari.UNDEFINED, role_mentions: Sequence[PartialRole | Snowflake | int] | bool | UndefinedType = hikari.UNDEFINED) → ResponseProxy[source]#
abstract async respond(content: Any | UndefinedType = hikari.UNDEFINED, delete_after: int | float | None = None, *, attachment: hikari.UndefinedOr[hikari.Resourceish] = hikari.UNDEFINED, attachments: hikari.UndefinedOr[t.Sequence[hikari.Resourceish]] = hikari.UNDEFINED, component: ComponentBuilder | UndefinedType = hikari.UNDEFINED, components: Sequence[ComponentBuilder] | UndefinedType = hikari.UNDEFINED, embed: Embed | UndefinedType = hikari.UNDEFINED, embeds: Sequence[Embed] | UndefinedType = hikari.UNDEFINED, flags: int | MessageFlag | UndefinedType = hikari.UNDEFINED, tts: bool | UndefinedType = hikari.UNDEFINED, nonce: str | UndefinedType = hikari.UNDEFINED, reply: PartialMessage | Snowflake | int | UndefinedType = hikari.UNDEFINED, reply_must_exist: bool | UndefinedType = hikari.UNDEFINED, mentions_everyone: bool | UndefinedType = hikari.UNDEFINED, mentions_reply: bool | UndefinedType = hikari.UNDEFINED, user_mentions: Sequence[PartialUser | Snowflake | int] | bool | UndefinedType = hikari.UNDEFINED, role_mentions: Sequence[PartialRole | Snowflake | int] | bool | UndefinedType = hikari.UNDEFINED) → ResponseProxy: Create a response to this context.

abstract async respond_with_modal(title: str, custom_id: str, component: hikari.UndefinedOr[special_endpoints.ComponentBuilder] = UNDEFINED, components: hikari.UndefinedOr[t.Sequence[special_endpoints.ComponentBuilder]] = UNDEFINED) → None[source]#: Create a modal response to this context.

New in version 2.3.1.

property app: app_.BotApp#: The BotApp instance the context is linked to.

abstract property author: User#: The author for the context.

property bot: app_.BotApp#: Alias for app.

abstract property channel_id: Snowflake#: The channel ID for the context.

abstract property command: t.Optional[commands.base.Command]#: The root command object that the context is for.

See also

invoked

property deferred: bool#: Whether the response from this context is currently deferred.

abstract property event: MessageCreateEvent | InteractionCreateEvent#: The event for the context.

abstract property guild_id: Snowflake | None#: The guild ID for the context.

property interaction: CommandInteraction | None#: The interaction that triggered this context. Will be None for prefix commands.

property invoked: t.Optional[commands.base.Command]#: The command or subcommand that was invoked in this context.

New in version 2.1.0.

abstract property invoked_with: str#: The command name or alias was used in the context.

abstract property member: Member | None#: The member for the context.

property options: OptionsProxy#: OptionsProxy wrapping the options that the user invoked the command with.

abstract property prefix: str#: The prefix that was used in the context.

property previous_response: ResponseProxy | None#: The last response sent for this context.

property raw_options: Dict[str, Any]#: Dictionary of str option name to option value that the user invoked the command with.

property resolved: ResolvedOptionData | None#: The resolved option data for this context. Will be None for prefix commands.

property responses: List[ResponseProxy]#: List of all previous responses sent for this context.

property user: User#: The user for the context. Alias for author.

class lightbulb.context.base.OptionsProxy(options: Dict[str, Any])[source]#

Proxy for the options that the command was invoked with allowing access using dot notation as well as dictionary lookup.

Parameters:: options (Dict[str, Any]) – Options to act as a proxy for.

items() → ItemsView[str, Any][source]#

Iterates through the options and returns a series of key:value pairs.

Returns:

The options items. This: is functionally similar to a list of tuples, where for each tuple, the key is the option name, and the value is the option value.

Return type:

ItemsView[str, Any]

class lightbulb.context.base.ResponseProxy(message: Message | None = None, fetcher: Callable[[], Coroutine[Any, Any, Message]] | None = None, editor: Callable[[ResponseProxy], Coroutine[Any, Any, Message]] | None = None, deleteable: bool = True)[source]#

Proxy for context responses. Allows fetching of the message created from the response lazily instead of a follow-up request being made immediately.

async delete() → None[source]#

Deletes the message that this object is proxying.

Returns:: None
Raises:: UnsupportedResponseOperation – This response cannot be deleted (for some ephemeral interaction responses).

async edit(*args: Any, **kwargs: Any) → Message[source]#

Edits the message that this object is proxying. Shortcut for hikari.messages.Message.edit.

Parameters:

*args – Args passed in to hikari.messages.Message.edit
**kwargs – Kwargs passed in to hikari.messages.Message.edit

Returns:

New message after edit.

Return type:

Message

Raises:

UnsupportedResponseOperation – This response cannot be edited (for ephemeral interaction followup responses).

async message() → Message[source]#

Fetches and/or returns the created message from the context response.

Returns:: The response’s created message.
Return type:: Message

Note

This object is awaitable (since version 2.2.2), hence the following is also valid.

# Where 'resp' is an instance of ResponseProxy

# Calling this method
message = await resp.message()
# Awaiting the object itself
message = await resp

Prefix Context#

class lightbulb.context.prefix.PrefixContext(app: app_.BotApp, event: hikari.MessageCreateEvent, command: t.Optional[commands.prefix.PrefixCommand], invoked_with: str, prefix: str)[source]#

Bases: Context

An implementation of Context for prefix commands.

Parameters:

app (BotApp) – The BotApp instance that the context is linked to.
event (MessageCreateEvent) – The event to create the context from.
command (Optional[PrefixCommand]) – The command that the context is for, or None if no command could be resolved.
invoked_with (str) – The name or alias that the command was invoked with.
prefix (str) – The prefix that was used in this context.

get_channel() → GuildChannel | Snowflake | None[source]#: The channel object for the context’s channel ID.

async respond(*args: Any, delete_after: int | float | None = None, **kwargs: Any) → ResponseProxy[source]#

Create a response for this context. This method directly calls respond. You should note that it is not possible to send ephemeral messages as responses to prefix commands. All message flags will be removed before the call to respond.

Parameters:

*args (Any) – Positional arguments passed to respond.
delete_after (Union[int, float, None]) – The number of seconds to wait before deleting this response.
**kwargs (Any) – Keyword arguments passed to respond.

Returns:

The created message object.

Return type:

Message

New in version 2.2.0: delete_after kwarg.

Method only preserved for API consistency. If you attempt to call this method for a prefix command, a NotImplementedError will always be raised.

Raises:: NotImplementedError – Always

New in version 2.3.1.

property author: User#: The author for the context.

property channel_id: Snowflake#: The channel ID for the context.

property command: t.Optional[commands.prefix.PrefixCommand]#: The root command object that the context is for.

See also

invoked

property event: MessageCreateEvent#: The event for the context.

property guild_id: Snowflake | None#: The guild ID for the context.

property invoked_with: str#: The command name or alias was used in the context.

property member: Member | None#: The member for the context.

property prefix: str#: The prefix that was used in the context.

property raw_options: Dict[str, Any]#: Dictionary of str option name to option value that the user invoked the command with.

Slash Context#

class lightbulb.context.slash.SlashContext(app: app_.BotApp, event: hikari.InteractionCreateEvent, command: commands.slash.SlashCommand)[source]#

Bases: ApplicationContext

An implementation of Context for slash commands.

Parameters:

app (BotApp) – The BotApp instance that the context is linked to.
event (InteractionCreateEvent) – The event to create the context from.
command (SlashCommand) – The command that the context is for.

property command: SlashCommand#: The root command object that the context is for.

See also

invoked

property prefix: str#: The prefix that was used in the context.

property raw_options: Dict[str, Any]#: Dictionary of str option name to option value that the user invoked the command with.

Message Context#

class lightbulb.context.message.MessageContext(app: app_.BotApp, event: hikari.InteractionCreateEvent, command: commands.message.MessageCommand)[source]#

Bases: ApplicationContext

An implementation of Context for message context menu commands.

Parameters:

app (BotApp) – The BotApp instance that the context is linked to.
event (InteractionCreateEvent) – The event to create the context from.
command (MessageCommand) – The command that the context is for.

Note that the target message that this command was invoked on will always be stored as the option target.

Example

@lightbulb.command("id", "Gets the ID of the selected message")
@lightbulb.implements(lightbulb.MessageCommand)
async def get_message_id(ctx: lightbulb.MessageContext) -> None:
    await ctx.respond(ctx.options.target.id)

New in version 2.2.0.

property command: MessageCommand#: The root command object that the context is for.

See also

invoked

property prefix: str#: The prefix that was used in the context.

property raw_options: Dict[str, Any]#: Dictionary of str option name to option value that the user invoked the command with.

User Context#

class lightbulb.context.user.UserContext(app: app_.BotApp, event: hikari.InteractionCreateEvent, command: commands.user.UserCommand)[source]#

Bases: ApplicationContext

An implementation of Context for user context menu commands.

Parameters:

app (BotApp) – The BotApp instance that the context is linked to.
event (InteractionCreateEvent) – The event to create the context from.
command (UserCommand) – The command that the context is for.

Note that the target user that this command was invoked on will always be stored as the option target.

Example

@lightbulb.command("id", "Gets the ID of the selected user")
@lightbulb.implements(lightbulb.UserCommand)
async def get_user_id(ctx: lightbulb.UserContext) -> None:
    await ctx.respond(ctx.options.target.id)

New in version 2.2.0.

property command: UserCommand#: The root command object that the context is for.

See also

invoked

property prefix: str#: The prefix that was used in the context.

property raw_options: Dict[str, Any]#: Dictionary of str option name to option value that the user invoked the command with.