Skip to main content

Python Library for Twitch IRC eccentricities

Project description


python-twitch-irc is a layer of logic which takes the Pydle package and provides (or modifies existing) logic to handle Twitch IRC pecularities.


python-twitch-irc can be installed via pip install python-twitch-irc


python-twitch-irc is a layer which sits above Pydle so if documentation is lacking, refer to Pydle documentation. Twitch IRC is not fully compliant with RFC1459 and later, so some behaviors may not function as expected (such as who/whois, nick, etc).


Utilizing this library requires a Twitch account and a token generated for that account. A token can be generated via TwitchApps. Note that the generated token has the prefix 'oauth' which should be removed before use.

Rate Limiting

TwitchIrc does not provide rate limiting. To see rates and limits, see Twitch Irc Guide.

Basic Usage

TwitchIrc is expected to be used as a base class.

from python_twitch_irc import TwitchIrc

# Simple echo bot.
class MyOwnBot(TwitchIrc):
    def on_connect(self):

    # Override from base class
    def on_message(self, timestamp, tags, channel, user, message):
        self.message(channel, message)

client = MyOwnBot('MyBot', 'MyTwitchOAuthToken').start()

Pydle IRC Functionality

Most of the Basic IRC functionality can be found via Pydle Documentation. It shold be noted that not all functionality provided by Pydle is compatible with Twitch IRC.

Twitch IRC functionality

TwitchIrc provides the following additional functionality. These functions may or may not require permissioning per channel.

def start(self):
  # Starts the connection the Twitch IRC servers

def stop(self):
  # Stops connection to Twitch IRC servers

def whisper(self, user, message):
  # Sends a whisper to a user

def message(self, target, message):
  # Sends a message to a channel or whisper to a user

def action(self, target, message):
  # Performs the IRC '<username> ACTION'
  # * John slaps Jim around a bit with a large trout

def timeout(self, channel, user, seconds, reason=None):
  # Times a user out for specified seconds from a channel

def ban(self, channel, user, reason=None):
  # Permanently bans a user from a channel

def unban(self, channel, user):
  # Unbans a user from a channel

def slow(self, channel, seconds):
  # Sets the message rate of a channel to specified seconds

def slow_off(self, channel):
  # Turns off slowmode

def followers(self, channel, restrict):
  # Sets a channel to follower mode only.  Restrict should be set to values as
  # defined here:

def followers_off(self, channel):
  # Turns off follower mode in a channel

def subscribers(self, channel):
  # Turns on subscriber mode in a channel

def subscribers_off(self, channel):
  # Turns off subscriber mode in a channel

def clear(self, channel):
  # Clears the chat history in a channel

def r9kbeta(self, channel):
  # Turns on r9kbeta mode in a channel

def r9kbeta_off(self, channel):
  # Turns off r9kbeta mode in a channel

def emoteonly(self, channel):
  # Turns on emote only mode in a channel

def emoteonly_off(self, channel):
  # Turns off emote only mode in a channel

def commercial(self, channel, seconds=30):
  # Runs a commercial in the channel.  Seconds should be an appropriate value
  # defined here:

def host(self, channel, target):
  # Hosts a channel

def unhost(self, channel):
  # Stops hosting a channel

def mod(self, channel, user):
  # Gives moderation powers to user in channel

def unmod(self, channel, user):
  # Removes moderation powers from user in channel

Twitch IRC Callbacks

TwitchIRC provides callbacks which can be overriden. Their purpose/meaning can be divined from Twitch Irc Guide.

def on_cleared_chat(self, timestamp, tags, channel):

def on_channel_ban(self, timestamp, tags, channel, user):

def on_hosting(self, timestamp, host, hostee, viewers):

def on_stop_hosting(self, timestamp, host, viewers):

def on_notice(self, timestamp, tags, channel, message):

def on_reconnect_cmd(self, timestamp):

def on_roomstate(self, timestamp, tags, channel):

def on_usernotice(self, timestamp, tags, channel, message):

def on_userstate(self, timestamp, tags, channel):

def on_whisper(self, timestamp, tags, user, message):

def on_message(self, timestamp, tags, channel, user, message):


By default, capabilities are enabled. To disable capabilities, override the following functions and return False:

def on_capability_twitch_tv_membership_available(self, value):
def on_capability_twitch_tv_tags_available(self, value):
def on_capability_twitch_tv_commands_available(self, value):


Development environment utilizes docker and docker-compose for building and testing the library.


The python_twitch_irc library can be build via ./


The unit tests can be run via ./ Local changes can be tested without rebuilding the test container via ./ but requires that the initial test container be built.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python-twitch-irc-1.1.0.tar.gz (5.7 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page