telegram-click-aio

Click 启发的命令行界面创建工具包，适用于 aiogram，针对异步IO优化。

请注意，此库只能与异步IO一起使用。如果您正在寻找一个非异步IO且与 python-telegram-bot 兼容的变体，请参阅 telegram-click！

功能

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

如何使用

将此库作为依赖项安装到您的项目中以使用它。

pip install telegram-click-aio

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

from aiogram import Bot
from aiogram.types import Message
from telegram_click_aio.decorator import command
from telegram_click_aio.argument import Argument

class MyBot:

    [...]
    
    @command(name='start', description='Start bot interaction')
    async def _start_command_callback(self, message: Message):
        # 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, bot: Bot, message: Message, age: int):
        await bot.send_message(message.chat.id, "New age: {}".format(age))

参数

telegram-click-aio使用自定义标记器解析参数

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

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

命名

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

类型

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

from telegram_click_aio.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_aio.argument import Flag

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

权限处理

如果命令仅在满足特定条件时才可执行，则可以使用permissions参数指定这些条件

from aiogram.types import Message
from telegram_click_aio.decorator import command
from telegram_click_aio.permission import GROUP_ADMIN

@command(name='permission', 
         description='Needs permission',
         permissions=GROUP_ADMIN)
async def _permission_command_callback(self, message: Message):

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

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

集成权限处理程序

自定义权限

如果内置权限都不符合您的需求，您可以简单地通过扩展Permission基类并传递MyPermission类的实例到permissions列表中来编写自己的权限处理程序。

from aiogram.types import Message
from telegram_click_aio.decorator import command
from telegram_click_aio.permission.base import Permission
from telegram_click_aio.permission import GROUP_ADMIN

class MyPermission(Permission):
    async def evaluate(self, message: Message) -> bool:
        from_user = 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, message: Message):

显示“权限拒绝”信息

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

目标命令

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

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

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

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

from aiogram.types import Message
from telegram_click_aio.decorator import command
from telegram_click_aio import CommandTarget
from telegram_click_aio.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, message: Message):

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

隐藏命令

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

async def hide_whois_if_admin(message: Message):
    user_id = message.from_user.id
    return user_id not in [123456]

此函数在每条消息上都会被评估，因此提供了来自 aiogram 的 message 对象，这允许您根据聊天和用户属性做出决策，以及其他事项。

错误处理

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

错误分为三类

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

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

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

• 输入验证错误，如

  • 无法正确解析参数
  • 为参数传递了无效值

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

• 在命令执行错误的情况下，用户将被通知其命令已崩溃，而不会提供任何具体的错误消息。

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

贡献

GitHub 是一个社交编码平台：如果您想编写代码，我鼓励您通过从这个仓库的分支中发起的拉取请求来贡献。为错误和新的功能创建 GitHub 问题，并对您感兴趣的问题进行评论。

许可

telegram-click-aio
Copyright (c) 2020 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.