Introduction
============
This repository provides a python library to make it easy to create
telegram bots using the python telegram API.
The basic idea is that you can define a function similar to the way you
would with the `click framework <https://click.palletsprojects.com>`__
and then automatically convert that into a form suitable for telegram.
Ideally, creating commands in a telegram bot should but just as easy as
writing a python function.
Getting Started
===============
The following describes how to get started as quickly as possible.
Install via pip
---------------
Do the usual ``pip install tbotg``.
Use BotFather to create a bot
-----------------------------
First, use the botfather to create a bot:
#. Go to ``BotFather`` in a Telegram chat.
#. Type ``/newbot`` to request a new bot.
#. Type the desired name when ``BotFather`` asks you for it.
#. Save the token ``BotFather`` gives you in ``~/.ox_secrets.csv`` as
.. code:: example
name,category,values,notes
token,YOUR_BOT_NAME,YOUR_TOKEN
- The ``~/.ox_secrets.csv`` file is a simple CSV file used to manage
secret information such as your telegram bot token.
Create a python file for your command
-------------------------------------
Next, create a python file for your bot. For example, you could create a
python file named ``mybot.py`` as shown below:
.. code:: python
"Example to show how to use tbotg"
import click
from tbotg.core.main_bot import TelegramMainBot
from tbotg.core.bcmds import ClickCmd
@click.command()
@click.option('--say', '/say', help='What to say')
@click.option('--count', '/count', type=int, help='How many times to repeat.')
def repeatntimes(say, count):
"Repeat something N times."
return 'I will repeat it %i times: %s' % (
count, ', '.join([say.upper()] * count))
class MyBot(TelegramMainBot):
"""Example bot.
"""
@classmethod
def make_cmds(cls):
"Make commands for bot."
return [ClickCmd(repeatntimes)]
Start the server
----------------
Run the serve using the ``tcli`` script provided by ``tbotg`` via the
following command line:
.. code:: bash
tcli serve --bot_cls MyBot --module 'mybot' --with_name ${YOUR_BOT_NAME}
where ``${YOUR_BOT_NAME}`` is the name of the bot you created with
``BotFather``
Note that you will need your ``PYTHONPATH`` set properly for python to
find your ``mybot.py`` module. For example, you could do something like
::
export PYTHONPATH=${PYTHONPATH}:`dirname /path/to/mybot.py`
Test the command on telegram
----------------------------
To test your command,
#. Start a chat with your bot on telegram.
#. Do ``/help`` to see available commands.
#. Do ``/repeatntimes`` to run your command
#. Click on the parameter buttons to set the values of ``say`` and
``count``.
#. Click the ``confirm`` button to run the command.
Note that you can also include command line arguments when calling a
command in Telegram via something like:
.. code:: example
/repeatntimes /say hi
and that option will be automatically filled in. Note that it is best to
use a leading slash (``/``) for these kinds of options and not the usual
double hyphen (``--``) since some versions of Telegram `auto-replace
double
hyphens <https://github.com/telegramdesktop/tdesktop/issues/522>`__ with
a "long dash".
Raw data
{
"_id": null,
"home_page": "http://github.com/aocks/tbotg",
"name": "tbotg",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "telegram generic bots",
"author": "Emin Martinian",
"author_email": "emin.martinian@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6e/29/b1509e32023d89379dc993e450d2b98e3d3d5369032f8cc9b9c0d6bb3018/tbotg-0.3.0.tar.gz",
"platform": null,
"description": "Introduction\n============\n\nThis repository provides a python library to make it easy to create\ntelegram bots using the python telegram API.\n\nThe basic idea is that you can define a function similar to the way you\nwould with the `click framework <https://click.palletsprojects.com>`__\nand then automatically convert that into a form suitable for telegram.\n\nIdeally, creating commands in a telegram bot should but just as easy as\nwriting a python function.\n\nGetting Started\n===============\n\nThe following describes how to get started as quickly as possible.\n\nInstall via pip\n---------------\n\nDo the usual ``pip install tbotg``.\n\nUse BotFather to create a bot\n-----------------------------\n\nFirst, use the botfather to create a bot:\n\n#. Go to ``BotFather`` in a Telegram chat.\n#. Type ``/newbot`` to request a new bot.\n#. Type the desired name when ``BotFather`` asks you for it.\n#. Save the token ``BotFather`` gives you in ``~/.ox_secrets.csv`` as\n\n.. code:: example\n\n name,category,values,notes\n token,YOUR_BOT_NAME,YOUR_TOKEN\n\n- The ``~/.ox_secrets.csv`` file is a simple CSV file used to manage\n secret information such as your telegram bot token.\n\nCreate a python file for your command\n-------------------------------------\n\nNext, create a python file for your bot. For example, you could create a\npython file named ``mybot.py`` as shown below:\n\n.. code:: python\n\n \"Example to show how to use tbotg\"\n\n import click\n\n from tbotg.core.main_bot import TelegramMainBot\n from tbotg.core.bcmds import ClickCmd\n\n\n @click.command()\n @click.option('--say', '/say', help='What to say')\n @click.option('--count', '/count', type=int, help='How many times to repeat.')\n def repeatntimes(say, count):\n \"Repeat something N times.\"\n return 'I will repeat it %i times: %s' % (\n count, ', '.join([say.upper()] * count))\n\n\n class MyBot(TelegramMainBot):\n \"\"\"Example bot.\n \"\"\"\n\n @classmethod\n def make_cmds(cls):\n \"Make commands for bot.\"\n\n return [ClickCmd(repeatntimes)]\n\nStart the server\n----------------\n\nRun the serve using the ``tcli`` script provided by ``tbotg`` via the\nfollowing command line:\n\n.. code:: bash\n\n tcli serve --bot_cls MyBot --module 'mybot' --with_name ${YOUR_BOT_NAME}\n\nwhere ``${YOUR_BOT_NAME}`` is the name of the bot you created with\n``BotFather``\n\nNote that you will need your ``PYTHONPATH`` set properly for python to\nfind your ``mybot.py`` module. For example, you could do something like\n\n::\n\n export PYTHONPATH=${PYTHONPATH}:`dirname /path/to/mybot.py`\n\nTest the command on telegram\n----------------------------\n\nTo test your command,\n\n#. Start a chat with your bot on telegram.\n#. Do ``/help`` to see available commands.\n#. Do ``/repeatntimes`` to run your command\n#. Click on the parameter buttons to set the values of ``say`` and\n ``count``.\n#. Click the ``confirm`` button to run the command.\n\nNote that you can also include command line arguments when calling a\ncommand in Telegram via something like:\n\n.. code:: example\n\n /repeatntimes /say hi\n\nand that option will be automatically filled in. Note that it is best to\nuse a leading slash (``/``) for these kinds of options and not the usual\ndouble hyphen (``--``) since some versions of Telegram `auto-replace\ndouble\nhyphens <https://github.com/telegramdesktop/tdesktop/issues/522>`__ with\na \"long dash\".\n",
"bugtrack_url": null,
"license": "GPL3",
"summary": "Tools for Telegram generic bots.",
"version": "0.3.0",
"split_keywords": [
"telegram",
"generic",
"bots"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6e29b1509e32023d89379dc993e450d2b98e3d3d5369032f8cc9b9c0d6bb3018",
"md5": "cb71fb3b6375f4b7b31e50cf96638227",
"sha256": "34628f72a0e9839c2602d02bf555c3682b412cdca04309daeb5868b92b514d6c"
},
"downloads": -1,
"filename": "tbotg-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "cb71fb3b6375f4b7b31e50cf96638227",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19743,
"upload_time": "2023-01-16T03:31:22",
"upload_time_iso_8601": "2023-01-16T03:31:22.712778Z",
"url": "https://files.pythonhosted.org/packages/6e/29/b1509e32023d89379dc993e450d2b98e3d3d5369032f8cc9b9c0d6bb3018/tbotg-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-16 03:31:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "aocks",
"github_project": "tbotg",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "tbotg"
}
JSON
