telegram-django-bot 1.1.0
Telegram Django Bot
License: MIT
Requires Python: >=3.8

Telegram Django Bot
============================

This library provides a Python high-level interface for creating Telegram Bots. It standardizes the coding in the best
practice of the web development. The library is based on `Django <https://www.djangoproject.com/>`_ and `Python-Telegram-Bot <https://python-telegram-bot.org/>`_.
It also provides viewset interface for managing data with.

If you start a new project, you could use `Telegram django bot template <https://github.com/alexanderaleskin/telergam_django_bot_template>`_ with preconfigured settings.

Install
------------

You can install via ``pip``:

.. code-block:: shell

    $ pip install telegram_django_bot


Then you can configure it in your app:


1. Add "telegram_django_bot" to your INSTALLED_APPS setting like this:

.. code-block:: python

    INSTALLED_APPS = [
        ...
        'telegram_django_bot',
        'django_json_widget', # needed for django admin site
    ]


If you are planning to use Django in asynchronous mode, then you need to set ``DJANGO_ALLOW_ASYNC_UNSAFE = True`` (otherwise DB writings will be failed).


2. Run ``python manage.py migrate`` to create the telegram_django_bot models (checked that the ``AUTH_USER_MODEL`` selected
in settings).


3. Set up constants in Django settings file:

* ``TELEGRAM_ROOT_UTRLCONF`` -  (same as ``ROOT_URLCONF`` for WEB) for using django notation in callback (routing) (strongly recommended)

  Not necessary, but useful settings:

* ``TELEGRAM_TOKEN`` - for adding "triggers",
* ``TELEGRAM_TEST_USER_IDS`` - for adding tests for your bot,
* Make sure, that ``LANGUAGE_CODE``, ``LANGUAGE_CODE``, ``USE_I18N`` are also used in the library for language localization.


4. This step connects ``Telegram Django Bot`` with ``Python-Telegram-Bot``. Add ``RouterCallbackMessageCommandHandler`` in handlers for using TELEGRAM_ROOT_UTRLCONF :

.. code-block:: python

    updater = Updater(bot=TG_DJ_Bot(settings.TELEGRAM_TOKEN))
    updater.dispatcher.add_handler(RouterCallbackMessageCommandHandler())

or in 20.x version :

.. code-block:: python

    bot = TG_DJ_Bot(settings.TELEGRAM_TOKEN)
    application = ApplicationBuilder().bot(bot).build()
    application.add_handler(RouterCallbackMessageCommandHandler())

    



Quick start
------------


Normally, Python-Telegram-Bot gives the next opportunities for bot creation:

* Python Interface for communication with Telegram API;
* Web service to get updates from telegram;

and Django:

* Django ORM  (communication with Database);
* Administration panel for management.


Telegram Django Bot provides next special opportunities:

* using Viewsets (typical action with model (create, update, list, delete));
* using Django localization.
* using function routing like urls routing in Django.
* creating general menu items with no-coding (through Django Admin Panel);
* collecting stats from user actions in the bot;
* other useful staff.


The key feature of the lib is ``TelegramViewSet`` - a class for managing Django ORM model. It is designed in a
similar way as `Django rest framework Viewset <https://www.django-rest-framework.org/api-guide/viewsets/>`_ , but has
a significant difference: while DRF Viewset provides a response in serializable format (usually in json format) to frontend app, TelegramViewSet
provides a response to the user in telegram interface in message format with buttons. So, you will manage data and receive
responses in human format by executing TelegramViewSet method. The methods use some kind of templates for generating human
responses (it is possible to overwrite these templates). By default, TelegramViewSet has 5 methods:

* ``create`` - create a new instance of the specified ORM model;
* ``change`` - update instance fields of specified ORM model;
* ``show_elem`` - show fields of the element and buttons with actions of this instance;
* ``show_list`` - show list of model elements (with pagination);
* ``delete`` - delete the instance


So, if, for example, you have a model of some *request* in your project:

.. code-block:: python

    from django.db import models

    class Request(models.Model):
        text = models.TextField()
        importance_level = models.PositiveSmallIntegerField()  # for example it will be integer field
        project = models.ForeignKey('Project', on_delete=models.CASCADE)
        tags = models.ManyToManyField('Tags')


The next piece of code gives the opportunity for full managing (create, update, show, delete) of this model from Telegram:

