twitch-observer Documentation¶
Turn Twitch chatter into Python events.
twitchobserver makes interacting with Twitch chat super easy. It is built and tuned for realtime applications. You can make chatbots chat. You can build Twitch Plays video games.
Features¶
- Pure Python: No extra dependencies. Just plain and simple Python.
- Small API: With a few classes and a handful of methods, you can learn it over a coffee break.
- Event Based: Makes writing apps easy and straightforward.
- Context Manager: Further simplifies working with observers.
TwitchChatObserver¶
-
class
twitchobserver.twitchobserver.
TwitchChatObserver
(nickname, password)¶ Class for watching a Twitch channel. Creates events for various chat messages.
Parameters: - nickname – The user nickname to connect to the channel as
- password – The OAuth token to authenticate with
-
add_moderator
(channel, nickname)¶ Adds a user to the list of chat moderators.
Parameters: - channel – The channel name
- nickname – The nickname of the user
-
ban_user
(user, channel)¶ Bans a user from a channel.
Parameters: - user – The user name
- channel – The channel name
-
change_name_color
(color)¶ Changes the color of your name in chat.
Parameters: color – The new color of the name. Can be a hex value like #000000 or one of the colors defined in colors.Color
-
clear_chat_history
(channel)¶ Clears the chat history of a channel.
Parameters: channel – The channel name
-
emoteonly_mode
(channel, enable=True)¶ Manages the emote-only mode of the chat.
Parameters: - channel – The channel name
- enable – Boolean to decide whether to enable or disable the emote-only mode (defaults to True)
-
followers_only_mode
(channel, enable=True)¶ Manages the followers-only mode of the chat.
Parameters: - channel – The channel name
- enable – Boolean to decide whether to enable or disable the followers-only mode (defaults to True)
-
get_events
()¶ Returns a sequence of events since the last time called.
Returns: A sequence of TwitchChatEvents
-
ignore_user
(nickname, channel)¶ Ignores a particular user by not showing his messages in chat.
Parameters: - nickname – The nickname of the user
- channel – The channel name
-
join_channel
(channel)¶ Joins a channel.
Parameters: channel – The channel name
-
leave_channel
(channel)¶ Leaves a channel.
Parameters: channel – The channel name
-
list_moderators
(channel)¶ Lists all moderators of a given channel.
Parameters: channel – The channel name
-
on_event
(event_type)¶ Decorator for event handlers based on the event type.
The handler needs to take an event as argument.
Parameters: event_type – A ChatEventType to listen for Usage:
>>> @observer.on_event(ChatEventType.TWITCHCHATJOIN) >>> def handle_join_event(event): >>> print(event.nickname + " joined")
-
r9k_mode
(channel, enable=True)¶ Manages the r9k mode of the chat where messages with more than nine characters are checked for uniquness.
Parameters: - channel – The channel name
- enable – Boolean to decide whether to enable or disable the r9k mode (defaults to True)
-
remove_moderator
(channel, nickname)¶ Removes a user from the list of chat moderators.
Parameters: - channel – The channel name
- nickname – The nickname of the user
-
send_message
(message, channel)¶ Sends a message to a channel.
Parameters: - message – The message to be send
- channel – The channel name
-
send_whisper
(user, message)¶ Sends a whisper (private message) to a user.
Parameters: - user – The user name
- message – The message to be whispered
-
set_marker
(channel)¶ Sets a stream marker for the Twitch Highlight feature.
Parameters: channel – The channel name
-
slow_mode
(channel, duration=10, enable=True)¶ Manages the slow mode of the chat, i.e. each message of a user needs to have duration of seconds in between them.
Parameters: - channel – The channel name
- duration – The duration of forced time between two messages (in seconds, defaults to 10)
- enable – Boolean to decide whether to enable or disable the slow mode (defaults to True)
-
start
()¶ Starts the observer.
Attempt to connect to the Twitch channel with the given nickname and password. If successful a worker thread will be started to handle socket communication.
Raises: RuntimeError – If authentication fails
-
stop
(force_stop=False)¶ Stops the observer.
Stop watching the channel, shutdown the socket, and stop the worker threads once all of the outbound events have been sent.
Parameters: force_stop – Immediately stop and do not wait for remaining outbound events to be sent.
-
subscribe
(callback)¶ Receive events from watched channel.
Parameters: callback – A function that takes a single TwitchChatEvent argument
-
subscribers_only_mode
(channel, enable=True)¶ Manages the subscribers-only mode of the chat where only the streamer, moderators and subscribers can write messages.
Parameters: - channel – The channel name
- enable – Boolean to decide whether to enable or disable the subscribers-only mode (defaults to True)
-
timout_user
(nickname, channel, duration=600)¶ Timeouts a user by deleting all previously send messages and letting him not be able to send messages for ten minutes (default) or for duration of seconds.
Parameters: - nickname – The nickname of the user
- channel – The channel name
- duration – The duration to ban the user from chat (in seconds). Defaults to ten minutes
-
unban_user
(user, channel)¶ Unbans a user from a channel.
Parameters: - user – The user name
- channel – The channel name
-
unignore_user
(nickname, channel)¶ Unignores a particular user by showing his messages in chat again.
Parameters: - nickname – The nickname of the user
- channel – The channel name
-
unsubscribe
(callback)¶ Unsubscribe a callback from the observer.
Parameters: callback – A function that has been subscribed prior
TwitchChatEvent¶
-
class
twitchobserver.twitchobserver.
TwitchChatEvent
(channel=None, command=None, message='')¶ A class for representing Twitch chat events.
Parameters: - type – Type of the event. Always will be ‘TWITCHCHATEVENT’
- nickname – The nickname of the user
- channel – The name of the channel
- command – The command sent. Will be one of the following: JOIN, PART or PRIVMSG
- message – The message sent by the user
-
dumps
()¶ Dump the event to a readable string for the socket communation.
BadTwitchChatEvent¶
-
class
twitchobserver.twitchobserver.
BadTwitchChatEvent
¶ A class that is raised if a bad Twitch chat event occured.
TwitchChatEventType¶
-
class
twitchobserver.twitchobserver.
TwitchChatEventType
¶ A collection of twitch chat event types.
-
TWITCHCHATCLEARCHAT
= 'TWITCHCHATCLEARCHAT'¶
-
TWITCHCHATCOMMAND
= 'TWITCHCHATCOMMAND'¶
-
TWITCHCHATHOSTTARGET
= 'TWITCHCHATHOSTTARGET'¶
-
TWITCHCHATJOIN
= 'TWITCHCHATJOIN'¶
-
TWITCHCHATLEAVE
= 'TWITCHCHATLEAVE'¶
-
TWITCHCHATMESSAGE
= 'TWITCHCHATMESSAGE'¶
-
TWITCHCHATMODE
= 'TWITCHCHATMODE'¶
-
TWITCHCHATNOTICE
= 'TWITCHCHATNOTICE'¶
-
TWITCHCHATRECONNECT
= 'TWITCHCHATRECONNECT'¶
-
TWITCHCHATROOMSTATE
= 'TWITCHCHATROOMSTATE'¶
-
TWITCHCHATUSERNOTICE
= 'TWITCHCHATUSERNOTICE'¶
-
TWITCHCHATUSERSTATE
= 'TWITCHCHATUSERSTATE'¶
-
TWITCHCHATWHISPER
= 'TWITCHCHATWHISPER'¶
-
TwitchChatColor¶
-
class
twitchobserver.twitchobserver.
TwitchChatColor
¶ A collection of colors for the chat name.
-
BLUE
= 'Blue'¶
-
BLUEVIOLET
= 'BlueViolet'¶
-
CADETBLUE
= 'CadetBlue'¶
-
CHOCOLATE
= 'Chocolate'¶
-
CORAL
= 'Coral'¶
-
DODGERBLUE
= 'DodgerBlue'¶
-
FIREBRICK
= 'Firebrick'¶
-
GOLDENROD
= 'GoldenRod'¶
-
GREEN
= 'Green'¶
-
HOTPINK
= 'HotPink'¶
-
ORANGERED
= 'OrangeRed'¶
-
RED
= 'Red'¶
-
SEAGREEN
= 'SeaGreen'¶
-
SPRINGGREEN
= 'SpringGreen'¶
-
YELLOWGREEN
= 'YellowGreen'¶
-