pytwitcherapi.session.TwitchSession

class pytwitcherapi.session.TwitchSession[source]

Bases: pytwitcherapi.session.OAuthSession

Session for making requests to the twitch api

Use TwitchSession.kraken_request(), TwitchSession.usher_request(), TwitchSession.oldapi_request() to make easier calls to the api directly.

To get authorization, the user has to grant PyTwitcher access. The workflow goes like this:

  1. Start the login server with TwitchSession.start_login_server().
  2. User should visit TwitchSession.get_auth_url() in his browser and follow insturctions (e.g Login and Allow PyTwitcher).
  3. Check if the session is authorized with TwitchSession.authorized().
  4. Shut the login server down with TwitchSession.shutdown_login_server().

Now you can use methods that need authorization.

__init__()[source]

Initialize a new TwitchSession

Raises:None

Methods

__init__() Initialize a new TwitchSession
authorization_url(url[, state]) Form an authorization URL.
close() Closes all adapters and as such the session
delete(url, **kwargs) Sends a DELETE request.
fetch_token(token_url[, code, ...]) Generic method for fetching an access token from the token endpoint.
fetch_viewers(game) Query the viewers and channels of the given game and
followed_streams(*args, **kwargs) Return the streams the current user follows.
get(url, **kwargs) Sends a GET request.
get_adapter(url) Returns the appropriate connection adapter for the given URL.
get_auth_url() Return the url for the user to authorize PyTwitcher
get_channel(name) Return the channel for the given name
get_channel_access_token(channel) Return the token and sig for the given channel
get_chat_server(channel) Get an appropriate chat server for the given channel
get_emote_picture(emote[, size]) Return the picture for the given emote
get_game(name) Get the game instance for a game name
get_playlist(channel) Return the playlist for the given channel
get_quality_options(channel) Get the available quality options for streams of the given channel
get_redirect_target(resp) Receives a Response.
get_stream(channel) Return the stream of the given channel
get_streams([game, channels, limit, offset]) Return a list of streams queried by a number of parameters
get_user(name) Get the user for the given name
head(url, **kwargs) Sends a HEAD request.
kraken_request(method, endpoint, **kwargs) Make a request to one of the kraken api endpoints.
merge_environment_settings(url, proxies, ...) Check the environment and merge it with some settings.
mount(prefix, adapter) Registers a connection adapter to a prefix.
new_state() Generates a state string to be used in authorizations.
oldapi_request(method, endpoint, **kwargs) Make a request to one of the old api endpoints.
options(url, **kwargs) Sends a OPTIONS request.
patch(url[, data]) Sends a PATCH request.
post(url[, data, json]) Sends a POST request.
prepare_request(request) Constructs a PreparedRequest for transmission and returns it.
put(url[, data]) Sends a PUT request.
query_login_user(*args, **kwargs) Query and return the currently logined user
rebuild_auth(prepared_request, response) When being redirected we may want to strip authentication from the request to avoid leaking credentials.
rebuild_method(prepared_request, response) When being redirected we may want to change the method of the request based on certain specs or browser behavior.
rebuild_proxies(prepared_request, proxies) This method re-evaluates the proxy configuration by considering the environment variables.
refresh_token(token_url[, refresh_token, ...]) Fetch a new access token using a refresh token.
register_compliance_hook(hook_type, hook) Register a hook for request/response tweaking.
request(method, url, **kwargs) Constructs a requests.Request, prepares it and sends it.
resolve_redirects(resp, req[, stream, ...]) Receives a Response.
search_channels(query[, limit, offset]) Search for channels and return them
search_games(query[, live]) Search for games that are similar to the query
search_streams(query[, hls, limit, offset]) Search for streams and return them
send(request, **kwargs) Send a given PreparedRequest.
shutdown_login_server() Shutdown the login server and thread
start_login_server() Start a server that will get a request from a user logging in.
token_from_fragment(authorization_response) Parse token from the URI fragment, used by MobileApplicationClients.
top_games([limit, offset]) Return the current top games
usher_request(method, endpoint, **kwargs) Make a request to one of the usher api endpoints.

Attributes

access_token
authorized Boolean that indicates whether this session has an OAuth token or not.
client_id
token Return the oauth token
baseurl = None

The baseurl that gets prepended to every request url

current_user = None

The currently logined user.

token

Return the oauth token

Returns:the token
Return type:dict
Raises:None
kraken_request(method, endpoint, **kwargs)[source]

Make a request to one of the kraken api endpoints.

Headers are automatically set to accept TWITCH_HEADER_ACCEPT. Also the client id from CLIENT_ID will be set. The url will be constructed of TWITCH_KRAKENURL and the given endpoint.

Parameters:
  • method (str) – the request method
  • endpoint (str) – the endpoint of the kraken api. The base url is automatically provided.
  • kwargs – keyword arguments of requests.Session.request()
Returns:

a resonse object
Return type:

requests.Response
Raises:

requests.HTTPError
usher_request(method, endpoint, **kwargs)[source]