.. code-block:: python

    from telegram_django_bot import forms as td_forms
    from telegram_django_bot.td_viewset import TelegramViewSet


    class RequestForm(td_forms.TelegramModelForm):
        class Meta:
            model = Request
            fields = ['text', 'importance_level', 'project', 'tags']


    class RequestViewSet(TelegramViewSet):
        model_form = RequestForm
        queryset = Request.objects.all()
        viewset_name = 'Request'


If you need, you can add extra actions to RequestViewSet for managing (see details information below) or change existing functions.
There are several parameters and secondary functions in TelegramViewSet for customizing logic if it is necessary.

In this example, ``TelegramModelForm`` was used. TelegramModelForm is a descendant of Django ModelForm. So, you could use
labels, clean functions and other parameters and functions for managing logic and displaying.


TelegramViewSet is designed to answer next user actions: clicking buttons and sometimes sending messages. The library imposes
`Django URL notation <https://docs.djangoproject.com/en/4.1/topics/http/urls/>`_ for mapping user actions to TelegramViewSet methods (or usual handlers).
Usually, for correct mapping you just need to set ``TELEGRAM_ROOT_UTRLCONF`` and use ``RouterCallbackMessageCommandHandler`` in
dispatcher as it is mentioned above in the *Install paragraph*.

For correct mapping *RequestViewSet*  you should write in the TELEGRAM_ROOT_UTRLCONF file something like this:

.. code-block:: python

    from django.urls import re_path
    from .views import RequestViewSet

    urlpatterns = [
        re_path(r"^rv/", RequestViewSet, name='RequestViewSet'),
    ]

From this point, you can use buttons with callback data "rv/<function_code>" for function calling. For example:

* "rv/cr" - RequestViewSet.create method;
* "rv/sl" - RequestViewSet.show_list;


See these examples for great understanding:


1. `Telegram django bot template <https://github.com/alexanderaleskin/telergam_django_bot_template>`_
2. `Drive Bot <https://github.com/alexanderaleskin/drive_bot>`_


Deep in details
------------------

In this chapter, we will analyze how everything works. The main task of the library is to unify the code and
provide frequently used functions for developing a bot, that is why a lot of logic is based on resources and paradigms
of Django <https://www.djangoproject.com/>`_ and `Python-Telegram-Bot <https://python-telegram-bot.org/>`_ . Let's analyze
key features of the library on the example of `Telegram django bot template <https://github.com/alexanderaleskin/telergam_django_bot_template>`_ .

.. important::

    The template is based on 13.x Python-Telegram-Bot version (synchronous version). So, the next examples is suitable for that version. For use with 20.x versions you need to do some modification.


Since Telegram bots are designed as a tool for responding to user requests, writing a bot begins
from the user request handler. For this, the standard tools of the Python-Telegram-Bot library are used ﹣
``telegram.ext.Update``:

.. code-block:: python

     from telegram.ext import Updater

     def main():
         ...

         updater = Updater(bot=TG_DJ_Bot(TELEGRAM_TOKEN))
         add_handlers(updater)
         updater.start_polling()
         updater.idle()

     if __name__ == '__main__':
         main()


As indicated in the example, to run the bot (Update) you need to specify a few things (the ``Python-Telegram-Bot`` library standard):

1. an instance of the ``telegram.Bot`` model with the specified API token. In this case, a descendant ``telegram_django_bot.tg_dj_bot.TG_DJ_Bot``
of the ``telegram.Bot`` class is used. It has additional functionality for convenience (we will return to it later);
2. Handlers that will be called in response to user requests.

In the example, the list of handlers is specified in the ``add_handlers`` function:



.. code-block:: python

     from telegram_django_bot.routing import RouterCallbackMessageCommandHandler

     ...

     def add_handlers(updater: Updater):
         dp=updater.dispatcher
         dp.add_handler(RouterCallbackMessageCommandHandler())


The example adds 1 super handler ``RouterCallbackMessageCommandHandler``, which allows you to write handlers
in the style of handling link requests in the same way as it is done in ``Django``. ``RouterCallbackMessageCommandHandler`` allows you to handle
messages, user commands and button clicks by users. In other words, it replaces the handlers
``MessageHandler, CommandHandler, CallbackQueryHandler`` . Since the ``Telegram Django Bot`` library is an extension,
it does not prohibit the use of standard handlers of the ``Python-Telegram-Bot`` library for handle user requests.
(sometimes it is simply necessary, for example, if you need to process responses to surveys (you need to use PollAnswerHandler)).

