lightbulb.utils

class FloatEnum(value)

Custom enum base class for enums with float values.

See also

to_choices()

class StrEnum(value)

Alias to enum.StrEnum in Python versions 3.11 or later, otherwise a custom enum base class for compatibility.

See also

to_choices()

get_command_data(command: CommandBase | type[CommandBase] | Group | SubGroup) → CommandData

Utility method to get the command data dataclass for a command instance, command class, group, or subgroup.

Parameters:

command – The command instance, command class, group, or subgroup to get the command data for.

Returns:

Command data dataclass for the given command.

Return type:

CommandData

async maybe_await(item: types.MaybeAwaitable[T]) → T

Await the given item if it is a coroutine, otherwise just return the given item.

Parameters:

item – The item to maybe await.

Returns:

The item, or the return once the item was awaited.

to_choices(raw: Sequence[ChoiceT], localize: bool = False) → Sequence[Choice[ChoiceT]]

to_choices(raw: Sequence[tuple[str, ChoiceT]], localize: bool = False) → Sequence[Choice[ChoiceT]]

to_choices(raw: type[StrEnum], localize: bool = False) → Sequence[Choice[str]]

to_choices(raw: type[IntEnum], localize: bool = False) → Sequence[Choice[int]]

to_choices(raw: type[FloatEnum], localize: bool = False) → Sequence[Choice[float]]

Convert various values to Choice objects for use within command options.

When using enums to define choices, you should use the enum types exported by this module where available (StrEnum, FloatEnum). This ensures that your type checker doesn’t complain. If you are using Python 3.11 or newer, you may use enum.StrEnum as the one provided by this module is just an alias. For integer enums you should always use the enum.IntEnum class.

Parameters:

• raw – The values to convert to Choice objects.

• localize – Whether the name of the choice should be interpreted as a localization key.

Returns:

A sequence of Choice objects.

Example

Using sequences as the input:

>>> lightbulb.utils.to_choices(["foo", "bar", "baz"])
[Choice("foo", "foo"), Choice("bar", "bar"), Choice("baz", "baz)]
>>> lightbulb.utils.to_choices([1, 2, 3])
[Choice("1", 1), Choice("2", 2), Choice("3", 3)]
>>> lightbulb.utils.to_choices([1.5, 2.5, 3.5])
[Choice("1", 1.5), Choice("2", 2.5), Choice("3", 3.5)]
>>> lightbulb.utils.to_choices([("foo", "val1"), ("bar", "val2"), ("baz", "val3")])
[Choice("foo", "val1"), Choice("bar", "val2"), Choice("baz", "val3")]
>>> lightbulb.utils.to_choices([("foo", 1), ("bar", 2), ("baz", 3)])
[Choice("foo", 1), Choice("bar", 2), Choice("baz", 3)]
>>> lightbulb.utils.to_choices([("foo", 1.5), ("bar", 2.5), ("baz", 3.5)])
[Choice("foo", 1.5), Choice("bar", 2.5), Choice("baz", 3.5)]

Using enums as the input:

>>> class StrChoices(lightbulb.utils.StrEnum):
...     FOO = "foo"
...     BAR = "bar"
...     BAZ = "baz"
>>> lightbulb.utils.to_choices(StrChoices)
[Choice("FOO", "foo"), Choice("BAR", "bar"), Choice("BAZ", "baz")]
>>> class IntChoices(enum.IntEnum):
...     FOO = 1
...     BAR = 2
...     BAZ = 3
>>> lightbulb.utils.to_choices(IntChoices)
[Choice("FOO", 1), Choice("BAR", 2), Choice("BAZ", 3)]
>>> class FloatChoices(lightbulb.utils.FloatEnum):
...     FOO = 1.5
...     BAR = 2.5
...     BAZ = 3.5
[Choice("FOO", 1.5), Choice("BAR", 2.5), Choice("BAZ", 3.5)]

Added in version 3.1.2.

EMPTY: Final[Any] = <lightbulb.Marker: 'EMPTY'>

Placeholder object returned when attempting to get the value for an option on a class instead of an instance.

Example

class YourCommand(lightbulb.SlashCommand, ...):
    option = lightbulb.string(...)
    ...

# The following will be True
YourCommand.option is lightbulb.utils.EMPTY