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"
}