Skip to main content

Click inspired command interface toolkit for pyton-telegram-bot

Project description

telegram-click https://badge.fury.io/py/telegram-click Build Status

Click inspired command interface toolkit for pyton-telegram-bot.

Features

  • Help message generation
  • Argument parsing, type conversion and validation
  • Permission handling
  • Error handling

How to use

Install this library as a dependency to use it in your project.

pip install telegram-click

Then annotate your command handler functions with the @command decorator of this library. The information you need to provide is used to generate the help messages.

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

class MyBot:

    [...]

    @command(name='start', description='Start bot interaction')
    def _start_command_callback(self, update: Update, context: CallbackContext):
        # 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')
             ])
    def _age_command_callback(self, update: Update, context: CallbackContext, age: int):
        context.bot.send_message(update.effective_chat.id, "New age: {}".format(age))

Arguments

telegram-click automatically parses arguments based on shlex POSIX rules so in general space acts as an argument delimiter and quoted arguments are parsed as a single one (supporting both double (") and single (') quote character).

Types

Since all user input initially is of type str there needs to be a type conversion if the expected type is not a str. For basic types like bool, int, float and str converters are built in to this library. If you want to use other types you have to specify how to convert the str input to your type using the converter attribute of the Argument constructor:

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')

Permission handling

If a command should only be executable when a specific criteria is met you can specify those criteria using the permissions parameter:

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

@command(name='permission', description='Needs permission',
         permissions=GROUP_ADMIN)
def _permission_command_callback(self, update: Update, context: CallbackContext):
    pass

Multiple permissions can be combined using &, | and ~ (not) operators.

If a user does not have permission to use a command it will not be displayed when this user generate a list of commands.

Integrated permission handlers

Name Description
PRIVATE_CHAT Requires command execution inside of a private chat
GROUP_CHAT Requires command execution inside a group
USER_ID Only allow users with a user id specified
USER_NAME Only allow users with a username specified
GROUP_CREATOR Only allow the group creator
GROUP_ADMIN Only allow the group admin

Custom permission handler

If none of the integrated handlers suit your needs you can simply write your own permission handler by extending the Permission base class and pass an instance of the MyPermission class to the list of permissions:

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

class MyPermission(Permission):
    def evaluate(self, update: Update, context: CallbackContext) -> 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)
def _permission_command_callback(self, update: Update, context: CallbackContext):
    pass

Show "Permission denied" message

By default command calls coming from a user without permission are ignored. If you want to send them a "permission denied" like message you can pass this message to the permission_denied_message argument of the @command decorator.

Error handling

telegram-click automatically handles errors when

  • an argument can not be parsed correctly
  • an invalid value is passed for an argument
  • too many arguments are passed

In these cases the message of the internal exception is sent to the chat along with a help message for the failed command.

Note: This error handling does also handle errors that occur in your handler function and (by default) prints the exception text to the chat. If you don't want to send the exception message to the user set the print_error parameter to False.

Limitations

Currently the decorator expects a classmethod meaning the first parameter of it is the self parameter. This will probably be supported in a future release.

Contributing

GitHub is for social coding: if you want to write code, I encourage contributions through pull requests from forks of this repository. Create GitHub tickets for bugs and new features and comment on the ones that you are interested in.

License

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

telegram_click-2.2.1.tar.gz (11.6 kB view details)

Uploaded Source

Built Distribution

telegram_click-2.2.1-py3-none-any.whl (17.9 kB view details)

Uploaded Python 3

File details

Details for the file telegram_click-2.2.1.tar.gz.

File metadata

  • Download URL: telegram_click-2.2.1.tar.gz
  • Upload date:
  • Size: 11.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/39.1.0 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.7.3

File hashes

Hashes for telegram_click-2.2.1.tar.gz
Algorithm Hash digest
SHA256 956d6906c3039724a9ae0b77efe6bfd1688f021e54436985641b1e47e28ceca3
MD5 b77237bfa4678462aa4b4471ee1c3365
BLAKE2b-256 afaae485578af5eeeecb0806595091b5c56bb3800d8553fd87074642263cadb1

See more details on using hashes here.

File details

Details for the file telegram_click-2.2.1-py3-none-any.whl.

File metadata

  • Download URL: telegram_click-2.2.1-py3-none-any.whl
  • Upload date:
  • Size: 17.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/39.1.0 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.7.3

File hashes

Hashes for telegram_click-2.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ea0174d32197f1b1d29bdc72f7c5449a5501687565f304cbee0c0a6c1b9e8ae9
MD5 2a25a24dca5c731bb92ced94b0fb8845
BLAKE2b-256 c1f932e443985c021e143551c07c5e6a3e30d14369ddeee4005ca5980cc435ba

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page