`Django notation <https://docs.djangoproject.com/en/4.1/topics/http/urls/>`_ of routing handlers is that paths to handlers are described in a separate file or files.
As in the ``Django`` standard, the main file (root) for routing is specified in the project settings, where paths to handlers or paths to groups of handlers are stored.
The ``TELEGRAM_ROOT_UTRLCONF`` (same as ``ROOT_URLCONF`` for WEB) attribute is used to specify the path to the file. In the example template, we have the following settings:


``bot_conf.settings.py``:

.. code-block:: python

     TELEGRAM_ROOT_UTRLCONF = 'bot_conf.utrls'


``bot_conf.utrls.py``:

.. code-block:: python

     from django.urls import re_path, include

     urlpatterns = [
         re_path('', include(('base.utrls', 'base'), namespace='base')),
     ]


That is, only 1 group of handlers is connected in the file (which corresponds to the ``base`` application at the conceptual level). You can
add several groups as well, this can be convenient if you create several folders (applications) for storing code.
As you can see ``Django`` functions are imported without any redefinition.

There is following code in the specified included file ``base.utrls.py`` :


.. code-block:: python

    from django.urls import re_path
    from django.conf import settings
    from telegram_django_bot.user_viewset import UserViewSet
    from .views import start, BotMenuElemViewSet, some_debug_func


    urlpatterns = [
        re_path('start', start, name='start'),
        re_path('main_menu', start, name='start'),

        re_path('sb/', BotMenuElemViewSet, name='BotMenuElemViewSet'),
        re_path('us/', UserViewSet, name='UserViewSet'),
    ]


    if settings.DEBUG:
        urlpatterns += [
            re_path('some_debug_func', some_debug_func, name='some_debug_func'),
        ]

So, the end handlers (which are defined in the ``base.views.py`` file) are specified here. Thus, if
user in the bot writes the command ``/start``, then ``Updater`` receives a message about the user's action and selects
the appropriate for the request handler ``RouterCallbackMessageCommandHandler`` from a set of handlers. Then the
handler ``RouterCallbackMessageCommandHandler`` searches the appropriate for string ``/start`` path in ``utrls`` and
finds a suitable path ``'' + 'start'``, and then executes corresponding start function.

This distribution of handlers allows you to group part of the handlers into modules and quickly connect or
change them, while not being afraid of confusion which handlers need to be called, as it can be if all paths from
different modules to handlers are described in one place as required by ``Python-Telegram-Bot``.

In this example file ``base.utrls.py`` also ViewSets are used in addition to simple handler functions like ``def start`` and ``def some_debug_func``.
ViewSet is an aggregator of several functions. The concept of it is that you quite often need to apply
the same operations for a dataset, such as create, update, show, delete an example of dataset.
There is the class ``telegram_django_bot.td_viewset.TelegramViewSet`` in the library  for such purposes. The class manages
the Django ORM database model. ``TelegramViewSet`` has 5 functions for managing the model:


========= ======== ===========================
 Метод     UTRL      Description
--------- -------- ---------------------------
create     cr       Create model
change     up       Change model attributes
delete     de       Deleting a model
show_elem  se       Display a model
show_list  sl       Display a list of models
========= ======== ===========================

Thus, if we want to call the ``BotMenuElemViewSet.create`` method to create an element, we need to use
path 'sb/cr', whereby the first part of the path 'sb/'  the router ``RouterCallbackMessageCommandHandler`` will execute
the ``BotMenuElemViewSet`` class, namely the ``TelegramViewSet.dispatch`` method, which in turn will call  the ``create`` method by analyzing the second part of the path
``cr``.

To sum up the scheme of handlers routing, there are following key points:

1. ``telegram.ext.Update`` is used as a receiver of messages from Telegram;
2. Standard handlers of the ``Python-Telegram-Bot`` library can be used as handlers. For convenient use Django's path scheme and ``TelegramViewSet`` you need to use ``RouterCallbackMessageCommandHandler``.
3. ``TelegramViewSet`` aggregates a set of standard functions for managing data, what is made possible to group code associated with one type of data type in one class (place).



TelegramViewSet features
~~~~~~~~~~~~~~~~~~~~~~~~

As described above, TelegramViewSet contains standard functions for data manipulation.
Due to such standard data processing methods, it turns out in the example to describe the logic of ``BotMenuElemViewSet`` in 40
lines of code, also using some customization for beautiful data displaying.


