python-telegram-handler 2.2.1
A python logging handler that sends logs via Telegram Bot Api.
License: MIT License
Keywords: telegram,logging,handler,bot

python-telegram-handler
***********************

.. image:: https://img.shields.io/pypi/status/python-telegram-handler.svg
    :target: https://github.com/sashgorokhov/python-telegram-handler

.. image:: https://img.shields.io/pypi/pyversions/python-telegram-handler.svg
    :target: https://pypi.python.org/pypi/python-telegram-handler

.. image:: https://badge.fury.io/py/python-telegram-handler.svg 
    :target: https://badge.fury.io/py/python-telegram-handler 

.. image:: https://travis-ci.org/sashgorokhov/python-telegram-handler.svg?branch=master 
    :target: https://travis-ci.org/sashgorokhov/python-telegram-handler 

.. image:: https://codecov.io/github/sashgorokhov/python-telegram-handler/coverage.svg?branch=master 
    :target: https://codecov.io/github/sashgorokhov/python-telegram-handler?branch=master 

.. image:: https://codeclimate.com/github/sashgorokhov/python-telegram-handler/badges/gpa.svg
   :target: https://codeclimate.com/github/sashgorokhov/python-telegram-handler
   :alt: Code Climate

.. image:: https://img.shields.io/github/license/sashgorokhov/python-telegram-handler.svg 
    :target: https://raw.githubusercontent.com/sashgorokhov/python-telegram-handler/master/LICENSE 


A python logging handler that sends logs via Telegram Bot Api

Installation
============

Via pip:

.. code-block:: shell

    pip install python-telegram-handler

Usage
=====

Register a new telegram bot and obtain a ``authentication token``. (Instructions here https://core.telegram.org/bots#3-how-do-i-create-a-bot)

After that, you must obtain a ``chat_id``. You can do that using included simple script. Start a new conversation with newly created bot, write something to it (it is important to initiate conversation first).

Also, there is an ability for handler to automatically retrieve ``chat_id``. This will be done on handler initialization. But you still have to start a conversation with bot. Be aware: if program stops, server restarts, or something else will happen - handler will try to retrieve chat id from telegram, and may fail, if it will not find a NEW message from you. So i recommend you to use a script below for obtaining chat id. 

Then run a command:

.. code-block:: shell

    python -m telegram_handler <your token here>
    
If all went ok, a ``chat_id`` will be printed to stdout.

Using ``token`` and ``chat_id``, configure log handler in your desired way.
For example, using dictConfig:

.. code-block:: python

        {
            'version': 1,
            'handlers': {
                'telegram': {
                    'class': 'telegram_handler.TelegramHandler',
                    'token': 'your token',
                    'chat_id': 'chat id'
                }
            },
            'loggers': {
                'my_logger': {
                    'handlers': ['telegram'],
                    'level': 'DEBUG'
                }
            }
        }

Formatting
==========

Currently the format of sent messages is very simple: ``<code>%(asctime)s</code> <b>%(levelname)s</b>\nFrom %(name)s:%(funcName)s\n%(message)s``
Exception traceback will be formatted as pre-formatted fixed-width code block. (https://core.telegram.org/bots/api#html-style)

If you want to tweak it, configure a ``telegram_handler.HtmlFormatter`` with your desired format string.
Using a dictConfig:

.. code-block:: python
        
        ...
        {
            'formatters': {
                'telegram': {
                    'class': 'telegram_handler.HtmlFormatter',
                    'fmt': '%(levelname)s %(message)s'
                }
            }
            'handlers': {
                'telegram': {
                    'class': 'telegram_handler.TelegramHandler',
                    'formatter': 'telegram',
                    'token': 'your token',
                    'chat_id': 'chat id'
                }
            }
        }
        ...

If you wish, you can enable emoji symbols in HtmlFormatter. Just specify `use_emoji=True` in HtmlFormatter settings.
This will add to levelname a :white_circle: for DEBUG, :large_blue_circle: for INFO, and :red_circle: for WARNING and ERROR levels. 

Proxy
===========

In case if you have to use this package inside the country where Telegram servers are blocked by gowrnment you can specify proxy urls in config.
Using a dictConfig:

.. code-block:: python
        
        ...
        {
            'handlers': {
                'telegram': {
                    'class': 'telegram_handler.TelegramHandler',
                    'formatter': 'telegram',
                    'token': 'your token',
                    'chat_id': 'chat id',
                    'proxies': {
                        'http': 'socks5://user:pass@host:port',
                        'https': 'socks5://user:pass@host:port'
                    }
                }
            }
        }
        ...

**Important!** If you plan to use *socks* proxy make sure you have ``requests`` package with ``socks`` support installed:

.. code-block:: shell

    pip install requests[socks]


.. :changelog:

History
-------

2.2.0 (2019-08-19)
++++++++++++++++++

* Add proxy support (#20) (by )

2.1.0 (2019-04-25)
++++++++++++++++++

* Send message as file if it is too large
* Fixes in MarkdownFormatter
* Fixes in HTMLFormatter
* Chat id retrieval fixes
* Drop py33 support from tests
* Update setup.py classifiers
* Removed print()-calls in HtmlFormatter (#12) (by Lukas Garberg)


2.0.2 (2017-11-20)
++++++++++++++++++

* fix TypeError in HtmlFormatter.format (by tompipen)


2.0 (2017-03-01)
++++++++++++++++

* Refactored HtmlFormatter and MarkdownFormatter
* Refactored TelegramHandler
* No more need to call a command to obtain a chat_id - it will be obtained automatically on handler init
* Rewritten tests
* Escape LogRecord things in HtmlFormatter
* Added optional emoji symbols in HtmlFormatter.

1.1.3 (2016-09-22)
++++++++++++++++++

* Setting escape_message field of StyledFormatter missed (@ihoru)

1.1.2 (2016-05-13)
++++++++++++++++++

* Fixed setup.py requires option (changed to install_requires)

1.1.1 (2016-04-20)
++++++++++++++++++

* Use HTML Formatter as default formatter for telegram handler

1.1.0 (2016-04-20)
++++++++++++++++++

* Introduced HTML Formatter
* Added log text escaping (closed #3)
* Added requests timeout setting (closed  #1)
* Catching and logging all requests and their exceptions (closed #2)

1.0.0 (2016-04-19)
++++++++++++++++++

* First PyPi release

0.1.0 (2016-04-19)
++++++++++++++++++

* Initial release