python-telegram-handler


Namepython-telegram-handler JSON
Version 2.2.1 PyPI version JSON
download
home_pagehttps://github.com/sashgorokhov/python-telegram-handler
SummaryA python logging handler that sends logs via Telegram Bot Api.
upload_time2021-05-13 09:17:54
maintainer
docs_urlNone
authorsashgorokhov
requires_python
licenseMIT License
keywords telegram logging handler bot
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI
coveralls test coverage No coveralls.
            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
            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/sashgorokhov/python-telegram-handler",
    "name": "python-telegram-handler",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "telegram,logging,handler,bot",
    "author": "sashgorokhov",
    "author_email": "sashgorokhov@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/ff/c0/4c943016e844b332aa2058cdb1d76aa0044d0c27596f362639a087d23a8a/python-telegram-handler-2.2.1.tar.gz",
    "platform": "",
    "description": "python-telegram-handler\n***********************\n\n.. image:: https://img.shields.io/pypi/status/python-telegram-handler.svg\n    :target: https://github.com/sashgorokhov/python-telegram-handler\n\n.. image:: https://img.shields.io/pypi/pyversions/python-telegram-handler.svg\n    :target: https://pypi.python.org/pypi/python-telegram-handler\n\n.. image:: https://badge.fury.io/py/python-telegram-handler.svg \n    :target: https://badge.fury.io/py/python-telegram-handler \n\n.. image:: https://travis-ci.org/sashgorokhov/python-telegram-handler.svg?branch=master \n    :target: https://travis-ci.org/sashgorokhov/python-telegram-handler \n\n.. image:: https://codecov.io/github/sashgorokhov/python-telegram-handler/coverage.svg?branch=master \n    :target: https://codecov.io/github/sashgorokhov/python-telegram-handler?branch=master \n\n.. image:: https://codeclimate.com/github/sashgorokhov/python-telegram-handler/badges/gpa.svg\n   :target: https://codeclimate.com/github/sashgorokhov/python-telegram-handler\n   :alt: Code Climate\n\n.. image:: https://img.shields.io/github/license/sashgorokhov/python-telegram-handler.svg \n    :target: https://raw.githubusercontent.com/sashgorokhov/python-telegram-handler/master/LICENSE \n\n\nA python logging handler that sends logs via Telegram Bot Api\n\nInstallation\n============\n\nVia pip:\n\n.. code-block:: shell\n\n    pip install python-telegram-handler\n\nUsage\n=====\n\nRegister a new telegram bot and obtain a ``authentication token``. (Instructions here https://core.telegram.org/bots#3-how-do-i-create-a-bot)\n\nAfter 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).\n\nAlso, 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. \n\nThen run a command:\n\n.. code-block:: shell\n\n    python -m telegram_handler <your token here>\n    \nIf all went ok, a ``chat_id`` will be printed to stdout.\n\nUsing ``token`` and ``chat_id``, configure log handler in your desired way.\nFor example, using dictConfig:\n\n.. code-block:: python\n\n        {\n            'version': 1,\n            'handlers': {\n                'telegram': {\n                    'class': 'telegram_handler.TelegramHandler',\n                    'token': 'your token',\n                    'chat_id': 'chat id'\n                }\n            },\n            'loggers': {\n                'my_logger': {\n                    'handlers': ['telegram'],\n                    'level': 'DEBUG'\n                }\n            }\n        }\n\nFormatting\n==========\n\nCurrently the format of sent messages is very simple: ``<code>%(asctime)s</code> <b>%(levelname)s</b>\\nFrom %(name)s:%(funcName)s\\n%(message)s``\nException traceback will be formatted as pre-formatted fixed-width code block. (https://core.telegram.org/bots/api#html-style)\n\nIf you want to tweak it, configure a ``telegram_handler.HtmlFormatter`` with your desired format string.\nUsing a dictConfig:\n\n.. code-block:: python\n        \n        ...\n        {\n            'formatters': {\n                'telegram': {\n                    'class': 'telegram_handler.HtmlFormatter',\n                    'fmt': '%(levelname)s %(message)s'\n                }\n            }\n            'handlers': {\n                'telegram': {\n                    'class': 'telegram_handler.TelegramHandler',\n                    'formatter': 'telegram',\n                    'token': 'your token',\n                    'chat_id': 'chat id'\n                }\n            }\n        }\n        ...\n\nIf you wish, you can enable emoji symbols in HtmlFormatter. Just specify `use_emoji=True` in HtmlFormatter settings.\nThis will add to levelname a :white_circle: for DEBUG, :large_blue_circle: for INFO, and :red_circle: for WARNING and ERROR levels. \n\nProxy\n===========\n\nIn 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.\nUsing a dictConfig:\n\n.. code-block:: python\n        \n        ...\n        {\n            'handlers': {\n                'telegram': {\n                    'class': 'telegram_handler.TelegramHandler',\n                    'formatter': 'telegram',\n                    'token': 'your token',\n                    'chat_id': 'chat id',\n                    'proxies': {\n                        'http': 'socks5://user:pass@host:port',\n                        'https': 'socks5://user:pass@host:port'\n                    }\n                }\n            }\n        }\n        ...\n\n**Important!** If you plan to use *socks* proxy make sure you have ``requests`` package with ``socks`` support installed:\n\n.. code-block:: shell\n\n    pip install requests[socks]\n\n\n.. :changelog:\n\nHistory\n-------\n\n2.2.0 (2019-08-19)\n++++++++++++++++++\n\n* Add proxy support (#20) (by )\n\n2.1.0 (2019-04-25)\n++++++++++++++++++\n\n* Send message as file if it is too large\n* Fixes in MarkdownFormatter\n* Fixes in HTMLFormatter\n* Chat id retrieval fixes\n* Drop py33 support from tests\n* Update setup.py classifiers\n* Removed print()-calls in HtmlFormatter (#12) (by Lukas Garberg)\n\n\n2.0.2 (2017-11-20)\n++++++++++++++++++\n\n* fix TypeError in HtmlFormatter.format (by tompipen)\n\n\n2.0 (2017-03-01)\n++++++++++++++++\n\n* Refactored HtmlFormatter and MarkdownFormatter\n* Refactored TelegramHandler\n* No more need to call a command to obtain a chat_id - it will be obtained automatically on handler init\n* Rewritten tests\n* Escape LogRecord things in HtmlFormatter\n* Added optional emoji symbols in HtmlFormatter.\n\n1.1.3 (2016-09-22)\n++++++++++++++++++\n\n* Setting escape_message field of StyledFormatter missed (@ihoru)\n\n1.1.2 (2016-05-13)\n++++++++++++++++++\n\n* Fixed setup.py requires option (changed to install_requires)\n\n1.1.1 (2016-04-20)\n++++++++++++++++++\n\n* Use HTML Formatter as default formatter for telegram handler\n\n1.1.0 (2016-04-20)\n++++++++++++++++++\n\n* Introduced HTML Formatter\n* Added log text escaping (closed #3)\n* Added requests timeout setting (closed  #1)\n* Catching and logging all requests and their exceptions (closed #2)\n\n1.0.0 (2016-04-19)\n++++++++++++++++++\n\n* First PyPi release\n\n0.1.0 (2016-04-19)\n++++++++++++++++++\n\n* Initial release",
    "bugtrack_url": null,
    "license": "MIT License",
    "summary": "A python logging handler that sends logs via Telegram Bot Api.",
    "version": "2.2.1",
    "split_keywords": [
        "telegram",
        "logging",
        "handler",
        "bot"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "500e16ea87fbbf1f8e027c5657125b6d",
                "sha256": "f6e9ca60e15fa4e4595e323cc57362fe20cca3ca16e06158ad726caa48b3b16e"
            },
            "downloads": -1,
            "filename": "python-telegram-handler-2.2.1.tar.gz",
            "has_sig": false,
            "md5_digest": "500e16ea87fbbf1f8e027c5657125b6d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 5974,
            "upload_time": "2021-05-13T09:17:54",
            "upload_time_iso_8601": "2021-05-13T09:17:54.148094Z",
            "url": "https://files.pythonhosted.org/packages/ff/c0/4c943016e844b332aa2058cdb1d76aa0044d0c27596f362639a087d23a8a/python-telegram-handler-2.2.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-05-13 09:17:54",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "sashgorokhov",
    "github_project": "python-telegram-handler",
    "travis_ci": true,
    "coveralls": false,
    "github_actions": false,
    "tox": true,
    "lcname": "python-telegram-handler"
}
        
Elapsed time: 0.06063s