To use all the features of the TelegramViewSet in your class, it should be inherited from it, as, for example, this is done
in the ``BotMenuElemViewSet``:


.. code-block:: python

    from telegram_django_bot.td_viewset import TelegramViewSet

    class BotMenuElemViewSet(TelegramViewSet):


In order to customize the ViewSet, you must specify 3 required attributes:

1. ``viewset_name`` - class name, used to display to telegram users
2. ``model_form`` - data form, used to specify which fields of the ORM database model to use in the viewset;
3. ``queryset`` - basic query for getting model elements.


The ``BotMenuElemViewSet`` is used the following values:

.. code-block:: python

    from telegram_django_bot import forms as td_forms
    from telegram_django_bot.models import BotMenuElem

    class BotMenuElemForm(td_forms.TelegramModelForm):
        form_name = _("Menu elem")

        class Meta:
            model = BotMenuElem
            fields = ['command', "is_visable", "callbacks_db", "message", "buttons_db"]

    class BotMenuElemViewSet(TelegramViewSet):
        viewset_name = 'BotMenuElem'
        model_form = BotMenuElemForm
        queryset = BotMenuElem.objects.all()


where ``BotMenuElemForm`` is a descendant of the ``Django ModelFrom`` class, so it has a similar structure and parameterization methods.
`` form_name ``  stands for the name of the form and is used in some messages sent to Telegram users.


TelegramViewSet has quite a lot in common with Viewset analogs tailored for WEB development (for example,
`django-rest-framework viewsets <https://www.django-rest-framework.org/api-guide/viewsets/>`_ ). However, as part of the development of Telegram bots, TelegramViewSet
has some special features:

1. An unusual way to create elements;
2. The display of information in bots is limited and most often comes down to displaying text and buttons, so the viewset in addition to business logic includes the creation of standard responses to user actions in the form of messages with buttons.



Forms
************


Since Telegram does not have the ability to create forms (in the classic Web sense) and communication between the bot and the user takes place in a chat, then
the most intuitive solution for filling out a form (creating an element) is filling the form attribute by attribute,
when the first element of the form is filled first, then the second, and so on. With this approach, it is necessary to use temporary storage for remembering
specified values in order to create an element from the form at the end. ``TelegramModelForm`` and ``TelegramForm`` are implemented just
in such way for taking over this process. The difference between these classes and the standard Django classes is precisely
in the modification of the method of filling in the form fields, otherwise they do not differ from standard forms.

``TelegramModelForm`` and ``TelegramForm`` as Django descendants of ``ModelForm`` and ``Form`` have the following parameters, which you may need to customize:

1. The clean function and other `form validation process functions <https://docs.djangoproject.com/en/4.1/ref/forms/validation/>`_ ;
2. ``labels`` - field names;
3. ``forms.HiddenInput`` - designation of hidden fields (hiding fields allows them not to be shown to the user, while using and configuring in forms or in ``TelegramViewSet``).



``TelegramViewSet`` is designed to interact with descendants of the ``TelegramModelForm`` class and allows you to use
generate forms with different fields, such as ``CharField, IntegerField`` or ``ForeignKey, ManyToManyField``. Also, it is a good idea
to use the ``prechoice_fields_values`` dictionary in ``TelegramViewSet`` descendants for improving the convenience of filling out forms for users.
It is possible to store a list of frequently used values of form fields in the ``prechoice_fields_values``.
This allows users to select the desired values by clicking buttons rather than
writing text manually. The template has an example of using this field:


.. code-block:: python

    class BotMenuElemViewSet(TelegramViewSet):
        ...

        prechoice_fields_values = {
            'is_visable': (
                (True, '👁 Visable'),
                (False, '🚫 Disabled'),
            )
        }

In this case, 2 values are specified for choosing true or false for the boolean field ``is_visable``. You can also use
``prechoice_fields_values`` for ``CharField, IntegerField`` or any other fields.
Sometimes the list of values needs to be generated dynamically, in which case you can override
``prechoice_fields_values`` as a ``@property`` function.


Key logic of TelegramViewSet
************************************************

The main function of the class, which is selected the function for managing data by the request of the user,  is ``TelegramViewSet.dispatch``.
Let's analyze its logic in more detail:

