Merge pull request #2017 from Artin-GH/patch-1

Fix backslash (\) issue in escape_markdown

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Description
+Include changes, new features and etc:
+
+## Describe your tests
+How did you test your change?
+
+Python version:
+
+OS:
+
+## Checklist:
+- [ ] I added/edited example on new feature/change (if exists)
+- [ ] My changes won't break backward compatibility
+- [ ] I made changes both for sync and async

.github/workflows/setup_python.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ '3.6','3.7','3.8','3.9', 'pypy-3.6', 'pypy-3.7' ] #'pypy-3.8', 'pypy-3.9' NOT SUPPORTED NOW
+        python-version: [ '3.7', '3.8', '3.9', '3.10', '3.11', 'pypy-3.7', 'pypy-3.8', 'pypy-3.9']
     name: ${{ matrix.python-version }} and tests
     steps:
       - uses: actions/checkout@v2

.gitignore

@@ -64,3 +64,7 @@ testMain.py
 #VS Code
 .vscode/
 .DS_Store
+*.code-workspace
+
+# documentation
+_build/

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

.readthedocs.yml

@@ -0,0 +1,19 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: doc_req.txt

.travis.yml

@@ -4,6 +4,7 @@ python:
     - "3.8"
     - "3.9"
     - "3.10"
+    - "3.11"
     - "pypy3"
 install: "pip install -r requirements.txt"
 script:

README.md