Make a request to one of the usher api endpoints.

The url will be constructed of TWITCH_USHERURL and the given endpoint.

Parameters:
  • method (str) – the request method
  • endpoint (str) – the endpoint of the usher api. The base url is automatically provided.
  • kwargs – keyword arguments of requests.Session.request()
Returns:

a resonse object
Return type:

requests.Response
Raises:

requests.HTTPError
oldapi_request(method, endpoint, **kwargs)[source]

Make a request to one of the old api endpoints.

The url will be constructed of TWITCH_APIURL and the given endpoint.

Parameters:
  • method (str) – the request method
  • endpoint (str) – the endpoint of the old api. The base url is automatically provided.
  • kwargs – keyword arguments of requests.Session.request()
Returns:

a resonse object
Return type:

requests.Response
Raises:

requests.HTTPError
fetch_viewers(game)[source]

Query the viewers and channels of the given game and set them on the object

Returns:the given game
Return type:models.Game
Raises:None
search_games(query, live=True)[source]

Search for games that are similar to the query

Parameters:
  • query (str) – the query string
  • live (bool) – If true, only returns games that are live on at least one channel
Returns:

A list of games
Return type:

list of models.Game instances
Raises:

None
top_games(limit=10, offset=0)[source]

Return the current top games

Parameters:
  • limit (int) – the maximum amount of top games to query
  • offset (int) – the offset in the top games
Returns:

a list of top games
Return type:

list of models.Game
Raises:

None
get_game(name)[source]

Get the game instance for a game name

Parameters:name (str) – the name of the game
Returns:the game instance
Return type:models.Game | None
Raises:None
get_channel(name)[source]

Return the channel for the given name

Parameters:name (str) – the channel name
Returns:the model instance
Return type:models.Channel
Raises:None
search_channels(query, limit=25, offset=0)[source]

Search for channels and return them

Parameters:
  • query (str) – the query string
  • limit (int) – maximum number of results
  • offset (int) – offset for pagination
Returns:

A list of channels
Return type:

list of models.Channel instances
Raises:

None
get_stream(channel)[source]

Return the stream of the given channel

Parameters:channel (str | models.Channel) – the channel that is broadcasting. Either name or models.Channel instance
Returns:the stream or None, if the channel is offline
Return type:models.Stream | None
Raises:None
get_streams(game=None, channels=None, limit=25, offset=0)[source]

Return a list of streams queried by a number of parameters sorted by number of viewers descending

Parameters:
  • game (str | models.Game) – the game or name of the game
  • channels (list of models.Channel or str) – list of models.Channels or channel names (can be mixed)
  • limit (int) – maximum number of results
  • offset (int) – offset for pagination
Returns:

A list of streams
Return type:

list of models.Stream
Raises:

None
search_streams(query, hls=False, limit=25, offset=0)[source]

Search for streams and return them

Parameters:
  • query (str) – the query string
  • hls (bool) – If true, only return streams that have hls stream
  • limit (int) – maximum number of results
  • offset (int) – offset for pagination
Returns:

A list of streams
Return type:

list of models.Stream instances
Raises:

None
followed_streams(*args, **kwargs)[source]

Return the streams the current user follows.

Needs authorization user_read.

Parameters:
  • limit (int) – maximum number of results
  • offset (int) – offset for pagination
Returns:

A list of streams
Return type:

list`of :class:`models.Stream instances
Raises:

exceptions.NotAuthorizedError
get_user(name)[source]

Get the user for the given name

Parameters:name (str) – The username
Returns:the user instance
Return type:models.User
Raises:None
query_login_user(*args, **kwargs)[source]

Query and return the currently logined user

Returns:The user instance
Return type:models.User
Raises:exceptions.NotAuthorizedError
get_playlist(channel)[source]

Return the playlist for the given channel

Parameters:channel (models.Channel | str) – the channel
Returns:the playlist
Return type:m3u8.M3U8
Raises:requests.HTTPError if channel is offline.
get_quality_options(channel)[source]

Get the available quality options for streams of the given channel

Possible values in the list:

  • source
  • high
  • medium
  • low
  • mobile
  • audio
Parameters:channel (models.Channel | str) – the channel or channel name
Returns:list of quality options
Return type:list of str
Raises:requests.HTTPError if channel is offline.
get_channel_access_token(channel)[source]

Return the token and sig for the given channel

Parameters:channel (channel | str) – the channel or channel name to get the access token for
Returns:The token and sig for the given channel
Return type:(unicode, unicode)
Raises:None
get_chat_server(channel)[source]

Get an appropriate chat server for the given channel

Usually the server is irc.twitch.tv. But because of the delicate twitch chat, they use a lot of servers. Big events are on special event servers. This method tries to find a good one.

Parameters:channel (models.Channel) – the channel with the chat
Returns:the server address and port
Return type:(str, int)
Raises:None
get_emote_picture(emote, size=1.0)[source]

Return the picture for the given emote

Parameters:
Returns:

A string resembling the picturedata of the emote
Return type:

str
Raises:

None