Metadata-Version: 1.1
Name: ListBot
Version: 1.0.1.2
Summary: Python Telegram bot
Home-page: https://github.com/vladislavburch/ListBot
Author: vladislavburch
Author-email: vladislavburch17@gmail.com
License: GPL2
Description: #
        
        .. raw:: html
        
           <p align="center">
        
        ListBot
        
        .. raw:: html
        
           <p align="center">
        
        A simple bot for Telegram.
        
        |Build Status| |PyPI| |Codacy grade|
        
        -  `Скачать и установить <#скачать>`__
        -  `Цель <#цель>`__
        -  `Основные определения <#основные-определения>`__
        -  `Введение <#введение>`__
        -  `Требования к проекту <#требования-к-проекту>`__
        -  `Проектирование системы <#проектирование-системы>`__
        
           -  `Технические аспекты <#технические-аспекты>`__
           -  `Логические аспекты <#логические-аспекты>`__
        
        -  `Выбор технологий <#выбор-технологий>`__
        
           -  `Выбор языка программирования <#выбор-языка-программирования>`__
           -  `Выбор используемых библиотек <#выбор-используемых-библиотек>`__
        
        -  `Описание технический решений <#описание-технических-решений>`__
        -  `Заключение <#заключение>`__
        -  `Список используемых источников <#список-используемых-источников>`__
        
        Скачать
        -------
        
         Есть три варианта установки данной программы: 1. Просто перейти по
        `ссылке <https://telegram.me/MDFileBot>`__ и начать общение с ботом.
        Этот вариант для тех, кто хочет просто пользоваться ботом 2. С помощью
        ``pip``
        
        ::
        
            $ pip install ListBot
        
        3. С помощью ``git``
        
        ::
        
            $ git clone https://vladislavburch/listbot.git
            $ cd listbot
            $ python setup.py install
        
        Цель
        ----
        
         Главной целью курсового проекта является реализация telegram-бота для
        получения с помощью него расписания занятий. Так же целью явлется
        научиться создавать и документировать ботов для telegram, написанных на
        языке программирования python. ## Основные определения *Telegram* —
        бесплатный кроссплатформенный мессенджер для смартфонов и других
        устройств, позволяющий обмениваться текстовыми сообщениями и
        медиафайлами различных форматов.
        
        *Бот* — специальная программа, выполняющая автоматически и/или по
        заданному расписанию какие-либо действия через интерфейсы,
        предназначенные для людей.
        
        *Unit-тесты* - процесс в программировании, который позволяет проверить
        исходный код на корректность, а также дает возможность разработчику
        удостовериться в том, что внесенные изменения не привели к появлению
        ошибок в уже протестированных местах программы. ## Введение Сейчас,
        когда  IT-технологии развиваются с невообразимой скоростью, скорость
        жизни тоже изменилась. Необходимость быстрого и удобного программного
        обеспечения, позволяющего производить рутинные действия вместо или
        вместе с человеком чувствуется как никогда. Боты решают проблему
        оптимизации времени. Маленькие программы, которые выигрывают *пару
        минут* и несколько байт памяти приобрели ценность.
        
        Как одно из рутинных занятий можно выделить проверку расписания. Часто
        студенты для этого заходят на сайт МГТУ или фотографируют его в начале
        семестра. Это неудобно по нескольким причинам: во первых, загрузка
        страниц в интернете *съедает* много трафика, а фотографии память на
        телефоне. Во-вторых, прогрузка страниц - это долго, так же как и поиск
        фотографии в телефоне, особенно фотографии, сделанной в начале семестра.
        ListBot ест меньше трафика и памяти, к тому же он значительно быстрее.
        
        Существует несколько вариантов просмотра расписания, но самым популярным
        является картинка. Но есть несколько минусов именно этого способа
        просмотра: использование оперативной памяти телефона и длительность
        загрузки. ListBot Отправляет расписание списком, иначе говоря текстовым
        сообщением, что позволяет не засорять память, выигрывая во времени. ##
        Требования к проекту 1. [x] Простой интерфейс Причина: облегчение работы
        с пользователем 2. [x] Наличие документации Причина: наличие у
        пользователя возможности узнать всю информацию о программе, а так же
        возможность обратной связи с пользователем 3. [x] Наличие нескольких
        вариантов скачивания и/или установки Причина: ориентация на
        пользователей, использующих разное ПО и обладающих разным уровнем знаний
        в области IT. ## Проектирование системы Схему работы telegram-боты можно
        разделить на две части: 1. Технические аспекты 2. Логические аспекты ###
        Технические аспекты Здесь стоит поговорить о том, как именно бот
        реализует взаимодействие с интернетом, а в частности с telegram.
        Основным для работы бота является метод **get_updates()**.
        
        При загрузке страницы https://api.telegram.org/botToken/getupdates мы
        сталкиваемся с тем, как бот реагирует на какие-то обновления. То есть
        если прислать боту сообщение, на странице метода **get_updates()** это
        отобразится.
        
        Принцип работы бота прост, он смотрит на эту страницу и как-то реагирует
        на полученное изменение.
        
        Теперь подробнее: все изменения на странице метода отображаются в виде
        *json-объектов*. Подробнее о них вы можете найти
        `тут <https://ru.wikipedia.org/wiki/JSON>`__. Для того, чтобы
        запрограммировать бота на определленую реакцию, вызываемую определенным
        сообщением необходимо это сообщение *вытащить* из json-объекта. Есть
        несколько способов это сделать: 1. Традиционным образом То есть взять
        все json-объекты ``all_updates = bot.get_updates()`` А затем выделить из
        них последний ``last_update = all_updates[len(all_updates)-1]`` Неудобно
        и громоздко использовать модуль ``requests`` или ``re``, поэтому в своей
        программе я пользуюсь API для telegram-ботов, которое называется
        telebot. Это позволяет сделать простые элементы бота более компактными.
        API устанавливается как модуль для python, об этом написано в
        приложении.
        
        Итак, наш вариант выглядит так:
        ``@bot.message_handler(content_types=['text']) def handle_text(message):     if (message.text == 'Hi') or (message.text == 'Hello'):         answer = constants.content[0]         bot.send_message(message.chat.id, answer)``
        Здесь написано, что если поле ``text`` json-объекта последнего
        обновления содержит строку *Hi* или *Hello*, то бот отправляет
        пользователю, который прислал это сообщение ответ. Сам ответ находится в
        отдельном файле: ``~/listbot/import/constants.py`` Для того, чтобы
        отправить сообщение бот использует метод **send_message(‘CHAT_ID’,string
        s)** И этот метод представляется в виде ссылки
        https://api.telegram.org/botToken/sendmessage с дополнительными
        параметрами ``CHAT_ID`` и ``string s``, то есть куда (в какой чат) и что
        отправить.
        
        Логические аспекты
        ~~~~~~~~~~~~~~~~~~
        
         Здесь речь пойдет о том, каким образом бот отвечает на определенные
        команды и запросы: Команды - это сообщения, которые вы пишете боту,
        начинающиеся со знака ``/``. Бот реагирует на 6 команд:
        
        ``/start``
        
        ``/list``
        
        ``/timetable``
        
        ``/download``
        
        ``/help``
        
        ``/site``
        
        При распознавании команды ``/start`` бот здоровается с пользователем и
        предлагает либо загрузить расписание группы ИУ8-33, либо оставить это
        поле свободным.
        
        При распознавании команды ``/list`` бот выводит полный список команд, на
        которые он умеет отвечать.
        
        При распознавании команды ``/timetable`` бот выводит расписание,
        загруженное на данный момент.
        
        При распознавании команды ``/download`` бот загружает расписание ИУ8-33
        с сайта МГТУ им. Баумана
        
        При разпознавании команды ``/help`` бот предлагает пользователю перейти
        на сайт `GitHub <https://github.com/vladislavburch/listbot>`__ для
        получения большего количества информации о принципе работы бота.
        
        При распознавании команды ``/site`` бот предлагает пользователю перейти
        на сайт МГТУ, чтобы посмотреть расписание
        
        Но, как мы знаем, бот умеет реагировать не только на команды, но и на
        обычные текстовые запросы, о чем он нам говорит ещё в самом начале
        работы с ним.
        
        Здесь все проще:
        
        *При получении сообщения с днем недели, бот присылает расписание занятий
        на этот день.*
        
        Диалог с пользователем бот реализует через кнопки
        (``telebot.types.KeyboardButton``), что упрощает регистрацию следующих
        шагов пользователя.
        
        Выбор технологий
        ----------------
        
         ### Выбор языка программирования Для курсового проекта при выборе языка
        программирования было произведено сравнение между двумя языками
        программирования: *“Python”* и *“C++”*.
        
        **“Python”** - высокоуровневый интерпретируемый язык программирования,
        преимущества которого заключаются в следующих характеристиках: -
        динамическая типизация - автоматическое управление памятью - механизм
        обработки исключений - простой синтаксис кода - большое количество
        сторонних библиотек Отрицательной чертой данного языка программирования
        является его *производительность*.
        
        **“C++”** - компилируемый, сильно типизированный язык программирования,
        плюсы которого проявляются в нижеперечисленных характеристиках: -
        высокая производительность - возможность работы на низком уровне с
        памятью, адресами, портами. - кросс-платформенность Из минусов стоит
        отметить: - строгую типизацию сложность привязывания библиотек.
        
        Для данного курсового проекта необходимо, чтобы для языка
        программирования было предоставлено Telegram API для написания
        телеграмм-бота и его функционала. Помимо Telegram API, должна
        присутствовать библиотека для работы с базой данных. А также следует
        отметить, что к проекту нет требований к производительности. Именно
        поэтому для данного курсового проекта был выбран язык программирования –
        «Python».
        
        Выбор используемых библиотек
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
         Список библиотек, использованных в проекте 1. telebot 2. unittest 3. os
        ## Описание технических решений
        
        Работа проводилась в среде разработки PyCharm. Модули там подключаются
        просто, через ``Настройки`` -> ``Интерпретатор python`` и т. д.
        Трудности поначалу возникли с интерпретатором: ``default`` python на
        маке версии меньше 3. Я установил новый и согласовал его с PyCharm.
        
        *Вторая трудность* возникла при выявлении багов у бота. Как найти и
        устранить все, если брать во внимание не только ошибки кода, но и
        логические и графические ошибки? Выход нашелся не сразу. Я запустил
        глобальное beta-тестирование, в котором принимали участие мои друзья,
        знакомые, одногруппники и т. д.
        
        Реализовать beta-тестирование с отслеживаемыми результатами оказалось
        легко, стоило только написать процедуру:
        
        ::
        
            def log(message, answer):
                print('\n------')
                from datetime import datetime
                print(datetime.now())
                print("Message from {0} {1}. (id = {2})\nText - {3}\nChat_id {4} ".format(message.from_user.first_name,
                                                                               message.from_user.last_name,
                                                                               str(message.from_user.id),
                                                                               message.text,
                                                                               str(message.chat.id)))
                print("Answer - ", answer)
        
        А затем вставить её в бота:
        
        ::
        
            ....................................
            @bot.message_handler(content_types=['text'])
            def handle_text(message):
                if (message.text == 'Hi') or (message.text == 'Hello'):
                    answer = constants.content[0]
                    bot.send_message(message.chat.id, answer)
                    log(message, answer)
                elif (message.text == 'Monday') or message.text == 'monday' or message.text == 'mon' or message.text == 'Mon' or message.text == 'Понедельник':
                    answer = constants.content[1]
                    bot.send_message(message.chat.id, answer)
                    log(message, answer)
              .....................................
        
        Что давало мне результаты выполнения команд ботом, и избавляло
        beta-тестеров от copy-past’a мне в сообщения.
        
        **NOTA BENE** Участники были предупреждены, что я буду видеть все их
        запросы.
        
        *Третья возникшая проблема* связана с тестами: осталось так и не
        реализовано автоматизированное тестирование поведения бота. Трудности
        возникли из-за отсутствия в ``Travis-CI`` модуля telebot.
        
        Заключение
        ----------
        
        В ходе работы над курсовым проектом был реализован бот для telegram,
        использованы такие ресурсы как ``GitHub``,\ ``Travis-CI``, ``PyPI``,
        ``telebotApi``, ``Codacy``. Было получено много знаний о принципе работы
        таких приложений, о документации и тестировании.
        
        Список использыемых источников
        ------------------------------
        
        `TelegramBots API documentation <https://core.telegram.org/bots/api>`__
        `CheeseShop
        Tutorial <https://wiki.python.org/moin/CheeseShopTutorial>`__
        `Хабрахабр <https://habrahabr.ru/post/316666/>`__
        `Telebot <https://github.com/eternnoir/pyTelegramBotAPI>`__
        
        .. |Build Status| image:: https://travis-ci.org/VladislavBurch/ListBot.svg?branch=master
           :target: https://travis-ci.org/VladislavBurch/ListBot
        .. |PyPI| image:: https://img.shields.io/pypi/v/nine.svg
           :target: https://pypi.python.org/pypi/ListBot/
        .. |Codacy grade| image:: https://img.shields.io/codacy/grade/e27821fb6289410b8f58338c7e0bc686.svg
           :target: https://www.codacy.com/app/VladislavBurch/ListBot/dashboard
        
Keywords: telegram bot
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
