Chat

The twitch chat is based on the IRC protocol RFC1459. The official documentation on the twitch chat is here: Twitch IRC Doc. The irc python lib might also be useful, because we use it as backend.

pytwitcherapi.IRCClient is a simple client, which can only connect to one channel/server at a time. When building applications, you probably wanna run the IRCClient in another thread, so it doesn’t block your application. The client is thread safe and has quite a few methods to send IRC commands, if the client is running in another thread. They are wrapped versions of methods from irc.client.ServerConnection. E.g. you can simply call pytwitcherapi.IRCClient.quit() from another thread. Here is a simple example, where we send messages to the channel. Change input to raw_input for python 2:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import threading

import pytwitcherapi

session = ...  # we assume an authenticated TwitchSession
channel = session.get_channel('somechannel')
client = pytwitcherapi.IRCClient(session, channel)
t = threading.Thread(target=client.process_forever)
t.start()

try:
    while True:
        m = input('Send Message:')
        if not m: break;
        # will be processed in other thread
        # sends a message to the server
        client.send_msg(m)
finally:
    client.shutdown()
    t.join()

Important

The connection will wait/block if you send more messages than twitch allows. See pytwitcherapi.chat.ServerConnection3.

You can make the client handle different IRC events. Subclass the client and create a method on_<eventtype>. For example to greet everyone who joins an IRC channel:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import pytwitcherapi

class MyIRCClient(pytwitcherapi.IRCClient):

    def on_join(self, connection, event):
        """Handles the join event and greets everone

        :param connection: the connection with the event
        :type connection: :class:`irc.client.ServerConnection`
        :param event: the event to handle
        :type event: :class:`irc.client.Event`
        :returns: None
        """
        target = event.source
        self.privmsg(target, 'Hello %s!' % target)

If you override pytwitcherapi.IRCClient.on_pubmsg() or pytwitcherapi.IRCClient.on_privmsg() make sure to call the super method:

1
2
3
4
5
6
7
8
from pytwitcherapi import chat

class MyIRCClient(pytwitcherapi.IRCClient):

    def on_privmsg(self, connection, event):
        super(MyIRCClient, self).on_privmsg(connection, event)

        print chat.Message3.from_event(event)

But printing out messages is not really useful. You probably want to access them in another thread. All private and public messages are stored in a thread safe message queue. By default the queue stores the last 100 messages. You can alter the queuesize when creating a client. 0 will make the queue store all messages.

Note

The Client is using two connections. One for sending messages (pytwitcherapi.IRCClient.in_connection) and one for receiving (pytwitcherapi.IRCClient.in_connection) them. With one message, you wouldn’t revceive your own messages processed from the server (with tags).

Here is a little example. To quit press CTRL-C:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import threading
import queue  # Queue for python 2

import pytwitcherapi

session = ...  # we assume an authenticated TwitchSession
channel = session.get_channel('somechannel')
client = pytwitcherapi.IRCClient(session, channel, queuesize=0)
t = threading.Thread(target=client.process_forever)
t.start()

try:
    while True:
        try:
            m = client.messages.get(block=False)
        except queue.Empty:
            pass
        else:
            # Now you have the message in the main thread
            # and can display the message in the
            # GUI or wherever you want
            print "Message from %s to %s: %s" % (m.source, m.target, m.text)
finally:
    client.shutdown()
    t.join()

Tags and metadata

Twitch does support tags. Tags store metadata about a message, like the color of the user, whether he is a subscriber, the pytwichterapi.chat.Emote etc. These messages get safed id the message queue: pytwitcherapi.IRCClient.messages. See the pytwitcherapi.chat.Message3 documentation for the additional metadata.

Here is a little example. To quit press CTRL-C:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import threading
import queue  # Queue for python 2

import pytwitcherapi

session = ...  # we assume an authenticated TwitchSession
channel = session.get_channel('somechannel')
client = pytwitcherapi.IRCClient(session, channel, queuesize=0)
t = threading.Thread(target=client.process_forever)
t.start()

try:
    while True:
        try:
            m = client.messages.get(block=False)
        except queue.Empty:
            pass
        else:
            print m.color
            print m.subscriber
            print m.turbo
            print m.emotes
            print m.user_type
finally:
    client.shutdown()
    t.join()