Metadata-Version: 2.1
Name: telegramlib
Version: 0.1.1
Summary: Easiest Python package to create Telegram bots.
Home-page: https://github.com/ilLancio/telegramlib
Author: Daniele Lanciotti
Author-email: daniele9001@gmail.com
License: MIT
Project-URL: Source, https://github.com/ilLancio/telegramlib
Project-URL: Tracker, https://github.com/ilLancio/telegramlib/issues
Project-URL: Documentation, https://illancio.github.io/telegramlib/
Project-URL: Changelog, https://github.com/ilLancio/telegramlib/blob/master/CHANGELOG.md
Project-URL: Homepage, https://illancio.github.io
Keywords: telegram,bot,api,easy
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anyio==4.4.0
Requires-Dist: APScheduler==3.10.4
Requires-Dist: certifi==2024.7.4
Requires-Dist: charset-normalizer==3.3.2
Requires-Dist: click==8.1.7
Requires-Dist: colorama==0.4.6
Requires-Dist: emoji==2.12.1
Requires-Dist: googletrans-py==4.0.0
Requires-Dist: gTTS==2.5.3
Requires-Dist: h11==0.14.0
Requires-Dist: h2==4.1.0
Requires-Dist: hpack==4.0.0
Requires-Dist: httpcore==1.0.5
Requires-Dist: httpx==0.27.0
Requires-Dist: hyperframe==6.0.1
Requires-Dist: idna==3.7
Requires-Dist: playsound==1.3.0
Requires-Dist: pydub==0.25.1
Requires-Dist: pyobjc==10.3.1
Requires-Dist: pyobjc-core==10.3.1
Requires-Dist: pyobjc-framework-Accessibility==10.3.1
Requires-Dist: pyobjc-framework-Accounts==10.3.1
Requires-Dist: pyobjc-framework-AddressBook==10.3.1
Requires-Dist: pyobjc-framework-AdServices==10.3.1
Requires-Dist: pyobjc-framework-AdSupport==10.3.1
Requires-Dist: pyobjc-framework-AppleScriptKit==10.3.1
Requires-Dist: pyobjc-framework-AppleScriptObjC==10.3.1
Requires-Dist: pyobjc-framework-ApplicationServices==10.3.1
Requires-Dist: pyobjc-framework-AppTrackingTransparency==10.3.1
Requires-Dist: pyobjc-framework-AudioVideoBridging==10.3.1
Requires-Dist: pyobjc-framework-AuthenticationServices==10.3.1
Requires-Dist: pyobjc-framework-AutomaticAssessmentConfiguration==10.3.1
Requires-Dist: pyobjc-framework-Automator==10.3.1
Requires-Dist: pyobjc-framework-AVFoundation==10.3.1
Requires-Dist: pyobjc-framework-AVKit==10.3.1
Requires-Dist: pyobjc-framework-AVRouting==10.3.1
Requires-Dist: pyobjc-framework-BackgroundAssets==10.3.1
Requires-Dist: pyobjc-framework-BrowserEngineKit==10.3.1
Requires-Dist: pyobjc-framework-BusinessChat==10.3.1
Requires-Dist: pyobjc-framework-CalendarStore==10.3.1
Requires-Dist: pyobjc-framework-CallKit==10.3.1
Requires-Dist: pyobjc-framework-CFNetwork==10.3.1
Requires-Dist: pyobjc-framework-Cinematic==10.3.1
Requires-Dist: pyobjc-framework-ClassKit==10.3.1
Requires-Dist: pyobjc-framework-CloudKit==10.3.1
Requires-Dist: pyobjc-framework-Cocoa==10.3.1
Requires-Dist: pyobjc-framework-Collaboration==10.3.1
Requires-Dist: pyobjc-framework-ColorSync==10.3.1
Requires-Dist: pyobjc-framework-Contacts==10.3.1
Requires-Dist: pyobjc-framework-ContactsUI==10.3.1
Requires-Dist: pyobjc-framework-CoreAudio==10.3.1
Requires-Dist: pyobjc-framework-CoreAudioKit==10.3.1
Requires-Dist: pyobjc-framework-CoreBluetooth==10.3.1
Requires-Dist: pyobjc-framework-CoreData==10.3.1
Requires-Dist: pyobjc-framework-CoreHaptics==10.3.1
Requires-Dist: pyobjc-framework-CoreLocation==10.3.1
Requires-Dist: pyobjc-framework-CoreMedia==10.3.1
Requires-Dist: pyobjc-framework-CoreMediaIO==10.3.1
Requires-Dist: pyobjc-framework-CoreMIDI==10.3.1
Requires-Dist: pyobjc-framework-CoreML==10.3.1
Requires-Dist: pyobjc-framework-CoreMotion==10.3.1
Requires-Dist: pyobjc-framework-CoreServices==10.3.1
Requires-Dist: pyobjc-framework-CoreSpotlight==10.3.1
Requires-Dist: pyobjc-framework-CoreText==10.3.1
Requires-Dist: pyobjc-framework-CoreWLAN==10.3.1
Requires-Dist: pyobjc-framework-CryptoTokenKit==10.3.1
Requires-Dist: pyobjc-framework-DataDetection==10.3.1
Requires-Dist: pyobjc-framework-DeviceCheck==10.3.1
Requires-Dist: pyobjc-framework-DictionaryServices==10.3.1
Requires-Dist: pyobjc-framework-DiscRecording==10.3.1
Requires-Dist: pyobjc-framework-DiscRecordingUI==10.3.1
Requires-Dist: pyobjc-framework-DiskArbitration==10.3.1
Requires-Dist: pyobjc-framework-DVDPlayback==10.3.1
Requires-Dist: pyobjc-framework-EventKit==10.3.1
Requires-Dist: pyobjc-framework-ExceptionHandling==10.3.1
Requires-Dist: pyobjc-framework-ExecutionPolicy==10.3.1
Requires-Dist: pyobjc-framework-ExtensionKit==10.3.1
Requires-Dist: pyobjc-framework-ExternalAccessory==10.3.1
Requires-Dist: pyobjc-framework-FileProvider==10.3.1
Requires-Dist: pyobjc-framework-FileProviderUI==10.3.1
Requires-Dist: pyobjc-framework-FinderSync==10.3.1
Requires-Dist: pyobjc-framework-FSEvents==10.3.1
Requires-Dist: pyobjc-framework-GameCenter==10.3.1
Requires-Dist: pyobjc-framework-GameController==10.3.1
Requires-Dist: pyobjc-framework-GameKit==10.3.1
Requires-Dist: pyobjc-framework-GameplayKit==10.3.1
Requires-Dist: pyobjc-framework-HealthKit==10.3.1
Requires-Dist: pyobjc-framework-ImageCaptureCore==10.3.1
Requires-Dist: pyobjc-framework-InputMethodKit==10.3.1
Requires-Dist: pyobjc-framework-InstallerPlugins==10.3.1
Requires-Dist: pyobjc-framework-InstantMessage==10.3.1
Requires-Dist: pyobjc-framework-Intents==10.3.1
Requires-Dist: pyobjc-framework-IntentsUI==10.3.1
Requires-Dist: pyobjc-framework-IOBluetooth==10.3.1
Requires-Dist: pyobjc-framework-IOBluetoothUI==10.3.1
Requires-Dist: pyobjc-framework-IOSurface==10.3.1
Requires-Dist: pyobjc-framework-iTunesLibrary==10.3.1
Requires-Dist: pyobjc-framework-KernelManagement==10.3.1
Requires-Dist: pyobjc-framework-LatentSemanticMapping==10.3.1
Requires-Dist: pyobjc-framework-LaunchServices==10.3.1
Requires-Dist: pyobjc-framework-libdispatch==10.3.1
Requires-Dist: pyobjc-framework-libxpc==10.3.1
Requires-Dist: pyobjc-framework-LinkPresentation==10.3.1
Requires-Dist: pyobjc-framework-LocalAuthentication==10.3.1
Requires-Dist: pyobjc-framework-LocalAuthenticationEmbeddedUI==10.3.1
Requires-Dist: pyobjc-framework-MailKit==10.3.1
Requires-Dist: pyobjc-framework-MapKit==10.3.1
Requires-Dist: pyobjc-framework-MediaAccessibility==10.3.1
Requires-Dist: pyobjc-framework-MediaLibrary==10.3.1
Requires-Dist: pyobjc-framework-MediaPlayer==10.3.1
Requires-Dist: pyobjc-framework-MediaToolbox==10.3.1
Requires-Dist: pyobjc-framework-Metal==10.3.1
Requires-Dist: pyobjc-framework-MetalFX==10.3.1
Requires-Dist: pyobjc-framework-MetalKit==10.3.1
Requires-Dist: pyobjc-framework-MetalPerformanceShaders==10.3.1
Requires-Dist: pyobjc-framework-MetalPerformanceShadersGraph==10.3.1
Requires-Dist: pyobjc-framework-MetricKit==10.3.1
Requires-Dist: pyobjc-framework-MLCompute==10.3.1
Requires-Dist: pyobjc-framework-ModelIO==10.3.1
Requires-Dist: pyobjc-framework-MultipeerConnectivity==10.3.1
Requires-Dist: pyobjc-framework-NaturalLanguage==10.3.1
Requires-Dist: pyobjc-framework-NetFS==10.3.1
Requires-Dist: pyobjc-framework-Network==10.3.1
Requires-Dist: pyobjc-framework-NetworkExtension==10.3.1
Requires-Dist: pyobjc-framework-NotificationCenter==10.3.1
Requires-Dist: pyobjc-framework-OpenDirectory==10.3.1
Requires-Dist: pyobjc-framework-OSAKit==10.3.1
Requires-Dist: pyobjc-framework-OSLog==10.3.1
Requires-Dist: pyobjc-framework-PassKit==10.3.1
Requires-Dist: pyobjc-framework-PencilKit==10.3.1
Requires-Dist: pyobjc-framework-PHASE==10.3.1
Requires-Dist: pyobjc-framework-Photos==10.3.1
Requires-Dist: pyobjc-framework-PhotosUI==10.3.1
Requires-Dist: pyobjc-framework-PreferencePanes==10.3.1
Requires-Dist: pyobjc-framework-PushKit==10.3.1
Requires-Dist: pyobjc-framework-Quartz==10.3.1
Requires-Dist: pyobjc-framework-QuickLookThumbnailing==10.3.1
Requires-Dist: pyobjc-framework-ReplayKit==10.3.1
Requires-Dist: pyobjc-framework-SafariServices==10.3.1
Requires-Dist: pyobjc-framework-SafetyKit==10.3.1
Requires-Dist: pyobjc-framework-SceneKit==10.3.1
Requires-Dist: pyobjc-framework-ScreenCaptureKit==10.3.1
Requires-Dist: pyobjc-framework-ScreenSaver==10.3.1
Requires-Dist: pyobjc-framework-ScreenTime==10.3.1
Requires-Dist: pyobjc-framework-ScriptingBridge==10.3.1
Requires-Dist: pyobjc-framework-SearchKit==10.3.1
Requires-Dist: pyobjc-framework-Security==10.3.1
Requires-Dist: pyobjc-framework-SecurityFoundation==10.3.1
Requires-Dist: pyobjc-framework-SecurityInterface==10.3.1
Requires-Dist: pyobjc-framework-SensitiveContentAnalysis==10.3.1
Requires-Dist: pyobjc-framework-ServiceManagement==10.3.1
Requires-Dist: pyobjc-framework-SharedWithYou==10.3.1
Requires-Dist: pyobjc-framework-SharedWithYouCore==10.3.1
Requires-Dist: pyobjc-framework-ShazamKit==10.3.1
Requires-Dist: pyobjc-framework-Social==10.3.1
Requires-Dist: pyobjc-framework-SoundAnalysis==10.3.1
Requires-Dist: pyobjc-framework-Speech==10.3.1
Requires-Dist: pyobjc-framework-SpriteKit==10.3.1
Requires-Dist: pyobjc-framework-StoreKit==10.3.1
Requires-Dist: pyobjc-framework-Symbols==10.3.1
Requires-Dist: pyobjc-framework-SyncServices==10.3.1
Requires-Dist: pyobjc-framework-SystemConfiguration==10.3.1
Requires-Dist: pyobjc-framework-SystemExtensions==10.3.1
Requires-Dist: pyobjc-framework-ThreadNetwork==10.3.1
Requires-Dist: pyobjc-framework-UniformTypeIdentifiers==10.3.1
Requires-Dist: pyobjc-framework-UserNotifications==10.3.1
Requires-Dist: pyobjc-framework-UserNotificationsUI==10.3.1
Requires-Dist: pyobjc-framework-VideoSubscriberAccount==10.3.1
Requires-Dist: pyobjc-framework-VideoToolbox==10.3.1
Requires-Dist: pyobjc-framework-Virtualization==10.3.1
Requires-Dist: pyobjc-framework-Vision==10.3.1
Requires-Dist: pyobjc-framework-WebKit==10.3.1
Requires-Dist: python-telegram-bot==21.4
Requires-Dist: pytz==2024.1
Requires-Dist: requests==2.32.3
Requires-Dist: six==1.16.0
Requires-Dist: sniffio==1.3.1
Requires-Dist: typing-extensions==4.12.2
Requires-Dist: tzlocal==5.2
Requires-Dist: unicodeit==0.7.5
Requires-Dist: urllib3==2.2.2

# telegramlib

Easiest Python package to create Telegram bots.

Developed by [ilLancio](https://illancio.github.io).

[![pypi](https://img.shields.io/badge/pypi-v0.1.1-blue)](https://pypi.org/project/telegramlib/)
[![python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
[![release date](https://img.shields.io/badge/release_date-august_2024-red)](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 updates

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

  *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/)
