# telegramlib
Easiest Python package to create Telegram bots.
Developed by [ilLancio](https://illancio.github.io).
[](https://pypi.org/project/telegramlib/)
[](https://www.python.org)
[](https://github.com/ilLancio/telegramlib/blob/master/CHANGELOG.md)
## Table of Contents
* [Installation](#installation)
* [Usage Examples](#usage-examples)
* [Complete List of Functions](#complete-list-of-functions)
* [Documentation](#documentation)
* [Changelog](#changelog)
* [License](#license)
* [Author](#author)
## Installation
You can install the package from [PyPI](https://pypi.org/project/telegramlib/) using pip:
```console
pip install telegramlib
```
## Usage examples
### Setting up your bot
1. **Obtain a Telegram bot token** from [BotFather](https://t.me/BotFather).
2. **Obtain your Telegram user ID** from [RawDataBot](https://t.me/raw_info_bot).
3. **Replace placeholders** with your actual bot token and user ID in the examples below.
### Example 1: Starting the Bot
Define a start function that performs what you want to happen when a user types the `/start` command. Then remember to add the command in the `start_bot` function along with your token and user id.
```python
from telegramlib import *
TOKEN = 'your Telegram bot token'
ADMIN = 'your user ID'
# Define a start command function
async def start():
await bot_reply_text('Bot started!')
# Bot configuration and start
start_bot(
token=TOKEN,
admin=ADMIN,
commands=start
)
```
```Telegram
User: /start
Bot: Bot started!
```
#### Disable user privacy
If you want to save user information, you must explicitly specify it as a parameter in the `start_bot` function by setting `privacy=False`, like so: `start_bot(token=TOKEN, ..., privacy=False)`. User information will be saved in the `database.json` file.
#### Legal Disclaimer: User Privacy and Data Handling
Please note that you are solely responsible for complying with all applicable data protection and privacy laws. This includes, but is not limited to, obtaining user consent where required, securely storing the data, and providing users with necessary disclosures regarding how their data will be used. The author of this library assumes no liability for any legal consequences arising from the use or misuse of this functionality.
#### Disable user updates
Disabling user privacy and being an admin yourself, you will receive informative messages from the bot about the activities of your bot's users. To disable or enable it, send it the `/usersupdates` command.
### Example 2: Other Commands and Message Handler
Define another command function that makes the bot respond by giving you the command arguments and a message handler that gives the user the name of the bot after being asked for it. Always remember to add the functions in `start_bot`.
```python
from telegramlib import *
TOKEN = 'your Telegram bot token'
ADMIN = 'your user ID'
# Define a start command function
async def start():
await bot_reply_text('Bot started!')
# Define another command function
async def yourcommand():
args = str( command_args() )
response = 'You sent me your command with these arguments: ' + args
await bot_reply_text(response)
# Define a message handler function
async def message():
if user_message() == "What's your name?":
await bot_reply_text('My name is ' + bot_name())
# Bot configuration and start
start_bot(
token=TOKEN,
admin=ADMIN,
commands=[start, yourcommand],
messages=message
)
```
```Telegram
User: /yourcommand Hello Bot!
Bot: You sent me your command with these arguments: ['Hello', 'Bot!']
User: What's your name
Bot: My name is <bot-name>
```
### Example 3: Scheduling Future Messages
Define the start function so that it schedules a daily task at 6 p.m., so, typing the start command, every day at 6 p.m. will be executed the contents of the `scheduled_task` function defined under, also to be added to the `start_bot` function. Additionally define a command that removes all user tasks.
```python
from telegramlib import *
TOKEN = 'your Telegram bot token'
ADMIN = 'your user ID'
# Define a start command function
async def start():
# Task scheduling. reset=True to remove old scheduled tasks
new_daily_job(scheduled_task, 18, 0, reset=True)
await bot_reply_text('Scheduled task every day at 6 p.m.')
# Define another command
async def removetasks():
remove_all_daily_jobs()
await bot_reply_text('Tasks all deleted')
# Define a scheduled function
async def scheduled_task():
await bot_reply_text('This is a scheduled task!')
# Bot configuration and start
start_bot(
token=TOKEN,
admin=ADMIN,
commands=[start, removetasks],
scheduled=scheduled_task
)
```
```Telegram
User: /start
Bot: Scheduled task every day at 6 p.m.
(at 6:00 PM)
Bot: This is a scheduled task!
User: /removetasks
Bot: Tasks all deleted
```
### Example 4: Users Parameters, Admin and Controllers
Specify in the `start_bot` function a dictionary representative of the users' default parameters. That done, you can access and modify those parameters with `get_param` and `set_param`. In the example we use within the start command and commands with access restricted to the admin and controllers, which are also specified in the `start_bot` function.
```python
from telegramlib import *
TOKEN = 'your Telegram bot token'
ADMIN = 'your user ID'
# Define a start command function
async def start():
set_param('parameter 2', False)
await bot_reply_text('Your parameter 2 is been set to False')
# Admin restricted access command
@admin_command
async def admincommand():
p = get_param('parameter 1')
await bot_reply_text(f'I am answering you because you are the admin and your parameter 1 is {p}')
# Controllers restricted access command
@controllers_command
async def controllercommand():
p = get_param('parameter 1')
await bot_reply_text(f'I am responding to you because you are an admin and an admin is always a controller. Your parameter 1 is {p}')
# Bot configuration and start
start_bot(
token=TOKEN,
admin=ADMIN,
commands=[start, admincommand, controllercommand],
controllers=[<user_id_1>, <user_id_2>],
params={'parameter 1': 42, 'parameter 2': True}
)
```
```Telegram
User: /start
Bot: Your parameter 2 is been set to False
User: /admincommand
Bot: I am answering you because you are the admin and your parameter 1 is 42
User: /controllercommand
Bot: I am responding to you because you are an admin and an admin is always controller. Your parameter 1 is 42
```
## Complete List of Functions
* `start_bot(token, admin, commands, messages=None, scheduled=None error=None, controllers = None, params=None, privacy=True)`
*Start the Telegram bot.*
* `command_args()`
*Get the command arguments.*
* `bot_reply_text(message, text_to_audio=False, translate_to=None, talking_about_latex=False)`
*Respond with a text from the bot.*
* `send(message, chat_id=None, save=True, token=None, parse_mode=ParseMode.HTML)`
*Send a message.*
* `delete(chat_id, message_id, token=None)`
*Delete a message.*
* `context()`
*Get the python-telegram-bot context.*
* `update()`
*Get the python-telegram-bot update.*
* `bot_name()`
*Get the name of the bot.*
* `set_param(key, value)`
*Set a parameter of the user.*
* `get_param(key)`
*Get a parameter of the user.*
* `get_chat(user=None, last=None, last_message=None, max_char=None, to_string=False, to_list=False, only_name_keys=False, without_keys=False)`
*Get a chat.*
* `admin_command(func)`
*Decorator for admin Telegram commands.*
* `controllers_command(func)`
*Decorator for controllers Telegram commands.*
#### Ready-to-use commands (to be added to start_bot for use)
* `terminal()`
*Admin Telegram command to type a command on the bot's machine terminal.*
* `follow()`
*Admin Telegram command to follow user messages.*
* `unfollow()`
*Admin Telegram command to stop following user messages.*
* `write()`
*Admin Telegram command to write a message to another user.*
* `ban()`
*Admin Telegram command to ban a user.*
* `sban()`
*Admin Telegram command to remove ban from a user.*
* `creator()`
*Telegram command to contact the creator of the bot.*
* `close_creator()`
*Telegram command to close the dialog with the bot creator.*
#### For scheduling tasks
* `new_daily_job_from_args(function, reset=False)`
*Create a new daily job by taking time from command arguments.*
* `get_command_args_daily_job_time_format(n_arg=0)`
*Get time from command arguments.*
* `is_daily_job_scheduled(function, hour, minute)`
*Check whether a daily job is scheduled.*
* `daily_jobs_scheduled_times_to_string(mex='', if_empty_mex='')`
*Convert scheduled daily job times to a string.*
* `remove_all_daily_jobs()`
*Remove all daily jobs.*
* `new_daily_job(function, hour, minute, reset=False)`
*Create a new daily job.*
## Documentation
You can find documentation [here](https://illancio.github.io/telegramlib/).
## Changelog
For a detailed history of changes, see the [Changelog](https://github.com/ilLancio/telegramlib/blob/master/CHANGELOG.md).
## License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/ilLancio/telegramlib/blob/master/LICENSE) file for details.
The licenses of the dependencies used in this project are listed in the file [THIRD_PARTY_LICENSES.txt](https://github.com/ilLancio/telegramlib/blob/master/THIRD_PARTY_LICENSES.txt).
## Author
* Daniele Lanciotti
Email: <daniele9001@gmail.com>
Website: [illancio.github.io](https://illancio.github.io/)
Raw data
{
"_id": null,
"home_page": "https://github.com/ilLancio/telegramlib",
"name": "telegramlib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "telegram, bot, api, easy",
"author": "Daniele Lanciotti",
"author_email": "daniele9001@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/30/94/d7ff927182c621463368651277a9472edd1b8b82821c5f44665576c0b3f2/telegramlib-0.1.3.tar.gz",
"platform": null,
"description": "# telegramlib\n\nEasiest Python package to create Telegram bots.\n\nDeveloped by [ilLancio](https://illancio.github.io).\n\n[](https://pypi.org/project/telegramlib/)\n[](https://www.python.org)\n[](https://github.com/ilLancio/telegramlib/blob/master/CHANGELOG.md)\n\n## Table of Contents\n\n* [Installation](#installation)\n* [Usage Examples](#usage-examples)\n* [Complete List of Functions](#complete-list-of-functions)\n* [Documentation](#documentation)\n* [Changelog](#changelog)\n* [License](#license)\n* [Author](#author)\n\n## Installation\n\nYou can install the package from [PyPI](https://pypi.org/project/telegramlib/) using pip:\n\n```console\npip install telegramlib\n```\n\n## Usage examples\n\n### Setting up your bot\n\n1. **Obtain a Telegram bot token** from [BotFather](https://t.me/BotFather).\n2. **Obtain your Telegram user ID** from [RawDataBot](https://t.me/raw_info_bot).\n3. **Replace placeholders** with your actual bot token and user ID in the examples below.\n\n### Example 1: Starting the Bot\n\nDefine a start function that performs what you want to happen when a user types the `/start` command. Then remember to add the command in the `start_bot` function along with your token and user id.\n\n```python\nfrom telegramlib import *\n\nTOKEN = 'your Telegram bot token'\nADMIN = 'your user ID'\n\n# Define a start command function\nasync def start():\n await bot_reply_text('Bot started!')\n\n# Bot configuration and start\nstart_bot(\n token=TOKEN,\n admin=ADMIN,\n commands=start\n)\n```\n\n```Telegram\nUser: /start\nBot: Bot started!\n```\n\n#### Disable user privacy\n\nIf you want to save user information, you must explicitly specify it as a parameter in the `start_bot` function by setting `privacy=False`, like so: `start_bot(token=TOKEN, ..., privacy=False)`. User information will be saved in the `database.json` file.\n\n#### Legal Disclaimer: User Privacy and Data Handling\n\nPlease note that you are solely responsible for complying with all applicable data protection and privacy laws. This includes, but is not limited to, obtaining user consent where required, securely storing the data, and providing users with necessary disclosures regarding how their data will be used. The author of this library assumes no liability for any legal consequences arising from the use or misuse of this functionality.\n\n#### Disable user updates\n\nDisabling user privacy and being an admin yourself, you will receive informative messages from the bot about the activities of your bot's users. To disable or enable it, send it the `/usersupdates` command.\n\n### Example 2: Other Commands and Message Handler\n\nDefine another command function that makes the bot respond by giving you the command arguments and a message handler that gives the user the name of the bot after being asked for it. Always remember to add the functions in `start_bot`.\n\n```python\nfrom telegramlib import *\n\nTOKEN = 'your Telegram bot token'\nADMIN = 'your user ID'\n\n# Define a start command function\nasync def start():\n await bot_reply_text('Bot started!')\n\n# Define another command function\nasync def yourcommand():\n args = str( command_args() )\n response = 'You sent me your command with these arguments: ' + args\n await bot_reply_text(response)\n\n# Define a message handler function\nasync def message():\n if user_message() == \"What's your name?\":\n await bot_reply_text('My name is ' + bot_name())\n\n# Bot configuration and start\nstart_bot(\n token=TOKEN,\n admin=ADMIN,\n commands=[start, yourcommand],\n messages=message\n)\n```\n\n```Telegram\nUser: /yourcommand Hello Bot!\nBot: You sent me your command with these arguments: ['Hello', 'Bot!']\nUser: What's your name\nBot: My name is <bot-name>\n```\n\n### Example 3: Scheduling Future Messages\n\nDefine the start function so that it schedules a daily task at 6 p.m., so, typing the start command, every day at 6 p.m. will be executed the contents of the `scheduled_task` function defined under, also to be added to the `start_bot` function. Additionally define a command that removes all user tasks.\n\n```python\nfrom telegramlib import *\n\nTOKEN = 'your Telegram bot token'\nADMIN = 'your user ID'\n\n# Define a start command function\nasync def start():\n # Task scheduling. reset=True to remove old scheduled tasks\n new_daily_job(scheduled_task, 18, 0, reset=True)\n await bot_reply_text('Scheduled task every day at 6 p.m.')\n\n# Define another command\nasync def removetasks():\n remove_all_daily_jobs()\n await bot_reply_text('Tasks all deleted')\n\n# Define a scheduled function\nasync\u00a0def\u00a0scheduled_task():\n await\u00a0bot_reply_text('This is a scheduled task!')\n\n# Bot configuration and start\nstart_bot(\n token=TOKEN,\n admin=ADMIN,\n commands=[start, removetasks],\n scheduled=scheduled_task\n)\n```\n\n```Telegram\nUser: /start\nBot: Scheduled task every day at 6 p.m.\n\n(at\u00a06:00\u00a0PM)\nBot: This is a scheduled task!\n\nUser: /removetasks\nBot: Tasks all deleted\n```\n\n### Example 4: Users Parameters, Admin and Controllers\n\nSpecify in the `start_bot` function a dictionary representative of the users' default parameters. That done, you can access and modify those parameters with `get_param` and `set_param`. In the example we use within the start command and commands with access restricted to the admin and controllers, which are also specified in the `start_bot` function.\n\n```python\nfrom telegramlib import *\n\nTOKEN = 'your Telegram bot token'\nADMIN = 'your user ID'\n\n# Define a start command function\nasync def start():\n set_param('parameter 2', False)\n await bot_reply_text('Your parameter 2 is been set to False')\n\n# Admin restricted access command\n@admin_command\nasync def admincommand():\n p = get_param('parameter 1')\n await bot_reply_text(f'I am answering you because you are the admin and your parameter 1 is {p}')\n\n# Controllers restricted access command\n@controllers_command\nasync def controllercommand():\n p = get_param('parameter 1')\n await bot_reply_text(f'I am responding to you because you are an admin and an admin is always a controller. Your parameter 1 is {p}')\n\n# Bot configuration and start\nstart_bot(\n token=TOKEN,\n admin=ADMIN,\n commands=[start, admincommand, controllercommand],\n controllers=[<user_id_1>, <user_id_2>],\n params={'parameter 1': 42, 'parameter 2': True}\n)\n```\n\n```Telegram\nUser: /start\nBot: Your parameter 2 is been set to False\nUser: /admincommand\nBot: I am answering you because you are the admin and your parameter 1 is 42\nUser: /controllercommand\nBot: I am responding to you because you are an admin and an admin is always controller. Your parameter 1 is 42\n```\n\n## Complete List of Functions\n\n* `start_bot(token, admin, commands, messages=None, scheduled=None error=None, controllers = None, params=None, privacy=True)`\n\n *Start the Telegram bot.*\n\n* `command_args()`\n\n *Get the command arguments.*\n\n* `bot_reply_text(message, text_to_audio=False, translate_to=None, talking_about_latex=False)`\n\n *Respond with a text from the bot.*\n\n* `send(message, chat_id=None, save=True, token=None, parse_mode=ParseMode.HTML)`\n\n *Send a message.*\n\n* `delete(chat_id, message_id, token=None)`\n\n *Delete a message.*\n\n* `context()`\n\n *Get the python-telegram-bot context.*\n\n* `update()`\n\n *Get the python-telegram-bot update.*\n\n* `bot_name()`\n\n *Get the name of the bot.*\n\n* `set_param(key, value)`\n\n *Set a parameter of the user.*\n\n* `get_param(key)`\n\n *Get a parameter of the user.*\n\n* `get_chat(user=None, last=None, last_message=None, max_char=None, to_string=False, to_list=False, only_name_keys=False, without_keys=False)`\n\n *Get a chat.*\n\n* `admin_command(func)`\n\n *Decorator for admin Telegram commands.*\n\n* `controllers_command(func)`\n\n *Decorator for controllers Telegram commands.*\n\n#### Ready-to-use commands (to be added to start_bot for use)\n\n* `terminal()`\n\n *Admin Telegram command to type a command on the bot's machine terminal.*\n\n* `follow()`\n\n *Admin Telegram command to follow user messages.*\n\n* `unfollow()`\n\n *Admin Telegram command to stop following user messages.*\n\n* `write()`\n\n *Admin Telegram command to write a message to another user.*\n\n* `ban()`\n\n *Admin Telegram command to ban a user.*\n\n* `sban()`\n\n *Admin Telegram command to remove ban from a user.*\n\n* `creator()`\n\n *Telegram command to contact the creator of the bot.*\n\n* `close_creator()`\n\n *Telegram command to close the dialog with the bot creator.*\n\n#### For scheduling tasks\n\n* `new_daily_job_from_args(function, reset=False)`\n\n *Create a new daily job by taking time from command arguments.*\n\n* `get_command_args_daily_job_time_format(n_arg=0)`\n\n *Get time from command arguments.*\n\n* `is_daily_job_scheduled(function, hour, minute)`\n\n *Check whether a daily job is scheduled.*\n\n* `daily_jobs_scheduled_times_to_string(mex='', if_empty_mex='')`\n\n *Convert scheduled daily job times to a string.*\n\n* `remove_all_daily_jobs()`\n\n *Remove all daily jobs.*\n\n* `new_daily_job(function, hour, minute, reset=False)`\n\n *Create a new daily job.*\n\n## Documentation\n\nYou can find documentation [here](https://illancio.github.io/telegramlib/).\n\n## Changelog\n\nFor a detailed history of changes, see the [Changelog](https://github.com/ilLancio/telegramlib/blob/master/CHANGELOG.md).\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/ilLancio/telegramlib/blob/master/LICENSE) file for details.\n\nThe licenses of the dependencies used in this project are listed in the file [THIRD_PARTY_LICENSES.txt](https://github.com/ilLancio/telegramlib/blob/master/THIRD_PARTY_LICENSES.txt).\n\n## Author\n\n* Daniele Lanciotti\n\n Email: <daniele9001@gmail.com>\n\n Website: [illancio.github.io](https://illancio.github.io/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Easiest Python package to create Telegram bots.",
"version": "0.1.3",
"project_urls": {
"Changelog": "https://github.com/ilLancio/telegramlib/blob/master/CHANGELOG.md",
"Documentation": "https://illancio.github.io/telegramlib/",
"Homepage": "https://illancio.github.io",
"Source": "https://github.com/ilLancio/telegramlib",
"Tracker": "https://github.com/ilLancio/telegramlib/issues"
},
"split_keywords": [
"telegram",
" bot",
" api",
" easy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5f6e223cbf45d309984874711d448663cf5c8c19a4ad31c67100e90060123d51",
"md5": "06ca965ea22fb65970c4e1e3c9498294",
"sha256": "26a3299ccdb9bfb3cbe558a0b2cfbcf9b820f4922dcdd89788b92eca12e941be"
},
"downloads": -1,
"filename": "telegramlib-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "06ca965ea22fb65970c4e1e3c9498294",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 30605,
"upload_time": "2024-08-20T00:05:35",
"upload_time_iso_8601": "2024-08-20T00:05:35.989196Z",
"url": "https://files.pythonhosted.org/packages/5f/6e/223cbf45d309984874711d448663cf5c8c19a4ad31c67100e90060123d51/telegramlib-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3094d7ff927182c621463368651277a9472edd1b8b82821c5f44665576c0b3f2",
"md5": "65e8184b34d63371f80a7311a9f0f3b3",
"sha256": "b24718c2f9d7622aab40907267e67b243d3459b6bc361c50a8f3a14139287008"
},
"downloads": -1,
"filename": "telegramlib-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "65e8184b34d63371f80a7311a9f0f3b3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 35259,
"upload_time": "2024-08-20T00:05:38",
"upload_time_iso_8601": "2024-08-20T00:05:38.548710Z",
"url": "https://files.pythonhosted.org/packages/30/94/d7ff927182c621463368651277a9472edd1b8b82821c5f44665576c0b3f2/telegramlib-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-20 00:05:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ilLancio",
"github_project": "telegramlib",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "telegramlib"
}
JSON
