diff --git a/lightbulb/client.py b/lightbulb/client.py index 366ca820..307ad250 100644 --- a/lightbulb/client.py +++ b/lightbulb/client.py @@ -67,11 +67,11 @@ class Client: execution_step_order (:obj:`~typing.Sequence` [ :obj:`~lightbulb.commands.execution.ExecutionStep` ]): The order that execution steps will be run in upon command processing. default_locale: (:obj:`~hikari.locales.Locale`): The default locale to use for command names and descriptions, - as well as option names and descriptions. If you are not using localizations then this will do nothing. + as well as option names and descriptions. Has no effect if localizations are not being used. localization_provider (:obj:`~typing.Callable` [ [ :obj:`str` ], :obj:`~typing.Mapping` [ :obj:`~hikari.locales.Locale`, :obj:`str` ] ]): The localization provider function to use. This will be called whenever the client needs to get the localizations for a key. Defaults to :obj:`~lightbulb.localization.localization_unsupported` - the client - does not support localizing commands and will instead raise an error. **Must** be passed if you intend + does not support localizing commands. **Must** be passed if you intend to support localizations. """ # noqa: E501 @@ -477,12 +477,12 @@ def client_from_app( execution_step_order (:obj:`~typing.Sequence` [ :obj:`~lightbulb.commands.execution.ExecutionStep` ]): The order that execution steps will be run in upon command processing. default_locale: (:obj:`~hikari.locales.Locale`): The default locale to use for command names and descriptions, - as well as option names and descriptions. If you are not using localizations then this will do nothing. + as well as option names and descriptions. Has no effect if localizations are not being used. Defaults to :obj:`hikari.locales.Locale.EN_US`. localization_provider (:obj:`~typing.Callable` [ [ :obj:`str` ], :obj:`~typing.Mapping` [ :obj:`~hikari.locales.Locale`, :obj:`str` ] ]): The localization provider function to use. This will be called whenever the client needs to get the localizations for a key. Defaults to :obj:`~lightbulb.localization.localization_unsupported` - the client - does not support localizing commands and will instead raise an error. **Must** be passed if you intend + does not support localizing commands. **Must** be passed if you intend to support localizations. Returns: diff --git a/lightbulb/commands/commands.py b/lightbulb/commands/commands.py index c4fffab6..3bce0c58 100644 --- a/lightbulb/commands/commands.py +++ b/lightbulb/commands/commands.py @@ -191,7 +191,7 @@ class CommandMeta(type): description (:obj:`str`, optional): The description of the command. Only required for slash commands. localize (:obj:`bool`, optional): Whether to localize the command's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from - which the actual name and description will be retrieved from. Defaults to :obj:`False`. + which the actual name and description will be retrieved. Defaults to :obj:`False`. nsfw (:obj:`bool`, optional): Whether the command should be marked as nsfw. Defaults to :obj:`False`. dm_enabled (:obj:`bool`, optional): Whether the command can be used in direct messages. Defaults to :obj:`True`. default_member_permissions (:obj:`hikari.Permissions`, optional): The default permissions required for a @@ -395,7 +395,7 @@ class SlashCommand(CommandBase, metaclass=CommandMeta, type=hikari.CommandType.S description (:obj:`str`, required): The description of the command. localize (:obj:`bool`, optional): Whether to localize the command's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from - which the actual name and description will be retrieved from. Defaults to :obj:`False`. + which the actual name and description will be retrieved. Defaults to :obj:`False`. nsfw (:obj:`bool`, optional): Whether the command should be marked as nsfw. Defaults to :obj:`False`. dm_enabled (:obj:`bool`, optional): Whether the command can be used in direct messages. Defaults to :obj:`True`. default_member_permissions (:obj:`hikari.Permissions`, optional): The default permissions required for a @@ -432,8 +432,8 @@ class UserCommand(CommandBase, metaclass=CommandMeta, type=hikari.CommandType.US Parameters: name (:obj:`str`, required): The name of the command. localize (:obj:`bool`, optional): Whether to localize the command's name and description. If :obj:`true`, - then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from - which the actual name and description will be retrieved from. Defaults to :obj:`False`. + then the ``name`` argument will instead be interpreted as a localization key from + which the actual name will be retrieved. Defaults to :obj:`False`. nsfw (:obj:`bool`, optional): Whether the command should be marked as nsfw. Defaults to :obj:`False`. dm_enabled (:obj:`bool`, optional): Whether the command can be used in direct messages. Defaults to :obj:`True`. default_member_permissions (:obj:`hikari.Permissions`, optional): The default permissions required for a @@ -473,8 +473,8 @@ class MessageCommand(CommandBase, metaclass=CommandMeta, type=hikari.CommandType Parameters: name (:obj:`str`, required): The name of the command. localize (:obj:`bool`, optional): Whether to localize the command's name and description. If :obj:`true`, - then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from - which the actual name and description will be retrieved from. Defaults to :obj:`False`. + then the ``name`` argument will instead be interpreted as a localization key from + which the actual name will be retrieved. Defaults to :obj:`False`. nsfw (:obj:`bool`, optional): Whether the command should be marked as nsfw. Defaults to :obj:`False`. dm_enabled (:obj:`bool`, optional): Whether the command can be used in direct messages. Defaults to :obj:`True`. default_member_permissions (:obj:`hikari.Permissions`, optional): The default permissions required for a diff --git a/lightbulb/commands/options.py b/lightbulb/commands/options.py index 5eb3cd47..9aba64da 100644 --- a/lightbulb/commands/options.py +++ b/lightbulb/commands/options.py @@ -75,7 +75,7 @@ class OptionData(t.Generic[D]): description: str """The description of the option.""" localize: bool = False - """Whether the name and description of the option will be localized.""" + """Whether the name and description of the option should be interpreted as localization keys.""" default: hikari.UndefinedOr[D] = hikari.UNDEFINED """The default value for the option.""" @@ -106,7 +106,7 @@ def __post_init__(self) -> None: if self.choices is not hikari.UNDEFINED: if len(self.choices) > 25: - raise ValueError("'choices' - there cannot be more than 25 choices") + raise ValueError("'choices' - cannot have more than 25 choices") for i, choice in enumerate(self.choices): if len(choice.name) < 1 or len(choice.name) > 100: @@ -299,7 +299,7 @@ def string( description (:obj:`str`): The description of the option. localize (:obj:`bool`): Whether to localize this option's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from which the - actual name and description will be retrieved from. Defaults to :obj:`False`. + actual name and description will be retrieved. Defaults to :obj:`False`. default (:obj:`~hikari.undefined.UndefinedOr` [ ``D`` ]): The default value for the option. choices (:obj:`~hikari.undefined.UndefinedOr` [ ``ChoicesT`` ]): The choices for the option. Any of the following can be interpreted as a choice: a sequence of :obj:`~hikari.commands.CommandChoice`, a mapping @@ -358,7 +358,7 @@ def integer( description (:obj:`str`): The description of the option. localize (:obj:`bool`): Whether to localize this option's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from which the - actual name and description will be retrieved from. Defaults to :obj:`False`. + actual name and description will be retrieved. Defaults to :obj:`False`. default (:obj:`~hikari.undefined.UndefinedOr` [ ``D`` ]): The default value for the option. choices (:obj:`~hikari.undefined.UndefinedOr` [ ``ChoicesT`` ]): The choices for the option. Any of the following can be interpreted as a choice: a sequence of :obj:`~hikari.commands.CommandChoice`, a mapping @@ -411,7 +411,7 @@ def boolean( description (:obj:`str`): The description of the option. localize (:obj:`bool`): Whether to localize this option's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from which the - actual name and description will be retrieved from. Defaults to :obj:`False`. + actual name and description will be retrieved. Defaults to :obj:`False`. default (:obj:`~hikari.undefined.UndefinedOr` [ ``D`` ]): The default value for the option. Returns: @@ -456,7 +456,7 @@ def number( description (:obj:`str`): The description of the option. localize (:obj:`bool`): Whether to localize this option's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from which the - actual name and description will be retrieved from. Defaults to :obj:`False`. + actual name and description will be retrieved. Defaults to :obj:`False`. default (:obj:`~hikari.undefined.UndefinedOr` [ ``D`` ]): The default value for the option. choices (:obj:`~hikari.undefined.UndefinedOr` [ ``ChoicesT`` ]): The choices for the option. Any of the following can be interpreted as a choice: a sequence of :obj:`~hikari.commands.CommandChoice`, a mapping @@ -509,7 +509,7 @@ def user( description (:obj:`str`): The description of the option. localize (:obj:`bool`): Whether to localize this option's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from which the - actual name and description will be retrieved from. Defaults to :obj:`False`. + actual name and description will be retrieved. Defaults to :obj:`False`. default (:obj:`~hikari.undefined.UndefinedOr` [ ``D`` ]): The default value for the option. Returns: @@ -547,7 +547,7 @@ def channel( description (:obj:`str`): The description of the option. localize (:obj:`bool`): Whether to localize this option's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from which the - actual name and description will be retrieved from. Defaults to :obj:`False`. + actual name and description will be retrieved. Defaults to :obj:`False`. default (:obj:`~hikari.undefined.UndefinedOr` [ ``D`` ]): The default value for the option. channel_types (:obj:`~hikari.undefined.UndefinedOr` [ :obj:`~typing.Sequence` [ :obj:`~hikari.channels.ChannelType` ]]): The channel types permitted for the option. @@ -587,7 +587,7 @@ def role( description (:obj:`str`): The description of the option. localize (:obj:`bool`): Whether to localize this option's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from which the - actual name and description will be retrieved from. Defaults to :obj:`False`. + actual name and description will be retrieved. Defaults to :obj:`False`. default (:obj:`~hikari.undefined.UndefinedOr` [ ``D`` ]): The default value for the option. Returns: @@ -624,7 +624,7 @@ def mentionable( description (:obj:`str`): The description of the option. localize (:obj:`bool`): Whether to localize this option's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from which the - actual name and description will be retrieved from. Defaults to :obj:`False`. + actual name and description will be retrieved. Defaults to :obj:`False`. default (:obj:`~hikari.undefined.UndefinedOr` [ ``D`` ]): The default value for the option. Returns: @@ -661,7 +661,7 @@ def attachment( description (:obj:`str`): The description of the option. localize (:obj:`bool`): Whether to localize this option's name and description. If :obj:`true`, then the ``name`` and ``description`` arguments will instead be interpreted as localization keys from which the - actual name and description will be retrieved from. Defaults to :obj:`False`. + actual name and description will be retrieved. Defaults to :obj:`False`. default (:obj:`~hikari.undefined.UndefinedOr` [ ``D`` ]): The default value for the option. Returns: diff --git a/lightbulb/localization.py b/lightbulb/localization.py index 34b867bd..ae9144c1 100644 --- a/lightbulb/localization.py +++ b/lightbulb/localization.py @@ -50,6 +50,11 @@ def localization_unsupported(_: str) -> t.NoReturn: Default localization provider. Functions to disable the ability to localize commands and options. If you want to use localized commands in your application you should specify a different built-in or custom localization provider. + + Raises: + :obj:`~lightbulb.exceptions.LocalizationFailedException`: Whenever called. This means that + when the client attempts to register commands with discord it will cause this error to be thrown if + any of the commands (or options) are marked as requiring localization. """ raise exceptions.LocalizationFailedException("no localization provider available - localization is not supported")