.. code-block:: python

    def dispatch(self, bot, update, user):

        self.bot = bot
        self.update = update
        self.user = user

        if update.callback_query:
            utrl = update.callback_query.data
        else:
            utrl = user.current_utrl

        self.utrl = utrl

        if settings.DEBUG:
            logging.info(f'utrl: {utrl}')

        utrl_args = self.get_utrl_params(re.sub(f'^{self.prefix}', '', self.utrl))
        if self.has_permissions(bot, update, user, utrl_args):
            chat_action, chat_action_args = self.viewset_routing[utrl_args[0]](*utrl_args[1:])
        else:
            chat_action = self.CHAT_ACTION_MESSAGE
            message = _('Sorry, you do not have permissions to this action.')
            buttons = []
            chat_action_args = (message, buttons)

        res = self.send_answer(chat_action, chat_action_args, utrl)

        utrl_path = utrl.split(self.ARGS_SEPARATOR_SYMBOL)[0]   # log without params as to much varients
        add_log_action(self.user.id, utrl_path)
        return res


Like a regular handler, the function takes 3 arguments as input: bot, update, user. After saving these arguments in class,
the determination of the current routing path is occurred. It is determined either by pressing a button in the bot (the ``callback_data`` value of the button), or
can be stored in the user attribute ``user.current_utrl``. The second option is possible if the user manually enters
some information (for example, filled in a text field of form). After that, the arguments are extracted from the path
to call a specific function. Storing and interacting with arguments in a path is similar to how ``sys.argv`` works. So,
for example, the string ``"sl&1&20"`` will be converted to the list ``['sl', '1', '20']``. The separator character between attributes
is ``&`` by default and can be changed via the ``TelegramViewSet.ARGS_SEPARATOR_SYMBOL`` variable.

When using ``TelegramViewSet`` you most likely won't have to interact with the argument string directly, since
``dispatch`` converts a string into arguments. And for creating a ``callback_data`` button string, that the user can call another method from Telegram interface, you should use
``TelegramViewSet.gm_callback_data`` function. In case you need more low-level interaction with function arguments, then
you can use the ``construct_utrl`` and ``get_utrl_params`` functions.

After receiving the utrl_args arguments and checking access rights, the managing method (action) is directly selected and called.
The first argument, which is the short name for the function, is popped from the utrl_args. All other arguments are passed as parameters
into a function. Inside the function, the necessary business logic and the data formatting for displaying to the user as a response take place.
Any such managing function in the ``TelegramViewSet`` class must return the action type ``chat_action`` and the parameters to that action ``chat_action_args``.
By default, the class has only 1 action ﹣ ``CHAT_ACTION_MESSAGE``, which means that the user will receive
a text message (possibly with buttons) as an answer for his/her action. The arguments for this action are the text of the message and a list of buttons (can be None).


After the function is processed, a response is sent to the user by ``send_answer`` function and the user's action is logged.


The methods to call in ``viewset_routing`` are the ``create, update, delete, show_elem, show_list`` methods.
You can also add your own methods. Suppose we want to add a ``def super_method(self, *args)`` method, then
you need to add the following lines in the class:

.. code-block:: python

    class SomeViewSetClass(TelegramViewSet):
        ...

        actions = ['create', 'change', 'delete', 'show_elem', 'show_list', 'super_method']

        command_routing_super_method = 'sm'


        def super_method(self, *args):
            ...


Where ``actions`` defines the list of available methods and ``command_routing_<method>`` defines the path (url; short name) of the method.

As noted above, the ``dispatch`` method performs a permissions check by calling the ``has_permissions`` method.
The check is performed by the classes specified in ``permission_classes`` and the default class is ``AllowAny``:

.. code-block:: python

    class TelegramViewSet:
        permission_classes = [AllowAny]



Additional TelegramViewSet Tools
************************************************

This section describes the following class functionality that makes it easier to write code:

1. External filters;
2. Data display setting options;
3. Helper functions for displaying data;
4. Helper functions of business logic;


External filters
+++++++++++++++++++++

Quite often, there is a situation when you need to work not with all the elements of a database table, but with some
group (for example, a group of elements with a specific foreign key). For such purposes, you should use the ``foreign_filters`` list,
which stores the values for filtering when the method is called. How exactly to use these filters is up to you, but
usually it is a good idea to use it in the ``get_queryset`` function. Thus, it is possible to pass to functions
additional arguments that do not break the key logic of standard functions. Using the template example, you can modify
``BotMenuElemViewSet`` so that if an additional parameter is specified, then the BotMenuElem list displays
only those elements that contain the specified parameter in their ``command`` attribute. To do this, you need to make the following changes to the code:


