Asset¶
- asyncfetch_ext
- asyncread
- asyncsave
- defset_dimensions
- defurl_for
- class twitchio.Asset¶
Represents an asset from Twitch.
Assets can be used to save or read from images or other media from Twitch. You can also retrieve the URL of the asset via the provided properties and methods.
New in version 3.0.0: Added the asset class which will replace all previous properties of models with attached media URLs.
Supported Operations¶
Operation
Usage(s)
Description
__str__
str(asset)
,f"{asset}"
Returns the asset’s URL.
__repr__
repr(asset)
,f"{asset!r}"
Returns the asset’s official representation.
- property url: str¶
The URL of the asset.
If the asset supports custom dimensions, the URL will contain the dimensions set.
See
set_dimensions()
for information on setting custom dimensions.
- property base_url: str¶
The base URL of the asset without any dimensions set.
This is the URL provided by Twitch before any dimensions are set.
- property qualified_name: str¶
A property that returns the qualified name of the asset.
This is the name of the asset with the file extension if one can be determined. If the file extension has not been set, this method returns the same as
name
.
- property ext: str | None¶
A property that returns the file extension of the asset.
Could be
None
if the asset does not have a valid file extension or it has not been determined yet.See: :meth:.fetch_ext` to try and force setting the file extension by content type.
- property dimensions: tuple[int, int] | None¶
A property that returns the dimensions of the asset if it supports custom dimensions or
None
.See:
set_dimensions()
for more information.
- set_dimensions(width: int, height: int) None ¶
Set the dimensions of the asset for saving or reading.
By default all assets that support custom dimensions already have pre-defined values set. If custom dimensions are not supported, a warning will be logged and the default dimensions will be used.
Warning
If you need to custom dimensions for an asset that supports it you should use this method before calling
save()
orread()
.Examples
# Fetch a game and set the box art dimensions to 720x960; which is a 3:4 aspect ratio. game: twitchio.Game = await client.fetch_game("League of Legends") game.box_art.set_dimensions(720, 960) # Call read or save... await game.box_art.save()
- url_for(width: int, height: int) str ¶
Return a new URL for the asset with the specified dimensions.
Note
This method does not return new dimensions on assets that do not support it.
Warning
This method does not set dimensions for saving or reading. If you need custom dimensions for an asset that supports it see:
set_dimensions()
.
- async fetch_ext() str | None ¶
Fetch and set the file extension of the asset by content type.
This method will try to fetch the file extension of the asset by making a HEAD request to the asset’s URL. If the content type is not recognized or the request fails, the file extension will remain unchanged.
For the majority of cases you should not need to use this method.
Warning
This method sets the file extension of the asset by content type.
- Returns
The file extension of the asset determined by the content type or
None
if it could not be determined.- Return type
str | None
- async save(fp: str | os.PathLike[Any] | io.BufferedIOBase | None = None, seek_start: bool = True, force_extension: bool = True) int ¶
Save this asset to a file or file-like object.
If
fp
isNone
, the asset will be saved to the current working directory with the asset’s default qualified name.Examples
Save with defaults
# Fetch a game and save the box art to the current working directory with the asset's default name. game: twitchio.Game = await client.fetch_game("League of Legends") await game.box_art.save()
Save with a custom name
# Fetch a game and save the box art to the current working directory with a custom name. game: twitchio.Game = await client.fetch_game("League of Legends") await game.box_art.save("custom_name.png")
Save with a file-like object
# Fetch a game and save the box art to a file-like object. game: twitchio.Game = await client.fetch_game("League of Legends") with open("custom_name.png", "wb") as fp: await game.box_art.save(fp)
- Parameters
fp (str | os.PathLike | io.BufferedIOBase | None) –
The file path or file-like object to save the asset to.
If
None
, the asset will be saved to the current working directory with the asset’s qualified name.If
fp
is a directory, the asset will be saved to the directory with the asset’s qualified name.Defaults to
None
.seek_start (bool) – Whether to seek to the start of the file after successfully writing data. Defaults to
True
.force_extension (bool) –
Whether to force the file extension of the asset to match the content type. Defaults to
True
.If no file extension was provided with
fp
settingforce_extension
toTrue
will force the file extension to match the content type provided by Twitch.
- Returns
The number of bytes written to the file or file-like object.
- Return type
- Raises
FileNotFoundError – Raised when
fp
is a directory or path to directory which can not be found or accessed.
- async read(*, seek_start: bool = True, chunk_size: int = 1024) BytesIO ¶
Read from the asset and return an
io.BytesIO
buffer.You can use this method to save the asset to memory and use it later.
Examples
# Fetch a game and read the box art to memory. game: twitchio.Game = await client.fetch_game("League of Legends") data: io.BytesIO = await game.box_art.read() # Later... some_bytes = data.read()
- Parameters
- Returns
A bytes buffer containing the asset’s data.
- Return type
Colour¶
- clsColour.announcement_blue
- clsColour.announcement_green
- clsColour.announcement_orange
- clsColour.announcement_primary
- clsColour.announcement_purple
- clsColour.blue
- clsColour.blue_violet
- clsColour.cadet_blue
- clsColour.chocolate
- clsColour.coral
- clsColour.dodger_blue
- clsColour.firebrick
- clsColour.from_hex
- clsColour.from_int
- clsColour.golden_rod
- clsColour.green
- clsColour.hot_pink
- clsColour.orange_red
- clsColour.red
- clsColour.sea_green
- clsColour.spring_green
- clsColour.yellow_green
- class twitchio.Colour¶
Helper class for working with colours in TwitchIO.
Tip
There is an alias for this class called Color.
Supported Operations¶
Operation
Usage(s)
Description
__str__
str(colour), f”{colour}”
Returns the colour as a hex string.
__repr__
repr(colour), f”{colour!r}”
Returns the colours official representation.
__eq__
colour1 == colour2
Checks if two colours are equal.
__format__
f”{colour:html}”, f”{colour:rgb}”, f”{colour:hls}”
Returns a colour str in the specified format.
__int__
int(colour)
Returns the code as an integer.
- property hex_clean: str¶
Property returning the colour as a hex string without any prefix.
E.g. “FFDD00”
- property rgb: tuple[int, int, int]¶
Property returning the colour as an RGB tuple of int.
E.g. (255, 221, 0)
- property hls: tuple[float, float, float]¶
Property returning the colour as an HLS tuple of float.
This is not the same as
hls_coords
.E.g. (52, 50, 100)
- property rgb_coords: tuple[float, ...]¶
Property returning the colour as an RGB tuple of float coordinates.
E.g. (1.0, 0.8666666666666667, 0.0)
- property hls_coords: tuple[float, ...]¶
Property returning the colour as an HLS tuple of float coordinates.
E.g. (0.14444444444444446, 0.5, 1.0)
- classmethod from_hex(hex_: str, /) Self ¶
Class method to create a
Colour
object from a hex string.A valid hex string can be in either one of the following formats:
“#FFDD00”
“FFDD00”
“0xFFDD00”
For ints see: [.from_int][twitchio.Colour.from_int].
Example
colour = twitchio.Colour.from_hex("#FFDD00") print(colour)
- classmethod from_int(code: int, /) Self ¶
Class method to create a
Colour
object from a base-10 or base-16 integer.A valid integer can be in either one of the following formats:
16768256
0xFFDD00
For hex strings see:
Colour.from_hex()
.Example
colour = twitchio.Colour.from_int(0xffdd00) print(colour)
- classmethod red() Self ¶
Class method to create a
Colour
with the default red colour from the Twitch API.This corresponds to hex: #FF0000
Example
red_colour = twitchio.Colour.red()
- classmethod blue() Self ¶
Class method to create a
Colour
with the default blue colour from the Twitch API.This corresponds to hex: #0000FF
Example
blue_colour = twitchio.Colour.blue()
- classmethod green() Self ¶
Class method to create a
Colour
with the default green colour from the Twitch API.This corresponds to hex: #008000
Example
green_colour = twitchio.Colour.green()
- classmethod firebrick() Self ¶
Class method to create a
Colour
with the default firebrick colour from the Twitch API.This corresponds to hex: #B22222
Example
firebrick_colour = twitchio.Colour.firebrick()
- classmethod coral() Self ¶
Class method to create a
Colour
with the default coral colour from the Twitch API.This corresponds to hex: #FF7F50
Example
coral_colour = twitchio.Colour.coral()
- classmethod yellow_green() Self ¶
Class method to create a
Colour
with the default yellow_green colour from the Twitch API.This corresponds to hex: #9ACD32
Example
yellow_green_colour = twitchio.Colour.yellow_green()
- classmethod orange_red() Self ¶
Class method to create a
Colour
with the default orange_red colour from the Twitch API.This corresponds to hex: #FF4500
Example
orange_red_colour = twitchio.Colour.orange_red()
- classmethod sea_green() Self ¶
Class method to create a
Colour
with the default sea_green colour from the Twitch API.This corresponds to hex: #2E8B57
Example
sea_green_colour = twitchio.Colour.sea_green()
- classmethod golden_rod() Self ¶
Class method to create a
Colour
with the default golden_rod colour from the Twitch API.This corresponds to hex: #DAA520
Example
golden_rod_colour = twitchio.Colour.golden_rod()
- classmethod chocolate() Self ¶
Class method to create a
Colour
with the default chocolate colour from the Twitch API.This corresponds to hex: #D2691E
Example
chocolate_colour = twitchio.Colour.chocolate()
- classmethod cadet_blue() Self ¶
Class method to create a
Colour
with the default cadet_blue colour from the Twitch API.This corresponds to hex: #5F9EA0
Example
cadet_blue_colour = twitchio.Colour.cadet_blue()
- classmethod dodger_blue() Self ¶
Class method to create a
Colour
with the default dodger_blue colour from the Twitch API.This corresponds to hex: #1E90FF
Example
dodger_blue_colour = twitchio.Colour.dodger_blue()
- classmethod hot_pink() Self ¶
Class method to create a
Colour
with the default hot_pink colour from the Twitch API.This corresponds to hex: #FF69B4
Example
hot_pink_colour = twitchio.Colour.hot_pink()
- classmethod blue_violet() Self ¶
Class method to create a
Colour
with the default blue_violet colour from the Twitch API.This corresponds to hex: #8A2BE2
Example
blue_violet_colour = twitchio.Colour.blue_violet()
- classmethod spring_green() Self ¶
Class method to create a
Colour
with the default spring_green colour from the Twitch API.This corresponds to hex: #00FF7F
Example
sping_green_colour = twitchio.Colour.spring_green()
- classmethod announcement_blue() str ¶
A helper class method returning the string “blue”, which can be used when sending an announcement.
Example
await ctx.send_announcement("Hello", colour=Colour.announcement_blue())
- classmethod announcement_green() str ¶
A helper class method returning the string “green”, which can be used when sending an announcement.
Example
await ctx.send_announcement("Hello", colour=Colour.announcement_green())
- classmethod announcement_orange() str ¶
A helper class method returning the string “orange”, which can be used when sending an announcement.
Example
await ctx.send_announcement("Hello", colour=Colour.announcement_orange())
- classmethod announcement_purple() str ¶
A helper class method returning the string “purple”, which can be used when sending an announcement.
Example
await ctx.send_announcement("Hello", colour=Colour.announcement_purple())
- classmethod announcement_primary() str ¶
A helper class method returning the string “primary”, which can be used when sending an announcement.
Note
“primary” is the default value used by Twitch and isn’t required to be sent. The channel’s accent color is used to highlight the announcement instead.
Example
await ctx.send_announcement("Hello", colour=Colour.announcement_primary())
Scopes¶
- analytics_read_extensions
- analytics_read_games
- bits_read
- channel_bot
- channel_edit_commercial
- channel_manage_ads
- channel_manage_broadcast
- channel_manage_extensions
- channel_manage_guest_star
- channel_manage_moderators
- channel_manage_polls
- channel_manage_predictions
- channel_manage_raids
- channel_manage_redemptions
- channel_manage_schedule
- channel_manage_videos
- channel_manage_vips
- channel_moderate
- channel_read_ads
- channel_read_charity
- channel_read_editors
- channel_read_goals
- channel_read_guest_star
- channel_read_hype_train
- channel_read_polls
- channel_read_predictions
- channel_read_redemptions
- channel_read_stream_key
- channel_read_subscriptions
- channel_read_vips
- chat_edit
- chat_read
- clips_edit
- moderation_read
- moderator_manage_announcements
- moderator_manage_automod
- moderator_manage_automod_settings
- moderator_manage_banned_users
- moderator_manage_blocked_terms
- moderator_manage_chat_messages
- moderator_manage_chat_settings
- moderator_manage_guest_star
- moderator_manage_shield_mode
- moderator_manage_shoutouts
- moderator_manage_unban_requests
- moderator_manage_warnings
- moderator_read_automod_settings
- moderator_read_blocked_terms
- moderator_read_chat_settings
- moderator_read_chatters
- moderator_read_followers
- moderator_read_guest_star
- moderator_read_moderators
- moderator_read_shield_mode
- moderator_read_shoutouts
- moderator_read_unban_requests
- moderator_read_vips
- moderator_read_warnings
- selected
- user_bot
- user_edit
- user_edit_follows
- user_manage_blocked_users
- user_manage_chat_color
- user_manage_whispers
- user_read_blocked_users
- user_read_broadcast
- user_read_chat
- user_read_email
- user_read_emotes
- user_read_follows
- user_read_moderated_channels
- user_read_subscriptions
- user_read_whispers
- user_write_chat
- whispers_edit
- whispers_read
- clsScopes.all
- defurlsafe
- class twitchio.Scopes(scopes: Iterable[str | _scope_property] | None = None, /, **kwargs: bool)¶
The Scopes class is a helper utility class to help with selecting and formatting scopes for use in Twitch OAuth.
The Scopes class can be initialised and used a few different ways:
Passing a
list[str]
of scopes to the constructor which can be in the same format as seen on Twitch. E.g.["user:read:email", ...]
.Passing
Keyword-Arguments
to the constructor. E.g.user_read_email=True
Or Constructing the class without passing anything and giving each required scope a bool when needed.
There is also a classmethod
all()
which selects all scopes for you.
All scopes on this class are special descriptors.
- analytics_read_extensions¶
Equivalent to the
analytics:read:extensions
scope on Twitch.
- analytics_read_games¶
Equivalent to the
analytics:read:games
scope on Twitch.
- bits_read¶
Equivalent to the
bits:read
scope on Twitch.
- channel_manage_ads¶
Equivalent to the
channel:manage:ads
scope on Twitch.
- channel_read_ads¶
Equivalent to the
channel:read:ads
scope on Twitch.
- channel_manage_broadcast¶
Equivalent to the
channel:manage:broadcast
scope on Twitch.
- channel_read_charity¶
Equivalent to the
channel:read:charity
scope on Twitch.
- channel_edit_commercial¶
Equivalent to the
channel:edit:commercial
scope on Twitch.
- channel_read_editors¶
Equivalent to the
channel:read:editors
scope on Twitch.
- channel_manage_extensions¶
Equivalent to the
channel:manage:extensions
scope on Twitch.
- channel_read_goals¶
Equivalent to the
channel:read:goals
scope on Twitch.
- channel_read_guest_star¶
Equivalent to the
channel:read:guest:star
scope on Twitch.
- channel_manage_guest_star¶
Equivalent to the
channel:manage:guest:star
scope on Twitch.
- channel_read_hype_train¶
Equivalent to the
channel:read:hype:train
scope on Twitch.
- channel_manage_moderators¶
Equivalent to the
channel:manage:moderators
scope on Twitch.
- channel_read_polls¶
Equivalent to the
channel:read:polls
scope on Twitch.
- channel_manage_polls¶
Equivalent to the
channel:manage:polls
scope on Twitch.
- channel_read_predictions¶
Equivalent to the
channel:read:predictions
scope on Twitch.
- channel_manage_predictions¶
Equivalent to the
channel:manage:predictions
scope on Twitch.
- channel_manage_raids¶
Equivalent to the
channel:manage:raids
scope on Twitch.
- channel_read_redemptions¶
Equivalent to the
channel:read:redemptions
scope on Twitch.
- channel_manage_redemptions¶
Equivalent to the
channel:manage:redemptions
scope on Twitch.
- channel_manage_schedule¶
Equivalent to the
channel:manage:schedule
scope on Twitch.
- channel_read_stream_key¶
Equivalent to the
channel:read:stream:key
scope on Twitch.
- channel_read_subscriptions¶
Equivalent to the
channel:read:subscriptions
scope on Twitch.
- channel_manage_videos¶
Equivalent to the
channel:manage:videos
scope on Twitch.
- channel_read_vips¶
Equivalent to the
channel:read:vips
scope on Twitch.
- channel_manage_vips¶
Equivalent to the
channel:manage:vips
scope on Twitch.
- clips_edit¶
Equivalent to the
clips:edit
scope on Twitch.
- moderation_read¶
Equivalent to the
moderation:read
scope on Twitch.
- moderator_manage_announcements¶
Equivalent to the
moderator:manage:announcements
scope on Twitch.
- moderator_manage_automod¶
Equivalent to the
moderator:manage:automod
scope on Twitch.
- moderator_read_automod_settings¶
Equivalent to the
moderator:read:automod:settings
scope on Twitch.
- moderator_manage_automod_settings¶
Equivalent to the
moderator:manage:automod:settings
scope on Twitch.
- moderator_manage_banned_users¶
Equivalent to the
moderator:manage:banned:users
scope on Twitch.
- moderator_read_blocked_terms¶
Equivalent to the
moderator:read:blocked:terms
scope on Twitch.
- moderator_manage_blocked_terms¶
Equivalent to the
moderator:manage:blocked:terms
scope on Twitch.
- moderator_manage_chat_messages¶
Equivalent to the
moderator:manage:chat:messages
scope on Twitch.
- moderator_read_chat_settings¶
Equivalent to the
moderator:read:chat:settings
scope on Twitch.
- moderator_manage_chat_settings¶
Equivalent to the
moderator:manage:chat:settings
scope on Twitch.
- moderator_read_chatters¶
Equivalent to the
moderator:read:chatters
scope on Twitch.
- moderator_read_followers¶
Equivalent to the
moderator:read:followers
scope on Twitch.
- moderator_read_guest_star¶
Equivalent to the
moderator:read:guest:star
scope on Twitch.
- moderator_manage_guest_star¶
Equivalent to the
moderator:manage:guest:star
scope on Twitch.
- moderator_read_shield_mode¶
Equivalent to the
moderator:read:shield:mode
scope on Twitch.
- moderator_manage_shield_mode¶
Equivalent to the
moderator:manage:shield:mode
scope on Twitch.
- moderator_read_shoutouts¶
Equivalent to the
moderator:read:shoutouts
scope on Twitch.
- moderator_manage_shoutouts¶
Equivalent to the
moderator:manage:shoutouts
scope on Twitch.
- moderator_read_unban_requests¶
Equivalent to the
moderator:read:unban:requests
scope on Twitch.
- moderator_manage_unban_requests¶
Equivalent to the
moderator:manage:unban:requests
scope on Twitch.
- moderator_read_warnings¶
Equivalent to the
moderator:read:warnings
scope on Twitch.
- moderator_manage_warnings¶
Equivalent to the
moderator:manage:warnings
scope on Twitch.
- moderator_read_moderators¶
Equivalent to the
moderator:read:moderators
scope on Twitch.
- moderator_read_vips¶
Equivalent to the
moderator:read:vips
scope on Twitch.
- user_edit¶
Equivalent to the
user:edit
scope on Twitch.
- user_edit_follows¶
Equivalent to the
user:edit:follows
scope on Twitch.
- user_read_blocked_users¶
Equivalent to the
user:read:blocked:users
scope on Twitch.
- user_manage_blocked_users¶
Equivalent to the
user:manage:blocked:users
scope on Twitch.
- user_read_broadcast¶
Equivalent to the
user:read:broadcast
scope on Twitch.
- user_manage_chat_color¶
Equivalent to the
user:manage:chat:color
scope on Twitch.
- user_read_email¶
Equivalent to the
user:read:email
scope on Twitch.
- user_read_follows¶
Equivalent to the
user:read:follows
scope on Twitch.
- user_read_moderated_channels¶
Equivalent to the
user:read:moderated:channels
scope on Twitch.
- user_read_subscriptions¶
Equivalent to the
user:read:subscriptions
scope on Twitch.
- user_read_emotes¶
Equivalent to the
user:read:emotes
scope on Twitch.
- user_manage_whispers¶
Equivalent to the
user:manage:whispers
scope on Twitch.
- user_read_whispers¶
Equivalent to the
user:read:whispers
scope on Twitch.
- channel_bot¶
Equivalent to the
channel:bot
scope on Twitch.
- channel_moderate¶
Equivalent to the
channel:moderate
scope on Twitch.
- chat_edit¶
Equivalent to the
chat:edit
scope on Twitch.
- chat_read¶
Equivalent to the
chat:read
scope on Twitch.
- user_bot¶
Equivalent to the
user:bot
scope on Twitch.
- user_read_chat¶
Equivalent to the
user:read:chat
scope on Twitch.
- user_write_chat¶
Equivalent to the
user:write:chat
scope on Twitch.
- whispers_read¶
Equivalent to the
whispers:read
scope on Twitch.
- whispers_edit¶
Equivalent to the
whispers:edit
scope on Twitch.
- urlsafe(*, unquote: bool = False) str ¶
Method which returns a URL-Safe formatted
str
of selected scopes.The string returned by this method is safe to use in browsers etc.
- Parameters
unqoute (bool) – If this is
True
, this will return scopes without URL quoting, E.g. asuser:read:email+channel:bot
compared touser%3Aread%3Aemail+channel%3Abot
. Defaults toFalse
.
Helpers¶
- twitchio.utils.url_encode_datetime(dt: datetime) str ¶
Formats a datetime object to an RFC 3339 compliant string and URL-encodes it. If the datetime object does not have a timezone, it is converted to UTC first.
- Parameters
dt (datetime.datetime) – Datetime object.
- Returns
The URL encoded parsed datetime object.
- Return type
- twitchio.utils.parse_timestamp(timestamp: str) datetime ¶
Parses a timestamp in ISO8601 format to a datetime object.
- Parameters
timestamp (str) – The ISO8601 timestamp to be parsed.
- Returns
The parsed datetime object.
- Return type
- twitchio.utils.setup_logging(*, handler: logging.Handler | None = None, formatter: logging.Formatter | None = None, level: int | None = None, root: bool = True) None ¶
A helper function to setup logging for your application.
- Parameters
handler (
logging.Handler
| None) – An optionallogging.Handler
to use. Defaults toNone
, which creates alogging.StreamHandler
by default.formatter (
logging.Formatter
| None) – An optionallogging.Formatter
to use. Defaults toNone
, which uses a custom TrueColour formatter by default, falling back to standard colour support and finally no colour support if no colour is supported.level (int | None) – An optional int indicating the level of logging output. Defaults to
20
, which isINFO
.root (bool) – An optional bool indicating whether logging should be setup on the root logger. When
False
, logging will only be setup for twitchio. Defaults toTrue
.
Examples
import logging import twitchio LOGGER: logging.Logger = logging.getLogger(__name__) twitchio.utils.setup_logging(level=logging.INFO) ... arg: str = "World!" LOGGER.info("Hello %s", arg)
HTTP¶
- class twitchio.Route¶
Route class used by TwitchIO to prepare HTTP requests to Twitch.
Warning
You should not change or instantiate this class manually, as it is used internally.
- token_for¶
The User ID that was used to gather a token for authentication. Could be an empty
str
.- Type
- method¶
The request method used.
- Type
Literal[‘GET’, ‘POST’, ‘PUT’, ‘PATCH’, ‘DELETE’, ‘OPTIONS’, ‘HEAD’, ‘CONNECT’, ‘TRACE’]
- class twitchio.HTTPAsyncIterator¶
TwitchIO async iterator for HTTP requests.
When a method or function returns this iterator you should call the returning function in one of the following two ways:
await method(...)
or
async for item in method(...)
When awaited the iterator will return a flattened list of all the items returned via the request for the first page only. If the endpoint is paginated, it is preferred you use
async for item in method(...)
in a list comprehension.When used with
async for
the iterator will return the next item available until no items remain or you break from the loop manually, E.g. withbreak
orreturn
etc.async for item in method(...)
will continue making requests on paginated endpoints to the next page as needed and when available.You can create a flattened list of all pages with a list comprehension.
Examples
# Flatten and return first page (20 results) streams = await bot.fetch_streams() # Flatten and return up to 1000 results (max 100 per page) which equates to 10 requests... streams = [stream async for stream in bot.fetch_streams(first=100, max_results=1000)] # Loop over results until we manually stop... async for item in bot.fetch_streams(first=100, max_results=1000): # Some logic... ... break
Important
Everything in this class is private internals, and should not be modified.