telegram-click

Click 启发的命令行界面创建工具包，用于 python-telegram-bot。

亲自尝试 example.py 的最新版本：@PythonTelegramClickBot

如果您正在寻找 asyncio 和 aiogram 支持，请前往 telegram-click-aio！

功能

• POSIX 风格的参数解析
  • 引用参数（/command "Hello World"）
  • 命名参数（/command --text "Hello World"）
  • 值分隔符（/command --text=myvalue ）
  • 标志（/command --yes）
  • 多个组合标志（《/command -Syu》）
  • 可选参数
  • 类型转换，包括对自定义类型的支持
  • 参数输入验证
• 自动帮助信息
  • 当命令使用无效参数时显示帮助信息
  • 使用单个方法列出所有可用命令
• 权限处理
  • 为每个命令分别设置权限
  • 限制命令执行为私有聊天或群管理员
  • 使用逻辑运算符组合权限
  • 创建自定义权限处理器
• 错误处理
  • 如果出现问题，自动发送错误和帮助信息
  • 编写自定义错误处理器

telegram-click被以下项目使用

• InfiniteWisdom
• DeineMudda
• keel-telegram-bot
• grocy-telegram-bot
• FrundenBot

希望还有更多其他项目 :)

如何使用

将此库作为依赖项安装，以在项目中使用。

pip install telegram-click

然后使用此库的@command装饰器注解你的命令处理函数

from telegram import Update
from telegram.ext import ContextTypes
from telegram_click.decorator import command
from telegram_click.argument import Argument

class MyBot:

    [...]
    
    @command(name='start', description='Start bot interaction')
    async def _start_command_callback(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
        # do something
        pass
        
    @command(name='age', 
             description='Set age',
             arguments=[
                 Argument(name='age',
                          description='The new age',
                          type=int,
                          validator=lambda x: x > 0,
                          example='25')
             ])
    async def _age_command_callback(self, update: Update, context: ContextTypes.DEFAULT_TYPE, age: int):
        context.bot.send_message(update.effective_chat.id, "New age: {}".format(age))

参数

telegram-click使用自定义分词器解析参数

• 空格用作参数分隔符，但在引号内除外（支持"和'）
• 参数键以--、—（长划线）或-（用于单字符键）开头
• 引号内的参数永远不会被视为参数键，即使以--或—开头
• 标志可以组合在单个参数中（例如-AxZ）

行为应该是相当直观的。如果不是，让我们讨论并改进它！

命名

参数可以有多个名称，以便允许简写名称。您为参数指定的第一个名称将用于回调参数名称（转换为蛇形命名法）。因此，建议将完整的单词参数名称作为第一个名称指定。

类型

由于所有用户输入最初都是str类型，因此如果期望的类型不是str，则需要类型转换。对于像bool、int、float和str这样的基本类型，此库内置了转换器。如果您想使用其他类型，您必须使用Argument构造函数的converter属性指定如何将str输入转换为您的类型。

from telegram_click.argument import Argument

Argument(name='age',
         description='The new age',
         type=MyType,
         converter=lambda x: MyType(x),
         validator=lambda x: x > 0,
         example='25')

标志

技术上可以使用Argument类来指定标志，但由于许多参数对于标志来说是隐式的，因此可以使用Flag类

from telegram_click.argument import Flag

Flag(name='flag',
     description='My boolean flag')

权限处理

如果命令应该在满足特定标准时才能执行，则可以使用permissions参数指定这些标准

from telegram import Update
from telegram.ext import ContextTypes
from telegram_click.decorator import command
from telegram_click.permission import GROUP_ADMIN

@command(name='permission', 
         description='Needs permission',
         permissions=GROUP_ADMIN)
async def _permission_command_callback(self, update: Update, context: ContextTypes.DEFAULT_TYPE):

可以使用&、|和~（非）运算符组合多个权限。

如果用户没有权限使用命令，则当此用户生成命令列表时，该命令将不会显示。

集成权限处理器

自定义权限

如果集成权限不适合您的需求，您可以简单地通过扩展Permission基类来编写自己的权限处理器，并将MyPermission类的实例传递给permissions列表

from telegram import Update
from telegram.ext import ContextTypes
from telegram_click.decorator import command
from telegram_click.permission.base import Permission
from telegram_click.permission import GROUP_ADMIN

class MyPermission(Permission):
    async def evaluate(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> bool:
        from_user = update.effective_message.from_user
        return from_user.id in [12345, 32435]
        
@command(name='permission', description='Needs permission',
         permissions=MyPermission() & GROUP_ADMIN)
async def _permission_command_callback(self, update: Update, context: ContextTypes.DEFAULT_TYPE):

显示“权限拒绝”消息

这种行为由错误处理器定义。默认错误处理器DefaultErrorHandler会静默忽略无权限用户的命令消息。要更改此行为，只需定义自己的自定义ErrorHandler类，如example.py中所示。

目标命令

Telegram支持使用@符号将命令针对特定机器人用户名

/start               # unspecified
/start@myAwesomeBot  # targeted at self
/start@someOtherBot  # targeted at other bot

当使用MessageHandler而不是CommandHandler时，可以捕获针对其他机器人的命令。默认情况下，只有没有目标的消息和直接针对您机器人的消息会被处理。

要控制此行为，请指定command_target参数

from telegram import Update
from telegram.ext import ContextTypes
from telegram_click.decorator import command
from telegram_click import CommandTarget
from telegram_click.permission import NOBODY

@command(name="commands",
         description="List commands supported by this bot.",
         permissions=NOBODY,
         command_target=CommandTarget.UNSPECIFIED | CommandTarget.SELF)
async def _unknown_command_callback(self, update: Update, context: ContextTypes.DEFAULT_TYPE):

您可以使用逻辑运算符组合CommandTarget，如上面的示例所示。

隐藏命令

在极少数情况下，隐藏命令以防止在帮助输出中显示可能是有用的。为此，您可以使用@command装饰器的hidden参数，通过传递True或False，或者一个可调用对象，例如这个

async def hide_whois_if_admin(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_id = update.effective_user.id
    return user_id not in [123456]

此函数在每次消息时都会被评估，因此提供了来自python-telegram-bot的update和context对象，这使得您可以根据聊天和用户属性等因素做出决策。

错误处理

telegram-click在大多数情况下会自动处理错误。

错误分为三类

• 权限错误
• 输入验证错误
• 命令执行错误

DefaultErrorHandler将按以下方式处理这些类别

• 权限错误将被静默忽略。

• 输入验证错误，例如

  • 一个参数无法正确解析
  • 传递给参数的值无效

  将发送异常消息以及用户试图使用的命令的帮助信息。

• 在命令执行错误时，用户将收到通知，表示他的命令已崩溃，而不提供任何特定的错误消息。

要为这些类别中的每一个修改行为，请定义一个ErrorHandler，并将其实例传递给@command装饰器的error_handler参数，如example.py中所示。

贡献

GitHub是社交编码的平台：如果您想编写代码，我鼓励您通过此存储库的分叉创建pull requests进行贡献。为错误和新功能创建GitHub票据，并评论您感兴趣的项目。

许可证

telegram-click
Copyright (c) 2019 Markus Ressel

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.