@@ -1,16 +1,20 @@
 
 [![PyPi Package Version](https://img.shields.io/pypi/v/pyTelegramBotAPI.svg)](https://pypi.python.org/pypi/pyTelegramBotAPI)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/pyTelegramBotAPI.svg)](https://pypi.python.org/pypi/pyTelegramBotAPI)
-[![Build Status](https://travis-ci.org/eternnoir/pyTelegramBotAPI.svg?branch=master)](https://travis-ci.org/eternnoir/pyTelegramBotAPI)
+[![Documentation Status](https://readthedocs.org/projects/pytba/badge/?version=latest)](https://pytba.readthedocs.io/en/latest/?badge=latest)
 [![PyPi downloads](https://img.shields.io/pypi/dm/pyTelegramBotAPI.svg)](https://pypi.org/project/pyTelegramBotAPI/)
+[![PyPi status](https://img.shields.io/pypi/status/pytelegrambotapi.svg?style=flat-square)](https://pypi.python.org/pypi/pytelegrambotapi)
 
 # <p align="center">pyTelegramBotAPI
 
 <p align="center">A simple, but extensible Python implementation for the <a href="https://core.telegram.org/bots/api">Telegram Bot API</a>.</p>
-<p align="center">Supports both sync and async ways.</p>
+<p align="center">Both synchronous and asynchronous.</p>
 
-## <p align="center">Supporting Bot API version: <a href="https://core.telegram.org/bots/api#december-30-2021">5.6</a>!
+## <p align="center">Supported Bot API version: <a href="https://core.telegram.org/bots/api#april-21-2023">6.7</a>!
 
+<h2><a href='https://pytba.readthedocs.io/en/latest/index.html'>Official documentation</a></h2>
+<h2><a href='https://pytba.readthedocs.io/ru/latest/index.html'>Official ru documentation</a></h2>
+	
 ## Contents
 
   * [Getting started](#getting-started)
@@ -52,7 +56,7 @@
     * [Logging](#logging)
     * [Proxy](#proxy)
     * [Testing](#testing)
-  * [API conformance](#api-conformance)
+  * [API conformance limitations](#api-conformance-limitations)
   * [AsyncTeleBot](#asynctelebot)
   * [F.A.Q.](#faq)
     * [How can I distinguish a User and a GroupChat in message.chat?](#how-can-i-distinguish-a-user-and-a-groupchat-in-messagechat)
@@ -60,14 +64,15 @@
   * [The Telegram Chat Group](#the-telegram-chat-group)
   * [Telegram Channel](#telegram-channel)
   * [More examples](#more-examples)
-  * [Bots using this API](#bots-using-this-api)
+  * [Code Template](#code-template)
+  * [Bots using this library](#bots-using-this-library)
 
 ## Getting started
 
-This API is tested with Python 3.6-3.10 and Pypy 3.
+This API is tested with Python 3.7-3.11 and Pypy 3.
 There are two ways to install the library:
 
-* Installation using pip (a Python package manager)*:
+* Installation using pip (a Python package manager):
 
 ```
 $ pip install pyTelegramBotAPI
@@ -79,10 +84,17 @@ $ git clone https://github.com/eternnoir/pyTelegramBotAPI.git
 $ cd pyTelegramBotAPI
 $ python setup.py install
 ```
+or:
+```
+$ pip install git+https://github.com/eternnoir/pyTelegramBotAPI.git
+```
 
 It is generally recommended to use the first option.
 
-**While the API is production-ready, it is still under development and it has regular updates, do not forget to update it regularly by calling `pip install pytelegrambotapi --upgrade`*
+*While the API is production-ready, it is still under development and it has regular updates, do not forget to update it regularly by calling*
+```
+pip install pytelegrambotapi --upgrade
+```
 
 ## Writing your first bot
 
@@ -153,7 +165,7 @@ To start the bot, simply open up a terminal and enter `python echo_bot.py` to ru
 All types are defined in types.py. They are all completely in line with the [Telegram API's definition of the types](https://core.telegram.org/bots/api#available-types), except for the Message's `from` field, which is renamed to `from_user` (because `from` is a Python reserved token). Thus, attributes such as `message_id` can be accessed directly with `message.message_id`. Note that `message.chat` can be either an instance of `User` or `GroupChat` (see [How can I distinguish a User and a GroupChat in message.chat?](#how-can-i-distinguish-a-user-and-a-groupchat-in-messagechat)).
 
 The Message object also has a `content_type`attribute, which defines the type of the Message. `content_type` can be one of the following strings:
-`text`, `audio`, `document`, `photo`, `sticker`, `video`, `video_note`, `voice`, `location`, `contact`, `new_chat_members`, `left_chat_member`, `new_chat_title`, `new_chat_photo`, `delete_chat_photo`, `group_chat_created`, `supergroup_chat_created`, `channel_chat_created`, `migrate_to_chat_id`, `migrate_from_chat_id`, `pinned_message`.
+`text`, `audio`, `document`, `photo`, `sticker`, `video`, `video_note`, `voice`, `location`, `contact`, `new_chat_members`, `left_chat_member`, `new_chat_title`, `new_chat_photo`, `delete_chat_photo`, `group_chat_created`, `supergroup_chat_created`, `channel_chat_created`, `migrate_to_chat_id`, `migrate_from_chat_id`, `pinned_message`, `web_app_data`.
 
 You can use some types in one function. Example:
 
@@ -253,7 +265,7 @@ def test_callback(call): # <- passes a CallbackQuery type object to your functio
 
 #### Shipping Query Handler
 Handle shipping queries
-`@bot.shipping_query_handeler() # <- passes a ShippingQuery type object to your function`
+`@bot.shipping_query_handler() # <- passes a ShippingQuery type object to your function`
 
 #### Pre Checkout Query Handler
 Handle pre checkoupt queries
@@ -344,7 +356,27 @@ def start(message):
     assert message.another_text == message.text + ':changed'
 ```
 There are other examples using middleware handler in the [examples/middleware](examples/middleware) directory.
-	
+
+#### Class-based middlewares
+There are class-based middlewares. 
+Basic class-based middleware looks like this:
+```python
+class Middleware(BaseMiddleware):
+    def __init__(self):
+        self.update_types = ['message']
+    def pre_process(self, message, data):
+        data['foo'] = 'Hello' # just for example
+        # we edited the data. now, this data is passed to handler.
+        # return SkipHandler() -> this will skip handler
+        # return CancelUpdate() -> this will cancel update
+    def post_process(self, message, data, exception=None):
+        print(data['foo'])
+        if exception: # check for exception
+            print(exception)
+```
+Class-based middleware should have to functions: post and pre process.
+So, as you can see, class-based middlewares work before and after handler execution.
+For more, check out in [examples](https://github.com/eternnoir/pyTelegramBotAPI/tree/master/examples/middleware/class_based)	
 	
 #### Custom filters
 Also, you can use built-in custom filters. Or, you can create your own filter.	
@@ -366,7 +398,7 @@ Here is example of creating filter-class:
 ```python
 class IsAdmin(telebot.custom_filters.SimpleCustomFilter):
     # Class will check whether the user is admin or creator in group or not
-    key='is_admin'
+    key='is_chat_admin'
     @staticmethod
     def check(message: telebot.types.Message):
         return bot.get_chat_member(message.chat.id,message.from_user.id).status in ['administrator','creator']
@@ -375,7 +407,7 @@ class IsAdmin(telebot.custom_filters.SimpleCustomFilter):
 bot.add_custom_filter(IsAdmin())
 	
 # Now, you can use it in handler.
-@bot.message_handler(is_admin=True)
+@bot.message_handler(is_chat_admin=True)
 def admin_of_group(message):
 	bot.send_message(message.chat.id, 'You are admin of this group!')
 
@@ -642,6 +674,8 @@ telebot.logger.setLevel(logging.DEBUG) # Outputs debug messages to console.
 ```
 
 ### Proxy
+For sync:
+
 You can use proxy for request. `apihelper.proxy` object will use by call `requests` proxies argument.
 
 ```python
@@ -656,6 +690,14 @@ If you want to use socket5 proxy you need install dependency `pip install reques
 apihelper.proxy = {'https':'socks5://userproxy:password@proxy_address:port'}
 ```
 
+For async:
+```python
+from telebot import asyncio_helper
+
+asyncio_helper.proxy = 'http://127.0.0.1:3128' #url
+```
+
+
 ### Testing
 You can disable or change the interaction with real Telegram server by using
 ```python
@@ -684,25 +726,10 @@ Result will be:
 
 
 
-## API conformance
-
-* ✔ [Bot API 5.6](https://core.telegram.org/bots/api#december-30-2021)
-* ✔ [Bot API 5.5](https://core.telegram.org/bots/api#december-7-2021)
-* ✔ [Bot API 5.4](https://core.telegram.org/bots/api#november-5-2021)
-* ➕ [Bot API 5.3](https://core.telegram.org/bots/api#june-25-2021) - ChatMember* classes are full copies of ChatMember
-* ✔ [Bot API 5.2](https://core.telegram.org/bots/api#april-26-2021)
-* ✔ [Bot API 5.1](https://core.telegram.org/bots/api#march-9-2021)
-* ✔ [Bot API 5.0](https://core.telegram.org/bots/api-changelog#november-4-2020)
-* ✔ [Bot API 4.9](https://core.telegram.org/bots/api-changelog#june-4-2020)
-* ✔ [Bot API 4.8](https://core.telegram.org/bots/api-changelog#april-24-2020)
-* ✔ [Bot API 4.7](https://core.telegram.org/bots/api-changelog#march-30-2020)
-* ✔ [Bot API 4.6](https://core.telegram.org/bots/api-changelog#january-23-2020)
+## API conformance limitations
 * ➕ [Bot API 4.5](https://core.telegram.org/bots/api-changelog#december-31-2019) - No nested MessageEntities and Markdown2 support
-* ✔ [Bot API 4.4](https://core.telegram.org/bots/api-changelog#july-29-2019)
-* ✔ [Bot API 4.3](https://core.telegram.org/bots/api-changelog#may-31-2019)
-* ✔ [Bot API 4.2](https://core.telegram.org/bots/api-changelog#april-14-2019)
-* ➕ [Bot API 4.1](https://core.telegram.org/bots/api-changelog#august-27-2018) - No Passport support
-* ➕ [Bot API 4.0](https://core.telegram.org/bots/api-changelog#july-26-2018)   - No Passport support
+* ➕ [Bot API 4.1](https://core.telegram.org/bots/api-changelog#august-27-2018)   - No Passport support
+* ➕ [Bot API 4.0](https://core.telegram.org/bots/api-changelog#july-26-2018)     - No Passport support
 
 
 ## AsyncTeleBot
@@ -746,10 +773,10 @@ As you can see here, keywords are await and async.
 Asynchronous tasks depend on processor performance. Many asynchronous tasks can run parallelly, while thread tasks will block each other.
 
 ### Differences in AsyncTeleBot
-AsyncTeleBot has different middlewares. See example on [middlewares](https://github.com/coder2020official/pyTelegramBotAPI/tree/master/examples/asynchronous_telebot/middleware)
+AsyncTeleBot is asynchronous. It uses aiohttp instead of requests module.
 	
 ### Examples
-See more examples in our [examples](https://github.com/coder2020official/pyTelegramBotAPI/tree/master/examples/asynchronous_telebot) folder
+See more examples in our [examples](https://github.com/eternnoir/pyTelegramBotAPI/tree/master/examples/asynchronous_telebot) folder
 	
 
 ## F.A.Q.
@@ -758,7 +785,6 @@ See more examples in our [examples](https://github.com/coder2020official/pyTeleg
 Telegram Bot API support new type Chat for message.chat.
 
 - Check the ```type``` attribute in ```Chat``` object:
--
 ```python
 if message.chat.type == "private":
     # private chat message
@@ -794,7 +820,15 @@ Join the [News channel](https://t.me/pyTelegramBotAPI). Here we will post releas
 * [Deep Linking](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/deep_linking.py)
 * [next_step_handler Example](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/step_example.py)
 
-## Bots using this API
+## Code Template
+Template is a ready folder that contains architecture of basic project.
+Here are some examples of template:
+	
+* [AsyncTeleBot template](https://github.com/coder2020official/asynctelebot_template)
+* [TeleBot template](https://github.com/coder2020official/telebot_template)
+	
+	
+## Bots using this library
 * [SiteAlert bot](https://telegram.me/SiteAlert_bot) ([source](https://github.com/ilteoood/SiteAlert-Python)) by *ilteoood* - Monitors websites and sends a notification on changes
 * [TelegramLoggingBot](https://github.com/aRandomStranger/TelegramLoggingBot) by *aRandomStranger*
 * [Telegram LMGTFY_bot](https://github.com/GabrielRF/telegram-lmgtfy_bot) by *GabrielRF* - Let me Google that for you.
@@ -843,5 +877,20 @@ Join the [News channel](https://t.me/pyTelegramBotAPI). Here we will post releas
 * [GrandQuiz Bot](https://github.com/Carlosma7/TFM-GrandQuiz) by [Carlosma7](https://github.com/Carlosma7). This bot is a trivia game that allows you to play with people from different ages. This project addresses the use of a system through chatbots to carry out a social and intergenerational game as an alternative to traditional game development.
 * [Diccionario de la RAE](https://t.me/dleraebot) ([source](https://github.com/studentenherz/dleraebot)) This bot lets you find difinitions of words in Spanish using [RAE's dictionary](https://dle.rae.es/). It features direct message and inline search.
 * [remoteTelegramShell](https://github.com/EnriqueMoran/remoteTelegramShell) by [EnriqueMoran](https://github.com/EnriqueMoran). Control your LinuxOS computer through Telegram.
-	
+* [Commerce Telegram Bot](https://github.com/ayitinya/commerce-telegram-bot/). Make purchases of items in a store with an Admin panel for data control and notifications.
+* [Pyfram-telegram-bot](https://github.com/skelly37/pyfram-telegram-bot) Query wolframalpha.com and make use of its API through Telegram.
+* [TranslateThisVideoBot](https://gitlab.com/WuerfelDev/translatethisvideo) This Bot can understand spoken text in videos and translate it to English
+* [Zyprexa](https://t.me/mathemathicsBot) ([source](https://github.com/atif5/zyprexa)) Zyprexa can solve, help you solve any mathematical problem you encounter and convert your regular mathematical expressions into beautiful imagery using LaTeX.
+* [Bincode-telegram-bot](https://github.com/tusharhero/bincode-telegram-bot) by [tusharhero](https://github.com/tusharhero) - Makes [bincodes](https://github.com/tusharhero/bincode) from text provides and also converts them back to text.
+* [hydrolib_bot](https://github.com/Mayson90/hydrolib_bot) Toolset for Hydrophilia tabletop game (game cards, rules, structure...).
+* [Gugumoe-bot](http://t.me/gugumoe_bot) ([source](https://github.com/GooGuJiang/Gugumoe-bot)) by [咕谷酱](https://gmoe.cc) GuXiaoJiang is a multi-functional robot, such as OSU game information query, IP test, animation screenshot search and other functions.
+* [Feedback-bot](https://github.com/coder2020official/feedbackbot) A feedback bot for user-admin communication. Made on AsyncTeleBot, using [template](https://github.com/coder2020official/asynctelebot_template).
+* [TeleServ](https://github.com/ablakely/TeleServ) by [ablakely](https://github.com/ablakely) This is a Telegram to IRC bridge which links as an IRC server and makes Telegram users appear as native IRC users.
+* [Simple Store Bot](https://github.com/AntonGlyzin/myshopbot) by [Anton Glyzin](https://github.com/AntonGlyzin) This is a simple telegram-store with an admin panel. Designed according to a template.
+* [Media Rating Bot](https://t.me/mediaratingbot) ([source](https://github.com/CommanderCRM/MediaRatingBot))by [CommanderCRM](https://github.com/CommanderCRM). This bot aggregates media (movies, TV series, etc.) ratings from IMDb, Rotten Tomatoes, Metacritic, TheMovieDB, FilmAffinity and also provides number of votes of said media on IMDb. 
+* [Spot Seek Bot](https://t.me/SpotSeekBot) ([source](https://github.com/arashnm80/spot-seek-bot)) by [Arashnm80](https://github.com/arashnm80). This is a free & open source telegram bot for downloading tracks, albums or playlists from spotify.
+* [CalendarIT Bot](https://t.me/calendarit_bot) ([source](https://github.com/codebyzen/CalendarIT_Telegram_Bot))by [CodeByZen](https://github.com/codebyzen). A simple, but extensible Python Telegram bot, can post acquainted with what is happening today, tomorrow or what happened 20 years ago to channel. 
+* [DownloadMusicBOT](https://github.com/fcoagz/DownloadMusicBOT) by *Francisco Griman* - It is a simple bot that downloads audio from YouTube videos on Telegram.
+* [AwesomeChatGPTBot](https://github.com/Kourva/AwesomeChatGPTBot) - Simple ChatGTP-3.5 bot. It is FREE and can remember chat history for a while With pre-defined roles!
+
 **Want to have your bot listed here? Just make a pull request. Only bots with public source code are accepted.**

doc_req.txt

@@ -0,0 +1,5 @@
+-r requirements.txt
+
+furo
+sphinx_copybutton
+git+https://github.com/eternnoir/pyTelegramBotAPI.git

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/async_version/index.rst

@@ -0,0 +1,48 @@
+====================
+AsyncTeleBot
+====================
+
+
+.. meta::
+   :description: Asynchronous pyTelegramBotAPI
+   :keywords: ptba, pytba, pyTelegramBotAPI, asynctelebot, documentation
+
+
+AsyncTeleBot methods
+--------------------
+
+.. automodule:: telebot.async_telebot
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+
+Asyncio filters
+---------------
+
+.. automodule:: telebot.asyncio_filters
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Asyncio handler backends
+------------------------
+
+
+
+.. automodule:: telebot.asyncio_handler_backends
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Extensions
+------------------------
+
+
+
+.. automodule:: telebot.ext.aio.webhooks
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/calldata.rst

@@ -0,0 +1,17 @@
+
+=====================
+Callback data factory
+=====================
+
+.. meta::
+   :description: Callback data factory in pyTelegramBotAPI
+   :keywords: ptba, pytba, pyTelegramBotAPI, callbackdatafactory, guide, callbackdata, factory
+
+
+callback\_data file
+-----------------------------
+
+.. automodule:: telebot.callback_data
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/conf.py

@@ -0,0 +1,72 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'pyTelegramBotAPI Documentation'
+copyright = '2022-2023, coder2020official'
+author = 'coder2020official'
+
+# The full version, including alpha/beta/rc tags
+release = '4.12.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.autodoc',
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+    
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'furo'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+#html_logo = 'logo.png'
+html_theme_options = {
+    "light_css_variables": {
+        "color-brand-primary": "#7C4DFF",
+        "color-brand-content": "#7C4DFF",
+    },
+    "light_logo": "logo.png",
+    "dark_logo": "logo2.png",
+}
+
+locale_dirs = ["locales/"]

docs/source/formatting.rst

@@ -0,0 +1,12 @@
+==================
+Formatting options
+==================
+
+.. meta::
+   :description: Formatting options in pyTelegramBotAPI
+   :keywords: html, markdown, parse_mode, formatting, ptba, pytba, pyTelegramBotAPI
+
+.. automodule:: telebot.formatting
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/index.rst

@@ -0,0 +1,69 @@
+.. pyTelegramBotAPI documentation master file, created by
+   sphinx-quickstart on Fri Feb 18 20:58:37 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+
+Welcome to pyTelegramBotAPI's documentation!
+============================================
+
+.. meta::
+   :description: Official documentation of pyTelegramBotAPI
+   :keywords: ptba, pytba, pyTelegramBotAPI, documentation, guide
+
+
+=======
+TeleBot
+=======
+TeleBot is synchronous and asynchronous implementation of  `Telegram Bot API <https://core.telegram.org/bots/api>`_.
+
+Chats
+-----
+English chat: `Private chat <https://telegram.me/joinchat/Bn4ixj84FIZVkwhk2jag6A>`__
+
+Russian chat: `@pytelegrambotapi_talks_ru <https://t.me/pytelegrambotapi_talks_ru>`__
+
+News: `@pyTelegramBotAPI <https://t.me/pytelegrambotapi>`__
+
+Pypi: `Pypi <https://pypi.org/project/pyTelegramBotAPI/>`__
+
+Source: `Github repository <https://github.com/eternnoir/pyTelegramBotAPI>`__
+
+Some features:
+--------------
+Easy to learn and use.
+
+Easy to understand.
+
+Both sync and async.
+
+Examples on features.
+
+States
+
+And more...
+
+Content
+--------
+.. toctree::
+
+   install
+   quick_start
+   types
+   sync_version/index
+   async_version/index
+   calldata
+   util
+   formatting
+
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+   

docs/source/install.rst

@@ -0,0 +1,45 @@
+==================
+Installation Guide
+==================
+
+.. meta::
+   :description: Installation of pyTelegramBotAPI
+   :keywords: ptba, pytba, pyTelegramBotAPI, installation, guide
+
+
+Using PIP
+----------
+.. code-block:: bash
+
+    $ pip install pyTelegramBotAPI
+
+Using pipenv
+------------
+.. code-block:: bash
+
+    $ pipenv install pyTelegramBotAPI
+
+By cloning repository
+---------------------
+.. code-block:: bash
+
+    $ git clone https://github.com/eternnoir/pyTelegramBotAPI.git
+    $ cd pyTelegramBotAPI
+    $ python setup.py install
+
+Directly using pip
+------------------
+.. code-block:: bash
+
+    $ pip install git+https://github.com/eternnoir/pyTelegramBotAPI.git
+
+
+It is generally recommended to use the first option.
+
+While the API is production-ready, it is still under development and it has regular updates, do not forget to update it regularly by calling:
+
+.. code-block:: bash
+
+    $ pip install pytelegrambotapi --upgrade
+
+

docs/source/locales/en/LC_MESSAGES/calldata.po

@@ -0,0 +1,127 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2022-11-29 14:44+0400\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../calldata.rst:4
+msgid "Callback data factory"
+msgstr ""
+
+#: ../../calldata.rst:6
+msgid "Callback data factory in pyTelegramBotAPI"
+msgstr ""
+
+#: ../../calldata.rst:6
+msgid ""
+"ptba, pytba, pyTelegramBotAPI, callbackdatafactory, guide, callbackdata, "
+"factory"
+msgstr ""
+
+#: ../../calldata.rst:12
+msgid "callback\\_data file"
+msgstr ""
+
+#: of telebot.callback_data:1
+msgid "Callback data factory's file."
+msgstr ""
+
+#: of telebot.callback_data.CallbackData:1
+#: telebot.callback_data.CallbackDataFilter:1
+msgid "Bases: :py:class:`object`"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData:1
+msgid "Callback data factory This class will help you to work with CallbackQuery"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.filter:1
+msgid "Generate filter"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.filter
+#: telebot.callback_data.CallbackData.new
+#: telebot.callback_data.CallbackData.parse
+#: telebot.callback_data.CallbackDataFilter.check
+msgid "Parameters"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.filter:3
+msgid "specified named parameters will be checked with CallbackQuery.data"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.filter
+#: telebot.callback_data.CallbackData.new
+#: telebot.callback_data.CallbackData.parse
+#: telebot.callback_data.CallbackDataFilter.check
+msgid "Returns"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.filter:4
+msgid "CallbackDataFilter class"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.new:1
+msgid "Generate callback data"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.new:3
+msgid "positional parameters of CallbackData instance parts"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.new:4
+msgid "named parameters"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.new:5
+msgid "str"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.parse:1
+msgid "Parse data from the callback data"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.parse:3
+msgid ""
+"string, use to telebot.types.CallbackQuery to parse it from string to a "
+"dict"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.parse:4
+msgid "dict parsed from callback data"
+msgstr ""
+
+#: of telebot.callback_data.CallbackDataFilter:1
+msgid "Filter for CallbackData."
+msgstr ""
+
+#: of telebot.callback_data.CallbackDataFilter.check:1
+msgid "Checks if query.data appropriates to specified config"
+msgstr ""
+
+#: of telebot.callback_data.CallbackDataFilter.check:3
+msgid "telebot.types.CallbackQuery"
+msgstr ""
+
+#: of telebot.callback_data.CallbackDataFilter.check:6
+msgid "True if query.data appropriates to specified config"
+msgstr ""
+
+#: of telebot.callback_data.CallbackDataFilter.check
+msgid "Return type"
+msgstr ""
+

docs/source/locales/en/LC_MESSAGES/formatting.po

@@ -0,0 +1,251 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2022-11-29 14:44+0400\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../formatting.rst:3
+msgid "Formatting options"
+msgstr ""
+
+#: ../../formatting.rst:5
+msgid "Formatting options in pyTelegramBotAPI"
+msgstr ""
+
+#: ../../formatting.rst:5
+msgid "html, markdown, parse_mode, formatting, ptba, pytba, pyTelegramBotAPI"
+msgstr ""
+
+#: of telebot.formatting:1
+msgid "Markdown & HTML formatting functions."
+msgstr ""
+
+#: of telebot.formatting.escape_html:1
+msgid "Escapes HTML characters in a string of HTML."
+msgstr ""
+
+#: of telebot.formatting.escape_html telebot.formatting.escape_markdown
+#: telebot.formatting.format_text telebot.formatting.hbold
+#: telebot.formatting.hcode telebot.formatting.hide_link
+#: telebot.formatting.hitalic telebot.formatting.hlink telebot.formatting.hpre
+#: telebot.formatting.hspoiler telebot.formatting.hstrikethrough
+#: telebot.formatting.hunderline telebot.formatting.mbold
+#: telebot.formatting.mcode telebot.formatting.mitalic telebot.formatting.mlink
+#: telebot.formatting.mspoiler telebot.formatting.mstrikethrough
+#: telebot.formatting.munderline
+msgid "Parameters"
+msgstr ""
+
+#: of telebot.formatting.escape_html:3
+msgid "The string of HTML to escape."
+msgstr ""
+
+#: of telebot.formatting.escape_html telebot.formatting.escape_markdown
+#: telebot.formatting.format_text telebot.formatting.hbold
+#: telebot.formatting.hcode telebot.formatting.hide_link
+#: telebot.formatting.hitalic telebot.formatting.hlink telebot.formatting.hpre
+#: telebot.formatting.hspoiler telebot.formatting.hstrikethrough
+#: telebot.formatting.hunderline telebot.formatting.mbold
+#: telebot.formatting.mcode telebot.formatting.mitalic telebot.formatting.mlink
+#: telebot.formatting.mspoiler telebot.formatting.mstrikethrough
+#: telebot.formatting.munderline
+msgid "Returns"
+msgstr ""
+
+#: of telebot.formatting.escape_html:6 telebot.formatting.escape_markdown:8
+msgid "The escaped string."
+msgstr ""
+
+#: of telebot.formatting.escape_html telebot.formatting.escape_markdown
+#: telebot.formatting.format_text telebot.formatting.hbold
+#: telebot.formatting.hcode telebot.formatting.hide_link
+#: telebot.formatting.hitalic telebot.formatting.hlink telebot.formatting.hpre
+#: telebot.formatting.hspoiler telebot.formatting.hstrikethrough
+#: telebot.formatting.hunderline telebot.formatting.mbold
+#: telebot.formatting.mcode telebot.formatting.mitalic telebot.formatting.mlink
+#: telebot.formatting.mspoiler telebot.formatting.mstrikethrough
+#: telebot.formatting.munderline
+msgid "Return type"
+msgstr ""
+
+#: of telebot.formatting.escape_html:7 telebot.formatting.escape_markdown:9
+#: telebot.formatting.format_text:17 telebot.formatting.hbold:10
+#: telebot.formatting.hcode:10 telebot.formatting.hide_link:7
+#: telebot.formatting.hitalic:10 telebot.formatting.hlink:13
+#: telebot.formatting.hpre:10 telebot.formatting.hspoiler:10
+#: telebot.formatting.hstrikethrough:10 telebot.formatting.hunderline:10
+#: telebot.formatting.mbold:10 telebot.formatting.mcode:10
+#: telebot.formatting.mitalic:10 telebot.formatting.mlink:13
+#: telebot.formatting.mspoiler:10 telebot.formatting.mstrikethrough:10
+#: telebot.formatting.munderline:10
+msgid ":obj:`str`"
+msgstr ""
+
+#: of telebot.formatting.escape_markdown:1
+msgid "Escapes Markdown characters in a string of Markdown."
+msgstr ""
+
+#: of telebot.formatting.escape_markdown:3
+msgid "Credits to: simonsmh"
+msgstr ""
+
+#: of telebot.formatting.escape_markdown:5
+msgid "The string of Markdown to escape."
+msgstr ""
+
+#: of telebot.formatting.format_text:1
+msgid "Formats a list of strings into a single string."
+msgstr ""
+
+#: of telebot.formatting.format_text:10
+msgid "Strings to format."
+msgstr ""
+
+#: of telebot.formatting.format_text:13
+msgid "The separator to use between each string."
+msgstr ""
+
+#: of telebot.formatting.format_text:16 telebot.formatting.hbold:9
+#: telebot.formatting.hcode:9 telebot.formatting.hitalic:9
+#: telebot.formatting.hlink:12 telebot.formatting.hpre:9
+#: telebot.formatting.hspoiler:9 telebot.formatting.hstrikethrough:9
+#: telebot.formatting.hunderline:9 telebot.formatting.mbold:9
+#: telebot.formatting.mcode:9 telebot.formatting.mitalic:9
+#: telebot.formatting.mlink:12 telebot.formatting.mspoiler:9
+#: telebot.formatting.mstrikethrough:9 telebot.formatting.munderline:9
+msgid "The formatted string."
+msgstr ""
+
+#: of telebot.formatting.hbold:1
+msgid "Returns an HTML-formatted bold string."
+msgstr ""
+
+#: of telebot.formatting.hbold:3 telebot.formatting.mbold:3
+msgid "The string to bold."
+msgstr ""
+
+#: of telebot.formatting.hbold:6 telebot.formatting.hcode:6
+#: telebot.formatting.hitalic:6 telebot.formatting.hlink:9
+#: telebot.formatting.hpre:6 telebot.formatting.hspoiler:6
+#: telebot.formatting.hstrikethrough:6 telebot.formatting.hunderline:6
+#: telebot.formatting.mbold:6 telebot.formatting.mcode:6
+#: telebot.formatting.mitalic:6 telebot.formatting.mlink:9
+#: telebot.formatting.mspoiler:6 telebot.formatting.mstrikethrough:6
+#: telebot.formatting.munderline:6
+msgid "True if you need to escape special characters. Defaults to True."
+msgstr ""
+
+#: of telebot.formatting.hcode:1
+msgid "Returns an HTML-formatted code string."
+msgstr ""
+
+#: of telebot.formatting.hcode:3 telebot.formatting.mcode:3
+msgid "The string to code."
+msgstr ""
+
+#: of telebot.formatting.hide_link:1
+msgid "Hide url of an image."
+msgstr ""
+
+#: of telebot.formatting.hide_link:3
+msgid "The url of the image."
+msgstr ""
+
+#: of telebot.formatting.hide_link:6
+msgid "The hidden url."
+msgstr ""
+
+#: of telebot.formatting.hitalic:1
+msgid "Returns an HTML-formatted italic string."
+msgstr ""
+
+#: of telebot.formatting.hitalic:3 telebot.formatting.mitalic:3
+msgid "The string to italicize."
+msgstr ""
+
+#: of telebot.formatting.hlink:1
+msgid "Returns an HTML-formatted link string."
+msgstr ""
+
+#: of telebot.formatting.hlink:3 telebot.formatting.mlink:3
+msgid "The string to link."
+msgstr ""
+
+#: of telebot.formatting.hlink:6 telebot.formatting.mlink:6
+msgid "The URL to link to."
+msgstr ""
+
+#: of telebot.formatting.hpre:1
+msgid "Returns an HTML-formatted preformatted string."
+msgstr ""
+
+#: of telebot.formatting.hpre:3
+msgid "The string to preformatted."
+msgstr ""
+
+#: of telebot.formatting.hspoiler:1
+msgid "Returns an HTML-formatted spoiler string."
+msgstr ""
+
+#: of telebot.formatting.hspoiler:3 telebot.formatting.mspoiler:3
+msgid "The string to spoiler."
+msgstr ""
+
+#: of telebot.formatting.hstrikethrough:1
+msgid "Returns an HTML-formatted strikethrough string."
+msgstr ""
+
+#: of telebot.formatting.hstrikethrough:3 telebot.formatting.mstrikethrough:3
+msgid "The string to strikethrough."
+msgstr ""
+
+#: of telebot.formatting.hunderline:1
+msgid "Returns an HTML-formatted underline string."
+msgstr ""
+
+#: of telebot.formatting.hunderline:3 telebot.formatting.munderline:3
+msgid "The string to underline."
+msgstr ""
+
+#: of telebot.formatting.mbold:1
+msgid "Returns a Markdown-formatted bold string."
+msgstr ""
+
+#: of telebot.formatting.mcode:1
+msgid "Returns a Markdown-formatted code string."
+msgstr ""
+
+#: of telebot.formatting.mitalic:1
+msgid "Returns a Markdown-formatted italic string."
+msgstr ""
+
+#: of telebot.formatting.mlink:1
+msgid "Returns a Markdown-formatted link string."
+msgstr ""
+
+#: of telebot.formatting.mspoiler:1
+msgid "Returns a Markdown-formatted spoiler string."
+msgstr ""
+
+#: of telebot.formatting.mstrikethrough:1
+msgid "Returns a Markdown-formatted strikethrough string."
+msgstr ""
+
+#: of telebot.formatting.munderline:1
+msgid "Returns a Markdown-formatted underline string."
+msgstr ""
+

docs/source/locales/en/LC_MESSAGES/index.po

@@ -0,0 +1,120 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2022-11-29 14:44+0400\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../index.rst:8
+msgid "Welcome to pyTelegramBotAPI's documentation!"
+msgstr ""
+
+#: ../../index.rst:10
+msgid "Official documentation of pyTelegramBotAPI"
+msgstr ""
+
+#: ../../index.rst:10
+msgid "ptba, pytba, pyTelegramBotAPI, documentation, guide"
+msgstr ""
+
+#: ../../index.rst:17
+msgid "TeleBot"
+msgstr ""
+
+#: ../../index.rst:18
+msgid ""
+"TeleBot is synchronous and asynchronous implementation of  `Telegram Bot "
+"API <https://core.telegram.org/bots/api>`_."
+msgstr ""
+
+#: ../../index.rst:21
+msgid "Chats"
+msgstr ""
+
+#: ../../index.rst:22
+msgid ""
+"English chat: `Private chat "
+"<https://telegram.me/joinchat/Bn4ixj84FIZVkwhk2jag6A>`__"
+msgstr ""
+
+#: ../../index.rst:24
+msgid ""
+"Russian chat: `@pytelegrambotapi_talks_ru "
+"<https://t.me/pytelegrambotapi_talks_ru>`__"
+msgstr ""
+
+#: ../../index.rst:26
+msgid "News: `@pyTelegramBotAPI <https://t.me/pytelegrambotapi>`__"
+msgstr ""
+
+#: ../../index.rst:28
+msgid "Pypi: `Pypi <https://pypi.org/project/pyTelegramBotAPI/>`__"
+msgstr ""
+
+#: ../../index.rst:30
+msgid ""
+"Source: `Github repository "
+"<https://github.com/eternnoir/pyTelegramBotAPI>`__"
+msgstr ""
+
+#: ../../index.rst:33
+msgid "Some features:"
+msgstr ""
+
+#: ../../index.rst:34
+msgid "Easy to learn and use."
+msgstr ""
+
+#: ../../index.rst:36
+msgid "Easy to understand."
+msgstr ""
+
+#: ../../index.rst:38
+msgid "Both sync and async."
+msgstr ""
+
+#: ../../index.rst:40
+msgid "Examples on features."
+msgstr ""
+
+#: ../../index.rst:42
+msgid "States"
+msgstr ""
+
+#: ../../index.rst:44
+msgid "And more..."
+msgstr ""
+
+#: ../../index.rst:47
+msgid "Content"
+msgstr ""
+
+#: ../../index.rst:63
+msgid "Indices and tables"
+msgstr ""
+
+#: ../../index.rst:65
+msgid ":ref:`genindex`"
+msgstr ""
+
+#: ../../index.rst:66
+msgid ":ref:`modindex`"
+msgstr ""
+
+#: ../../index.rst:67
+msgid ":ref:`search`"
+msgstr ""
+

docs/source/locales/en/LC_MESSAGES/install.po

@@ -0,0 +1,58 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2022-11-29 14:44+0400\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../install.rst:3
+msgid "Installation Guide"
+msgstr ""
+
+#: ../../install.rst:5
+msgid "Installation of pyTelegramBotAPI"
+msgstr ""
+
+#: ../../install.rst:5
+msgid "ptba, pytba, pyTelegramBotAPI, installation, guide"
+msgstr ""
+
+#: ../../install.rst:11
+msgid "Using PIP"
+msgstr ""
+
+#: ../../install.rst:17
+msgid "Using pipenv"
+msgstr ""
+
+#: ../../install.rst:23
+msgid "By cloning repository"
+msgstr ""
+
+#: ../../install.rst:31
+msgid "Directly using pip"
+msgstr ""
+
+#: ../../install.rst:37
+msgid "It is generally recommended to use the first option."
+msgstr ""
+
+#: ../../install.rst:39
+msgid ""
+"While the API is production-ready, it is still under development and it "
+"has regular updates, do not forget to update it regularly by calling:"
+msgstr ""
+

docs/source/locales/en/LC_MESSAGES/quick_start.po

@@ -0,0 +1,40 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2022-11-29 14:44+0400\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../quick_start.rst:4
+msgid "Quick start"
+msgstr ""
+
+#: ../../quick_start.rst:6
+msgid "Quickstart guide"
+msgstr ""
+
+#: ../../quick_start.rst:6
+msgid "ptba, pytba, pyTelegramBotAPI, quickstart, guide"
+msgstr ""
+
+#: ../../quick_start.rst:11
+msgid "Synchronous TeleBot"
+msgstr ""
+
+#: ../../quick_start.rst:16
+msgid "Asynchronous TeleBot"
+msgstr ""
+

docs/source/locales/en/LC_MESSAGES/util.po

@@ -0,0 +1,355 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2023-07-08 23:07+0500\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../source/util.rst:3
+msgid "Utils"
+msgstr ""
+
+#: ../../source/util.rst:5
+msgid "Utils in pyTelegramBotAPI"
+msgstr ""
+
+#: ../../source/util.rst:5
+msgid "ptba, pytba, pyTelegramBotAPI, utils, guide"
+msgstr ""
+
+#: ../../source/util.rst:11
+msgid "util file"
+msgstr ""
+
+#: of telebot.util.antiflood:1
+msgid ""
+"Use this function inside loops in order to avoid getting TooManyRequests "
+"error. Example:"
+msgstr ""
+
+#: of telebot.service_utils.is_bytes telebot.service_utils.is_dict
+#: telebot.service_utils.is_pil_image telebot.util.antiflood
+#: telebot.util.escape telebot.util.extract_arguments
+#: telebot.util.extract_command telebot.util.is_command
+#: telebot.util.parse_web_app_data telebot.util.quick_markup
+#: telebot.util.smart_split telebot.util.split_string telebot.util.user_link
+#: telebot.util.validate_web_app_data telebot.util.webhook_google_functions
+msgid "Parameters"
+msgstr ""
+
+#: of telebot.util.antiflood:10
+msgid "The function to call"
+msgstr ""
+
+#: of telebot.util.antiflood:13
+msgid "Number of retries to send"
+msgstr ""
+
+#: of telebot.util.antiflood:16
+msgid "The arguments to pass to the function"
+msgstr ""
+
+#: of telebot.util.antiflood:19
+msgid "The keyword arguments to pass to the function"
+msgstr ""
+
+#: of telebot.service_utils.generate_random_token
+#: telebot.service_utils.is_bytes telebot.service_utils.is_dict
+#: telebot.service_utils.is_pil_image telebot.util.antiflood
+#: telebot.util.escape telebot.util.extract_arguments
+#: telebot.util.extract_command telebot.util.is_command
+#: telebot.util.parse_web_app_data telebot.util.quick_markup
+#: telebot.util.smart_split telebot.util.split_string telebot.util.user_link
+#: telebot.util.validate_web_app_data telebot.util.webhook_google_functions
+msgid "Returns"
+msgstr ""
+
+#: of telebot.util.antiflood:22
+msgid "None"
+msgstr ""
+
+#: of telebot.service_utils.chunks:1
+msgid "Yield successive n-sized chunks from lst."
+msgstr ""
+
+#: ../../docstring of telebot.util.content_type_media:1
+msgid "Contains all media content types."
+msgstr ""
+
+#: ../../docstring of telebot.util.content_type_service:1
+msgid "Contains all service content types such as `User joined the group`."
+msgstr ""
+
+#: of telebot.util.escape:1
+msgid ""
+"Replaces the following chars in `text` ('&' with '&amp;', '<' with '&lt;'"
+" and '>' with '&gt;')."
+msgstr ""
+
+#: of telebot.util.escape:3
+msgid "the text to escape"
+msgstr ""
+
+#: of telebot.util.escape:4
+msgid "the escaped text"
+msgstr ""
+
+#: of telebot.util.extract_arguments:1
+msgid "Returns the argument after the command."
+msgstr ""
+
+#: of telebot.util.extract_arguments:3 telebot.util.extract_command:4
+msgid "Examples:"
+msgstr ""
+
+#: of telebot.util.extract_arguments:10
+msgid "String to extract the arguments from a command"
+msgstr ""
+
+#: of telebot.util.extract_arguments:13
+msgid "the arguments if `text` is a command (according to is_command), else None."
+msgstr ""
+
+#: of telebot.service_utils.generate_random_token
+#: telebot.service_utils.is_bytes telebot.service_utils.is_dict
+#: telebot.service_utils.is_pil_image telebot.util.extract_arguments
+#: telebot.util.extract_command telebot.util.is_command
+#: telebot.util.quick_markup telebot.util.smart_split telebot.util.split_string
+#: telebot.util.user_link
+msgid "Return type"
+msgstr ""
+
+#: of telebot.util.extract_arguments:14 telebot.util.extract_command:16
+msgid ":obj:`str` or :obj:`None`"
+msgstr ""
+
+#: of telebot.util.extract_command:1
+msgid ""
+"Extracts the command from `text` (minus the '/') if `text` is a command "
+"(see is_command). If `text` is not a command, this function returns None."
+msgstr ""
+
+#: of telebot.util.extract_command:12
+msgid "String to extract the command from"
+msgstr ""
+
+#: of telebot.util.extract_command:15
+msgid "the command if `text` is a command (according to is_command), else None."
+msgstr ""
+
+#: of telebot.service_utils.generate_random_token:1
+msgid ""
+"Generates a random token consisting of letters and digits, 16 characters "
+"long."
+msgstr ""
+
+#: of telebot.service_utils.generate_random_token:3
+msgid "a random token"
+msgstr ""
+
+#: of telebot.service_utils.generate_random_token:4 telebot.util.user_link:22
+msgid ":obj:`str`"
+msgstr ""
+
+#: of telebot.service_utils.is_bytes:1
+msgid "Returns True if the given object is a bytes object."
+msgstr ""
+
+#: of telebot.service_utils.is_bytes:3 telebot.service_utils.is_dict:3
+#: telebot.service_utils.is_pil_image:3
+msgid "object to be checked"
+msgstr ""
+
+#: of telebot.service_utils.is_bytes:6
+msgid "True if the given object is a bytes object."
+msgstr ""
+
+#: of telebot.service_utils.is_bytes:7 telebot.service_utils.is_dict:7
+#: telebot.service_utils.is_pil_image:7 telebot.util.is_command:7
+msgid ":obj:`bool`"
+msgstr ""
+
+#: of telebot.util.is_command:1
+msgid ""
+"Checks if `text` is a command. Telegram chat commands start with the '/' "
+"character."
+msgstr ""
+
+#: of telebot.util.is_command:3
+msgid "Text to check."
+msgstr ""
+
+#: of telebot.util.is_command:6
+msgid "True if `text` is a command, else False."
+msgstr ""
+
+#: of telebot.service_utils.is_dict:1
+msgid "Returns True if the given object is a dictionary."
+msgstr ""
+
+#: of telebot.service_utils.is_dict:6
+msgid "True if the given object is a dictionary."
+msgstr ""
+
+#: of telebot.service_utils.is_pil_image:1
+msgid "Returns True if the given object is a PIL.Image.Image object."
+msgstr ""
+
+#: of telebot.service_utils.is_pil_image:6
+msgid "True if the given object is a PIL.Image.Image object."
+msgstr ""
+
+#: of telebot.service_utils.is_string:1
+msgid "Returns True if the given object is a string."
+msgstr ""
+
+#: of telebot.util.parse_web_app_data:1
+msgid "Parses web app data."
+msgstr ""
+
+#: of telebot.util.parse_web_app_data:3 telebot.util.validate_web_app_data:3
+msgid "The bot token"
+msgstr ""
+
+#: of telebot.util.parse_web_app_data:6 telebot.util.validate_web_app_data:6
+msgid "The raw init data"
+msgstr ""
+
+#: of telebot.util.parse_web_app_data:9 telebot.util.validate_web_app_data:9
+msgid "The parsed init data"
+msgstr ""
+
+#: of telebot.util.quick_markup:1
+msgid ""
+"Returns a reply markup from a dict in this format: {'text': kwargs} This "
+"is useful to avoid always typing 'btn1 = InlineKeyboardButton(...)' 'btn2"
+" = InlineKeyboardButton(...)'"
+msgstr ""
+
+#: of telebot.util.quick_markup:4 telebot.util.user_link:5
+msgid "Example:"
+msgstr ""
+
+#: of telebot.util.quick_markup:6
+msgid "Using quick_markup:"
+msgstr ""
+
+#: of telebot.util.quick_markup:31
+msgid ""
+"a dict containing all buttons to create in this format: {text: kwargs} "
+"{str:}"
+msgstr ""
+
+#: of telebot.util.quick_markup:34
+msgid "number of :class:`telebot.types.InlineKeyboardButton` objects on each row"
+msgstr ""
+
+#: of telebot.util.quick_markup:37
+msgid "InlineKeyboardMarkup"
+msgstr ""
+
+#: of telebot.util.quick_markup:38
+msgid ":obj:`types.InlineKeyboardMarkup`"
+msgstr ""
+
+#: of telebot.util.smart_split:1
+msgid ""
+"Splits one string into multiple strings, with a maximum amount of "
+"`chars_per_string` characters per string. This is very useful for "
+"splitting one giant message into multiples. If `chars_per_string` > 4096:"
+" `chars_per_string` = 4096. Splits by '\\n', '. ' or ' ' in exactly this "
+"priority."
+msgstr ""
+
+#: of telebot.util.smart_split:6 telebot.util.split_string:4
+msgid "The text to split"
+msgstr ""
+
+#: of telebot.util.smart_split:9
+msgid "The number of maximum characters per part the text is split to."
+msgstr ""
+
+#: of telebot.util.smart_split:12 telebot.util.split_string:10
+msgid "The splitted text as a list of strings."
+msgstr ""
+
+#: of telebot.util.smart_split:13 telebot.util.split_string:11
+msgid ":obj:`list` of :obj:`str`"
+msgstr ""
+
+#: of telebot.util.split_string:1
+msgid ""
+"Splits one string into multiple strings, with a maximum amount of "
+"`chars_per_string` characters per string. This is very useful for "
+"splitting one giant message into multiples."
+msgstr ""
+
+#: of telebot.util.split_string:7
+msgid "The number of characters per line the text is split into."
+msgstr ""
+
+#: ../../docstring of telebot.util.update_types:1
+msgid "All update types, should be used for allowed_updates parameter in polling."
+msgstr ""
+
+#: of telebot.util.user_link:1
+msgid ""
+"Returns an HTML user link. This is useful for reports. Attention: Don't "
+"forget to set parse_mode to 'HTML'!"
+msgstr ""
+
+#: of telebot.util.user_link:11
+msgid ""
+"You can use formatting.* for all other formatting options(bold, italic, "
+"links, and etc.) This method is kept for backward compatibility, and it "
+"is recommended to use formatting.* for more options."
+msgstr ""
+
+#: of telebot.util.user_link:15
+msgid "the user (not the user_id)"
+msgstr ""
+
+#: of telebot.util.user_link:18
+msgid "include the user_id"
+msgstr ""
+
+#: of telebot.util.user_link:21
+msgid "HTML user link"
+msgstr ""
+
+#: of telebot.util.validate_web_app_data:1
+msgid "Validates web app data."
+msgstr ""
+
+#: of telebot.util.webhook_google_functions:1
+msgid "A webhook endpoint for Google Cloud Functions FaaS."
+msgstr ""
+
+#: of telebot.util.webhook_google_functions:3
+msgid "The bot instance"
+msgstr ""
+
+#: of telebot.util.webhook_google_functions:6
+msgid "The request object"
+msgstr ""
+
+#: of telebot.util.webhook_google_functions:9
+msgid "The response object"
+msgstr ""
+
+#~ msgid "int row width"
+#~ msgstr ""
+

docs/source/locales/ru/LC_MESSAGES/calldata.po

@@ -0,0 +1,130 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2022-11-29 14:44+0400\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../calldata.rst:4
+msgid "Callback data factory"
+msgstr "Фабрика callback data"
+
+#: ../../calldata.rst:6
+msgid "Callback data factory in pyTelegramBotAPI"
+msgstr "Фабрика callback data в pyTelegramBotAPI"
+
+#: ../../calldata.rst:6
+msgid ""
+"ptba, pytba, pyTelegramBotAPI, callbackdatafactory, guide, callbackdata, "
+"factory"
+msgstr ""
+"ptba, pytba, pyTelegramBotAPI, callbackdatafactory, гайд, callbackdata, "
+"фабрика"
+
+#: ../../calldata.rst:12
+msgid "callback\\_data file"
+msgstr "Файл callback\\_data"
+
+#: of telebot.callback_data:1
+msgid "Callback data factory's file."
+msgstr "Файл фабрики callback data."
+
+#: of telebot.callback_data.CallbackData:1
+#: telebot.callback_data.CallbackDataFilter:1
+msgid "Bases: :py:class:`object`"
+msgstr "Базовые классы: :py:class:`object`"
+
+#: of telebot.callback_data.CallbackData:1
+msgid "Callback data factory This class will help you to work with CallbackQuery"
+msgstr "Фабрика Callback data. Этот класс поможет вам в работе с CallbackQuery"
+
+#: of telebot.callback_data.CallbackData.filter:1
+msgid "Generate filter"
+msgstr "Сгенерировать фильтр"
+
+#: of telebot.callback_data.CallbackData.filter
+#: telebot.callback_data.CallbackData.new
+#: telebot.callback_data.CallbackData.parse
+#: telebot.callback_data.CallbackDataFilter.check
+msgid "Parameters"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.filter:3
+msgid "specified named parameters will be checked with CallbackQuery.data"
+msgstr "заданные именованные параметры будут проверены в CallbackQuery.data"
+
+#: of telebot.callback_data.CallbackData.filter
+#: telebot.callback_data.CallbackData.new
+#: telebot.callback_data.CallbackData.parse
+#: telebot.callback_data.CallbackDataFilter.check
+msgid "Returns"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.filter:4
+msgid "CallbackDataFilter class"
+msgstr "Класс CallbackDataFilter"
+
+#: of telebot.callback_data.CallbackData.new:1
+msgid "Generate callback data"
+msgstr "Сгенерировать callback data"
+
+#: of telebot.callback_data.CallbackData.new:3
+msgid "positional parameters of CallbackData instance parts"
+msgstr "позиционные параметры экземпляра CallbackData"
+
+#: of telebot.callback_data.CallbackData.new:4
+msgid "named parameters"
+msgstr "именованные параметры"
+
+#: of telebot.callback_data.CallbackData.new:5
+msgid "str"
+msgstr ""
+
+#: of telebot.callback_data.CallbackData.parse:1
+msgid "Parse data from the callback data"
+msgstr "Получить данные из callback data"
+
+#: of telebot.callback_data.CallbackData.parse:3
+msgid ""
+"string, use to telebot.types.CallbackQuery to parse it from string to a "
+"dict"
+msgstr ""
+"string, примените к telebot.types.CallbackQuery, чтобы преобразовать "
+"callback_data из строки (str) в словарь (dict)"
+
+#: of telebot.callback_data.CallbackData.parse:4
+msgid "dict parsed from callback data"
+msgstr "словарь (dict), полученный из callback data"
+
+#: of telebot.callback_data.CallbackDataFilter:1
+msgid "Filter for CallbackData."
+msgstr "Фильтр для CallbackData."
+
+#: of telebot.callback_data.CallbackDataFilter.check:1
+msgid "Checks if query.data appropriates to specified config"
+msgstr "Проверяет, соответствует ли query.data заданной конфигурации"
+
+#: of telebot.callback_data.CallbackDataFilter.check:3
+msgid "telebot.types.CallbackQuery"
+msgstr ""
+
+#: of telebot.callback_data.CallbackDataFilter.check:6
+msgid "True if query.data appropriates to specified config"
+msgstr "True, если query.data соответствует заданной конфигурации"
+
+#: of telebot.callback_data.CallbackDataFilter.check
+msgid "Return type"
+msgstr ""

docs/source/locales/ru/LC_MESSAGES/formatting.po

@@ -0,0 +1,251 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2022-11-29 14:44+0400\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../formatting.rst:3
+msgid "Formatting options"
+msgstr "Параметры форматирования"
+
+#: ../../formatting.rst:5
+msgid "Formatting options in pyTelegramBotAPI"
+msgstr "Параметры форматирования в pyTelegramBotAPI"
+
+#: ../../formatting.rst:5
+msgid "html, markdown, parse_mode, formatting, ptba, pytba, pyTelegramBotAPI"
+msgstr "html, markdown, parse_mode, форматирование, ptba, pytba, pyTelegramBotAPI"
+
+#: of telebot.formatting:1
+msgid "Markdown & HTML formatting functions."
+msgstr "Функции форматирования Markdown & HTML."
+
+#: of telebot.formatting.escape_html:1
+msgid "Escapes HTML characters in a string of HTML."
+msgstr "Пропускает HTML символы в HTML строке."
+
+#: of telebot.formatting.escape_html telebot.formatting.escape_markdown
+#: telebot.formatting.format_text telebot.formatting.hbold
+#: telebot.formatting.hcode telebot.formatting.hide_link
+#: telebot.formatting.hitalic telebot.formatting.hlink telebot.formatting.hpre
+#: telebot.formatting.hspoiler telebot.formatting.hstrikethrough
+#: telebot.formatting.hunderline telebot.formatting.mbold
+#: telebot.formatting.mcode telebot.formatting.mitalic telebot.formatting.mlink
+#: telebot.formatting.mspoiler telebot.formatting.mstrikethrough
+#: telebot.formatting.munderline
+msgid "Parameters"
+msgstr ""
+
+#: of telebot.formatting.escape_html:3
+msgid "The string of HTML to escape."
+msgstr "HTML строка, которую нужно пропустить."
+
+#: of telebot.formatting.escape_html telebot.formatting.escape_markdown
+#: telebot.formatting.format_text telebot.formatting.hbold
+#: telebot.formatting.hcode telebot.formatting.hide_link
+#: telebot.formatting.hitalic telebot.formatting.hlink telebot.formatting.hpre
+#: telebot.formatting.hspoiler telebot.formatting.hstrikethrough
+#: telebot.formatting.hunderline telebot.formatting.mbold
+#: telebot.formatting.mcode telebot.formatting.mitalic telebot.formatting.mlink
+#: telebot.formatting.mspoiler telebot.formatting.mstrikethrough
+#: telebot.formatting.munderline
+msgid "Returns"
+msgstr ""
+
+#: of telebot.formatting.escape_html:6 telebot.formatting.escape_markdown:8
+msgid "The escaped string."
+msgstr "Пропускаемая строка."
+
+#: of telebot.formatting.escape_html telebot.formatting.escape_markdown
+#: telebot.formatting.format_text telebot.formatting.hbold
+#: telebot.formatting.hcode telebot.formatting.hide_link
+#: telebot.formatting.hitalic telebot.formatting.hlink telebot.formatting.hpre
+#: telebot.formatting.hspoiler telebot.formatting.hstrikethrough
+#: telebot.formatting.hunderline telebot.formatting.mbold
+#: telebot.formatting.mcode telebot.formatting.mitalic telebot.formatting.mlink
+#: telebot.formatting.mspoiler telebot.formatting.mstrikethrough
+#: telebot.formatting.munderline
+msgid "Return type"
+msgstr ""
+
+#: of telebot.formatting.escape_html:7 telebot.formatting.escape_markdown:9
+#: telebot.formatting.format_text:17 telebot.formatting.hbold:10
+#: telebot.formatting.hcode:10 telebot.formatting.hide_link:7
+#: telebot.formatting.hitalic:10 telebot.formatting.hlink:13
+#: telebot.formatting.hpre:10 telebot.formatting.hspoiler:10
+#: telebot.formatting.hstrikethrough:10 telebot.formatting.hunderline:10
+#: telebot.formatting.mbold:10 telebot.formatting.mcode:10
+#: telebot.formatting.mitalic:10 telebot.formatting.mlink:13
+#: telebot.formatting.mspoiler:10 telebot.formatting.mstrikethrough:10
+#: telebot.formatting.munderline:10
+msgid ":obj:`str`"
+msgstr ""
+
+#: of telebot.formatting.escape_markdown:1
+msgid "Escapes Markdown characters in a string of Markdown."
+msgstr "Пропускает Markdown символы в Markdown строке."
+
+#: of telebot.formatting.escape_markdown:3
+msgid "Credits to: simonsmh"
+msgstr ""
+
+#: of telebot.formatting.escape_markdown:5
+msgid "The string of Markdown to escape."
+msgstr "Markdown строка, которую нужно пропустить."
+
+#: of telebot.formatting.format_text:1
+msgid "Formats a list of strings into a single string."
+msgstr "Преобразовывает набор строк в одну."
+
+#: of telebot.formatting.format_text:10
+msgid "Strings to format."
+msgstr "Строки для преобразования."
+
+#: of telebot.formatting.format_text:13
+msgid "The separator to use between each string."
+msgstr "Символ для разделения строк."
+
+#: of telebot.formatting.format_text:16 telebot.formatting.hbold:9
+#: telebot.formatting.hcode:9 telebot.formatting.hitalic:9
+#: telebot.formatting.hlink:12 telebot.formatting.hpre:9
+#: telebot.formatting.hspoiler:9 telebot.formatting.hstrikethrough:9
+#: telebot.formatting.hunderline:9 telebot.formatting.mbold:9
+#: telebot.formatting.mcode:9 telebot.formatting.mitalic:9
+#: telebot.formatting.mlink:12 telebot.formatting.mspoiler:9
+#: telebot.formatting.mstrikethrough:9 telebot.formatting.munderline:9
+msgid "The formatted string."
+msgstr "Преобразованная строка."
+
+#: of telebot.formatting.hbold:1
+msgid "Returns an HTML-formatted bold string."
+msgstr "Возвращает выделенную жирным шрифтом HTML строку."
+
+#: of telebot.formatting.hbold:3 telebot.formatting.mbold:3
+msgid "The string to bold."
+msgstr "Строка для выделения жирным шрифтом."
+
+#: of telebot.formatting.hbold:6 telebot.formatting.hcode:6
+#: telebot.formatting.hitalic:6 telebot.formatting.hlink:9
+#: telebot.formatting.hpre:6 telebot.formatting.hspoiler:6
+#: telebot.formatting.hstrikethrough:6 telebot.formatting.hunderline:6
+#: telebot.formatting.mbold:6 telebot.formatting.mcode:6
+#: telebot.formatting.mitalic:6 telebot.formatting.mlink:9
+#: telebot.formatting.mspoiler:6 telebot.formatting.mstrikethrough:6
+#: telebot.formatting.munderline:6
+msgid "True if you need to escape special characters. Defaults to True."
+msgstr "True если вам нужно пропустить спец. символы. По умолчанию True."
+
+#: of telebot.formatting.hcode:1
+msgid "Returns an HTML-formatted code string."
+msgstr "Возвращает выделенную как код HTML строку."
+
+#: of telebot.formatting.hcode:3 telebot.formatting.mcode:3
+msgid "The string to code."
+msgstr "Строка для выделения как код."
+
+#: of telebot.formatting.hide_link:1
+msgid "Hide url of an image."
+msgstr "Делает невидимым URL изображения."
+
+#: of telebot.formatting.hide_link:3
+msgid "The url of the image."
+msgstr "URL изображения."
+
+#: of telebot.formatting.hide_link:6
+msgid "The hidden url."
+msgstr "Невидимый URL."
+
+#: of telebot.formatting.hitalic:1
+msgid "Returns an HTML-formatted italic string."
+msgstr "Возвращает выделенную курсивом HTML строку."
+
+#: of telebot.formatting.hitalic:3 telebot.formatting.mitalic:3
+msgid "The string to italicize."
+msgstr "Строка для выделения курсивом."
+
+#: of telebot.formatting.hlink:1
+msgid "Returns an HTML-formatted link string."
+msgstr "Возвращает HTML строку с гиперссылкой."
+
+#: of telebot.formatting.hlink:3 telebot.formatting.mlink:3
+msgid "The string to link."
+msgstr "Строка для добавления гиперссылки."
+
+#: of telebot.formatting.hlink:6 telebot.formatting.mlink:6
+msgid "The URL to link to."
+msgstr "URL для создания гиперссылки."
+
+#: of telebot.formatting.hpre:1
+msgid "Returns an HTML-formatted preformatted string."
+msgstr "Возвращает предварительно отформатированную HTML строку."
+
+#: of telebot.formatting.hpre:3
+msgid "The string to preformatted."
+msgstr "Строка для предварительного форматирования."
+
+#: of telebot.formatting.hspoiler:1
+msgid "Returns an HTML-formatted spoiler string."
+msgstr "Возвращает выделенную как спойлер HTML строку."
+
+#: of telebot.formatting.hspoiler:3 telebot.formatting.mspoiler:3
+msgid "The string to spoiler."
+msgstr "Строка для выделения как спойлер."
+
+#: of telebot.formatting.hstrikethrough:1
+msgid "Returns an HTML-formatted strikethrough string."
+msgstr "Возвращает зачеркнутую HTML строку."
+
+#: of telebot.formatting.hstrikethrough:3 telebot.formatting.mstrikethrough:3
+msgid "The string to strikethrough."
+msgstr "Строка для зачеркивания."
+
+#: of telebot.formatting.hunderline:1
+msgid "Returns an HTML-formatted underline string."
+msgstr "Возвращает подчеркнутую HTML строку."
+
+#: of telebot.formatting.hunderline:3 telebot.formatting.munderline:3
+msgid "The string to underline."
+msgstr "Строка для подчёркивания."
+
+#: of telebot.formatting.mbold:1
+msgid "Returns a Markdown-formatted bold string."
+msgstr "Возвращает выделенную жирным шрифтом Markdown строку."
+
+#: of telebot.formatting.mcode:1
+msgid "Returns a Markdown-formatted code string."
+msgstr "Возвращает выделенную как код Markdown строку."
+
+#: of telebot.formatting.mitalic:1
+msgid "Returns a Markdown-formatted italic string."
+msgstr "Возвращает выделенную курсивом Markdown строку."
+
+#: of telebot.formatting.mlink:1
+msgid "Returns a Markdown-formatted link string."
+msgstr "Возвращает Markdown строку с гиперссылкой."
+
+#: of telebot.formatting.mspoiler:1
+msgid "Returns a Markdown-formatted spoiler string."
+msgstr "Возвращает выделенную как спойлер Markdown строку."
+
+#: of telebot.formatting.mstrikethrough:1
+msgid "Returns a Markdown-formatted strikethrough string."
+msgstr "Возвращает зачеркнутую Markdown строку."
+
+#: of telebot.formatting.munderline:1
+msgid "Returns a Markdown-formatted underline string."
+msgstr "Возвращает подчеркнутую Markdown строку."
+

docs/source/locales/ru/LC_MESSAGES/index.po

@@ -0,0 +1,128 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2022-11-29 14:44+0400\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../index.rst:8
+msgid "Welcome to pyTelegramBotAPI's documentation!"
+msgstr "Добро пожаловать в документацию pyTelegramBotAPI!"
+
+#: ../../index.rst:10
+msgid "Official documentation of pyTelegramBotAPI"
+msgstr "Официальная документация pyTelegramBotAPI"
+
+#: ../../index.rst:10
+msgid "ptba, pytba, pyTelegramBotAPI, documentation, guide"
+msgstr "ptba, pytba, pyTelegramBotAPI, документация, гайд"
+
+#: ../../index.rst:17
+msgid "TeleBot"
+msgstr ""
+
+#: ../../index.rst:18
+msgid ""
+"TeleBot is synchronous and asynchronous implementation of  `Telegram Bot "
+"API <https://core.telegram.org/bots/api>`_."
+msgstr ""
+"TeleBot это синхронная и асинхронная реализация `Telegram Bot "
+"API <https://core.telegram.org/bots/api>`_."
+
+#: ../../index.rst:21
+msgid "Chats"
+msgstr "Чаты"
+
+#: ../../index.rst:22
+msgid ""
+"English chat: `Private chat "
+"<https://telegram.me/joinchat/Bn4ixj84FIZVkwhk2jag6A>`__"
+msgstr ""
+"Англоязычный чат: `Private chat "
+"<https://telegram.me/joinchat/Bn4ixj84FIZVkwhk2jag6A>`__"
+
+#: ../../index.rst:24
+msgid ""
+"Russian chat: `@pytelegrambotapi_talks_ru "
+"<https://t.me/pytelegrambotapi_talks_ru>`__"
+msgstr ""
+"Русскоязычный чат: `@pytelegrambotapi_talks_ru "
+"<https://t.me/pytelegrambotapi_talks_ru>`__"
+
+#: ../../index.rst:26
+msgid "News: `@pyTelegramBotAPI <https://t.me/pytelegrambotapi>`__"
+msgstr "Новости: `@pyTelegramBotAPI <https://t.me/pytelegrambotapi>`__"
+
+#: ../../index.rst:28
+msgid "Pypi: `Pypi <https://pypi.org/project/pyTelegramBotAPI/>`__"
+msgstr ""
+
+#: ../../index.rst:30
+msgid ""
+"Source: `Github repository "
+"<https://github.com/eternnoir/pyTelegramBotAPI>`__"
+msgstr ""
+"Исходники: `Github repository "
+"<https://github.com/eternnoir/pyTelegramBotAPI>`__"
+
+#: ../../index.rst:33
+msgid "Some features:"
+msgstr "Некоторые особенности:"
+
+#: ../../index.rst:34
+msgid "Easy to learn and use."
+msgstr "Простой в изучении и использовании."
+
+#: ../../index.rst:36
+msgid "Easy to understand."
+msgstr "Простой в понимании."
+
+#: ../../index.rst:38
+msgid "Both sync and async."
+msgstr "И синхронный, и асинхронный."
+
+#: ../../index.rst:40
+msgid "Examples on features."
+msgstr "Примеры возможностей."
+
+#: ../../index.rst:42
+msgid "States"
+msgstr "Состояния (стейты, FSM)"
+
+#: ../../index.rst:44
+msgid "And more..."
+msgstr "И другое..."
+
+#: ../../index.rst:47
+msgid "Content"
+msgstr "Содержимое"
+
+#: ../../index.rst:63
+msgid "Indices and tables"
+msgstr "Ссылки"
+
+#: ../../index.rst:65
+msgid ":ref:`genindex`"
+msgstr ""
+
+#: ../../index.rst:66
+msgid ":ref:`modindex`"
+msgstr ""
+
+#: ../../index.rst:67
+msgid ":ref:`search`"
+msgstr ""
+

docs/source/locales/ru/LC_MESSAGES/install.po

@@ -0,0 +1,59 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2022-11-29 14:44+0400\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../install.rst:3
+msgid "Installation Guide"
+msgstr "Гайд по установке"
+
+#: ../../install.rst:5
+msgid "Installation of pyTelegramBotAPI"
+msgstr "Установка pyTelegramBotAPI"
+
+#: ../../install.rst:5
+msgid "ptba, pytba, pyTelegramBotAPI, installation, guide"
+msgstr "ptba, pytba, pyTelegramBotAPI, установка, гайд"
+
+#: ../../install.rst:11
+msgid "Using PIP"
+msgstr "Используя PIP"
+
+#: ../../install.rst:17
+msgid "Using pipenv"
+msgstr "Используя pipenv"
+
+#: ../../install.rst:23
+msgid "By cloning repository"
+msgstr "Клонируя репозиторий"
+
+#: ../../install.rst:31
+msgid "Directly using pip"
+msgstr "Напрямую используя pip"
+
+#: ../../install.rst:37
+msgid "It is generally recommended to use the first option."
+msgstr "Рекомендуется использовать первый вариант."
+
+#: ../../install.rst:39
+msgid ""
+"While the API is production-ready, it is still under development and it "
+"has regular updates, do not forget to update it regularly by calling:"
+msgstr "Новые версии библиотеки имеют больше фич, улучшений и баг фиксов. Не забывайте"
+" обновляться вызывая:"
+

docs/source/locales/ru/LC_MESSAGES/quick_start.po

@@ -0,0 +1,40 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2022-11-29 14:44+0400\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../quick_start.rst:4
+msgid "Quick start"
+msgstr "Быстрый старт"
+
+#: ../../quick_start.rst:6
+msgid "Quickstart guide"
+msgstr "Быстрый старт - гайд"
+
+#: ../../quick_start.rst:6
+msgid "ptba, pytba, pyTelegramBotAPI, quickstart, guide"
+msgstr "ptba, pytba, pyTelegramBotAPI, быстрый старт, гайд"
+
+#: ../../quick_start.rst:11
+msgid "Synchronous TeleBot"
+msgstr "Синхронный телебот"
+
+#: ../../quick_start.rst:16
+msgid "Asynchronous TeleBot"
+msgstr "Асинхронный телебот"
+

docs/source/locales/ru/LC_MESSAGES/util.po

@@ -0,0 +1,393 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2022, coder2020official
+# This file is distributed under the same license as the pyTelegramBotAPI
+# Documentation package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pyTelegramBotAPI Documentation \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2023-07-08 23:07+0500\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: ../../source/util.rst:3
+msgid "Utils"
+msgstr "Утилиты"
+
+#: ../../source/util.rst:5
+msgid "Utils in pyTelegramBotAPI"
+msgstr "Утилиты в pyTelegramBotAPI"
+
+#: ../../source/util.rst:5
+msgid "ptba, pytba, pyTelegramBotAPI, utils, guide"
+msgstr "ptba, pytba, pyTelegramBotAPI, утилиты, гайд"
+
+#: ../../source/util.rst:11
+msgid "util file"
+msgstr "Файл util"
+
+#: of telebot.util.antiflood:1
+msgid ""
+"Use this function inside loops in order to avoid getting TooManyRequests "
+"error. Example:"
+msgstr ""
+"Используйте эту функцию в циклах, чтобы избежать ошибки TooManyRequests. "
+"Пример:"
+
+#: of telebot.service_utils.is_bytes telebot.service_utils.is_dict
+#: telebot.service_utils.is_pil_image telebot.util.antiflood
+#: telebot.util.escape telebot.util.extract_arguments
+#: telebot.util.extract_command telebot.util.is_command
+#: telebot.util.parse_web_app_data telebot.util.quick_markup
+#: telebot.util.smart_split telebot.util.split_string telebot.util.user_link
+#: telebot.util.validate_web_app_data telebot.util.webhook_google_functions
+msgid "Parameters"
+msgstr ""
+
+#: of telebot.util.antiflood:10
+msgid "The function to call"
+msgstr "Вызываемая функция"
+
+#: of telebot.util.antiflood:13
+msgid "Number of retries to send"
+msgstr ""
+
+#: of telebot.util.antiflood:16
+msgid "The arguments to pass to the function"
+msgstr "Аргументы, для передачи в функцию"
+
+#: of telebot.util.antiflood:19
+msgid "The keyword arguments to pass to the function"
+msgstr "Именованные аргументы для передачи в функцию"
+
+#: of telebot.service_utils.generate_random_token
+#: telebot.service_utils.is_bytes telebot.service_utils.is_dict
+#: telebot.service_utils.is_pil_image telebot.util.antiflood
+#: telebot.util.escape telebot.util.extract_arguments
+#: telebot.util.extract_command telebot.util.is_command
+#: telebot.util.parse_web_app_data telebot.util.quick_markup
+#: telebot.util.smart_split telebot.util.split_string telebot.util.user_link
+#: telebot.util.validate_web_app_data telebot.util.webhook_google_functions
+msgid "Returns"
+msgstr ""
+
+#: of telebot.util.antiflood:22
+msgid "None"
+msgstr ""
+
+#: of telebot.service_utils.chunks:1
+msgid "Yield successive n-sized chunks from lst."
+msgstr "Генерирует последовательные части списка, состоящие из n элементов."
+
+#: ../../docstring of telebot.util.content_type_media:1
+msgid "Contains all media content types."
+msgstr "Содержит все виды медиа."
+
+#: ../../docstring of telebot.util.content_type_service:1
+msgid "Contains all service content types such as `User joined the group`."
+msgstr "Содержит все виды сервисных сообщений, такие как `User joined the group`."
+
+#: of telebot.util.escape:1
+msgid ""
+"Replaces the following chars in `text` ('&' with '&amp;', '<' with '&lt;'"
+" and '>' with '&gt;')."
+msgstr ""
+"Заменяет следующие символы в `text` ('&' на '&amp;', '<' на '&lt;' и '>' "
+"на '&gt;')."
+
+#: of telebot.util.escape:3
+msgid "the text to escape"
+msgstr "Текст для замены символов"
+
+#: of telebot.util.escape:4
+msgid "the escaped text"
+msgstr "Отформатированный текст"
+
+#: of telebot.util.extract_arguments:1
+msgid "Returns the argument after the command."
+msgstr "Возвращает аргументы команды."
+
+#: of telebot.util.extract_arguments:3 telebot.util.extract_command:4
+msgid "Examples:"
+msgstr "Примеры:"
+
+#: of telebot.util.extract_arguments:10
+msgid "String to extract the arguments from a command"
+msgstr "Строка для извлечения аргументов команды"
+
+#: of telebot.util.extract_arguments:13
+msgid "the arguments if `text` is a command (according to is_command), else None."
+msgstr ""
+"Аргументы, если `text` является командой (согласно is_command), в "
+"остальных случаях None."
+
+#: of telebot.service_utils.generate_random_token
+#: telebot.service_utils.is_bytes telebot.service_utils.is_dict
+#: telebot.service_utils.is_pil_image telebot.util.extract_arguments
+#: telebot.util.extract_command telebot.util.is_command
+#: telebot.util.quick_markup telebot.util.smart_split telebot.util.split_string
+#: telebot.util.user_link
+msgid "Return type"
+msgstr ""
+
+#: of telebot.util.extract_arguments:14 telebot.util.extract_command:16
+msgid ":obj:`str` or :obj:`None`"
+msgstr ":obj:`str` или :obj:`None`"
+
+#: of telebot.util.extract_command:1
+msgid ""
+"Extracts the command from `text` (minus the '/') if `text` is a command "
+"(see is_command). If `text` is not a command, this function returns None."
+msgstr ""
+"Извлекает команду из `text` (исключает '/') если `text` является командой"
+" (см. is_command). Если `text` не является командой, эта функция "
+"возвращает None."
+
+#: of telebot.util.extract_command:12
+msgid "String to extract the command from"
+msgstr "Строка, из которой нужно извлечь команду"
+
+#: of telebot.util.extract_command:15
+msgid "the command if `text` is a command (according to is_command), else None."
+msgstr ""
+"Команда, если `text` является командой (согласно is_command), в остальных"
+" случаях None."
+
+#: of telebot.service_utils.generate_random_token:1
+msgid ""
+"Generates a random token consisting of letters and digits, 16 characters "
+"long."
+msgstr ""
+"Генерирует рандомный токен, состоящий из латинских букв и цифр длиной 16 "
+"символов."
+
+#: of telebot.service_utils.generate_random_token:3
+msgid "a random token"
+msgstr "Сгенерированный токен"
+
+#: of telebot.service_utils.generate_random_token:4 telebot.util.user_link:22
+msgid ":obj:`str`"
+msgstr ""
+
+#: of telebot.service_utils.is_bytes:1
+msgid "Returns True if the given object is a bytes object."
+msgstr "Возвращает True если полученный объект является bytes."
+
+#: of telebot.service_utils.is_bytes:3 telebot.service_utils.is_dict:3
+#: telebot.service_utils.is_pil_image:3
+msgid "object to be checked"
+msgstr "Объект для проверки"
+
+#: of telebot.service_utils.is_bytes:6
+msgid "True if the given object is a bytes object."
+msgstr "True, если полученный объект является bytes."
+
+#: of telebot.service_utils.is_bytes:7 telebot.service_utils.is_dict:7
+#: telebot.service_utils.is_pil_image:7 telebot.util.is_command:7
+msgid ":obj:`bool`"
+msgstr ""
+
+#: of telebot.util.is_command:1
+msgid ""
+"Checks if `text` is a command. Telegram chat commands start with the '/' "
+"character."
+msgstr ""
+"Проверяет, является ли `text` командой. Команды в Telegram начинаются с "
+"символа '/'."
+
+#: of telebot.util.is_command:3
+msgid "Text to check."
+msgstr "Текст для проверки."
+
+#: of telebot.util.is_command:6
+msgid "True if `text` is a command, else False."
+msgstr "True, если `text` является командой, иначе False."
+
+#: of telebot.service_utils.is_dict:1
+msgid "Returns True if the given object is a dictionary."
+msgstr "Возвращает True, если полученный объект является словарём (dict)."
+
+#: of telebot.service_utils.is_dict:6
+msgid "True if the given object is a dictionary."
+msgstr "True, если полученный объект является словарём (dict)."
+
+#: of telebot.service_utils.is_pil_image:1
+msgid "Returns True if the given object is a PIL.Image.Image object."
+msgstr "Возвращает True, если полученный объект является PIL.Image.Image."
+
+#: of telebot.service_utils.is_pil_image:6
+msgid "True if the given object is a PIL.Image.Image object."
+msgstr "True, если полученный объект является PIL.Image.Image."
+
+#: of telebot.service_utils.is_string:1
+msgid "Returns True if the given object is a string."
+msgstr "Возвращает True, если полученный объект является строкой (str)."
+
+#: of telebot.util.parse_web_app_data:1
+msgid "Parses web app data."
+msgstr "Обрабатывает данные, полученные от web app."
+
+#: of telebot.util.parse_web_app_data:3 telebot.util.validate_web_app_data:3
+msgid "The bot token"
+msgstr "Токен бота"
+
+#: of telebot.util.parse_web_app_data:6 telebot.util.validate_web_app_data:6
+msgid "The raw init data"
+msgstr "Необработанные данные"
+
+#: of telebot.util.parse_web_app_data:9 telebot.util.validate_web_app_data:9
+msgid "The parsed init data"
+msgstr "Обработанные данные"
+
+#: of telebot.util.quick_markup:1
+msgid ""
+"Returns a reply markup from a dict in this format: {'text': kwargs} This "
+"is useful to avoid always typing 'btn1 = InlineKeyboardButton(...)' 'btn2"
+" = InlineKeyboardButton(...)'"
+msgstr ""
+"Возвращает reply markup из словаря следующего формата: {'text': kwargs}. "
+"Удобно использовать вместо постоянного использования 'btn1 = "
+"InlineKeyboardButton(...)' 'btn2 = InlineKeyboardButton(...)'"
+
+#: of telebot.util.quick_markup:4 telebot.util.user_link:5
+msgid "Example:"
+msgstr "Пример:"
+
+#: of telebot.util.quick_markup:6
+msgid "Using quick_markup:"
+msgstr "Используя quick_markup:"
+
+#: of telebot.util.quick_markup:31
+msgid ""
+"a dict containing all buttons to create in this format: {text: kwargs} "
+"{str:}"
+msgstr ""
+"Словарь, содержащий все кнопки для создания reply markup в следующем "
+"формате: {text: kwargs} {str:}"
+
+#: of telebot.util.quick_markup:34
+msgid "number of :class:`telebot.types.InlineKeyboardButton` objects on each row"
+msgstr ""
+
+#: of telebot.util.quick_markup:37
+msgid "InlineKeyboardMarkup"
+msgstr ""
+
+#: of telebot.util.quick_markup:38
+msgid ":obj:`types.InlineKeyboardMarkup`"
+msgstr ""
+
+#: of telebot.util.smart_split:1
+msgid ""
+"Splits one string into multiple strings, with a maximum amount of "
+"`chars_per_string` characters per string. This is very useful for "
+"splitting one giant message into multiples. If `chars_per_string` > 4096:"
+" `chars_per_string` = 4096. Splits by '\\n', '. ' or ' ' in exactly this "
+"priority."
+msgstr ""
+"Разбивает строку на несколько, каждая из которых будет не длиннее "
+"`characters_per_string`. Удобно использовать для разбиения одного "
+"гигантского сообщения на несколько. Если `chars_per_string` > 4096: "
+"`chars_per_string` = 4096. Разбивает строку по '\\n', '. ' или ' ' именно"
+" в таком порядке."
+
+#: of telebot.util.smart_split:6 telebot.util.split_string:4
+msgid "The text to split"
+msgstr "Текст для разбиения"
+
+#: of telebot.util.smart_split:9
+msgid "The number of maximum characters per part the text is split to."
+msgstr ""
+"Максимальное количество символов в части текста, на которые он будет "
+"разбит."
+
+#: of telebot.util.smart_split:12 telebot.util.split_string:10
+msgid "The splitted text as a list of strings."
+msgstr "Список частей разбитого текста."
+
+#: of telebot.util.smart_split:13 telebot.util.split_string:11
+msgid ":obj:`list` of :obj:`str`"
+msgstr ""
+
+#: of telebot.util.split_string:1
+msgid ""
+"Splits one string into multiple strings, with a maximum amount of "
+"`chars_per_string` characters per string. This is very useful for "
+"splitting one giant message into multiples."
+msgstr ""
+"Разбивает одну строку на несколько, каждая из которых будет не длиннее "
+"`characters_per_string`. Удобно использовать для разбиения одного "
+"гигантского сообщения на несколько."
+
+#: of telebot.util.split_string:7
+msgid "The number of characters per line the text is split into."
+msgstr "Количество символов в одной строке, на которые будет разбит текст."
+
+#: ../../docstring of telebot.util.update_types:1
+msgid "All update types, should be used for allowed_updates parameter in polling."
+msgstr ""
+"Все виды апдейтов, рекомендуется использовать в качестве параметра "
+"allowed_updates функции polling."
+
+#: of telebot.util.user_link:1
+msgid ""
+"Returns an HTML user link. This is useful for reports. Attention: Don't "
+"forget to set parse_mode to 'HTML'!"
+msgstr ""
+"Возвращает HTML ссылку на пользователя. Удобно использовать для отчетов. "
+"Важно: Не забудьте установить значение 'HTML' в parse_mode!"
+
+#: of telebot.util.user_link:11
+msgid ""
+"You can use formatting.* for all other formatting options(bold, italic, "
+"links, and etc.) This method is kept for backward compatibility, and it "
+"is recommended to use formatting.* for more options."
+msgstr ""
+"Вы можете использовать formatting.* во всех остальных вариантах "
+"форматирования(bold, italic, links, и прочее). Этот метод сохранён для "
+"обратной совместимости, рекомендуется использовать formatting.* для "
+"большего количества вариантов."
+
+#: of telebot.util.user_link:15
+msgid "the user (not the user_id)"
+msgstr "Пользователь (не id пользователя)"
+
+#: of telebot.util.user_link:18
+msgid "include the user_id"
+msgstr "Добавить id пользователя"
+
+#: of telebot.util.user_link:21
+msgid "HTML user link"
+msgstr "Ссылка на пользователя в формате HTML"
+
+#: of telebot.util.validate_web_app_data:1
+msgid "Validates web app data."
+msgstr "Проверяет данные, полученные от web app."
+
+#: of telebot.util.webhook_google_functions:1
+msgid "A webhook endpoint for Google Cloud Functions FaaS."
+msgstr "Endpoint вебхука для Google Cloud Functions FaaS."
+
+#: of telebot.util.webhook_google_functions:3
+msgid "The bot instance"
+msgstr "Инстанс бота"
+
+#: of telebot.util.webhook_google_functions:6
+msgid "The request object"
+msgstr "HTTP-запрос"
+
+#: of telebot.util.webhook_google_functions:9
+msgid "The response object"
+msgstr "Объект, полученный в качестве ответа"
+
+#~ msgid "int row width"
+#~ msgstr "Количество кнопок в одной строке, int"
+

docs/source/quick_start.rst

@@ -0,0 +1,20 @@
+
+===========
+Quick start
+===========
+
+.. meta::
+   :description: Quickstart guide
+   :keywords: ptba, pytba, pyTelegramBotAPI, quickstart, guide
+
+Synchronous TeleBot
+-------------------
+.. literalinclude:: ../../examples/echo_bot.py
+    :language: python
+
+Asynchronous TeleBot
+--------------------
+.. literalinclude:: ../../examples/asynchronous_telebot/echo_bot.py
+    :language: python
+
+

docs/source/sync_version/index.rst

@@ -0,0 +1,41 @@
+===============
+TeleBot version
+===============
+
+.. meta::
+   :description: Synchronous pyTelegramBotAPI documentation
+   :keywords: ptba, pytba, pyTelegramBotAPI, methods, guide, files, sync
+
+TeleBot methods
+---------------
+.. automodule:: telebot
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+custom_filters file
+------------------------------
+
+.. automodule:: telebot.custom_filters
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+handler_backends file
+--------------------------------
+
+.. automodule:: telebot.handler_backends
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Extensions
+------------------------
+
+
+
+.. automodule:: telebot.ext.sync.webhooks
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/types.rst

@@ -0,0 +1,10 @@
+============
+Types of API
+============
+
+
+
+.. automodule:: telebot.types
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/util.rst

@@ -0,0 +1,16 @@
+============
+Utils
+============
+
+.. meta::
+   :description: Utils in pyTelegramBotAPI
+   :keywords: ptba, pytba, pyTelegramBotAPI, utils, guide
+
+
+util file
+-------------------
+
+.. automodule:: telebot.util
+   :members:
+   :undoc-members:
+   :show-inheritance:

examples/anonymous_bot.py

@@ -9,7 +9,7 @@ import telebot
 from telebot import types
 
 # Initialize bot with your token
-bot = telebot.TeleBot(TOKEN)
+bot = telebot.TeleBot('TOKEN')
 
 # The `users` variable is needed to contain chat ids that are either in the search or in the active dialog, like {chat_id, chat_id}
 users = {}
@@ -47,7 +47,7 @@ def find(message: types.Message):
     if message.chat.id not in users:
         bot.send_message(message.chat.id, 'Finding...')
 
-        if freeid == None:
+        if freeid is None:
             freeid = message.chat.id
         else:
             # Question:

examples/asynchronous_telebot/callback_data_examples/advanced_calendar_example/filters.py

@@ -0,0 +1,26 @@
+from telebot import types
+from telebot.async_telebot import AsyncTeleBot
+from telebot.asyncio_filters import AdvancedCustomFilter
+from telebot.callback_data import CallbackData, CallbackDataFilter
+
+calendar_factory = CallbackData("year", "month", prefix="calendar")
+calendar_zoom = CallbackData("year", prefix="calendar_zoom")
+
+
+class CalendarCallbackFilter(AdvancedCustomFilter):
+    key = 'calendar_config'
+
+    async def check(self, call: types.CallbackQuery, config: CallbackDataFilter):
+        return config.check(query=call)
+
+
+class CalendarZoomCallbackFilter(AdvancedCustomFilter):
+    key = 'calendar_zoom_config'
+
+    async def check(self, call: types.CallbackQuery, config: CallbackDataFilter):
+        return config.check(query=call)
+
+
+def bind_filters(bot: AsyncTeleBot):
+    bot.add_custom_filter(CalendarCallbackFilter())
+    bot.add_custom_filter(CalendarZoomCallbackFilter())

examples/asynchronous_telebot/callback_data_examples/advanced_calendar_example/keyboards.py

@@ -0,0 +1,92 @@
+import calendar
+from datetime import date, timedelta
+
+from filters import calendar_factory, calendar_zoom
+from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton
+
+EMTPY_FIELD = '1'
+WEEK_DAYS = [calendar.day_abbr[i] for i in range(7)]
+MONTHS = [(i, calendar.month_name[i]) for i in range(1, 13)]
+
+
+def generate_calendar_days(year: int, month: int):
+    keyboard = InlineKeyboardMarkup(row_width=7)
+    today = date.today()
+
+    keyboard.add(
+        InlineKeyboardButton(
+            text=date(year=year, month=month, day=1).strftime('%b %Y'),
+            callback_data=EMTPY_FIELD
+        )
+    )
+    keyboard.add(*[
+        InlineKeyboardButton(
+            text=day,
+            callback_data=EMTPY_FIELD
+        )
+        for day in WEEK_DAYS
+    ])
+
+    for week in calendar.Calendar().monthdayscalendar(year=year, month=month):
+        week_buttons = []
+        for day in week:
+            day_name = ' '
+            if day == today.day and today.year == year and today.month == month:
+                day_name = '🔘'
+            elif day != 0:
+                day_name = str(day)
+            week_buttons.append(
+                InlineKeyboardButton(
+                    text=day_name,
+                    callback_data=EMTPY_FIELD
+                )
+            )
+        keyboard.add(*week_buttons)
+
+    previous_date = date(year=year, month=month, day=1) - timedelta(days=1)
+    next_date = date(year=year, month=month, day=1) + timedelta(days=31)
+
+    keyboard.add(
+        InlineKeyboardButton(
+            text='Previous month',
+            callback_data=calendar_factory.new(year=previous_date.year, month=previous_date.month)
+        ),
+        InlineKeyboardButton(
+            text='Zoom out',
+            callback_data=calendar_zoom.new(year=year)
+        ),
+        InlineKeyboardButton(
+            text='Next month',
+            callback_data=calendar_factory.new(year=next_date.year, month=next_date.month)
+        ),
+    )
+
+    return keyboard
+
+
+def generate_calendar_months(year: int):
+    keyboard = InlineKeyboardMarkup(row_width=3)
+    keyboard.add(
+        InlineKeyboardButton(
+            text=date(year=year, month=1, day=1).strftime('Year %Y'),
+            callback_data=EMTPY_FIELD
+        )
+    )
+    keyboard.add(*[
+        InlineKeyboardButton(
+            text=month,
+            callback_data=calendar_factory.new(year=year, month=month_number)
+        )
+        for month_number, month in MONTHS
+    ])
+    keyboard.add(
+        InlineKeyboardButton(
+            text='Previous year',
+            callback_data=calendar_zoom.new(year=year - 1)
+        ),
+        InlineKeyboardButton(
+            text='Next year',
+            callback_data=calendar_zoom.new(year=year + 1)
+        )
+    )
+    return keyboard

examples/asynchronous_telebot/callback_data_examples/advanced_calendar_example/main.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""
+This Example will show you an advanced usage of CallbackData.
+In this example calendar was implemented
+"""
+import asyncio
+from datetime import date
+
+from filters import calendar_factory, calendar_zoom, bind_filters
+from keyboards import generate_calendar_days, generate_calendar_months, EMTPY_FIELD
+from telebot import types
+from telebot.async_telebot import AsyncTeleBot
+
+API_TOKEN = ''
+bot = AsyncTeleBot(API_TOKEN)
+
+
+@bot.message_handler(commands='start')
+async def start_command_handler(message: types.Message):
+    await bot.send_message(message.chat.id,
+                           f"Hello {message.from_user.first_name}. This bot is an example of calendar keyboard."
+                           "\nPress /calendar to see it.")
+
+
+@bot.message_handler(commands='calendar')
+async def calendar_command_handler(message: types.Message):
+    now = date.today()
+    await bot.send_message(message.chat.id, 'Calendar',
+                           reply_markup=generate_calendar_days(year=now.year, month=now.month))
+
+
+@bot.callback_query_handler(func=None, calendar_config=calendar_factory.filter())
+async def calendar_action_handler(call: types.CallbackQuery):
+    callback_data: dict = calendar_factory.parse(callback_data=call.data)
+    year, month = int(callback_data['year']), int(callback_data['month'])
+
+    await bot.edit_message_reply_markup(call.message.chat.id, call.message.id,
+                                        reply_markup=generate_calendar_days(year=year, month=month))
+
+
+@bot.callback_query_handler(func=None, calendar_zoom_config=calendar_zoom.filter())
+async def calendar_zoom_out_handler(call: types.CallbackQuery):
+    callback_data: dict = calendar_zoom.parse(callback_data=call.data)
+    year = int(callback_data.get('year'))
+
+    await bot.edit_message_reply_markup(call.message.chat.id, call.message.id,
+                                        reply_markup=generate_calendar_months(year=year))
+
+
+@bot.callback_query_handler(func=lambda call: call.data == EMTPY_FIELD)
+async def callback_empty_field_handler(call: types.CallbackQuery):
+    await bot.answer_callback_query(call.id)
+
+
+if __name__ == '__main__':
+    bind_filters(bot)
+    asyncio.run(bot.infinity_polling())

examples/asynchronous_telebot/chat_member_example.py

@@ -23,12 +23,12 @@ async def my_chat_m(message: types.ChatMemberUpdated):
 #content_Type_service is:
 #'new_chat_members', 'left_chat_member', 'new_chat_title', 'new_chat_photo', 'delete_chat_photo', 'group_chat_created',
 #'supergroup_chat_created', 'channel_chat_created', 'migrate_to_chat_id', 'migrate_from_chat_id', 'pinned_message',
-#'proximity_alert_triggered', 'voice_chat_scheduled', 'voice_chat_started', 'voice_chat_ended', 
-#'voice_chat_participants_invited', 'message_auto_delete_timer_changed'
+#'proximity_alert_triggered', 'video_chat_scheduled', 'video_chat_started', 'video_chat_ended', 
+#'video_chat_participants_invited', 'message_auto_delete_timer_changed'
 # this handler deletes service messages
 
 @bot.message_handler(content_types=util.content_type_service)
 async def delall(message: types.Message):
     await bot.delete_message(message.chat.id,message.message_id)
 import asyncio
-asyncio.run(bot.polling())
+asyncio.run(bot.polling(allowed_updates=util.update_types))

examples/asynchronous_telebot/continue_handling.py

@@ -0,0 +1,27 @@
+from telebot.async_telebot import AsyncTeleBot
+from telebot.asyncio_handler_backends import ContinueHandling
+
+
+bot = AsyncTeleBot('TOKEN')
+
+@bot.message_handler(commands=['start'])
+async def start(message):
+    await bot.send_message(message.chat.id, 'Hello World!')
+    return ContinueHandling()
+
+@bot.message_handler(commands=['start'])
+async def start2(message):
+    """
+    This handler comes after the first one, but it will never be called.
+    But you can call it by returning ContinueHandling() in the first handler.
+
+    If you return ContinueHandling() in the first handler, the next 
+    registered handler with appropriate filters will be called.
+    """
+    await bot.send_message(message.chat.id, 'Hello World2!')
+
+import asyncio 
+asyncio.run(bot.polling()) # just a reminder that infinity polling
+# wraps polling into try/except block just as sync version,
+# but you can use any of them because neither of them stops if you
+# pass non_stop=True

examples/asynchronous_telebot/custom_filters/advanced_text_filter.py

@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+"""
+This Example will show you usage of TextFilter
+In this example you will see how to use TextFilter
+with (message_handler, callback_query_handler, poll_handler)
+"""
+import asyncio
+
+from telebot import types
+from telebot.async_telebot import AsyncTeleBot
+from telebot.asyncio_filters import TextMatchFilter, TextFilter, IsReplyFilter
+
+bot = AsyncTeleBot("")
+
+
+@bot.message_handler(text=TextFilter(equals='hello'))
+async def hello_handler(message: types.Message):
+    await bot.send_message(message.chat.id, message.text)
+
+
+@bot.message_handler(text=TextFilter(equals='hello', ignore_case=True))
+async def hello_handler_ignore_case(message: types.Message):
+    await bot.send_message(message.chat.id, message.text + ' ignore case')
+
+
+@bot.message_handler(text=TextFilter(contains=['good', 'bad']))
+async def contains_handler(message: types.Message):
+    await bot.send_message(message.chat.id, message.text)
+
+
+@bot.message_handler(text=TextFilter(contains=['good', 'bad'], ignore_case=True))
+async def contains_handler_ignore_case(message: types.Message):
+    await bot.send_message(message.chat.id, message.text + ' ignore case')
+
+
+@bot.message_handler(text=TextFilter(starts_with='st'))  # stArk, steve, stONE
+async def starts_with_handler(message: types.Message):
+    await bot.send_message(message.chat.id, message.text)
+
+
+@bot.message_handler(text=TextFilter(starts_with='st', ignore_case=True))  # STark, sTeve, stONE
+async def starts_with_handler_ignore_case(message: types.Message):
+    await bot.send_message(message.chat.id, message.text + ' ignore case')
+
+
+@bot.message_handler(text=TextFilter(ends_with='ay'))  # wednesday, SUNday, WeekDay
+async def ends_with_handler(message: types.Message):
+    await bot.send_message(message.chat.id, message.text)
+
+
+@bot.message_handler(text=TextFilter(ends_with='ay', ignore_case=True))  # wednesdAY, sundAy, WeekdaY
+async def ends_with_handler_ignore_case(message: types.Message):
+    await bot.send_message(message.chat.id, message.text + ' ignore case')
+
+
+@bot.message_handler(text=TextFilter(equals='/callback'))
+async def send_callback(message: types.Message):
+    keyboard = types.InlineKeyboardMarkup(
+        keyboard=[
+            [types.InlineKeyboardButton(text='callback data', callback_data='example')],
+            [types.InlineKeyboardButton(text='ignore case callback data', callback_data='ExAmPLe')]
+        ]
+    )
+    await bot.send_message(message.chat.id, message.text, reply_markup=keyboard)
+
+
+@bot.callback_query_handler(func=None, text=TextFilter(equals='example'))
+async def callback_query_handler(call: types.CallbackQuery):
+    await bot.answer_callback_query(call.id, call.data, show_alert=True)
+
+
+@bot.callback_query_handler(func=None, text=TextFilter(equals='example', ignore_case=True))
+async def callback_query_handler_ignore_case(call: types.CallbackQuery):
+    await bot.answer_callback_query(call.id, call.data + " ignore case", show_alert=True)
+
+
+@bot.message_handler(text=TextFilter(equals='/poll'))
+async def send_poll(message: types.Message):
+    await bot.send_poll(message.chat.id, question='When do you prefer to work?', options=['Morning', 'Night'])
+    await bot.send_poll(message.chat.id, question='WHEN DO you pRefeR to worK?', options=['Morning', 'Night'])
+
+
+@bot.poll_handler(func=None, text=TextFilter(equals='When do you prefer to work?'))
+async def poll_question_handler(poll: types.Poll):
+    print(poll.question)
+
+
+@bot.poll_handler(func=None, text=TextFilter(equals='When do you prefer to work?', ignore_case=True))
+async def poll_question_handler_ignore_case(poll: types.Poll):
+    print(poll.question + ' ignore case')
+
+
+# either hi or contains one of (привет, salom)
+@bot.message_handler(text=TextFilter(equals="hi", contains=('привет', 'salom'), ignore_case=True))
+async def multiple_patterns_handler(message: types.Message):
+    await bot.send_message(message.chat.id, message.text)
+
+
+# starts with one of (mi, mea) for ex. minor, milk, meal, meat
+@bot.message_handler(text=TextFilter(starts_with=['mi', 'mea'], ignore_case=True))
+async def multiple_starts_with_handler(message: types.Message):
+    await bot.send_message(message.chat.id, message.text)
+
+
+# ends with one of (es, on) for ex. Jones, Davies, Johnson, Wilson
+@bot.message_handler(text=TextFilter(ends_with=['es', 'on'], ignore_case=True))
+async def multiple_ends_with_handler(message: types.Message):
+    await bot.send_message(message.chat.id, message.text)
+
+
+# !ban /ban .ban !бан /бан .бан
+@bot.message_handler(is_reply=True,
+                     text=TextFilter(starts_with=('!', '/', '.'), ends_with=['ban', 'бан'], ignore_case=True))
+async def ban_command_handler(message: types.Message):
+    if len(message.text) == 4 and message.chat.type != 'private':
+        try:
+            await bot.ban_chat_member(message.chat.id, message.reply_to_message.from_user.id)
+            await bot.reply_to(message.reply_to_message, 'Banned.')
+        except Exception as err:
+            print(err.args)
+            return
+
+
+if __name__ == '__main__':
+    bot.add_custom_filter(TextMatchFilter())
+    bot.add_custom_filter(IsReplyFilter())
+    asyncio.run(bot.polling())

examples/asynchronous_telebot/custom_states.py

@@ -1,15 +1,27 @@
-import telebot
 from telebot import asyncio_filters
 from telebot.async_telebot import AsyncTeleBot
-bot = AsyncTeleBot('TOKEN')
+
+# list of storages, you can use any storage
+from telebot.asyncio_storage import StateMemoryStorage
+
+# new feature for states.
+from telebot.asyncio_handler_backends import State, StatesGroup
+
+# default state storage is statememorystorage
+bot = AsyncTeleBot('TOKEN', state_storage=StateMemoryStorage())
+
+
+# Just create different statesgroup
+class MyStates(StatesGroup):
+    name = State() # statesgroup should contain states
+    surname = State()
+    age = State()
 
 
 
-class MyStates:
-    name = 1
-    surname = 2
-    age = 3
-
+# set_state -> sets a new state
+# delete_state -> delets state if exists
+# get_state -> returns state if exists
 
 
 @bot.message_handler(commands=['start'])
@@ -17,7 +29,7 @@ async def start_ex(message):
     """
     Start command. Here we are starting state
     """
-    await bot.set_state(message.from_user.id, MyStates.name)
+    await bot.set_state(message.from_user.id, MyStates.name, message.chat.id)
     await bot.send_message(message.chat.id, 'Hi, write me a name')
  
 
@@ -28,39 +40,45 @@ async def any_state(message):
     Cancel state
     """
     await bot.send_message(message.chat.id, "Your state was cancelled.")
-    await bot.delete_state(message.from_user.id)
+    await bot.delete_state(message.from_user.id, message.chat.id)
 
 @bot.message_handler(state=MyStates.name)
 async def name_get(message):
     """
-    State 1. Will process when user's state is 1.
+    State 1. Will process when user's state is MyStates.name.
     """
     await bot.send_message(message.chat.id, f'Now write me a surname')
-    await bot.set_state(message.from_user.id, MyStates.surname)
-    async with bot.retrieve_data(message.from_user.id) as data:
+    await bot.set_state(message.from_user.id, MyStates.surname, message.chat.id)
+    async with bot.retrieve_data(message.from_user.id, message.chat.id) as data:
         data['name'] = message.text
  
  
 @bot.message_handler(state=MyStates.surname)
 async def ask_age(message):
     """
-    State 2. Will process when user's state is 2.
+    State 2. Will process when user's state is MyStates.surname.
     """
     await bot.send_message(message.chat.id, "What is your age?")
-    await bot.set_state(message.from_user.id, MyStates.age)
-    async with bot.retrieve_data(message.from_user.id) as data:
+    await bot.set_state(message.from_user.id, MyStates.age, message.chat.id)
+    async with bot.retrieve_data(message.from_user.id, message.chat.id) as data:
         data['surname'] = message.text
  
 # result
 @bot.message_handler(state=MyStates.age, is_digit=True)
 async def ready_for_answer(message):
-    async with bot.retrieve_data(message.from_user.id) as data:
+    """
+    State 3. Will process when user's state is MyStates.age.
+    """
+    async with bot.retrieve_data(message.from_user.id, message.chat.id) as data:
         await bot.send_message(message.chat.id, "Ready, take a look:\n<b>Name: {name}\nSurname: {surname}\nAge: {age}</b>".format(name=data['name'], surname=data['surname'], age=message.text), parse_mode="html")
-    await bot.delete_state(message.from_user.id)
+    await bot.delete_state(message.from_user.id, message.chat.id)
 
 #incorrect number
 @bot.message_handler(state=MyStates.age, is_digit=False)
 async def age_incorrect(message):
+    """
+    Will process for wrong input when state is MyState.age
+    """
     await bot.send_message(message.chat.id, 'Looks like you are submitting a string in the field age. Please enter a number')
 
 # register filters
@@ -68,8 +86,6 @@ async def age_incorrect(message):
 bot.add_custom_filter(asyncio_filters.StateFilter(bot))
 bot.add_custom_filter(asyncio_filters.IsDigitFilter())
 
-# set saving states into file.
-bot.enable_saving_states() # you can delete this if you do not need to save states
 
 import asyncio
 asyncio.run(bot.polling())

examples/asynchronous_telebot/detect_changes.py

@@ -0,0 +1,28 @@
+#!/usr/bin/python
+
+# This is a simple echo bot using the decorator mechanism.
+# It echoes any incoming text messages.
+
+from telebot.async_telebot import AsyncTeleBot
+bot = AsyncTeleBot('TOKEN')
+
+
+
+# Handle '/start' and '/help'
+@bot.message_handler(commands=['help', 'start'])
+async def send_welcome(message):
+    await bot.reply_to(message, """\
+Hi there, I am EchoBot.
+I am here to echo your kind words back to you. Just say anything nice and I'll say the exact same thing to you!\
+""")
+
+
+# Handle all other messages with content_type 'text' (content_types defaults to ['text'])
+@bot.message_handler(func=lambda message: True)
+async def echo_message(message):
+    await bot.reply_to(message, message.text)
+
+
+import asyncio
+# only for versions 4.7.0+
+asyncio.run(bot.polling(restart_on_change=True))

examples/asynchronous_telebot/formatting_example.py

@@ -0,0 +1,54 @@
+from telebot.async_telebot import AsyncTeleBot
+from telebot import formatting
+
+bot = AsyncTeleBot('token')
+
+
+@bot.message_handler(commands=['start'])
+async def start_message(message):
+    await bot.send_message(
+        message.chat.id,
+        # function which connects all strings
+        formatting.format_text(
+            formatting.mbold(message.from_user.first_name),
+            formatting.mitalic(message.from_user.first_name),
+            formatting.munderline(message.from_user.first_name),
+            formatting.mstrikethrough(message.from_user.first_name),
+            formatting.mcode(message.from_user.first_name),
+            separator=" " # separator separates all strings
+        ),
+        parse_mode='MarkdownV2'
+    )
+
+    # just a bold text using markdownv2
+    await bot.send_message(
+        message.chat.id,
+        formatting.mbold(message.from_user.first_name),
+        parse_mode='MarkdownV2'
+    )
+
+    # html
+    await bot.send_message(
+        message.chat.id,
+        formatting.format_text(
+            formatting.hbold(message.from_user.first_name),
+            formatting.hitalic(message.from_user.first_name),
+            formatting.hunderline(message.from_user.first_name),
+            formatting.hstrikethrough(message.from_user.first_name),
+            formatting.hcode(message.from_user.first_name),
+            # hide_link is only for html
+            formatting.hide_link('https://telegra.ph/file/c158e3a6e2a26a160b253.jpg'),
+            separator=" "
+        ),
+        parse_mode='HTML'
+    )
+
+    # just a bold text in html
+    await bot.send_message(
+        message.chat.id,
+        formatting.hbold(message.from_user.first_name),
+        parse_mode='HTML'
+    )
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/middleware/flooding_middleware.py

@@ -1,9 +1,7 @@
 # Just a little example of middleware handlers
 
-import telebot
-from telebot.asyncio_handler_backends import BaseMiddleware
+from telebot.asyncio_handler_backends import BaseMiddleware, CancelUpdate
 from telebot.async_telebot import AsyncTeleBot
-from telebot.async_telebot import CancelUpdate
 bot = AsyncTeleBot('TOKEN')
 
 
@@ -37,4 +35,4 @@ async def start(message):
     await bot.send_message(message.chat.id, 'Hello!')
 
 import asyncio
-asyncio.run(bot.polling())
+asyncio.run(bot.polling())

examples/asynchronous_telebot/middleware/i18n_middleware_example/i18n_base_midddleware.py

@@ -0,0 +1,120 @@
+import contextvars
+import gettext
+import os
+
+from telebot.asyncio_handler_backends import BaseMiddleware
+
+try:
+    from babel.support import LazyProxy
+
+    babel_imported = True
+except ImportError:
+    babel_imported = False
+
+
+class I18N(BaseMiddleware):
+    """
+    This middleware provides high-level tool for internationalization
+    It is based on gettext util.
+    """
+
+    context_lang = contextvars.ContextVar('language', default=None)
+
+    def __init__(self, translations_path, domain_name: str):
+        super().__init__()
+        self.update_types = self.process_update_types()
+
+        self.path = translations_path
+        self.domain = domain_name
+        self.translations = self.find_translations()
+
+    @property
+    def available_translations(self):
+        return list(self.translations)
+
+    def gettext(self, text: str, lang: str = None):
+        """
+        Singular translations
+        """
+
+        if lang is None:
+            lang = self.context_lang.get()
+
+        if lang not in self.translations:
+            return text
+
+        translator = self.translations[lang]
+        return translator.gettext(text)
+
+    def ngettext(self, singular: str, plural: str, lang: str = None, n=1):
+        """
+        Plural translations
+        """
+        if lang is None:
+            lang = self.context_lang.get()
+
+        if lang not in self.translations:
+            if n == 1:
+                return singular
+            return plural
+
+        translator = self.translations[lang]
+        return translator.ngettext(singular, plural, n)
+
+    def lazy_gettext(self, text: str, lang: str = None):
+        if not babel_imported:
+            raise RuntimeError('babel module is not imported. Check that you installed it.')
+        return LazyProxy(self.gettext, text, lang, enable_cache=False)
+
+    def lazy_ngettext(self, singular: str, plural: str, lang: str = None, n=1):
+        if not babel_imported:
+            raise RuntimeError('babel module is not imported. Check that you installed it.')
+        return LazyProxy(self.ngettext, singular, plural, lang, n, enable_cache=False)
+
+    async def get_user_language(self, obj):
+        """
+        You need to override this method and return user language
+        """
+        raise NotImplementedError
+
+    def process_update_types(self) -> list:
+        """
+        You need to override this method and return any update types which you want to be processed
+        """
+        raise NotImplementedError
+
+    async def pre_process(self, message, data):
+        """
+        context language variable will be set each time when update from 'process_update_types' comes
+        value is the result of 'get_user_language' method
+        """
+        self.context_lang.set(await self.get_user_language(obj=message))
+
+    async def post_process(self, message, data, exception):
+        pass
+
+    def find_translations(self):
+        """
+        Looks for translations with passed 'domain' in passed 'path'
+        """
+        if not os.path.exists(self.path):
+            raise RuntimeError(f"Translations directory by path: {self.path!r} was not found")
+
+        result = {}
+
+        for name in os.listdir(self.path):
+            translations_path = os.path.join(self.path, name, 'LC_MESSAGES')
+
+            if not os.path.isdir(translations_path):
+                continue
+
+            po_file = os.path.join(translations_path, self.domain + '.po')
+            mo_file = po_file[:-2] + 'mo'
+
+            if os.path.isfile(po_file) and not os.path.isfile(mo_file):
+                raise FileNotFoundError(f"Translations for: {name!r} were not compiled!")
+
+            with open(mo_file, 'rb') as file:
+                result[name] = gettext.GNUTranslations(file)
+
+        return result

examples/asynchronous_telebot/middleware/i18n_middleware_example/keyboards.py

@@ -0,0 +1,34 @@
+from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton, ReplyKeyboardMarkup, KeyboardButton
+
+
+def languages_keyboard():
+    return InlineKeyboardMarkup(
+        keyboard=[
+            [
+                InlineKeyboardButton(text="English", callback_data='en'),
+                InlineKeyboardButton(text="Русский", callback_data='ru'),
+                InlineKeyboardButton(text="O'zbekcha", callback_data='uz_Latn')
+            ]
+        ]
+    )
+
+
+def clicker_keyboard(_):
+    return InlineKeyboardMarkup(
+        keyboard=[
+            [
+                InlineKeyboardButton(text=_("click"), callback_data='click'),
+            ]
+        ]
+    )
+
+
+def menu_keyboard(_):
+    keyboard = ReplyKeyboardMarkup(resize_keyboard=True)
+    keyboard.add(
+        KeyboardButton(text=_("My user id")),
+        KeyboardButton(text=_("My user name")),
+        KeyboardButton(text=_("My first name"))
+    )
+
+    return keyboard

examples/asynchronous_telebot/middleware/i18n_middleware_example/locales/en/LC_MESSAGES/messages.po

@@ -0,0 +1,81 @@
+# English translations for PROJECT.
+# Copyright (C) 2022 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2022-02-19 18:37+0500\n"
+"PO-Revision-Date: 2022-02-18 16:22+0500\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: en\n"
+"Language-Team: en <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: keyboards.py:20
+msgid "click"
+msgstr ""
+
+#: keyboards.py:29
+msgid "My user id"
+msgstr ""
+
+#: keyboards.py:30
+msgid "My user name"
+msgstr ""
+
+#: keyboards.py:31
+msgid "My first name"
+msgstr ""
+
+#: main.py:97
+msgid ""
+"Hello, {user_fist_name}!\n"
+"This is the example of multilanguage bot.\n"
+"Available commands:\n"
+"\n"
+"/lang - change your language\n"
+"/plural - pluralization example\n"
+"/menu - text menu example"
+msgstr ""
+
+#: main.py:121
+msgid "Language has been changed"
+msgstr ""
+
+#: main.py:130 main.py:150
+#, fuzzy
+msgid "You have {number} click"
+msgid_plural "You have {number} clicks"
+msgstr[0] ""
+msgstr[1] ""
+
+#: main.py:135 main.py:155
+msgid ""
+"This is clicker.\n"
+"\n"
+msgstr ""
+
+#: main.py:163
+msgid "This is ReplyKeyboardMarkup menu example in multilanguage bot."
+msgstr ""
+
+#: main.py:203
+msgid "Seems you confused language"
+msgstr ""
+
+#~ msgid ""
+#~ "Hello, {user_fist_name}!\n"
+#~ "This is the example of multilanguage bot.\n"
+#~ "Available commands:\n"
+#~ "\n"
+#~ "/lang - change your language\n"
+#~ "/plural - pluralization example"
+#~ msgstr ""
+

examples/asynchronous_telebot/middleware/i18n_middleware_example/locales/ru/LC_MESSAGES/messages.po

@@ -0,0 +1,82 @@
+# Russian translations for PROJECT.
+# Copyright (C) 2022 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2022-02-19 18:37+0500\n"
+"PO-Revision-Date: 2022-02-18 16:22+0500\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: ru\n"
+"Language-Team: ru <LL@li.org>\n"
+"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && "
+"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: keyboards.py:20
+msgid "click"
+msgstr "Клик"
+
+#: keyboards.py:29
+msgid "My user id"
+msgstr "Мой user id"
+
+#: keyboards.py:30
+msgid "My user name"
+msgstr "Мой user name"
+
+#: keyboards.py:31
+msgid "My first name"
+msgstr "Мой first name"
+
+#: main.py:97
+msgid ""
+"Hello, {user_fist_name}!\n"
+"This is the example of multilanguage bot.\n"
+"Available commands:\n"
+"\n"
+"/lang - change your language\n"
+"/plural - pluralization example\n"
+"/menu - text menu example"
+msgstr ""
+"Привет, {user_fist_name}!\n"
+"Это пример мультиязычного бота.\n"
+"Доступные команды:\n"
+"\n"
+"/lang - изменить язык\n"
+"/plural - пример плюрализации\n"
+"/menu - Пример текстового меню"
+
+#: main.py:121
+msgid "Language has been changed"
+msgstr "Язык был сменён"
+
+#: main.py:130 main.py:150
+msgid "You have {number} click"
+msgid_plural "You have {number} clicks"
+msgstr[0] "У вас {number} клик"
+msgstr[1] "У вас {number} клика"
+msgstr[2] "У вас {number} кликов"
+
+#: main.py:135 main.py:155
+msgid ""
+"This is clicker.\n"
+"\n"
+msgstr ""
+"Это кликер.\n"
+"\n"
+
+#: main.py:163
+msgid "This is ReplyKeyboardMarkup menu example in multilanguage bot."
+msgstr "Это пример ReplyKeyboardMarkup меню в мультиязычном боте."
+
+#: main.py:203
+msgid "Seems you confused language"
+msgstr "Кажется, вы перепутали язык"
+

examples/asynchronous_telebot/middleware/i18n_middleware_example/locales/uz_Latn/LC_MESSAGES/messages.po

@@ -0,0 +1,80 @@
+# Uzbek (Latin) translations for PROJECT.
+# Copyright (C) 2022 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2022-02-19 18:37+0500\n"
+"PO-Revision-Date: 2022-02-18 16:22+0500\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: uz_Latn\n"
+"Language-Team: uz_Latn <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: keyboards.py:20
+msgid "click"
+msgstr "clik"
+
+#: keyboards.py:29
+msgid "My user id"
+msgstr "Mani user id"
+
+#: keyboards.py:30
+msgid "My user name"
+msgstr "Mani user name"
+
+#: keyboards.py:31
+msgid "My first name"
+msgstr "Mani first name"
+
+#: main.py:97
+msgid ""
+"Hello, {user_fist_name}!\n"
+"This is the example of multilanguage bot.\n"
+"Available commands:\n"
+"\n"
+"/lang - change your language\n"
+"/plural - pluralization example\n"
+"/menu - text menu example"
+msgstr ""
+"Salom, {user_fist_name}!\n"
+"Bu multilanguage bot misoli.\n"
+"Mavjud buyruqlar:\n"
+"\n"
+"/lang - tilni ozgartirish\n"
+"/plural - pluralizatsiya misoli\n"
+"/menu - text menu misoli"
+
+#: main.py:121
+msgid "Language has been changed"
+msgstr "Til ozgartirildi"
+
+#: main.py:130 main.py:150
+msgid "You have {number} click"
+msgid_plural "You have {number} clicks"
+msgstr[0] "Sizda {number}ta clik"
+msgstr[1] "Sizda {number}ta clik"
+
+#: main.py:135 main.py:155
+msgid ""
+"This is clicker.\n"
+"\n"
+msgstr ""
+"Bu clicker.\n"
+"\n"
+
+#: main.py:163
+msgid "This is ReplyKeyboardMarkup menu example in multilanguage bot."
+msgstr "Bu multilanguage bot da replykeyboardmarkup menyu misoli."
+
+#: main.py:203
+msgid "Seems you confused language"
+msgstr "Tilni adashtirdiz"
+

examples/asynchronous_telebot/middleware/i18n_middleware_example/main.py

@@ -0,0 +1,214 @@
+"""
+In this example you will learn how to adapt your bot to different languages
+Using built-in middleware I18N.
+
+You need to install babel package 'https://pypi.org/project/Babel/'
+Babel provides a command-line interface for working with message catalogs
+After installing babel package you have a script called 'pybabel'
+Too see all the commands open terminal and type 'pybabel --help'
+Full description for pybabel commands can be found here: 'https://babel.pocoo.org/en/latest/cmdline.html'
+
+Create a directory 'locales' where our translations will be stored
+
+First we need to extract texts:
+    pybabel extract -o locales/{domain_name}.pot --input-dirs .
+{domain_name}.pot - is the file where all translations are saved
+The name of this file should be the same as domain which you pass to I18N class
+In this example domain_name will be 'messages'
+
+For gettext (singular texts) we use '_' alias and it works perfect
+You may also you some alias for ngettext (plural texts) but you can face with a problem that
+your plural texts are not being extracted
+That is because by default 'pybabel extract' recognizes the following keywords:
+ _, gettext, ngettext, ugettext, ungettext, dgettext, dngettext, N_
+To add your own keyword you can use '-k' flag
+In this example for 'ngettext' i will assign double underscore alias '__'
+
+Full command with pluralization support will look so:
+    pybabel extract -o locales/{domain_name}.pot -k __:1,2 --input-dirs .
+
+Then create directories with translations (get list of all locales: 'pybabel --list-locales'):
+    pybabel init -i locales/{domain_name}.pot -d locales -l en
+    pybabel init -i locales/{domain_name}.pot -d locales -l ru
+    pybabel init -i locales/{domain_name}.pot -d locales -l uz_Latn
+
+Now you can translate the texts located in locales/{language}/LC_MESSAGES/{domain_name}.po
+After you translated all the texts you need to compile .po files:
+    pybabel compile -d locales
+
+When you delete/update your texts you also need to update them in .po files:
+    pybabel extract -o locales/{domain_name}.pot -k __:1,2 --input-dirs .
+    pybabel update -i locales/{domain_name}.pot -d locales
+    - translate
+    pybabel compile -d locales
+
+If you have any exceptions check:
+    - you have installed babel
+    - translations are ready, so you just compiled it
+    - in the commands above you replaced {domain_name} to messages
+    - you are writing commands from correct path in terminal
+"""
+
+import asyncio
+from typing import Union
+
+import keyboards
+from telebot import types
+from telebot.async_telebot import AsyncTeleBot
+from telebot.asyncio_filters import TextMatchFilter, TextFilter
+from i18n_base_middleware import I18N
+from telebot.asyncio_storage.memory_storage import StateMemoryStorage
+
+
+class I18NMiddleware(I18N):
+
+    def process_update_types(self) -> list:
+        """
+        Here you need to return a list of update types which you want to be processed
+        """
+        return ['message', 'callback_query']
+
+    async def get_user_language(self, obj: Union[types.Message, types.CallbackQuery]):
+        """
+        This method is called when new update comes (only updates which you return in 'process_update_types' method)
+        Returned language will be used in 'pre_process' method of parent class
+        Returned language will be set to context language variable.
+        If you need to get translation with user's actual language you don't have to pass it manually
+        It will be automatically passed from context language value.
+        However if you need some other language you can always pass it.
+        """
+
+        user_id = obj.from_user.id
+
+        if user_id not in users_lang:
+            users_lang[user_id] = 'en'
+
+        return users_lang[user_id]
+
+
+storage = StateMemoryStorage()
+bot = AsyncTeleBot("", state_storage=storage)
+
+i18n = I18NMiddleware(translations_path='locales', domain_name='messages')
+_ = i18n.gettext  # for singular translations
+__ = i18n.ngettext  # for plural translations
+
+# These are example storages, do not use it in a production development
+users_lang = {}
+users_clicks = {}
+
+
+@bot.message_handler(commands='start')
+async def start_handler(message: types.Message):
+    text = _("Hello, {user_fist_name}!\n"
+             "This is the example of multilanguage bot.\n"
+             "Available commands:\n\n"
+             "/lang - change your language\n"
+             "/plural - pluralization example\n"
+             "/menu - text menu example")
+
+    # remember don't use f string for interpolation, use .format method instead
+    text = text.format(user_fist_name=message.from_user.first_name)
+    await bot.send_message(message.from_user.id, text)
+
+
+@bot.message_handler(commands='lang')
+async def change_language_handler(message: types.Message):
+    await bot.send_message(message.chat.id, "Choose language\nВыберите язык\nTilni tanlang",
+                           reply_markup=keyboards.languages_keyboard())
+
+
+@bot.callback_query_handler(func=None, text=TextFilter(contains=['en', 'ru', 'uz_Latn']))
+async def language_handler(call: types.CallbackQuery):
+    lang = call.data
+    users_lang[call.from_user.id] = lang
+
+    # When you changed user language, you have to pass it manually beacause it is not changed in context
+    await bot.edit_message_text(_("Language has been changed", lang=lang), call.from_user.id, call.message.id)
+
+
+@bot.message_handler(commands='plural')
+async def pluralization_handler(message: types.Message):
+    if not users_clicks.get(message.from_user.id):
+        users_clicks[message.from_user.id] = 0
+    clicks = users_clicks[message.from_user.id]
+
+    text = __(
+        singular="You have {number} click",
+        plural="You have {number} clicks",
+        n=clicks
+    )
+    text = _("This is clicker.\n\n") + text.format(number=clicks)
+
+    await bot.send_message(message.chat.id, text, reply_markup=keyboards.clicker_keyboard(_))
+
+
+@bot.callback_query_handler(func=None, text=TextFilter(equals='click'))
+async def click_handler(call: types.CallbackQuery):
+    if not users_clicks.get(call.from_user.id):
+        users_clicks[call.from_user.id] = 1
+    else:
+        users_clicks[call.from_user.id] += 1
+
+    clicks = users_clicks[call.from_user.id]
+
+    text = __(
+        singular="You have {number} click",
+        plural="You have {number} clicks",
+        n=clicks
+    )
+    text = _("This is clicker.\n\n") + text.format(number=clicks)
+
+    await bot.edit_message_text(text, call.from_user.id, call.message.message_id,
+                                reply_markup=keyboards.clicker_keyboard(_))
+
+
+@bot.message_handler(commands='menu')
+async def menu_handler(message: types.Message):
+    text = _("This is ReplyKeyboardMarkup menu example in multilanguage bot.")
+    await bot.send_message(message.chat.id, text, reply_markup=keyboards.menu_keyboard(_))
+
+
+# For lazy tranlations
+# lazy gettext is used when you don't know user's locale
+# It can be used for example to handle text buttons in multilanguage bot
+# The actual translation will be delayed until update comes and context language is set
+l_ = i18n.lazy_gettext
+
+
+# Handlers below will handle text according to user's language
+@bot.message_handler(text=l_("My user id"))
+async def return_user_id(message: types.Message):
+    await bot.send_message(message.chat.id, str(message.from_user.id))
+
+
+@bot.message_handler(text=l_("My user name"))
+async def return_user_id(message: types.Message):
+    username = message.from_user.username
+    if not username:
+        username = '-'
+    await bot.send_message(message.chat.id, username)
+
+
+# You can make it case insensitive
+@bot.message_handler(text=TextFilter(equals=l_("My first name"), ignore_case=True))
+async def return_user_id(message: types.Message):
+    await bot.send_message(message.chat.id, message.from_user.first_name)
+
+
+all_menu_texts = []
+for language in i18n.available_translations:
+    for menu_text in ("My user id", "My user name", "My first name"):
+        all_menu_texts.append(_(menu_text, language))
+
+
+# When user confused language. (handles all menu buttons texts)
+@bot.message_handler(text=TextFilter(contains=all_menu_texts, ignore_case=True))
+async def missed_message(message: types.Message):
+    await bot.send_message(message.chat.id, _("Seems you confused language"), reply_markup=keyboards.menu_keyboard(_))
+
+
+if __name__ == '__main__':
+    bot.setup_middleware(i18n)
+    bot.add_custom_filter(TextMatchFilter())
+    asyncio.run(bot.infinity_polling())

examples/asynchronous_telebot/multibot/README.MD

@@ -0,0 +1,17 @@
+You probably have seen bots which allow you to send them token of your bot and then handle updates providing some functionality for your bot.
+<br>
+This type of bots are called <b>multibots</b>. They are created using webhooks.
+<br>
+
+This is the example of simple multibot.<br>
+In order to reproduce this example you need to have <b>domain and ssl connection</b>.
+<br>
+If you have, go to config.py and specify your data.
+<br>
+There is also file called <b>nginx_conf.conf</b>,  we will use nginx as proxy-server and this file is example nginx.conf file.
+<br>
+Make sure that server_name and port are the same in both config and nginx_conf
+<br>
+(nginx_conf.conf IS NOT complete, you would probably use tools like certbot to add ssl connection to it)
+<br>
+Also, in this example I used dictionary as tokens storage, but in production you should use database so that you can re-set webhooks in case bot restarts.

examples/asynchronous_telebot/multibot/config.py

@@ -0,0 +1,6 @@
+MAIN_BOT_TOKEN = "your_main_bot_token"
+
+WEBHOOK_HOST = "your_domain.com"
+WEBHOOK_PATH = "telegram_webhook"
+WEBAPP_HOST = "0.0.0.0"
+WEBAPP_PORT = 3500

examples/asynchronous_telebot/multibot/handlers.py

@@ -0,0 +1,15 @@
+from telebot.async_telebot import AsyncTeleBot
+from telebot import types
+
+
+async def hello_handler(message: types.Message, bot: AsyncTeleBot):
+    await bot.send_message(message.chat.id, "Hi :)")
+
+
+async def echo_handler(message: types.Message, bot: AsyncTeleBot):
+    await bot.send_message(message.chat.id, message.text)
+
+
+def register_handlers(bot: AsyncTeleBot):
+    bot.register_message_handler(hello_handler, func=lambda message: message.text == 'Hello', pass_bot=True)
+    bot.register_message_handler(echo_handler, pass_bot=True)

examples/asynchronous_telebot/multibot/main.py

@@ -0,0 +1,56 @@
+import asyncio
+
+from aiohttp import web
+from telebot import types, util
+from telebot.async_telebot import AsyncTeleBot
+from handlers import register_handlers
+
+import config
+
+main_bot = AsyncTeleBot(config.MAIN_BOT_TOKEN)
+app = web.Application()
+tokens = {config.MAIN_BOT_TOKEN: True}
+
+
+async def webhook(request):
+    token = request.match_info.get('token')
+    if not tokens.get(token):
+        return web.Response(status=404)
+
+    if request.headers.get('content-type') != 'application/json':
+        return web.Response(status=403)
+
+    json_string = await request.json()
+    update = types.Update.de_json(json_string)
+    if token == main_bot.token:
+        await main_bot.process_new_updates([update])
+        return web.Response()
+
+    from_update_bot = AsyncTeleBot(token)
+    register_handlers(from_update_bot)
+    await from_update_bot.process_new_updates([update])
+    return web.Response()
+
+
+app.router.add_post("/" + config.WEBHOOK_PATH + "/{token}", webhook)
+
+
+@main_bot.message_handler(commands=['add_bot'])
+async def add_bot(message: types.Message):
+    token = util.extract_arguments(message.text)
+    tokens[token] = True
+
+    new_bot = AsyncTeleBot(token)
+    await new_bot.delete_webhook()
+    await new_bot.set_webhook(f"{config.WEBHOOK_HOST}/{config.WEBHOOK_PATH}/{token}")
+
+    await new_bot.send_message(message.chat.id, "Webhook was set.")
+
+
+async def main():
+    await main_bot.delete_webhook()
+    await main_bot.set_webhook(f"{config.WEBHOOK_HOST}/{config.WEBHOOK_PATH}/{config.MAIN_BOT_TOKEN}")
+    web.run_app(app, host=config.WEBAPP_HOST, port=config.WEBAPP_PORT)
+
+if __name__ == '__main__':
+    asyncio.run(main())

examples/asynchronous_telebot/multibot/nginx_conf.conf

@@ -0,0 +1,8 @@
+server {
+    server_name your_domain.com;
+
+    location /telegram_webhook/ {
+        proxy_pass http://localhost:3500;
+    }
+
+}

examples/asynchronous_telebot/set_command_example.py

@@ -0,0 +1,35 @@
+#!/usr/bin/python
+
+# This is a set_my_commands example.
+# Press on [/] button in telegram client.
+# Important, to update the command menu, be sure to exit the chat with the bot and log in again
+# Important, command for chat_id and for group have a higher priority than for all
+
+import asyncio
+import telebot
+from telebot.async_telebot import AsyncTeleBot
+
+
+API_TOKEN = '<api_token>'
+bot = AsyncTeleBot(API_TOKEN)
+
+
+async def main():
+    # use in for delete with the necessary scope and language_code if necessary
+    await bot.delete_my_commands(scope=None, language_code=None)
+
+    await bot.set_my_commands(
+        commands=[
+            telebot.types.BotCommand("command1", "command1 description"),
+            telebot.types.BotCommand("command2", "command2 description")
+        ],
+        # scope=telebot.types.BotCommandScopeChat(12345678)  # use for personal command menu for users
+        # scope=telebot.types.BotCommandScopeAllPrivateChats()  # use for all private chats
+    )
+    
+    cmd = await bot.get_my_commands(scope=None, language_code=None)
+    print([c.to_json() for c in cmd])
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

examples/asynchronous_telebot/timer_bot_async.py

@@ -0,0 +1,52 @@
+#!/usr/bin/python3
+
+# This is a simple bot with schedule timer 
+# https://github.com/ibrb/python-aioschedule
+# https://schedule.readthedocs.io
+
+import asyncio
+import aioschedule
+from telebot.async_telebot import AsyncTeleBot
+
+API_TOKEN = '<api_token>'
+bot = AsyncTeleBot(API_TOKEN)
+
+
+async def beep(chat_id) -> None:
+    """Send the beep message."""
+    await bot.send_message(chat_id, text='Beep!')
+    aioschedule.clear(chat_id)  # return schedule.CancelJob not working in aioschedule use tag for delete
+
+
+@bot.message_handler(commands=['help', 'start'])
+async def send_welcome(message):
+    await bot.reply_to(message, "Hi! Use /set <seconds> to set a timer")
+
+
+@bot.message_handler(commands=['set'])
+async def set_timer(message):
+    args = message.text.split()
+    if len(args) > 1 and args[1].isdigit():
+        sec = int(args[1])
+        aioschedule.every(sec).seconds.do(beep, message.chat.id).tag(message.chat.id)
+    else:
+        await bot.reply_to(message, 'Usage: /set <seconds>')
+
+
+@bot.message_handler(commands=['unset'])
+def unset_timer(message):
+    aioschedule.clean(message.chat.id)
+
+
+async def scheduler():
+    while True:
+        await aioschedule.run_pending()
+        await asyncio.sleep(1)
+
+
+async def main():
+    await asyncio.gather(bot.infinity_polling(), scheduler())
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

examples/asynchronous_telebot/webhooks/async_webhook_aiohttp_echo_bot.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# This is an async echo bot using decorators and webhook with aiohttp
+# It echoes any incoming text messages and does not use the polling method.
+
+import logging
+import ssl
+import asyncio
+from aiohttp import web
+import telebot
+from telebot.async_telebot import AsyncTeleBot
+
+API_TOKEN = '<api_token>'
+WEBHOOK_HOST = '<ip/host where the bot is running>'
+WEBHOOK_PORT = 8443  # 443, 80, 88 or 8443 (port need to be 'open')
+WEBHOOK_LISTEN = '0.0.0.0'  # In some VPS you may need to put here the IP addr
+WEBHOOK_SSL_CERT = './webhook_cert.pem'  # Path to the ssl certificate
+WEBHOOK_SSL_PRIV = './webhook_pkey.pem'  # Path to the ssl private key
+WEBHOOK_URL_BASE = "https://{}:{}".format(WEBHOOK_HOST, WEBHOOK_PORT)
+WEBHOOK_URL_PATH = "/{}/".format(API_TOKEN)
+
+# Quick'n'dirty SSL certificate generation:
+#
+# openssl genrsa -out webhook_pkey.pem 2048
+# openssl req -new -x509 -days 3650 -key webhook_pkey.pem -out webhook_cert.pem
+#
+# When asked for "Common Name (e.g. server FQDN or YOUR name)" you should reply
+# with the same value in you put in WEBHOOK_HOST
+
+logger = telebot.logger
+telebot.logger.setLevel(logging.INFO)
+bot = AsyncTeleBot(API_TOKEN)
+
+
+# Process webhook calls
+async def handle(request):
+    if request.match_info.get('token') == bot.token:
+        request_body_dict = await request.json()
+        update = telebot.types.Update.de_json(request_body_dict)
+        asyncio.ensure_future(bot.process_new_updates([update]))
+        return web.Response()
+    else:
+        return web.Response(status=403)
+
+
+# Handle '/start' and '/help'
+@bot.message_handler(commands=['help', 'start'])
+async def send_welcome(message):
+    await bot.reply_to(message,
+                 ("Hi there, I am EchoBot.\n"
+                  "I am here to echo your kind words back to you."))
+
+
+# Handle all other messages
+@bot.message_handler(func=lambda message: True, content_types=['text'])
+async def echo_message(message):
+    await bot.reply_to(message, message.text)
+
+
+# Remove webhook and closing session before exiting
+async def shutdown(app):
+    logger.info('Shutting down: removing webhook')
+    await bot.remove_webhook()
+    logger.info('Shutting down: closing session')
+    await bot.close_session()
+
+
+async def setup():
+    # Remove webhook, it fails sometimes the set if there is a previous webhook
+    logger.info('Starting up: removing old webhook')
+    await bot.remove_webhook()
+    # Set webhook
+    logger.info('Starting up: setting webhook')
+    await bot.set_webhook(url=WEBHOOK_URL_BASE + WEBHOOK_URL_PATH,
+                certificate=open(WEBHOOK_SSL_CERT, 'r'))
+    app = web.Application()
+    app.router.add_post('/{token}/', handle)
+    app.on_cleanup.append(shutdown)
+    return app
+
+
+if __name__ == '__main__':
+    # Build ssl context
+    context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
+    context.load_cert_chain(WEBHOOK_SSL_CERT, WEBHOOK_SSL_PRIV)
+    # Start aiohttp server
+    web.run_app(
+        setup(),
+        host=WEBHOOK_LISTEN,
+        port=WEBHOOK_PORT,
+        ssl_context=context,
+    )

examples/asynchronous_telebot/webhooks/run_webhooks.py

@@ -0,0 +1,45 @@
+#!/usr/bin/python
+
+# This is a simple echo bot using the decorator mechanism.
+# It echoes any incoming text messages.
+# Example on built-in function to receive and process webhooks.
+
+from telebot.async_telebot import AsyncTeleBot
+import asyncio
+bot = AsyncTeleBot('TOKEN')
+
+
+WEBHOOK_SSL_CERT = './webhook_cert.pem'  # Path to the ssl certificate
+WEBHOOK_SSL_PRIV = './webhook_pkey.pem'  # Path to the ssl private key
+DOMAIN = '1.2.3.4' # either domain, or ip address of vps
+
+# Quick'n'dirty SSL certificate generation:
+#
+# openssl genrsa -out webhook_pkey.pem 2048
+# openssl req -new -x509 -days 3650 -key webhook_pkey.pem -out webhook_cert.pem
+#
+# When asked for "Common Name (e.g. server FQDN or YOUR name)" you should reply
+# with the same value in you put in WEBHOOK_HOST
+
+
+# Handle '/start' and '/help'
+@bot.message_handler(commands=['help', 'start'])
+async def send_welcome(message):
+    await bot.reply_to(message, """\
+Hi there, I am EchoBot.
+I am here to echo your kind words back to you. Just say anything nice and I'll say the exact same thing to you!\
+""")
+
+
+# Handle all other messages with content_type 'text' (content_types defaults to ['text'])
+@bot.message_handler(func=lambda message: True)
+async def echo_message(message):
+    await bot.reply_to(message, message.text)
+
+
+# it uses fastapi + uvicorn
+asyncio.run(bot.run_webhooks(
+    listen=DOMAIN,
+    certificate=WEBHOOK_SSL_CERT,
+    certificate_key=WEBHOOK_SSL_PRIV
+))

examples/asynchronous_telebot/webhooks/webhook_starlette_echo_bot.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python
+"""
+Asynchronous Telegram Echo Bot example.
+
+This is a simple bot that echoes each message that is received onto the chat.
+It uses the Starlette ASGI framework to receive updates via webhook requests.
+"""
+
+import uvicorn
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse, Response
+from starlette.routing import Route
+from telebot.async_telebot import AsyncTeleBot
+from telebot.types import Message, Update
+
+API_TOKEN = "TOKEN"
+
+WEBHOOK_HOST = "<ip/domain>"
+WEBHOOK_PORT = 8443  # 443, 80, 88 or 8443 (port need to be 'open')
+WEBHOOK_LISTEN = "0.0.0.0"
+WEBHOOK_SSL_CERT = "./webhook_cert.pem"  # Path to the ssl certificate
+WEBHOOK_SSL_PRIV = "./webhook_pkey.pem"  # Path to the ssl private key
+WEBHOOK_URL = f"https://{WEBHOOK_HOST}:{WEBHOOK_PORT}/telegram"
+WEBHOOK_SECRET_TOKEN = "SECRET_TOKEN"
+
+logger = telebot.logger
+telebot.logger.setLevel(logging.INFO)
+
+bot = AsyncTeleBot(token=API_TOKEN)
+
+# BOT HANDLERS
+@bot.message_handler(commands=["help", "start"])
+async def send_welcome(message: Message):
+    """
+    Handle '/start' and '/help'
+    """
+    await bot.reply_to(
+        message,
+        ("Hi there, I am EchoBot.\n" "I am here to echo your kind words back to you."),
+    )
+
+
+@bot.message_handler(func=lambda _: True, content_types=["text"])
+async def echo_message(message: Message):
+    """
+    Handle all other messages
+    """
+    await bot.reply_to(message, message.text)
+
+
+# WEBSERVER HANDLERS
+async def telegram(request: Request) -> Response:
+    """Handle incoming Telegram updates."""
+    token_header_name = "X-Telegram-Bot-Api-Secret-Token"
+    if request.headers.get(token_header_name) != WEBHOOK_SECRET_TOKEN:
+        return PlainTextResponse("Forbidden", status_code=403)
+    await bot.process_new_updates([Update.de_json(await request.json())])
+    return Response()
+
+
+async def startup() -> None:
+    """Register webhook for telegram updates."""
+    webhook_info = await bot.get_webhook_info(30)
+    if WEBHOOK_URL != webhook_info.url:
+        logger.debug(
+            f"updating webhook url, old: {webhook_info.url}, new: {WEBHOOK_URL}"
+        )
+        if not await bot.set_webhook(
+            url=WEBHOOK_URL, secret_token=WEBHOOK_SECRET_TOKEN
+        ):
+            raise RuntimeError("unable to set webhook")
+
+
+app = Starlette(
+    routes=[
+        Route("/telegram", telegram, methods=["POST"]),
+    ],
+    on_startup=[startup],
+)
+
+
+uvicorn.run(
+    app,
+    host=WEBHOOK_HOST,
+    port=WEBHOOK_LISTEN,
+    ssl_certfile=WEBHOOK_SSL_CERT,
+    ssl_keyfile=WEBHOOK_SSL_PRIV,
+)

examples/callback_data_examples/advanced_calendar_example/filters.py

@@ -0,0 +1,25 @@
+import telebot
+from telebot import types, AdvancedCustomFilter
+from telebot.callback_data import CallbackData, CallbackDataFilter
+
+calendar_factory = CallbackData("year", "month", prefix="calendar")
+calendar_zoom = CallbackData("year", prefix="calendar_zoom")
+
+
+class CalendarCallbackFilter(AdvancedCustomFilter):
+    key = 'calendar_config'
+
+    def check(self, call: types.CallbackQuery, config: CallbackDataFilter):
+        return config.check(query=call)
+
+
+class CalendarZoomCallbackFilter(AdvancedCustomFilter):
+    key = 'calendar_zoom_config'
+
+    def check(self, call: types.CallbackQuery, config: CallbackDataFilter):
+        return config.check(query=call)
+
+
+def bind_filters(bot: telebot.TeleBot):
+    bot.add_custom_filter(CalendarCallbackFilter())
+    bot.add_custom_filter(CalendarZoomCallbackFilter())

examples/callback_data_examples/advanced_calendar_example/keyboards.py

@@ -0,0 +1,92 @@
+import calendar
+from datetime import date, timedelta
+
+from examples.callback_data_examples.advanced_calendar_example.filters import calendar_factory, calendar_zoom
+from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton
+
+EMTPY_FIELD = '1'
+WEEK_DAYS = [calendar.day_abbr[i] for i in range(7)]
+MONTHS = [(i, calendar.month_name[i]) for i in range(1, 13)]
+
+
+def generate_calendar_days(year: int, month: int):
+    keyboard = InlineKeyboardMarkup(row_width=7)
+    today = date.today()
+
+    keyboard.add(
+        InlineKeyboardButton(
+            text=date(year=year, month=month, day=1).strftime('%b %Y'),
+            callback_data=EMTPY_FIELD
+        )
+    )
+    keyboard.add(*[
+        InlineKeyboardButton(
+            text=day,
+            callback_data=EMTPY_FIELD
+        )
+        for day in WEEK_DAYS
+    ])
+
+    for week in calendar.Calendar().monthdayscalendar(year=year, month=month):
+        week_buttons = []
+        for day in week:
+            day_name = ' '
+            if day == today.day and today.year == year and today.month == month:
+                day_name = '🔘'
+            elif day != 0:
+                day_name = str(day)
+            week_buttons.append(
+                InlineKeyboardButton(
+                    text=day_name,
+                    callback_data=EMTPY_FIELD
+                )
+            )
+        keyboard.add(*week_buttons)
+
+    previous_date = date(year=year, month=month, day=1) - timedelta(days=1)
+    next_date = date(year=year, month=month, day=1) + timedelta(days=31)
+
+    keyboard.add(
+        InlineKeyboardButton(
+            text='Previous month',
+            callback_data=calendar_factory.new(year=previous_date.year, month=previous_date.month)
+        ),
+        InlineKeyboardButton(
+            text='Zoom out',
+            callback_data=calendar_zoom.new(year=year)
+        ),
+        InlineKeyboardButton(
+            text='Next month',
+            callback_data=calendar_factory.new(year=next_date.year, month=next_date.month)
+        ),
+    )
+
+    return keyboard
+
+
+def generate_calendar_months(year: int):
+    keyboard = InlineKeyboardMarkup(row_width=3)
+    keyboard.add(
+        InlineKeyboardButton(
+            text=date(year=year, month=1, day=1).strftime('Year %Y'),
+            callback_data=EMTPY_FIELD
+        )
+    )
+    keyboard.add(*[
+        InlineKeyboardButton(
+            text=month,
+            callback_data=calendar_factory.new(year=year, month=month_number)
+        )
+        for month_number, month in MONTHS
+    ])
+    keyboard.add(
+        InlineKeyboardButton(
+            text='Previous year',
+            callback_data=calendar_zoom.new(year=year - 1)
+        ),
+        InlineKeyboardButton(
+            text='Next year',
+            callback_data=calendar_zoom.new(year=year + 1)
+        )
+    )
+    return keyboard

examples/callback_data_examples/advanced_calendar_example/main.py

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+"""
+This Example will show you an advanced usage of CallbackData.
+In this example calendar was implemented
+"""
+
+from datetime import date
+
+from examples.callback_data_examples.advanced_calendar_example.keyboards import generate_calendar_days, \
+    generate_calendar_months, EMTPY_FIELD
+from filters import calendar_factory, calendar_zoom, bind_filters
+from telebot import types, TeleBot
+
+API_TOKEN = ''
+bot = TeleBot(API_TOKEN)
+
+
+@bot.message_handler(commands='start')
+def start_command_handler(message: types.Message):
+    bot.send_message(message.chat.id,
+                     f"Hello {message.from_user.first_name}. This bot is an example of calendar keyboard."
+                     "\nPress /calendar to see it.")
+
+
+@bot.message_handler(commands='calendar')
+def calendar_command_handler(message: types.Message):
+    now = date.today()
+    bot.send_message(message.chat.id, 'Calendar', reply_markup=generate_calendar_days(year=now.year, month=now.month))
+
+
+@bot.callback_query_handler(func=None, calendar_config=calendar_factory.filter())
+def calendar_action_handler(call: types.CallbackQuery):
+    callback_data: dict = calendar_factory.parse(callback_data=call.data)
+    year, month = int(callback_data['year']), int(callback_data['month'])
+
+    bot.edit_message_reply_markup(call.message.chat.id, call.message.id,
+                                  reply_markup=generate_calendar_days(year=year, month=month))
+
+
+@bot.callback_query_handler(func=None, calendar_zoom_config=calendar_zoom.filter())
+def calendar_zoom_out_handler(call: types.CallbackQuery):
+    callback_data: dict = calendar_zoom.parse(callback_data=call.data)
+    year = int(callback_data.get('year'))
+
+    bot.edit_message_reply_markup(call.message.chat.id, call.message.id,
+                                  reply_markup=generate_calendar_months(year=year))
+
+
+@bot.callback_query_handler(func=lambda call: call.data == EMTPY_FIELD)
+def callback_empty_field_handler(call: types.CallbackQuery):
+    bot.answer_callback_query(call.id)
+
+
+if __name__ == '__main__':
+    bind_filters(bot)
+    bot.infinity_polling()

examples/chat_member_example.py

@@ -23,8 +23,8 @@ def my_chat_m(message: types.ChatMemberUpdated):
 #content_Type_service is:
 #'new_chat_members', 'left_chat_member', 'new_chat_title', 'new_chat_photo', 'delete_chat_photo', 'group_chat_created',
 #'supergroup_chat_created', 'channel_chat_created', 'migrate_to_chat_id', 'migrate_from_chat_id', 'pinned_message',
-#'proximity_alert_triggered', 'voice_chat_scheduled', 'voice_chat_started', 'voice_chat_ended', 
-#'voice_chat_participants_invited', 'message_auto_delete_timer_changed'
+#'proximity_alert_triggered', 'video_chat_scheduled', 'video_chat_started', 'video_chat_ended',
+#'video_chat_participants_invited', 'message_auto_delete_timer_changed'
 # this handler deletes service messages
 
 @bot.message_handler(content_types=util.content_type_service)

examples/continue_handling.py

@@ -0,0 +1,23 @@
+from telebot import TeleBot
+from telebot.handler_backends import ContinueHandling
+
+
+bot = TeleBot('TOKEN')
+
+@bot.message_handler(commands=['start'])
+def start(message):
+    bot.send_message(message.chat.id, 'Hello World!')
+    return ContinueHandling()
+
+@bot.message_handler(commands=['start'])
+def start2(message):
+    """
+    This handler comes after the first one, but it will never be called.
+    But you can call it by returning ContinueHandling() in the first handler.
+
+    If you return ContinueHandling() in the first handler, the next 
+    registered handler with appropriate filters will be called.
+    """
+    bot.send_message(message.chat.id, 'Hello World2!')
+
+bot.infinity_polling()

examples/create_invite_link.py

@@ -0,0 +1,33 @@
+import telebot
+from time import sleep, time
+from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton #Only for creating Inline Buttons, not necessary for creating Invite Links
+
+Token = "api_token" #Your Bot Access Token
+Group_ID = -1234567890 #Group ID for which invite link is to be created
+
+bot = telebot.TeleBot(Token, parse_mode="HTML")
+
+#/start command message
+@bot.message_handler(commands=['start'])
+def startmsg(msg):
+    bot.reply_to(msg, "Hey there, I'm a bot made by pyTelegramBotAPI!")
+
+#Get notified of incoming members in group
+@bot.message_handler(content_types=['new_chat_members'])
+def newmember(msg):
+    #Create an invite link class that contains info about the created invite link using create_chat_invite_link() with parameters
+    invite = bot.create_chat_invite_link(Group_ID, member_limit=1, expire_date=int(time())+45) #Here, the link will auto-expire in 45 seconds
+    InviteLink = invite.invite_link #Get the actual invite link from 'invite' class
+    
+    mrkplink = InlineKeyboardMarkup() #Created Inline Keyboard Markup
+    mrkplink.add(InlineKeyboardButton("Join our group 🚀", url=InviteLink)) #Added Invite Link to Inline Keyboard
+    
+    bot.send_message(msg.chat.id, f"Hey there {msg.from_user.first_name}, Click the link below to join our Official Group.", reply_markup=mrkplink)
+    
+    #This will send a message with the newly-created invite link as markup button.
+    #The member limit will be 1 and expiring time will be 45 sec.
+
+
+
+
+bot.infinity_polling()

examples/custom_filters/advanced_text_filter.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+"""
+This Example will show you usage of TextFilter
+In this example you will see how to use TextFilter
+with (message_handler, callback_query_handler, poll_handler)
+"""
+
+from telebot import TeleBot, types
+from telebot.custom_filters import TextFilter, TextMatchFilter, IsReplyFilter
+
+bot = TeleBot("")
+
+
+@bot.message_handler(text=TextFilter(equals='hello'))
+def hello_handler(message: types.Message):
+    bot.send_message(message.chat.id, message.text)
+
+
+@bot.message_handler(text=TextFilter(equals='hello', ignore_case=True))
+def hello_handler_ignore_case(message: types.Message):
+    bot.send_message(message.chat.id, message.text + ' ignore case')
+
+
+@bot.message_handler(text=TextFilter(contains=['good', 'bad']))
+def contains_handler(message: types.Message):
+    bot.send_message(message.chat.id, message.text)
+
+
+@bot.message_handler(text=TextFilter(contains=['good', 'bad'], ignore_case=True))
+def contains_handler_ignore_case(message: types.Message):
+    bot.send_message(message.chat.id, message.text + ' ignore case')
+
+
+@bot.message_handler(text=TextFilter(starts_with='st'))  # stArk, steve, stONE
+def starts_with_handler(message: types.Message):
+    bot.send_message(message.chat.id, message.text)
+
+
+@bot.message_handler(text=TextFilter(starts_with='st', ignore_case=True))  # STark, sTeve, stONE
+def starts_with_handler_ignore_case(message: types.Message):
+    bot.send_message(message.chat.id, message.text + ' ignore case')
+
+
+@bot.message_handler(text=TextFilter(ends_with='ay'))  # wednesday, SUNday, WeekDay
+def ends_with_handler(message: types.Message):
+    bot.send_message(message.chat.id, message.text)
+
+
+@bot.message_handler(text=TextFilter(ends_with='ay', ignore_case=True))  # wednesdAY, sundAy, WeekdaY
+def ends_with_handler_ignore_case(message: types.Message):
+    bot.send_message(message.chat.id, message.text + ' ignore case')
+
+
+@bot.message_handler(text=TextFilter(equals='/callback'))
+def send_callback(message: types.Message):
+    keyboard = types.InlineKeyboardMarkup(
+        keyboard=[
+            [types.InlineKeyboardButton(text='callback data', callback_data='example')],
+            [types.InlineKeyboardButton(text='ignore case callback data', callback_data='ExAmPLe')]
+        ]
+    )
+    bot.send_message(message.chat.id, message.text, reply_markup=keyboard)
+
+
+@bot.callback_query_handler(func=None, text=TextFilter(equals='example'))
+def callback_query_handler(call: types.CallbackQuery):
+    bot.answer_callback_query(call.id, call.data, show_alert=True)
+
+
+@bot.callback_query_handler(func=None, text=TextFilter(equals='example', ignore_case=True))
+def callback_query_handler_ignore_case(call: types.CallbackQuery):
+    bot.answer_callback_query(call.id, call.data + " ignore case", show_alert=True)
+
+
+@bot.message_handler(text=TextFilter(equals='/poll'))
+def send_poll(message: types.Message):
+    bot.send_poll(message.chat.id, question='When do you prefer to work?', options=['Morning', 'Night'])
+    bot.send_poll(message.chat.id, question='WHEN DO you pRefeR to worK?', options=['Morning', 'Night'])
+
+
+@bot.poll_handler(func=None, text=TextFilter(equals='When do you prefer to work?'))
+def poll_question_handler(poll: types.Poll):
+    print(poll.question)
+
+
+@bot.poll_handler(func=None, text=TextFilter(equals='When do you prefer to work?', ignore_case=True))
+def poll_question_handler_ignore_case(poll: types.Poll):
+    print(poll.question + ' ignore case')
+
+
+# either hi or contains one of (привет, salom)
+@bot.message_handler(text=TextFilter(equals="hi", contains=('привет', 'salom'), ignore_case=True))
+def multiple_patterns_handler(message: types.Message):
+    bot.send_message(message.chat.id, message.text)
+
+
+# starts with one of (mi, mea) for ex. minor, milk, meal, meat
+@bot.message_handler(text=TextFilter(starts_with=['mi', 'mea'], ignore_case=True))
+def multiple_starts_with_handler(message: types.Message):
+    bot.send_message(message.chat.id, message.text)
+
+
+# ends with one of (es, on) for ex. Jones, Davies, Johnson, Wilson
+@bot.message_handler(text=TextFilter(ends_with=['es', 'on'], ignore_case=True))
+def multiple_ends_with_handler(message: types.Message):
+    bot.send_message(message.chat.id, message.text)
+
+
+# !ban /ban .ban !бан /бан .бан
+@bot.message_handler(is_reply=True,
+                     text=TextFilter(starts_with=('!', '/', '.'), ends_with=['ban', 'бан'], ignore_case=True))
+def ban_command_handler(message: types.Message):
+    if len(message.text) == 4 and message.chat.type != 'private':
+        try:
+            bot.ban_chat_member(message.chat.id, message.reply_to_message.from_user.id)
+            bot.reply_to(message.reply_to_message, 'Banned.')
+        except Exception as err:
+            print(err.args)
+            return
+
+
+if __name__ == '__main__':
+    bot.add_custom_filter(TextMatchFilter())
+    bot.add_custom_filter(IsReplyFilter())
+    bot.infinity_polling()

examples/custom_states.py

@@ -1,14 +1,39 @@
-import telebot
+import telebot # telebot
 
 from telebot import custom_filters
+from telebot.handler_backends import State, StatesGroup #States
 
-bot = telebot.TeleBot("")
+# States storage
+from telebot.storage import StateMemoryStorage
 
 
-class MyStates:
-    name = 1
-    surname = 2
-    age = 3
+# Starting from version 4.4.0+, we support storages.
+# StateRedisStorage -> Redis-based storage.
+# StatePickleStorage -> Pickle-based storage.
+# For redis, you will need to install redis.
+# Pass host, db, password, or anything else,
+# if you need to change config for redis.
+# Pickle requires path. Default path is in folder .state-saves.
+# If you were using older version of pytba for pickle, 
+# you need to migrate from old pickle to new by using
+# StatePickleStorage().convert_old_to_new()
+
+
+
+# Now, you can pass storage to bot.
+state_storage = StateMemoryStorage() # you can init here another storage
+
+bot = telebot.TeleBot("TOKEN",
+state_storage=state_storage)
+
+
+# States group.
+class MyStates(StatesGroup):
+    # Just name variables differently
+    name = State() # creating instances of State class is enough from now
+    surname = State()
+    age = State()
+
 
 
 
@@ -17,50 +42,60 @@ def start_ex(message):
     """
     Start command. Here we are starting state
     """
-    bot.set_state(message.from_user.id, MyStates.name)
+    bot.set_state(message.from_user.id, MyStates.name, message.chat.id)
     bot.send_message(message.chat.id, 'Hi, write me a name')
  
 
- 
-@bot.message_handler(state="*", commands='cancel')
+# Any state
+@bot.message_handler(state="*", commands=['cancel'])
 def any_state(message):
     """
     Cancel state
     """
     bot.send_message(message.chat.id, "Your state was cancelled.")
-    bot.delete_state(message.from_user.id)
+    bot.delete_state(message.from_user.id, message.chat.id)
 
 @bot.message_handler(state=MyStates.name)
 def name_get(message):
     """
-    State 1. Will process when user's state is 1.
+    State 1. Will process when user's state is MyStates.name.
     """
-    bot.send_message(message.chat.id, f'Now write me a surname')
-    bot.set_state(message.from_user.id, MyStates.surname)
-    with bot.retrieve_data(message.from_user.id) as data:
+    bot.send_message(message.chat.id, 'Now write me a surname')
+    bot.set_state(message.from_user.id, MyStates.surname, message.chat.id)
+    with bot.retrieve_data(message.from_user.id, message.chat.id) as data:
         data['name'] = message.text
  
  
 @bot.message_handler(state=MyStates.surname)
 def ask_age(message):
     """
-    State 2. Will process when user's state is 2.
+    State 2. Will process when user's state is MyStates.surname.
     """
     bot.send_message(message.chat.id, "What is your age?")
-    bot.set_state(message.from_user.id, MyStates.age)
-    with bot.retrieve_data(message.from_user.id) as data:
+    bot.set_state(message.from_user.id, MyStates.age, message.chat.id)
+    with bot.retrieve_data(message.from_user.id, message.chat.id) as data:
         data['surname'] = message.text
  
 # result
 @bot.message_handler(state=MyStates.age, is_digit=True)
 def ready_for_answer(message):
-    with bot.retrieve_data(message.from_user.id) as data:
-        bot.send_message(message.chat.id, "Ready, take a look:\n<b>Name: {name}\nSurname: {surname}\nAge: {age}</b>".format(name=data['name'], surname=data['surname'], age=message.text), parse_mode="html")
-    bot.delete_state(message.from_user.id)
+    """
+    State 3. Will process when user's state is MyStates.age.
+    """
+    with bot.retrieve_data(message.from_user.id, message.chat.id) as data:
+        msg = ("Ready, take a look:\n<b>"
+               f"Name: {data['name']}\n"
+               f"Surname: {data['surname']}\n"
+               f"Age: {message.text}</b>")
+        bot.send_message(message.chat.id, msg, parse_mode="html")
+    bot.delete_state(message.from_user.id, message.chat.id)
 
 #incorrect number
 @bot.message_handler(state=MyStates.age, is_digit=False)
 def age_incorrect(message):
+    """
+    Wrong response for MyStates.age
+    """
     bot.send_message(message.chat.id, 'Looks like you are submitting a string in the field age. Please enter a number')
 
 # register filters
@@ -68,7 +103,4 @@ def age_incorrect(message):
 bot.add_custom_filter(custom_filters.StateFilter(bot))
 bot.add_custom_filter(custom_filters.IsDigitFilter())
 
-# set saving states into file.
-bot.enable_saving_states() # you can delete this if you do not need to save states
-
-bot.infinity_polling(skip_pending=True)
+bot.infinity_polling(skip_pending=True)

examples/detect_changes.py

@@ -0,0 +1,28 @@
+#!/usr/bin/python
+
+# This is a simple echo bot using the decorator mechanism.
+# It echoes any incoming text messages.
+
+import telebot
+
+API_TOKEN = '<api_token>'
+
+bot = telebot.TeleBot(API_TOKEN)
+
+
+# Handle '/start' and '/help'
+@bot.message_handler(commands=['help', 'start'])
+def send_welcome(message):
+    bot.reply_to(message, """\
+Hi there, I am EchoBot.
+I am here to echo your kind words back to you. Just say anything nice and I'll say the exact same thing to you!\
+""")
+
+
+# Handle all other messages with content_type 'text' (content_types defaults to ['text'])
+@bot.message_handler(func=lambda message: True)
+def echo_message(message):
+    bot.reply_to(message, message.text)
+
+# only for versions 4.7.0+
+bot.infinity_polling(restart_on_change=True)

examples/formatting_example.py

@@ -0,0 +1,53 @@
+from telebot import TeleBot
+from telebot import formatting
+
+bot = TeleBot('TOKEN')
+
+
+@bot.message_handler(commands=['start'])
+def start_message(message):
+    bot.send_message(
+        message.chat.id,
+        # function which connects all strings
+        formatting.format_text(
+            formatting.mbold(message.from_user.first_name),
+            formatting.mitalic(message.from_user.first_name),
+            formatting.munderline(message.from_user.first_name),
+            formatting.mstrikethrough(message.from_user.first_name),
+            formatting.mcode(message.from_user.first_name),
+            separator=" " # separator separates all strings
+        ),
+        parse_mode='MarkdownV2'
+    )
+
+    # just a bold text using markdownv2
+    bot.send_message(
+        message.chat.id,
+        formatting.mbold(message.from_user.first_name),
+        parse_mode='MarkdownV2'
+    )
+
+    # html
+    bot.send_message(
+        message.chat.id,
+        formatting.format_text(
+            formatting.hbold(message.from_user.first_name),
+            formatting.hitalic(message.from_user.first_name),
+            formatting.hunderline(message.from_user.first_name),
+            formatting.hstrikethrough(message.from_user.first_name),
+            formatting.hcode(message.from_user.first_name),
+            # hide_link is only for html
+            formatting.hide_link('https://telegra.ph/file/c158e3a6e2a26a160b253.jpg'),
+            separator=" "
+        ),
+        parse_mode='HTML'
+    )
+
+    # just a bold text in html
+    bot.send_message(
+        message.chat.id,
+        formatting.hbold(message.from_user.first_name),
+        parse_mode='HTML'
+    )
+
+bot.infinity_polling()

examples/inline_example.py

@@ -42,7 +42,7 @@ def query_video(inline_query):
     try:
         r = types.InlineQueryResultVideo('1',
                                          'https://github.com/eternnoir/pyTelegramBotAPI/blob/master/tests/test_data/test_video.mp4?raw=true',
-                                         'video/mp4', 'Video',
+                                         'video/mp4', 
                                          'https://raw.githubusercontent.com/eternnoir/pyTelegramBotAPI/master/examples/detailed_example/rooster.jpg',
                                          'Title'
                                          )

examples/middleware/README.md

@@ -0,0 +1,35 @@
+# Middlewares
+
+## Type of middlewares in pyTelegramBotAPI
+Currently, synchronous version of pyTelegramBotAPI has two types of middlewares:
+
+- Class-based middlewares
+- Function-based middlewares
+
+## Purpose of middlewares
+Middlewares are designed to get update before handler's execution.
+
+## Class-based middlewares
+This type of middleware has more functionality compared to function-based one.
+
+Class based middleware should be instance of `telebot.handler_backends.BaseMiddleware.`
+
+Each middleware should have 2 main functions:
+
+`pre_process` -> is a method of class which receives update, and data.
+
+Data - is a dictionary, which could be passed right to handler, and `post_process` function.
+
+`post_process` -> is a function of class which receives update, data, and exception, that happened in handler. If handler was executed correctly - then exception will equal to None.
+
+## Function-based middlewares
+To use function-based middleware, you should set `apihelper.ENABLE_MIDDLEWARE = True`.
+This type of middleware is created by using a decorator for middleware.
+With this type middleware, you can retrieve update immediately after update came. You should set update_types as well.
+
+## Why class-based middlewares are better?
+- You can pass data between post, pre_process functions, and handler.
+- If there is an exception in handler, you will get exception parameter with exception class in post_process.
+- Has post_process -> method which works after the handler's execution.
+
+## Take a look at examples for more.

examples/middleware/class_based/antiflood_middleware.py

@@ -0,0 +1,39 @@
+# Just a little example of middleware handlers
+
+from telebot.handler_backends import BaseMiddleware
+from telebot import TeleBot
+from telebot.handler_backends import CancelUpdate
+bot = TeleBot('TOKEN',
+            use_class_middlewares=True) # if you don't set it to true, middlewares won't work
+
+
+class SimpleMiddleware(BaseMiddleware):
+    def __init__(self, limit) -> None:
+        self.last_time = {}
+        self.limit = limit
+        self.update_types = ['message']
+        # Always specify update types, otherwise middlewares won't work
+
+
+    def pre_process(self, message, data):
+        if not message.from_user.id in self.last_time:
+            # User is not in a dict, so lets add and cancel this function
+            self.last_time[message.from_user.id] = message.date
+            return
+        if message.date - self.last_time[message.from_user.id] < self.limit:
+            # User is flooding
+            bot.send_message(message.chat.id, 'You are making request too often')
+            return CancelUpdate()
+        self.last_time[message.from_user.id] = message.date
+
+        
+    def post_process(self, message, data, exception):
+        pass
+
+bot.setup_middleware(SimpleMiddleware(2))
+
+@bot.message_handler(commands=['start'])
+def start(message): # you don't have to put data in handler.
+    bot.send_message(message.chat.id, 'Hello!')
+
+bot.infinity_polling()

examples/middleware/class_based/basic_example.py

@@ -0,0 +1,32 @@
+from telebot import TeleBot
+from telebot.handler_backends import BaseMiddleware
+
+bot = TeleBot('TOKEN', use_class_middlewares=True) # set use_class_middlewares to True!
+# otherwise, class-based middlewares won't execute.
+
+# You can use this classes for cancelling update or skipping handler:
+# from telebot.handler_backends import CancelUpdate, SkipHandler
+
+class Middleware(BaseMiddleware):
+    def __init__(self):
+        self.update_types = ['message']
+    def pre_process(self, message, data):
+        data['foo'] = 'Hello' # just for example
+        # we edited the data. now, this data is passed to handler.
+        # return SkipHandler() -> this will skip handler
+        # return CancelUpdate() -> this will cancel update
+    def post_process(self, message, data, exception=None):
+        print(data['foo'])
+        if exception: # check for exception
+            print(exception)
+
+@bot.message_handler(commands=['start'])
+def start(message, data: dict): # you don't have to put data parameter in handler if you don't need it.
+    bot.send_message(message.chat.id, data['foo'])
+    data['foo'] = 'Processed' # we changed value of data.. this data is now passed to post_process.
+
+
+# Setup middleware
+bot.setup_middleware(Middleware())
+
+bot.infinity_polling()

examples/middleware/class_based/i18n_middleware/i18n_base_middleware.py

@@ -0,0 +1,121 @@
+import gettext
+import os
+import threading
+
+from telebot.handler_backends import BaseMiddleware
+
+try:
+    from babel.support import LazyProxy
+
+    babel_imported = True
+except ImportError:
+    babel_imported = False
+
+
+class I18N(BaseMiddleware):
+    """
+    This middleware provides high-level tool for internationalization
+    It is based on gettext util.
+    """
+
+    context_lang = threading.local()
+
+    def __init__(self, translations_path, domain_name: str):
+        super().__init__()
+        self.update_types = self.process_update_types()
+
+        self.path = translations_path
+        self.domain = domain_name
+        self.translations = self.find_translations()
+
+    @property
+    def available_translations(self):
+        return list(self.translations)
+
+    def gettext(self, text: str, lang: str = None):
+        """
+        Singular translations
+        """
+
+        if lang is None:
+            lang = self.context_lang.language
+
+        if lang not in self.translations:
+            return text
+
+        translator = self.translations[lang]
+        return translator.gettext(text)
+
+    def ngettext(self, singular: str, plural: str, lang: str = None, n=1):
+        """
+        Plural translations
+        """
+        if lang is None:
+            lang = self.context_lang.language
+
+        if lang not in self.translations:
+            if n == 1:
+                return singular
+            return plural
+
+        translator = self.translations[lang]
+        return translator.ngettext(singular, plural, n)
+
+    def lazy_gettext(self, text: str, lang: str = None):
+        if not babel_imported:
+            raise RuntimeError('babel module is not imported. Check that you installed it.')
+        return LazyProxy(self.gettext, text, lang, enable_cache=False)
+
+    def lazy_ngettext(self, singular: str, plural: str, lang: str = None, n=1):
+        if not babel_imported:
+            raise RuntimeError('babel module is not imported. Check that you installed it.')
+        return LazyProxy(self.ngettext, singular, plural, lang, n, enable_cache=False)
+
+    def get_user_language(self, obj):
+        """
+        You need to override this method and return user language
+        """
+        raise NotImplementedError
+
+    def process_update_types(self) -> list:
+        """
+        You need to override this method and return any update types which you want to be processed
+        """
+        raise NotImplementedError
+
+    def pre_process(self, message, data):
+        """
+        context language variable will be set each time when update from 'process_update_types' comes
+        value is the result of 'get_user_language' method
+        """
+
+        self.context_lang.language = self.get_user_language(obj=message)
+
+    def post_process(self, message, data, exception):
+        pass
+
+    def find_translations(self):
+        """
+        Looks for translations with passed 'domain' in passed 'path'
+        """
+        if not os.path.exists(self.path):
+            raise RuntimeError(f"Translations directory by path: {self.path!r} was not found")
+
+        result = {}
+
+        for name in os.listdir(self.path):
+            translations_path = os.path.join(self.path, name, 'LC_MESSAGES')
+
+            if not os.path.isdir(translations_path):
+                continue
+
+            po_file = os.path.join(translations_path, self.domain + '.po')
+            mo_file = po_file[:-2] + 'mo'
+
+            if os.path.isfile(po_file) and not os.path.isfile(mo_file):
+                raise FileNotFoundError(f"Translations for: {name!r} were not compiled!")
+
+            with open(mo_file, 'rb') as file:
+                result[name] = gettext.GNUTranslations(file)
+
+        return result

examples/middleware/class_based/i18n_middleware/keyboards.py

@@ -0,0 +1,34 @@
+from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton, ReplyKeyboardMarkup, KeyboardButton
+
+
+def languages_keyboard():
+    return InlineKeyboardMarkup(
+        keyboard=[
+            [
+                InlineKeyboardButton(text="English", callback_data='en'),
+                InlineKeyboardButton(text="Русский", callback_data='ru'),
+                InlineKeyboardButton(text="O'zbekcha", callback_data='uz_Latn')
+            ]
+        ]
+    )
+
+
+def clicker_keyboard(_):
+    return InlineKeyboardMarkup(
+        keyboard=[
+            [
+                InlineKeyboardButton(text=_("click"), callback_data='click'),
+            ]
+        ]
+    )
+
+
+def menu_keyboard(_):
+    keyboard = ReplyKeyboardMarkup(resize_keyboard=True)
+    keyboard.add(
+        KeyboardButton(text=_("My user id")),
+        KeyboardButton(text=_("My user name")),
+        KeyboardButton(text=_("My first name"))
+    )
+
+    return keyboard

examples/middleware/class_based/i18n_middleware/locales/en/LC_MESSAGES/messages.po

@@ -0,0 +1,81 @@
+# English translations for PROJECT.
+# Copyright (C) 2022 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2022-02-19 18:37+0500\n"
+"PO-Revision-Date: 2022-02-18 16:22+0500\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: en\n"
+"Language-Team: en <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: keyboards.py:20
+msgid "click"
+msgstr ""
+
+#: keyboards.py:29
+msgid "My user id"
+msgstr ""
+
+#: keyboards.py:30
+msgid "My user name"
+msgstr ""
+
+#: keyboards.py:31
+msgid "My first name"
+msgstr ""
+
+#: main.py:97
+msgid ""
+"Hello, {user_fist_name}!\n"
+"This is the example of multilanguage bot.\n"
+"Available commands:\n"
+"\n"
+"/lang - change your language\n"
+"/plural - pluralization example\n"
+"/menu - text menu example"
+msgstr ""
+
+#: main.py:121
+msgid "Language has been changed"
+msgstr ""
+
+#: main.py:130 main.py:150
+#, fuzzy
+msgid "You have {number} click"
+msgid_plural "You have {number} clicks"
+msgstr[0] ""
+msgstr[1] ""
+
+#: main.py:135 main.py:155
+msgid ""
+"This is clicker.\n"
+"\n"
+msgstr ""
+
+#: main.py:163
+msgid "This is ReplyKeyboardMarkup menu example in multilanguage bot."
+msgstr ""
+
+#: main.py:203
+msgid "Seems you confused language"
+msgstr ""
+
+#~ msgid ""
+#~ "Hello, {user_fist_name}!\n"
+#~ "This is the example of multilanguage bot.\n"
+#~ "Available commands:\n"
+#~ "\n"
+#~ "/lang - change your language\n"
+#~ "/plural - pluralization example"
+#~ msgstr ""
+

examples/middleware/class_based/i18n_middleware/locales/ru/LC_MESSAGES/messages.po

@@ -0,0 +1,82 @@
+# Russian translations for PROJECT.
+# Copyright (C) 2022 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2022-02-19 18:37+0500\n"
+"PO-Revision-Date: 2022-02-18 16:22+0500\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: ru\n"
+"Language-Team: ru <LL@li.org>\n"
+"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && "
+"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: keyboards.py:20
+msgid "click"
+msgstr "Клик"
+
+#: keyboards.py:29
+msgid "My user id"
+msgstr "Мой user id"
+
+#: keyboards.py:30
+msgid "My user name"
+msgstr "Мой user name"
+
+#: keyboards.py:31
+msgid "My first name"
+msgstr "Мой first name"
+
+#: main.py:97
+msgid ""
+"Hello, {user_fist_name}!\n"
+"This is the example of multilanguage bot.\n"
+"Available commands:\n"
+"\n"
+"/lang - change your language\n"
+"/plural - pluralization example\n"
+"/menu - text menu example"
+msgstr ""
+"Привет, {user_fist_name}!\n"
+"Это пример мультиязычного бота.\n"
+"Доступные команды:\n"
+"\n"
+"/lang - изменить язык\n"
+"/plural - пример плюрализации\n"
+"/menu - Пример текстового меню"
+
+#: main.py:121
+msgid "Language has been changed"
+msgstr "Язык был сменён"
+
+#: main.py:130 main.py:150
+msgid "You have {number} click"
+msgid_plural "You have {number} clicks"
+msgstr[0] "У вас {number} клик"
+msgstr[1] "У вас {number} клика"
+msgstr[2] "У вас {number} кликов"
+
+#: main.py:135 main.py:155
+msgid ""
+"This is clicker.\n"
+"\n"
+msgstr ""
+"Это кликер.\n"
+"\n"
+
+#: main.py:163
+msgid "This is ReplyKeyboardMarkup menu example in multilanguage bot."
+msgstr "Это пример ReplyKeyboardMarkup меню в мультиязычном боте."
+
+#: main.py:203
+msgid "Seems you confused language"
+msgstr "Кажется, вы перепутали язык"
+

examples/middleware/class_based/i18n_middleware/locales/uz_Latn/LC_MESSAGES/messages.po

@@ -0,0 +1,80 @@
+# Uzbek (Latin) translations for PROJECT.
+# Copyright (C) 2022 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2022-02-19 18:37+0500\n"
+"PO-Revision-Date: 2022-02-18 16:22+0500\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: uz_Latn\n"
+"Language-Team: uz_Latn <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: keyboards.py:20
+msgid "click"
+msgstr "clik"
+
+#: keyboards.py:29
+msgid "My user id"
+msgstr "Mani user id"
+
+#: keyboards.py:30
+msgid "My user name"
+msgstr "Mani user name"
+
+#: keyboards.py:31
+msgid "My first name"
+msgstr "Mani first name"
+
+#: main.py:97
+msgid ""
+"Hello, {user_fist_name}!\n"
+"This is the example of multilanguage bot.\n"
+"Available commands:\n"
+"\n"
+"/lang - change your language\n"
+"/plural - pluralization example\n"
+"/menu - text menu example"
+msgstr ""
+"Salom, {user_fist_name}!\n"
+"Bu multilanguage bot misoli.\n"
+"Mavjud buyruqlar:\n"
+"\n"
+"/lang - tilni ozgartirish\n"
+"/plural - pluralizatsiya misoli\n"
+"/menu - text menu misoli"
+
+#: main.py:121
+msgid "Language has been changed"
+msgstr "Til ozgartirildi"
+
+#: main.py:130 main.py:150
+msgid "You have {number} click"
+msgid_plural "You have {number} clicks"
+msgstr[0] "Sizda {number}ta clik"
+msgstr[1] "Sizda {number}ta clik"
+
+#: main.py:135 main.py:155
+msgid ""
+"This is clicker.\n"
+"\n"
+msgstr ""
+"Bu clicker.\n"
+"\n"
+
+#: main.py:163
+msgid "This is ReplyKeyboardMarkup menu example in multilanguage bot."
+msgstr "Bu multilanguage bot da replykeyboardmarkup menyu misoli."
+
+#: main.py:203
+msgid "Seems you confused language"
+msgstr "Tilni adashtirdiz"
+

examples/middleware/class_based/i18n_middleware/main.py

@@ -0,0 +1,211 @@
+"""
+In this example you will learn how to adapt your bot to different languages
+Using built-in middleware I18N.
+
+You need to install babel package 'https://pypi.org/project/Babel/'
+Babel provides a command-line interface for working with message catalogs
+After installing babel package you have a script called 'pybabel'
+Too see all the commands open terminal and type 'pybabel --help'
+Full description for pybabel commands can be found here: 'https://babel.pocoo.org/en/latest/cmdline.html'
+
+Create a directory 'locales' where our translations will be stored
+
+First we need to extract texts:
+    pybabel extract -o locales/{domain_name}.pot --input-dirs .
+{domain_name}.pot - is the file where all translations are saved
+The name of this file should be the same as domain which you pass to I18N class
+In this example domain_name will be 'messages'
+
+For gettext (singular texts) we use '_' alias and it works perfect
+You may also you some alias for ngettext (plural texts) but you can face with a problem that
+your plural texts are not being extracted
+That is because by default 'pybabel extract' recognizes the following keywords:
+ _, gettext, ngettext, ugettext, ungettext, dgettext, dngettext, N_
+To add your own keyword you can use '-k' flag
+In this example for 'ngettext' i will assign double underscore alias '__'
+
+Full command with pluralization support will look so:
+    pybabel extract -o locales/{domain_name}.pot -k __:1,2 --input-dirs .
+
+Then create directories with translations (get list of all locales: 'pybabel --list-locales'):
+    pybabel init -i locales/{domain_name}.pot -d locales -l en
+    pybabel init -i locales/{domain_name}.pot -d locales -l ru
+    pybabel init -i locales/{domain_name}.pot -d locales -l uz_Latn
+
+Now you can translate the texts located in locales/{language}/LC_MESSAGES/{domain_name}.po
+After you translated all the texts you need to compile .po files:
+    pybabel compile -d locales
+
+When you delete/update your texts you also need to update them in .po files:
+    pybabel extract -o locales/{domain_name}.pot -k __:1,2 --input-dirs .
+    pybabel update -i locales/{domain_name}.pot -d locales
+    - translate
+    pybabel compile -d locales
+
+If you have any exceptions check:
+    - you have installed babel
+    - translations are ready, so you just compiled it
+    - in the commands above you replaced {domain_name} to messages
+    - you are writing commands from correct path in terminal
+"""
+
+import asyncio
+from typing import Union
+
+import keyboards
+from i18n_base_middleware import I18N
+from telebot import TeleBot
+from telebot import types, StateMemoryStorage
+from telebot.custom_filters import TextMatchFilter, TextFilter
+
+class I18NMiddleware(I18N):
+
+    def process_update_types(self) -> list:
+        """
+        Here you need to return a list of update types which you want to be processed
+        """
+        return ['message', 'callback_query']
+
+    def get_user_language(self, obj: Union[types.Message, types.CallbackQuery]):
+        """
+        This method is called when new update comes (only updates which you return in 'process_update_types' method)
+        Returned language will be used in 'pre_process' method of parent class
+        Returned language will be set to context language variable.
+        If you need to get translation with user's actual language you don't have to pass it manually
+        It will be automatically passed from context language value.
+        However if you need some other language you can always pass it.
+        """
+
+        user_id = obj.from_user.id
+
+        if user_id not in users_lang:
+            users_lang[user_id] = 'en'
+
+        return users_lang[user_id]
+
+
+storage = StateMemoryStorage()
+bot = TeleBot("", state_storage=storage, use_class_middlewares=True)
+
+i18n = I18NMiddleware(translations_path='locales', domain_name='messages')
+_ = i18n.gettext  # for singular translations
+__ = i18n.ngettext  # for plural translations
+
+# These are example storages, do not use it in a production development
+users_lang = {}
+users_clicks = {}
+
+@bot.message_handler(commands=['start'])
+def start_handler(message: types.Message):
+    text = _("Hello, {user_fist_name}!\n"
+             "This is the example of multilanguage bot.\n"
+             "Available commands:\n\n"
+             "/lang - change your language\n"
+             "/plural - pluralization example\n"
+             "/menu - text menu example")
+
+    # remember don't use f string for interpolation, use .format method instead
+    text = text.format(user_fist_name=message.from_user.first_name)
+    bot.send_message(message.from_user.id, text)
+
+
+@bot.message_handler(commands=['lang'])
+def change_language_handler(message: types.Message):
+    bot.send_message(message.chat.id, "Choose language\nВыберите язык\nTilni tanlang",
+                     reply_markup=keyboards.languages_keyboard())
+
+
+@bot.callback_query_handler(func=None, text=TextFilter(contains=['en', 'ru', 'uz_Latn']))
+def language_handler(call: types.CallbackQuery):
+    lang = call.data
+    users_lang[call.from_user.id] = lang
+
+    # When you changed user language, you have to pass it manually beacause it is not changed in context
+    bot.edit_message_text(_("Language has been changed", lang=lang), call.from_user.id, call.message.id)
+
+
+@bot.message_handler(commands=['plural'])
+def pluralization_handler(message: types.Message):
+    if not users_clicks.get(message.from_user.id):
+        users_clicks[message.from_user.id] = 0
+    clicks = users_clicks[message.from_user.id]
+
+    text = __(
+        singular="You have {number} click",
+        plural="You have {number} clicks",
+        n=clicks
+    )
+    text = _("This is clicker.\n\n") + text.format(number=clicks)
+
+    bot.send_message(message.chat.id, text, reply_markup=keyboards.clicker_keyboard(_))
+
+
+@bot.callback_query_handler(func=None, text=TextFilter(equals='click'))
+def click_handler(call: types.CallbackQuery):
+    if not users_clicks.get(call.from_user.id):
+        users_clicks[call.from_user.id] = 1
+    else:
+        users_clicks[call.from_user.id] += 1
+
+    clicks = users_clicks[call.from_user.id]
+
+    text = __(
+        singular="You have {number} click",
+        plural="You have {number} clicks",
+        n=clicks
+    )
+    text = _("This is clicker.\n\n") + text.format(number=clicks)
+
+    bot.edit_message_text(text, call.from_user.id, call.message.message_id,
+                          reply_markup=keyboards.clicker_keyboard(_))
+
+
+@bot.message_handler(commands=['menu'])
+def menu_handler(message: types.Message):
+    text = _("This is ReplyKeyboardMarkup menu example in multilanguage bot.")
+    bot.send_message(message.chat.id, text, reply_markup=keyboards.menu_keyboard(_))
+
+
+# For lazy tranlations
+# lazy gettext is used when you don't know user's locale
+# It can be used for example to handle text buttons in multilanguage bot
+# The actual translation will be delayed until update comes and context language is set
+l_ = i18n.lazy_gettext
+
+
+# Handlers below will handle text according to user's language
+@bot.message_handler(text=l_("My user id"))
+def return_user_id(message: types.Message):
+    bot.send_message(message.chat.id, str(message.from_user.id))
+
+
+@bot.message_handler(text=l_("My user name"))
+def return_user_id(message: types.Message):
+    username = message.from_user.username
+    if not username:
+        username = '-'
+    bot.send_message(message.chat.id, username)
+
+
+# You can make it case-insensitive
+@bot.message_handler(text=TextFilter(equals=l_("My first name"), ignore_case=True))
+def return_user_id(message: types.Message):
+    bot.send_message(message.chat.id, message.from_user.first_name)
+
+
+all_menu_texts = []
+for language in i18n.available_translations:
+    for menu_text in ("My user id", "My user name", "My first name"):
+        all_menu_texts.append(_(menu_text, language))
+
+
+# When user confused language. (handles all menu buttons texts)
+@bot.message_handler(text=TextFilter(contains=all_menu_texts, ignore_case=True))
+def missed_message(message: types.Message):
+    bot.send_message(message.chat.id, _("Seems you confused language"), reply_markup=keyboards.menu_keyboard(_))
+
+
+if __name__ == '__main__':
+    bot.setup_middleware(i18n)
+    bot.add_custom_filter(TextMatchFilter())
+    asyncio.run(bot.infinity_polling())

examples/middleware/function_based/i18n_gettext/i18n_class.py

@@ -0,0 +1,77 @@
+import gettext
+import os
+import threading
+
+
+class I18N:
+    """
+    This class provides high-level tool for internationalization
+    It is based on gettext util.
+    """
+
+    context_lang = threading.local()
+
+    def __init__(self, translations_path, domain_name: str):
+        self.path = translations_path
+        self.domain = domain_name
+        self.translations = self.find_translations()
+
+    @property
+    def available_translations(self):
+        return list(self.translations)
+
+    def gettext(self, text: str, lang: str = None):
+        """
+        Singular translations
+        """
+
+        if lang is None:
+            lang = self.context_lang.language
+
+        if lang not in self.translations:
+            return text
+
+        translator = self.translations[lang]
+        return translator.gettext(text)
+
+    def ngettext(self, singular: str, plural: str, lang: str = None, n=1):
+        """
+        Plural translations
+        """
+        if lang is None:
+            lang = self.context_lang.language
+
+        if lang not in self.translations:
+            if n == 1:
+                return singular
+            return plural
+
+        translator = self.translations[lang]
+        return translator.ngettext(singular, plural, n)
+
+
+    def find_translations(self):
+        """
+        Looks for translations with passed 'domain' in passed 'path'
+        """
+        if not os.path.exists(self.path):
+            raise RuntimeError(f"Translations directory by path: {self.path!r} was not found")
+
+        result = {}
+
+        for name in os.listdir(self.path):
+            translations_path = os.path.join(self.path, name, 'LC_MESSAGES')
+
+            if not os.path.isdir(translations_path):
+                continue
+
+            po_file = os.path.join(translations_path, self.domain + '.po')
+            mo_file = po_file[:-2] + 'mo'
+
+            if os.path.isfile(po_file) and not os.path.isfile(mo_file):
+                raise FileNotFoundError(f"Translations for: {name!r} were not compiled!")
+
+            with open(mo_file, 'rb') as file:
+                result[name] = gettext.GNUTranslations(file)
+
+        return result

examples/middleware/function_based/i18n_gettext/keyboards.py

@@ -0,0 +1,23 @@
+from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton
+
+
+def languages_keyboard():
+    return InlineKeyboardMarkup(
+        keyboard=[
+            [
+                InlineKeyboardButton(text="English", callback_data='en'),
+                InlineKeyboardButton(text="Русский", callback_data='ru'),
+                InlineKeyboardButton(text="O'zbekcha", callback_data='uz_Latn')
+            ]
+        ]
+    )
+
+
+def clicker_keyboard(_):
+    return InlineKeyboardMarkup(
+        keyboard=[
+            [
+                InlineKeyboardButton(text=_("click"), callback_data='click'),
+            ]
+        ]
+    )

examples/middleware/function_based/i18n_gettext/locales/en/LC_MESSAGES/messages.po

@@ -0,0 +1,50 @@
+# English translations for PROJECT.
+# Copyright (C) 2022 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2022-02-18 17:54+0500\n"
+"PO-Revision-Date: 2022-02-18 16:22+0500\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: en\n"
+"Language-Team: en <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: keyboards.py:20
+msgid "click"
+msgstr ""
+
+#: main.py:78
+msgid ""
+"Hello, {user_fist_name}!\n"
+"This is the example of multilanguage bot.\n"
+"Available commands:\n"
+"\n"
+"/lang - change your language\n"
+"/plural - pluralization example"
+msgstr ""
+
+#: main.py:102
+msgid "Language has been changed"
+msgstr ""
+
+#: main.py:114
+#, fuzzy
+msgid "You have {number} click"
+msgid_plural "You have {number} clicks"
+msgstr[0] ""
+msgstr[1] ""
+
+#: main.py:120
+msgid ""
+"This is clicker.\n"
+"\n"
+msgstr ""

examples/middleware/function_based/i18n_gettext/locales/ru/LC_MESSAGES/messages.po

@@ -0,0 +1,59 @@
+# Russian translations for PROJECT.
+# Copyright (C) 2022 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2022-02-18 17:54+0500\n"
+"PO-Revision-Date: 2022-02-18 16:22+0500\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: ru\n"
+"Language-Team: ru <LL@li.org>\n"
+"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && "
+"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: keyboards.py:20
+msgid "click"
+msgstr "Клик"
+
+#: main.py:78
+msgid ""
+"Hello, {user_fist_name}!\n"
+"This is the example of multilanguage bot.\n"
+"Available commands:\n"
+"\n"
+"/lang - change your language\n"
+"/plural - pluralization example"
+msgstr ""
+"Привет, {user_fist_name}!\n"
+"Это пример мультиязычного бота.\n"
+"Доступные команды:\n"
+"\n"
+"/lang - изменить язык\n"
+"/plural - пример плюрализации"
+
+#: main.py:102
+msgid "Language has been changed"
+msgstr "Язык был сменён"
+
+#: main.py:114
+msgid "You have {number} click"
+msgid_plural "You have {number} clicks"
+msgstr[0] "У вас {number} клик"
+msgstr[1] "У вас {number} клика"
+msgstr[2] "У вас {number} кликов"
+
+#: main.py:120
+msgid ""
+"This is clicker.\n"
+"\n"
+msgstr ""
+"Это кликер.\n"
+"\n"

examples/middleware/function_based/i18n_gettext/locales/uz_Latn/LC_MESSAGES/messages.po

@@ -0,0 +1,57 @@
+# Uzbek (Latin) translations for PROJECT.
+# Copyright (C) 2022 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2022-02-18 17:54+0500\n"
+"PO-Revision-Date: 2022-02-18 16:22+0500\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: uz_Latn\n"
+"Language-Team: uz_Latn <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.1\n"
+
+#: keyboards.py:20
+msgid "click"
+msgstr "clik"
+
+#: main.py:78
+msgid ""
+"Hello, {user_fist_name}!\n"
+"This is the example of multilanguage bot.\n"
+"Available commands:\n"
+"\n"
+"/lang - change your language\n"
+"/plural - pluralization example"
+msgstr ""
+"Salom, {user_fist_name}!\n"
+"Bu multilanguage bot misoli.\n"
+"Mavjud buyruqlar:\n"
+"\n"
+"/lang - tilni ozgartirish\n"
+"/plural - pluralizatsiya misoli"
+
+#: main.py:102
+msgid "Language has been changed"
+msgstr "Til ozgartirildi"
+
+#: main.py:114
+msgid "You have {number} click"
+msgid_plural "You have {number} clicks"
+msgstr[0] "Sizda {number}ta clik"
+msgstr[1] "Sizda {number}ta clik"
+
+#: main.py:120
+msgid ""
+"This is clicker.\n"
+"\n"
+msgstr ""
+"Bu clicker.\n"
+"\n"

examples/middleware/function_based/i18n_gettext/main.py

@@ -0,0 +1,134 @@
+"""
+In this example you will learn how to adapt your bot to different languages
+Using built-in class I18N.
+You need to install babel package 'https://pypi.org/project/Babel/'
+Babel provides a command-line interface for working with message catalogs
+After installing babel package you have a script called 'pybabel'
+Too see all the commands open terminal and type 'pybabel --help'
+Full description for pybabel commands can be found here: 'https://babel.pocoo.org/en/latest/cmdline.html'
+Create a directory 'locales' where our translations will be stored
+First we need to extract texts:
+    pybabel extract -o locales/{domain_name}.pot --input-dirs .
+{domain_name}.pot - is the file where all translations are saved
+The name of this file should be the same as domain which you pass to I18N class
+In this example domain_name will be 'messages'
+For gettext (singular texts) we use '_' alias and it works perfect
+You may also you some alias for ngettext (plural texts) but you can face with a problem that
+your plural texts are not being extracted
+That is because by default 'pybabel extract' recognizes the following keywords:
+ _, gettext, ngettext, ugettext, ungettext, dgettext, dngettext, N_
+To add your own keyword you can use '-k' flag
+In this example for 'ngettext' i will assign double underscore alias '__'
+Full command with pluralization support will look so:
+    pybabel extract -o locales/{domain_name}.pot -k __:1,2 --input-dirs .
+Then create directories with translations (get list of all locales: 'pybabel --list-locales'):
+    pybabel init -i locales/{domain_name}.pot -d locales -l en
+    pybabel init -i locales/{domain_name}.pot -d locales -l ru
+    pybabel init -i locales/{domain_name}.pot -d locales -l uz_Latn
+Now you can translate the texts located in locales/{language}/LC_MESSAGES/{domain_name}.po
+After you translated all the texts you need to compile .po files:
+    pybabel compile -d locales
+When you delete/update your texts you also need to update them in .po files:
+    pybabel extract -o locales/{domain_name}.pot -k __:1,2 --input-dirs .
+    pybabel update -i locales/{domain_name}.pot -d locales
+    - translate
+    pybabel compile -d locales
+If you have any exceptions check:
+    - you have installed babel
+    - translations are ready, so you just compiled it
+    - in the commands above you replaced {domain_name} to messages
+    - you are writing commands from correct path in terminal
+"""
+
+from telebot import TeleBot, types, custom_filters
+from telebot import apihelper
+from telebot.storage.memory_storage import StateMemoryStorage
+
+import keyboards
+from i18n_class import I18N
+
+apihelper.ENABLE_MIDDLEWARE = True
+storage = StateMemoryStorage()
+# IMPORTANT! This example works only if polling is non-threaded.
+bot = TeleBot("", state_storage=storage, threaded=False)
+
+i18n = I18N(translations_path='locales', domain_name='messages')
+_ = i18n.gettext  # for singular translations
+__ = i18n.ngettext  # for plural translations
+
+# These are example storages, do not use it in a production development
+users_lang = {}
+users_clicks = {}
+
+
+@bot.middleware_handler(update_types=['message', 'callback_query'])
+def set_contex_language(bot_instance, message):
+    i18n.context_lang.language = users_lang.get(message.from_user.id, 'en')
+
+
+@bot.message_handler(commands=['start'])
+def start_handler(message: types.Message):
+    text = _("Hello, {user_fist_name}!\n"
+             "This is the example of multilanguage bot.\n"
+             "Available commands:\n\n"
+             "/lang - change your language\n"
+             "/plural - pluralization example")
+
+    # remember don't use f string for interpolation, use .format method instead
+    text = text.format(user_fist_name=message.from_user.first_name)
+    bot.send_message(message.from_user.id, text)
+
+
+@bot.message_handler(commands=['lang'])
+def change_language_handler(message: types.Message):
+    bot.send_message(message.chat.id, "Choose language\nВыберите язык\nTilni tanlang",
+                     reply_markup=keyboards.languages_keyboard())
+
+
+@bot.callback_query_handler(func=None, text=custom_filters.TextFilter(contains=['en', 'ru', 'uz_Latn']))
+def language_handler(call: types.CallbackQuery):
+    lang = call.data
+    users_lang[call.from_user.id] = lang
+
+    # When you change user's language, pass language explicitly coz it's not changed in context
+    bot.edit_message_text(_("Language has been changed", lang=lang), call.from_user.id, call.message.id)
+    bot.delete_state(call.from_user.id)
+
+
+@bot.message_handler(commands=['plural'])
+def pluralization_handler(message: types.Message):
+    if not users_clicks.get(message.from_user.id):
+        users_clicks[message.from_user.id] = 0
+    clicks = users_clicks[message.from_user.id]
+
+    text = __(
+        singular="You have {number} click",
+        plural="You have {number} clicks",
+        n=clicks,
+    )
+    text = _("This is clicker.\n\n") + text.format(number=clicks)
+    bot.send_message(message.chat.id, text, reply_markup=keyboards.clicker_keyboard(_))
+
+
+@bot.callback_query_handler(func=None, text=custom_filters.TextFilter(equals='click'))
+def click_handler(call: types.CallbackQuery):
+    if not users_clicks.get(call.from_user.id):
+        users_clicks[call.from_user.id] = 1
+    else:
+        users_clicks[call.from_user.id] += 1
+
+    clicks = users_clicks[call.from_user.id]
+
+    text = __(
+        singular="You have {number} click",
+        plural="You have {number} clicks",
+        n=clicks
+    )
+    text = _("This is clicker.\n\n") + text.format(number=clicks)
+    bot.edit_message_text(text, call.from_user.id, call.message.message_id,
+                          reply_markup=keyboards.clicker_keyboard(_))
+
+
+if __name__ == '__main__':
+    bot.add_custom_filter(custom_filters.TextMatchFilter())
+    bot.infinity_polling()

examples/multibot/README.MD

@@ -0,0 +1,17 @@
+You probably have seen bots which allow you to send them token of your bot and then handle updates providing some functionality for your bot.
+<br>
+This type of bots are called <b>multibots</b>. They are created using webhooks.
+<br>
+
+This is the example of simple multibot.<br>
+In order to reproduce this example you need to have <b>domain and ssl connection</b>.
+<br>
+If you have, go to config.py and specify your data.
+<br>
+There is also file called <b>nginx_conf.conf</b>,  we will use nginx as proxy-server and this file is example nginx.conf file.
+<br>
+Make sure that server_name and port are the same in both config and nginx_conf
+<br>
+(nginx_conf.conf IS NOT complete, you would probably use tools like certbot to add ssl connection to it)
+<br>
+Also, in this example I used dictionary as tokens storage, but in production you should use database so that you can re-set webhooks in case bot restarts.

examples/multibot/config.py

@@ -0,0 +1,6 @@
+MAIN_BOT_TOKEN = "your_main_bot_token"
+
+WEBHOOK_HOST = "your_domain.com"
+WEBHOOK_PATH = "telegram_webhook"
+WEBAPP_HOST = "0.0.0.0"
+WEBAPP_PORT = 3500

examples/multibot/handlers.py

@@ -0,0 +1,14 @@
+from telebot import types, TeleBot
+
+
+def hello_handler(message: types.Message, bot: TeleBot):
+    bot.send_message(message.chat.id, "Hi :)")
+
+
+def echo_handler(message: types.Message, bot: TeleBot):
+    bot.send_message(message.chat.id, message.text)
+
+
+def register_handlers(bot: TeleBot):
+    bot.register_message_handler(hello_handler, func=lambda message: message.text == 'Hello', pass_bot=True)
+    bot.register_message_handler(echo_handler, pass_bot=True)

examples/multibot/main.py

@@ -0,0 +1,48 @@
+from flask import Flask
+from flask import request, abort
+from telebot import TeleBot, types, util
+from handlers import register_handlers
+
+import config
+
+main_bot = TeleBot(config.MAIN_BOT_TOKEN)
+app = Flask(__name__)
+tokens = {config.MAIN_BOT_TOKEN: True}
+
+
+@app.route(f"/{config.WEBHOOK_PATH}/<token>", methods=['POST'])
+def webhook(token: str):
+    if not tokens.get(token):
+        return abort(404)
+
+    if request.headers.get('content-type') != 'application/json':
+        return abort(403)
+
+    json_string = request.get_data().decode('utf-8')
+    update = types.Update.de_json(json_string)
+    if token == main_bot.token:
+        main_bot.process_new_updates([update])
+        return ''
+
+    from_update_bot = TeleBot(token)
+    register_handlers(from_update_bot)
+    from_update_bot.process_new_updates([update])
+    return ''
+
+
+@main_bot.message_handler(commands=['add_bot'])
+def add_bot(message: types.Message):
+    token = util.extract_arguments(message.text)
+    tokens[token] = True
+
+    new_bot = TeleBot(token)
+    new_bot.delete_webhook()
+    new_bot.set_webhook(f"{config.WEBHOOK_HOST}/{config.WEBHOOK_PATH}/{token}")
+
+    new_bot.send_message(message.chat.id, "Webhook was set.")
+
+
+if __name__ == '__main__':
+    main_bot.delete_webhook()
+    main_bot.set_webhook(f"{config.WEBHOOK_HOST}/{config.WEBHOOK_PATH}/{config.MAIN_BOT_TOKEN}")
+    app.run(host=config.WEBAPP_HOST, port=config.WEBAPP_PORT)