PyTg

Version 0.4.10

A Python package that communicates with the Telegram messenger CLI, to send and receive messages and more. Since January 2014

Telegram is an Whatsapp like Instant messenger, with clients for virtually every device you use.

Works with Python 2.7 and 3

I really recommend to use Python 3, because of it's build in unicode support. Python 2 uses ascii only bytestrings, causing much, much trouble when dealing with characters like öäüß or emojis. (Trust me, I've been there)
~ luckydonald

Alternative: BotApi

If you'd like to use the Telegram Bot Api instead, there also is pytgbot. It features a complete object oriented approach, mapping all the possible server responses. So you always know what attributes to expect.

Content

• Documentation
• Install
• Usage
• Contribute
• In case of errors
  • Verbose logging
• Examples

Install

Dependencies

• Install the Telegram CLI (from @vysheng), follow the official Instructions
• Install up to date fork of Telegram CLI (by @kenorb-contrib), follow the Instructions there.

Pytg

Install form PyPI

pip install pytg

To upgrade append the --upgrade flag.

Install from source

(Beta versions are in the development branch)

• a) Get the latest pytg code from github.
  git clone https://github.com/luckydonald/pytg.git && cd pytg
• b) To update already existing code, navigate to the root inside the pytg folder, then git pull
• Install sudo python setup.py install
  • The dependency "DictObject" should be installed automatically by this. If not, it is available on PyPI:
    sudo pip install DictObject
  • Same goes for "luckydonaldUtils":
    sudo pip install luckydonald-utils

Done.

Usage

Note: The examples files produce syntax errors for python 3.0 - 3.2, the pytg package itself is not affacted by this!
To fix, just remove the u in front of the strings: change u"foobar" to "foobar (see issue #39 and Python 3.3 accepts u'unicode' syntax again).

Start telegram

Create a Telegram Instance. This will manage the CLI process, and registers the Sender and Receiver for you.

from pytg import Telegram
tg = Telegram(
	telegram="/path/to/tg/bin/telegram-cli",
	pubkey_file="/path/to/tg/tg-server.pub")
receiver = tg.receiver
sender = tg.sender

If you don't want pytg to start the cli for you, start it yourself with --json -P 4458 (port 4458). You can then use the Receiver and/or the Sender like this:

from pytg.sender import Sender
from pytg.receiver import Receiver
receiver = Receiver(host="localhost", port=4458)
sender = Sender(host="localhost", port=4458)

Send a message

sender.send_msg("username", "Hello World!")
# Easy huh?

Receiving messages

You need a function as main loop.

@coroutine # from pytg.utils import coroutine
def main_loop():
	while not QUIT:
		msg = (yield) # it waits until it got a message, stored now in msg.
		print("Message: ", msg.text)
		# do more stuff here!
	#
#

Last step is to register that function:

# start the Receiver, so we can get messages!
receiver.start()

# let "main_loop" get new message events.
# You can supply arguments here, like main_loop(foo, bar).
receiver.message(main_loop())
# now it will call the main_loop function and yield the new messages.

That's the basics. Have a look into the examples folder. For starters, I recommend:

• dump.py - is usefull to see, how the messages look like.
• ping.py - is usefull to see how to interact with pytg, send messages etc.

More Documentation

The Sender object features a rich build-in help, inside the python interpreter type:

from pytg.sender import Sender
help(Sender)  # list all commands
help(Sender.get_self)  # get help for a specific command

This is also availabe as generated documentation here on github. Also have a look at the Changelog to see what's going on.

To generate the documentation yourself:

from pytg.sender import create_automatic_documentation; create_automatic_documentation()

You can also have a look at the old documentation

Contribute

You can help!

• by reporting issues
• by commiting patches/pull requests
• with testing

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 as well. Receiving messages is already possible with all three (even simultaneously). Also it features neat classes for everything. Currently I lack the time to continue that.
See the develop branch for that. Maybe you can help make that happen.

In case of errors

First you should set logging to level DEBUG to see what's going on.

# add this to the first lines in your file
import logging
logging.basicConfig(level=logging.DEBUG)

If you are about to open a new issue, search the existing ones (open and closed) first. Sometimes they are already reported or even solved.

Examples

There are some example scripts in the examples folder:

• command_send_message: Simplest way to just send a message.

• command_who_am_i: A simple example printing infos about yourself

  • get the @username etc.

• command_dialog_list: Simpler example printing the list of chats you have.

  • Shows how to execute commands like dialog_list on the CLI.

• bot_dump: A small bot printing the msg message object.

  • So you can see yourself how messages look like.

• bot_ping: A simple bot reacting to messages.

  • like the dump bot, but it responds to a ping with a pong.

• bot_source_of_reply: When replying to any message with #top, the bot will show you the origin of that reply.

  • This demonstrates how you could use message_get command and the reply_id information.

• bot_with_context: Talk to a bot, not only a simple command.

  • Demonstrates how to build converations with the use of generators and the yield statement.

URL Changes

If you started with pytg after 2015, you can ignore this. If you cloned from luckydonald/pytg, you can ignore this. Here is how to update your local git clone to this url when your old one was set to https://github.com/efaisal/pytg.git` (before I started maintaining it in September 2014)

# navigate into the clone
cd pytg	 # not pytg/pytg!
# change to the new url
git remote set-url origin https://github.com/luckydonald/pytg.git
# download the changes
git pull
# don't forget to install the newest official cli: https://github.com/vysheng/tg

If that failes at some point, just Install it from scratch.

Thanks!