{"id":14128674,"url":"https://github.com/luckydonald/pytg","last_synced_at":"2025-04-04T10:06:00.582Z","repository":{"id":13333846,"uuid":"16020818","full_name":"luckydonald/pytg","owner":"luckydonald","description":"Python package that wraps around Telegram messenger CLI. Send and receive messages, and more.","archived":false,"fork":false,"pushed_at":"2021-09-20T22:11:10.000Z","size":446,"stargazers_count":368,"open_issues_count":60,"forks_count":76,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-03-28T09:07:55.741Z","etag":null,"topics":["bot","cli","pypi","pytg","python","receive-messages","sender","telegram","telegram-bot","telegram-cli"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luckydonald.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-01-18T06:59:57.000Z","updated_at":"2025-03-07T08:57:09.000Z","dependencies_parsed_at":"2022-09-26T22:20:27.376Z","dependency_job_id":null,"html_url":"https://github.com/luckydonald/pytg","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luckydonald%2Fpytg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luckydonald%2Fpytg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luckydonald%2Fpytg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luckydonald%2Fpytg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luckydonald","download_url":"https://codeload.github.com/luckydonald/pytg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157281,"owners_count":20893220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","cli","pypi","pytg","python","receive-messages","sender","telegram","telegram-bot","telegram-cli"],"created_at":"2024-08-15T16:02:02.058Z","updated_at":"2025-04-04T10:06:00.554Z","avatar_url":"https://github.com/luckydonald.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# **PyTg** \r\n#### Version [0.4.10](https://github.com/luckydonald/pytg/blob/master/CHANGELOG.md#changelog) ####\r\n[![Join pytg_group group on telegram](https://img.shields.io/badge/Telegram%20Group-Join-blue.svg)](https://telegram.me/pytg_group) [![get it from PyPI](https://img.shields.io/pypi/v/pytg.svg)](https://pypi.python.org/pypi/pytg) [![PyPI](https://img.shields.io/pypi/dm/pytg.svg)](https://pypi.python.org/pypi/pytg/0.4.6/)\r\n\r\nA Python package that communicates with the [Telegram messenger CLI](https://github.com/vysheng/tg), to send and receive messages and more. *Since January 2014*\r\n\r\n[Telegram](https://telegram.org) is an Whatsapp like Instant messenger, with clients for virtually every device you use.\r\n\r\nWorks with Python  2.7 and 3    \r\n\r\n\u003e I really recommend to use Python 3, because of it's build in unicode support.\r\nPython 2 uses ascii only bytestrings, causing much, **much trouble** when dealing with characters like öäüß or emojis. (Trust me, I've been there)     \r\n~ luckydonald\r\n\r\n### Alternative: [BotApi](https://github.com/luckydonald/pytgbot)\r\nIf you'd like to use the **Telegram Bot Api** instead, there also is [pytgbot](https://github.com/luckydonald/pytgbot).\r\nIt features a complete object oriented approach, mapping all the possible server responses. So you always know what attributes to expect.\r\n\r\n## Content\r\n- [Documentation](#documentation)\r\n- [Install](#install)\r\n- [Usage](#usage)\r\n- [Contribute](#contribute)\r\n- [In case of errors](#in-case-of-errors)\r\n   - [Verbose logging](#in-case-of-errors)\r\n- [Examples](#examples)\r\n\r\n\r\n\r\n## **Install**\r\n### Dependencies\r\n - ~~Install the Telegram CLI (from @vysheng), follow the [official Instructions](https://github.com/vysheng/tg)~~\r\n - Install up to date fork of Telegram CLI (by @kenorb-contrib), follow the [Instructions](https://github.com/kenorb-contrib/tg) there. \r\n\r\n### Pytg\r\n##### Install form PyPI [![on PyPI](https://img.shields.io/pypi/v/pytg.svg)](https://pypi.python.org/pypi/pytg)\r\n\r\n```shell\r\npip install pytg\r\n```    \r\nTo upgrade append the ```--upgrade``` flag.\r\n \r\n##### Install from source\r\n(Beta versions are in the [development branch](https://github.com/luckydonald/pytg/tree/development))    \r\n\r\n - a) Get the latest pytg code from github.    \r\n    ```git clone https://github.com/luckydonald/pytg.git \u0026\u0026 cd pytg```     \r\n - b) To update already existing code, navigate to the root inside the pytg folder, then ```git pull```\r\n - Install\r\n    ```sudo python setup.py install```\r\n    - The dependency \"[DictObject](https://github.com/luckydonald/DictObject)\" should be installed automatically by this. If not, it is available on PyPI:    \r\n     ```sudo pip install DictObject```\r\n    - Same goes for \"[luckydonaldUtils](https://github.com/luckydonald/luckydonald-utils)\":    \r\n     ```sudo pip install luckydonald-utils```\r\n    \r\n Done.\r\n\r\n## **Usage**\r\n\r\n\u003e***Note***: The examples files produce syntax errors for python 3.0 - 3.2, the pytg package itself is not affacted by this!    \r\n\u003e To fix, just remove the ```u``` in front of the strings: change ```u\"foobar\"``` to ```\"foobar``` (see [issue #39](https://github.com/luckydonald/pytg/issues/39#issuecomment-129992777) and [Python 3.3 accepts ```u'unicode'``` syntax again](https://docs.python.org/3/whatsnew/3.3.html?highlight=unicode)). \r\n\r\n#### *Start* telegram\r\n\r\nCreate a Telegram Instance.\r\nThis will manage the CLI process, and registers the Sender and Receiver for you.\r\n\r\n```python\r\nfrom pytg import Telegram\r\ntg = Telegram(\r\n\ttelegram=\"/path/to/tg/bin/telegram-cli\",\r\n\tpubkey_file=\"/path/to/tg/tg-server.pub\")\r\nreceiver = tg.receiver\r\nsender = tg.sender\r\n```\r\n\r\nIf you don't want pytg to start the cli for you, start it yourself with ```--json -P 4458``` (port 4458).\r\nYou can then use the Receiver and/or the Sender like this: \r\n\r\n\r\n```python\r\nfrom pytg.sender import Sender\r\nfrom pytg.receiver import Receiver\r\nreceiver = Receiver(host=\"localhost\", port=4458)\r\nsender = Sender(host=\"localhost\", port=4458)\r\n```\r\n\r\n#### *Send* a message\r\n\r\n```python\r\nsender.send_msg(\"username\", \"Hello World!\")\r\n# Easy huh?\r\n```\r\n    \r\n#### *Receiving* messages\r\n\r\nYou need a function as main loop.\r\n```python\r\n@coroutine # from pytg.utils import coroutine\r\ndef main_loop():\r\n\twhile not QUIT:\r\n\t\tmsg = (yield) # it waits until it got a message, stored now in msg.\r\n\t\tprint(\"Message: \", msg.text)\r\n\t\t# do more stuff here!\r\n\t#\r\n#\r\n```\r\n\r\nLast step is to register that function:\r\n\r\n```python\r\n# start the Receiver, so we can get messages!\r\nreceiver.start()\r\n\r\n# let \"main_loop\" get new message events.\r\n# You can supply arguments here, like main_loop(foo, bar).\r\nreceiver.message(main_loop())\r\n# now it will call the main_loop function and yield the new messages.\r\n```\r\n\r\nThat's the basics. Have a look into the examples folder. For starters, I recommend:    \r\n* dump.py - is usefull to see, how the messages look like.    \r\n* ping.py - is usefull to see how to interact with pytg, send messages etc.\r\n\r\n## More Documentation\r\nThe ```Sender``` object features a rich build-in help, inside the python interpreter type:\r\n```python\r\nfrom pytg.sender import Sender\r\nhelp(Sender)  # list all commands\r\nhelp(Sender.get_self)  # get help for a specific command\r\n``` \r\n\r\nThis is also availabe as [generated documentation](https://github.com/luckydonald/pytg/blob/master/DOCUMENTATION.md) here on github.\r\nAlso have a look at the [Changelog](https://github.com/luckydonald/pytg/blob/master/CHANGELOG.md#changelog) to see what's going on.\r\n\r\nTo generate the documentation yourself:\r\n```python\r\nfrom pytg.sender import create_automatic_documentation; create_automatic_documentation()\r\n```\r\n\r\nYou can also have a look at [the old documentation](https://github.com/luckydonald/pytg/blob/master/DOCUMENTATION_manual.md)\r\n\r\n## Contribute\r\n###### You can help!\r\n\r\n* by [reporting issues](https://github.com/luckydonald/pytg/issues)\r\n* by commiting patches/[pull requests](https://github.com/luckydonald/pytg/pulls)\r\n* with testing\r\n \r\n*Note: There is a version in the making, supporting the cli via socket (as before), the CLI via its build in python (aka. tgl) and brand new, the [Telegram bot api](https://github.com/luckydonald/pytgbot) as well.\r\nReceiving messages is already possible with all three (even simultaneously).\r\nAlso it features neat classes for everything. Currently I lack the time to continue that.  \r\nSee the develop branch for that. Maybe you can help make that happen.*\r\n\r\n## In case of errors ##\r\nFirst you should set logging to level `DEBUG` to see what's going on.\r\n```python\r\n# add this to the first lines in your file\r\nimport logging\r\nlogging.basicConfig(level=logging.DEBUG)\r\n```\r\nIf you are about to open a new issue, search the existing ones (open and closed) first.\r\nSometimes they are already reported or even solved.\r\n\r\n## Examples\r\nThere are some example scripts in the [examples folder](https://github.com/luckydonald/pytg/tree/master/examples):\r\n\r\n- [command_send_message](https://github.com/luckydonald/pytg/blob/master/examples/command_send_message.py): Simplest way to just send a message.\r\n    \r\n- [command_who_am_i](https://github.com/luckydonald/pytg/blob/master/examples/command_who_am_i.py): A simple example printing infos about yourself\r\n    - get the **@username** etc.\r\n    \r\n- [command_dialog_list](https://github.com/luckydonald/pytg/blob/master/examples/command_dialog_list.py): Simpler example printing the list of chats you have.\r\n    - Shows how to execute commands like `dialog_list` on the CLI.\r\n    \r\n- [bot_dump](https://github.com/luckydonald/pytg/blob/master/examples/bot_dump.py):  A small bot printing the `msg` message object.\r\n    - So you can see yourself how messages look like.    \r\n    \r\n- [bot_ping](https://github.com/luckydonald/pytg/blob/master/examples/bot_ping.py):  A simple bot reacting to messages.\r\n    - like the dump bot, but it responds to a `ping` with a `pong`.\r\n    \r\n- [bot_source_of_reply](https://github.com/luckydonald/pytg/blob/master/examples/bot_source_of_reply.py): When replying to any message with `#top`, the bot will show you the origin of that reply.\r\n    - This demonstrates how you could use `message_get` command and the `reply_id` information.\r\n\r\n- [bot_with_context](https://github.com/luckydonald/pytg/blob/master/examples/bot_with_context.py): Talk to a bot, not only a simple command.\r\n    - Demonstrates how to build converations with the use of generators and the `yield` statement.\r\n\r\n\r\n## URL Changes\r\nIf you started with pytg after 2015, you can ignore this. If you cloned from `luckydonald/pytg`, you can ignore this.\r\nHere is how to update your local git clone to this url when your old one was set to [https://github.com/efaisal/pytg.git`](https://github.com/efaisal) (before I started maintaining it in September 2014)\r\n```shell\r\n# navigate into the clone\r\ncd pytg\t # not pytg/pytg!\r\n# change to the new url\r\ngit remote set-url origin https://github.com/luckydonald/pytg.git\r\n# download the changes\r\ngit pull\r\n# don't forget to install the newest official cli: https://github.com/vysheng/tg\r\n```\r\nIf that failes at some point, just Install it from scratch. \r\n\r\n\r\nThanks!\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluckydonald%2Fpytg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluckydonald%2Fpytg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluckydonald%2Fpytg/lists"}