.. code-block:: python

    class BotMenuElemViewSet(TelegramViewSet):
        ...

        foreign_filter_amount = 1

        def get_queryset(self):
            queryset = super().get_queryset()
            if self.foreign_filters[0]:
                queryset = queryset.filter(command__contains=self.foreign_filters[0])
            return queryset


Where ``foreign_filter_amount`` specifies the number of foreign filters. To call a method with a filter value, you must
specify them right after the function name in the path (utrls): ``"sb/sl&start&2"``, ``"sb/sl&start&2&1"``, ``"sb/sl&hello``.
It is worth noting that if we do not want to specify a filter, then we need to skip the argument in the path (utrls) in the next way: ``"sb/sl&&2"``.

There is no need to construct and process filters in paths (utrls) directly, since the functions ``gm_callback_data`` and ``get_utrl_params``
know how to work with them. gm_callback_data also has a parameter ``add_filters`` (default True) which defines
whether to include filters in the generated path (utrl) or not. If the value is False , then it is necessary in the function arguments
manually specify filters: ``self.gm_callback_data('show_list', 'start', add_filters=False)`` (will generate ``"sb/sl&start``).
This allows you to change the value of filters when generating paths.

A more detailed use of external filters can be seen in the example of `Drive Bot <https://github.com/alexanderaleskin/drive_bot>`_ .

Data display options
++++++++++++++++++++++++++++++++++++++++++

The ``TelegramViewSet`` has the following options for displaying model elements:

* ``updating_fields: list`` - list of fields that can be changed (displayed when showing the element (``show_elem``);
* ``show_cancel_updating_button: bool = True`` - shows a cancel button when changing fields, which leads back to the displaying element (``show_elem``);
* ``deleting_with_confirm: bool = True`` - ask the user for confirmation when deleting an element;
* ``cancel_adding_button: InlineKeyboardButtonDJ = None`` - cancel button when creating an element (``create`` method);
* ``use_name_and_id_in_elem_showing: bool = True`` - enables the use of the name and ID of the element when displaying this element (methods ``show_list`` and ``show_elem``);
* ``meta_texts_dict: dict`` - a dictionary that stores standard texts for display (texts are used in all methods).



However, these fields are not always enough and you need to redefine the logic of helper functions for a beautiful display of information.


Helper functions for displaying data
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


The ``TelegramViewSet`` class describes the following helper functions for generating a response message:


* ``def gm_no_elem`` - if no element with this ID was found;
* ``def gm_success_created`` - successful creation of the model;
* ``def gm_next_field`` - when moving to the next form attribute;
* ``def gm_next_field_choice_buttons`` - generates buttons to select options for a specific form attribute (used inside ``gm_next_field``);
* ``def gm_value_error`` - error output when adding a form attribute;
* ``def gm_self_variant`` - generates a message about the need to write the value manually by the user;
* ``def gm_show_elem_or_list_fields`` - displays model fields in the message (used in ``show_elem`` with ``full_show=True``, and in ``show_list`` ﹣with ``full_show=False``);
* ``def gm_value_str`` - generates a string displaying a specific attribute (used in ``gm_show_elem_or_list_fields``);
* ``def gm_show_elem_create_buttons`` - displays available buttons (actions) when showing a model element (calling ``show_elem``) ;
* ``def gm_show_list_button_names`` - generates the names of item buttons when displaying the list (calling ``show_list``);

Depending on the need for customization, it is necessary to redefine these functions.


Helper functions of business logic
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The ``TelegramViewSet`` class uses the following helper functions:

* ``def get_queryset`` - allows you to modify Model queries to the database (most often used to filter elements, as in the example above);
* ``def create_or_update_helper`` - main logic for ``create`` and ``update`` methods;
* ``def show_list_get_queryset`` - allows you to customize the selection of items to display in show_list;


handler_decor
~~~~~~~~~~~~~~~~

When writing your own handlers, it is recommended to use a wrapper like ``telegram_django_bot.utils.handler_decor``,
which performs the following functions:

* Getting or creating a user in the database;
* In case of an error inside the handler function, returns an error message to the user;
* Logs the handler call;
* Tracks where the user came from;
* Choice of language for sending messages to the user (in the case of localization enabled);

This handler is also used inside ``RouterCallbackMessageCommandHandler``, and as a result in calling ``TelegramViewSet`` classes.

Localization
~~~~~~~~~~~~~~~~

The library expands the `Django localization tools <https://docs.djangoproject.com/en/4.1/topics/i18n/>`_ for use in Telegram.
To support the use of different languages, the main elements of the Python-Telegram-Bot library are redefined in ``telegram_django_bot.telegram_lib_redefinition``:


1. ``telegram.Bot`` -> ``telegram_django_bot.BotDJ`` ;
2. ``telegram.ReplyMarkup`` -> ``telegram_django_bot.ReplyMarkupDJ`` ;
3. ``telegram.KeyboardButton`` -> ``telegram_django_bot.KeyboardButtonDJ`` ;
4. ``telegram.InlineKeyboardButton`` -> ``telegram_django_bot.InlineKeyboardButtonDJ`` ;
5. ``telegram.InlineKeyboardMarkup`` -> ``telegram_django_bot.InlineKeyboardMarkupDJ``.


When using these classes in code, multilingual support comes down to the following steps:


1. Specifying the necessary settings in the settings.py file: ``LANGUAGES`` - list of languages, ``LANGUAGE_CODE`` - default language;
2. Create folder with translations: ``$ django-admin makemessages -l <language_code>``
3. Necessary texts for translation are wrapped in ``gettext`` and ``gettext_lazy`` from ``django.utils.translation`` (how it works in Django `read here <https://docs.djangoproject.com/en /4.1/topics/i18n/translation/#standard-translation>`_ )
4. Run command ``$ django-admin makemessages -a`` to update texts for translation (created in locale folder)
5. Generation of translation files ``$ django-admin compilemessages``.

Only a part of the functions uses localization in the template. It is made for easy understanding. The usage of localization can be seen in the example
functions ``some_debug_func``.


Extra lib features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The library provides some additional tools for the convenience of developing and managing the bot.

Embedded ORM lib models
************************************


For the correct work of ``TelegramViewSet`` and other components the Django ORM model representing the user in Telegram must be inherited
from ``telegram_django_bot.models.TelegramUser``, as these components use its fields. ``TelegramUser`` inherited from
``django.contrib.auth.models.AbstractUser`` (which allows you to authorize users on the site if necessary) and has
the following additional fields:

* ``id`` - redefined to use user ID from telegrams;
* ``seed_code`` - arbitrary value from 1 to 100 to randomly group users for tests and analysis;
* ``telegram_username`` - username of the user in telegram;
* ``telegram_language_code`` - telegram language code (some languages have dialects and as a result the code designation is more than 2 symbols);
* ``timezone`` - the user's time zone (for determining the time);
* ``current_utrl`` - path (utrl) of the last user action (used in ``TelegramViewSet``);
* ``current_utrl_code_dttm`` - time of the last action, when saving the path;
* ``current_utrl_context_db`` - path context (utrl);
* ``current_utrl_form_db`` - intermediate data for the form. Acts as a temporary data store when filling out a form;

Fields ``current_utrl_<suffix>`` are needed for ``TelegramViewSet``, ``TelegramModelForm`` and are needed in exceptional cases
when writing code. The model also has the following methods (property) to simplify interaction with model fields:

* ``current_utrl_form`` (property) - returns the current temporarily stored path form data (utrl);
* ``current_utrl_context`` (property) - returns the current path context (utrl);
* ``save_form_in_db`` - saves the form in the ``current_utrl_form_db`` field;
* ``save_context_in_db`` - saves the context in the field ``current_utrl_context_db``;
* ``clear_status`` - clears the data associated with the used path (fields ``current_utrl_<suffix>``) ;
* ``language_code`` (property) - returns the language code in which messages should be generated for the user;


If you want, you can create your self Django ORM model representing the user, you just need to copy
``id, telegram_username, telegram_language_code, current_utrl, current_utrl_code_dttm, current_utrl_context_db, current_utrl_form_db``
and corresponding functions.


The library also describes additional models to improve the usability of the bot:

* ``ActionLog`` - stores user actions. Records help to collect analytics and make triggers that work on certain actions;
* ``TeleDeepLink`` - stores data on which links new users have clicked (to analyze input traffic);
* ``BotMenuElem`` - Quite often a bot needs messages that have only static data. These pages can be help and start messages. ``BotMenuElem`` allows you to configure such pages through the admin panel, without having to write anything in the code. In ``BotMenuElem`` there is the ability to customize pages depending on the starting deeplinks. ``BotMenuElem`` can not only add buttons to the message, but also send different files. To do this, you must specify ``media`` and the file format ``message_format``. ``BotMenuElem`` allows you to quickly change bot menu blocks without having to make changes to the code;
* ``BotMenuElemAttrText`` - helper model for ``BotMenuElem``, responsible for translating texts into other languages. The elements themselves are created depending on the specified languages in the ``LANGUAGES`` settings. You only need to fill in the translation in the ``translated_text`` field;
* ``Trigger`` - allows you to create triggers depending on certain actions. For example, remind the user that he has left incomplete order, or give a discount if it is inactive for a long time. For triggers to work, you need to add tasks from ``telegram_django_bot.tasks.create_triggers`` to CeleryBeat schedule;
* ``UserTrigger`` - helper model for ``Trigger``, controlling to whom triggers have already been sent;


Additional functions of TG_DJ_Bot
*********************************************

To improve convenience, ``TG_DJ_Bot`` has several high-level functions:

* ``send_format_message`` - Allows you to send a message of an arbitrary type (internally, depending on the ``message_format`` selects the appropriate method of the ``Python-Telegram-Bot`` library). An important feature of this function is that if the user clicks on the button, then the previous message of the bot is changed, rather than a new one being sent. If, nevertheless you need to send a new message to the user, then you need to set the parameter ``only_send=True`` ;
* ``edit_or_send`` - wrapper of the ``send_format_message`` method for sending text messages with buttons;
* ``send_botmenuelem`` - Sends a ``BotMenuElem`` to the user. The ``update`` argument can be empty;
* ``task_send_message_handler`` - created for sending messages to many users. Handles situations where the user blocked the bot, deleted or when the limit for sending messages to users is reached;


Utils
**********

The following additional functions are provided in the libraries:


* ``telegram_django_bot.utils.add_log_action`` - to create a user ActionLog;
* ``telegram_django_bot.utils.CalendarPagination`` - class for generating a calendar with buttons;
* ``telegram_django_bot.user_viewset.UserViewSet`` - telegram user class for changing language and time zone;


Routing details
********************

In this section, we will analyze the work of ``RouterCallbackMessageCommandHandler`` and ``telegram_reverse`` in a little more detail.

As described earlier ``RouterCallbackMessageCommandHandler`` is used to be able to write handlers in the style
Django. Also ``RouterCallbackMessageCommandHandler`` provides the ability to handle calls to ``BotMenuElem`` as
through commands, and through callback. This is achieved by using the functions ``all_command_bme_handler`` and
``all_callback_bme_handler``. By default, ``BotMenuElem`` call handling is enabled and handled after
no suitable path was found in the description of utrls (paths in Django notation). If there is no ``BotMenuElem`` element
match is found, the ``BotMenuElem`` is considered to be configured incorrectly and an error message is returned to the user.
You can create a class with the ``only_utrl=True`` attribute, what is disable calls to ``BotMenuElem``.

The example template contains the use of the ``telegram_reverse`` function, the essence of which is to generate a path (string) to the
handler specified in the function argument. The function is analogous to the `reverse <https://docs.djangoproject.com/en/4.1/ref/urlresolvers/#reverse>`_ Django function
and avoids errors when changing paths.



Tests
**********************

The library also extends the ``django.test.TestCase`` capabilities for use with Telegram through the ``TD_TestCase`` class.

The simplest approach for testing the bot is to generate messages that the bot expects from Telegram and
send a response to Telegram (to check that the bot's response messages are in the correct format). Class ``TD_TestCase``
has a function ``create_update`` for easy and fast creation of ``Telegram.Update`` which generates the request
telegram user. So the overall design looks like this:

1. A ``Telegram.Update`` is created for emitting a user request;
2. The ``handle_update`` lambda function, which uses ``RouterCallbackMessageCommandHandler``,  is called with created update. It does its staff and as a result sends a real message to the test user. Due to this, the correctness of the response data format  is checked by Telegram;
3. The correctness of the sent data and changes in the database is checked using the standard tools ``django.test.TestCase``.

You need to specify at least one test user ID in the ``TELEGRAM_TEST_USER_IDS`` settings section for correct tests work.
Messages will be sent to that user, so the bot needs to have permission to write to that user.

In the ``tests`` folder you could find test examples.