Twitchapi

*************

.. note:: This Version introduces a lot of breaking changes. Please see the :doc:`v4-migration` to learn how to migrate.

Keystone Features
-----------------

- EventSub now supports the newly added Websocket transport
- EventSub is now using TwitchObject based callback payloads instead of raw dictionaries
- Chat now supports Command Middleware, check out :doc:`/tutorial/chat-use-middleware` for more info
- Added :const:`~twitchAPI.oauth.UserAuthenticationStorageHelper` to cut down on common boilerplate code, check out :doc:`/tutorial/reuse-user-token` for more info

Twitch
------

- Added new fields :const:`~twitchAPI.object.api.ChannelInformation.is_branded_content` and :const:`~twitchAPI.object.api.ChannelInformation.content_classification_labels` to response of :const:`~twitchAPI.twitch.Twitch.get_channel_information()`
- Added new parameters :paramref:`~twitchAPI.twitch.Twitch.modify_channel_information.is_branded_content` and :paramref:`~twitchAPI.twitch.Twitch.modify_channel_information.content_classification_labels` to :const:`~twitchAPI.twitch.Twitch.modify_channel_information()`
- Added new Endpoint "Get Content Classification Labels" :const:`~twitchAPI.twitch.Twitch.get_content_classification_labels()`

- Removed the following deprecated Endpoints:

- "Get Soundstrack Current Track"
- "Get SoundTrack Playlist"
- "Get Soundtrack Playlists"

- :const:`~twitchAPI.twitch.Twitch.get_polls()` now allows up to 20 poll IDs
- :const:`~twitchAPI.twitch.Twitch.get_channel_followers()` can now also be used without the required Scope or just with App Authentication
- Added new parameter :paramref:`~twitchAPI.twitch.Twitch.get_clips.is_featured` to :const:`~twitchAPI.twitch.Twitch.get_clips()` and added :const:`~twitchAPI.object.api.Clip.is_featured` to result.

EventSub
--------

- Moved old EventSub from :const:`twitchAPI.eventsub` to new package :const:`twitchAPI.eventsub.webhook` and renamed it to :const:`~twitchAPI.eventsub.webhook.EventSubWebhook`
- Added new EventSub Websocket transport :const:`~twitchAPI.eventsub.websocket.EventSubWebsocket`
- All EventSub callbacks now use :const:`~twitchAPI.object.base.TwitchObject` based Payloads instead of raw dictionaries. See :ref:`eventsub-available-topics` for a list of all available Payloads
- Added :const:`~twitchAPI.eventsub.base.EventSubBase.listen_channel_update_v2()`
- Added option for :const:`~twitchAPI.eventsub.webhook.EventSubWebhook` to specify a asyncio loop via :paramref:`~twitchAPI.eventsub.webhook.EventSubWebhook.callback_loop` in which to run all callbacks in
- Added option for :const:`~twitchAPI.eventsub.websocket.EventSubWebsocket` to specify a asyncio loop via :paramref:`~twitchAPI.eventsub.websocket.EventSubWebsocket.callback_loop` in which to run all callbacks in
- Added automatical removal of tailing ``/`` in :paramref:`~twitchAPI.eventsub.webhook.EventSubWebhook.callback_url` if present
- Fixed broken handling of malformed HTTP requests made to the callback endport of :const:`~twitchAPI.eventsub.webhook.EventSubWebhook`
- Made :const:`~twitchAPI.eventsub.webhook.EventSubWebhook` more easily mockable via ``twitch-cli`` by adding :paramref:`~twitchAPI.eventsub.webhook.EventSubWebhook.subscription_url`
- Added optional subscription revokation handler via :paramref:`~twitchAPI.eventsub.webhook.EventSubWebhook.revocation_handler` to :const:`~twitchAPI.eventsub.webhook.EventSubWebhook`

PubSub
------

- Handle Authorization Revoked messages (Thanks https://github.com/Braastos )
- Added option to specify a asyncio loop via :paramref:`~twitchAPI.pubsub.PubSub.callback_loop` in which to run all callbacks in

Chat
----

- Added Chat Command Middleware, a way to decide if a command should run, see :doc:`/tutorial/chat-use-middleware` for more info.
- Added the following default Chat Command Middleware:

- :const:`~twitchAPI.chat.middleware.ChannelRestriction`
- :const:`~twitchAPI.chat.middleware.UserRestriction`
- :const:`~twitchAPI.chat.middleware.StreamerOnly`
- :const:`~twitchAPI.chat.middleware.ChannelCommandCooldown`
- :const:`~twitchAPI.chat.middleware.ChannelUserCommandCooldown`
- :const:`~twitchAPI.chat.middleware.GlobalCommandCooldown`

- Added option to specify a asyncio loop via :paramref:`~twitchAPI.chat.Chat.callback_loop` in which to run all callbacks in
- Fixed errors raised in callbacks not being properly reported
- Added Hype Chat related fields to :const:`~twitchAPI.chat.ChatMessage`
- Improved logging
- Fixed KeyError when encountering some Notice events
- Added new reply tags :paramref:`~twitchAPI.chat.ChatMessage.reply_thread_parent_msg_id` and :paramref:`~twitchAPI.chat.ChatMessage.reply_thread_parent_user_login` to :const:`~twitchAPI.chat.ChatMessage`
- Reconnects no longer duplicate the channel join list
- :const:`twitchAPI.chat.Chat.start()` now thows an error should Chat() not have been awaited


OAuth
-----

- Added :const:`~twitchAPI.oauth.UserAuthenticationStorageHelper`, a easy plug and play way to generate user auth tokens only on demand
- Made it possible to mock all auth flows with ``twitch-cli``

Other
-----

- Added :const:`~twitchAPI.object.base.AsyncIterTwitchObject.current_cursor()` to :const:`~twitchAPI.object.base.AsyncIterTwitchObject`
- Renamed module ``twitchAPI.types`` to :const:`twitchAPI.type`
- Moved all API related TwitchObjects from module :const:`twitchAPI.object` to :const:`twitchAPI.object.api`
- Removed default imports from module :const:`twitchAPI`


****************

****************

Twitch
------

- Added missing field `emote_mode` to response of :const:`~twitchAPI.twitch.Twitch.get_chat_settings()` and :const:`~twitchAPI.twitch.Twitch.update_chat_settings()` (https://github.com/Teekeks/pyTwitchAPI/issues/234)

Chat
----

- Fixed timing based `AttributeError: 'NoneType' object has no attribute 'get'` in NoticeEvent during reconnect
- Ensured that only Chat Messages will ever be parsed as chat commands
- Added functionality to set per channel based prefixes (https://github.com/Teekeks/pyTwitchAPI/issues/229):

- :const:`~twitchAPI.chat.Chat.set_channel_prefix()` to set a custom prefix for the given channel(s)
- :const:`~twitchAPI.chat.Chat.reset_channel_prefix()` to remove a custom set prefix for the given channel(s)


****************

****************

Twitch
------

- Added new :const:`~twitchAPI.object.ChatBadgeVersion` related fields to the following Endpoints: (Thanks https://github.com/stolenvw )

- :const:`~twitchAPI.twitch.Twitch.get_chat_badges()`
- :const:`~twitchAPI.twitch.Twitch.get_global_chat_badges()`

- :const:`~twitchAPI.twitch.Twitch.set_user_authentication()` now tries to refresh the given token set if it seems to be out of date
- removed the following deprecated endpoints:

- "Replace Stream Tags"
- "Get Stream Tags"
- "Get All Stream Tags"
- "Redeem Code"
- "Get Code Status"

- Fixed condition logic when parameter `first` was given for the following Endpoints:

- :const:`~twitchAPI.twitch.Twitch.get_chatters()` (Thanks https://github.com/d7415 )
- :const:`~twitchAPI.twitch.Twitch.get_soundtrack_playlist()`
- :const:`~twitchAPI.twitch.Twitch.get_soundtrack_playlists()`

PubSub
------

- PubSub now cleanly reestablishes the connection when the websocket was unexpectedly closed

****************

****************

Twitch
------

- Added the following new Endpoints:

- "Get Channel Followers" :const:`~twitchAPI.twitch.Twitch.get_channel_followers()`
- "Get Followed Channels" :const:`~twitchAPI.twitch.Twitch.get_followed_channels()`

- Fixed TypeError: __api_get_request() got an unexpected keyword argument 'body' (Thanks https://github.com/JC-Chung )

EventSub
--------

- Added new Topic :const:`~twitchAPI.eventsub.EventSub.listen_channel_follow_v2()`

Chat
----

- Bot is now correctly reconnecting and rejoining channels after losing connection
- added :const:`~twitchAPI.chat.Chat.is_subscriber()` (Thanks https://github.com/stolenvw )
- added new Event :const:`~twitchAPI.types.ChatEvent.NOTICE` - Triggered when server sends a notice message (Thanks https://github.com/stolenvw )


****************

****************

Twitch
------

- Added the new Endpoint "Send a Shoutout" :const:`~twitchAPI.twitch.Twitch.send_a_shoutout()`
- :const:`~twitchAPI.twitch.Twitch.get_users_follows()` is now marked as deprecated
- Added missing parameter :code:`type` to :const:`~twitchAPI.twitch.Twitch.get_streams()`

Helper
------

- Added new Async Generator helper :const:`~twitchAPI.helper.limit()`, with this you can limit the amount of results returned from the given AsyncGenerator to a maximum number

EventSub
--------

- Added the following new Topics:

- "Channel Shoutout Create" :const:`~twitchAPI.eventsub.EventSub.listen_channel_shoutout_create()`
- "Channel Shoutout Receive" :const:`~twitchAPI.eventsub.EventSub.listen_channel_shoutout_receive()`

PubSub
------

- Added new Topic "Low trust Users" :const:`~twitchAPI.pubsub.PubSub.listen_low_trust_users()`

Chat
----

- Improved rate limit handling of :const:`~twitchAPI.chat.Chat.join_room()` when joining multiple rooms per call
- The following functions now all ignore the capitalization of the given chat room:

- :const:`~twitchAPI.chat.Chat.join_room()`
- :const:`~twitchAPI.chat.Chat.leave_room()`
- :const:`~twitchAPI.chat.Chat.is_mod()`
- :const:`~twitchAPI.chat.Chat.send_message()`

- Added :const:`initial_channel` to :const:`~twitchAPI.chat.Chat.__init__()`, with this you can auto join channels on bot startup
- Added :const:`~twitchAPI.chat.Chat.is_in_room()`
- Added :const:`~twitchAPI.chat.Chat.log_no_registered_command_handler`, with this you can control if the "no registered handler for event" warnings should be logged or not


OAuth
-----

- Added the following new AuthScopes:

- :const:`~twitchAPI.types.AuthScope.MODERATOR_MANAGE_SHOUTOUTS`
- :const:`~twitchAPI.types.AuthScope.MODERATOR_READ_SHOUTOUTS`
- :const:`~twitchAPI.types.AuthScope.MODERATOR_READ_FOLLOWERS`

- Improved async handling of :const:`~twitchAPI.oauth.UserAuthenticator`


****************

****************

Twitch
------

- Added the following Endpoints:

- "Get AutoMod Settings" :const:`~twitchAPI.twitch.Twitch.get_automod_settings()`
- "Update AutoMod Settings" :const:`~twitchAPI.twitch.Twitch.update_automod_settings()`

- Added :const:`~twitchAPI.twitch.Twitch.session_timeout` config. With this you can optionally change the timeout behavior across the entire library

OAuth
-----

- Added the following new AuthScopes:

- :const:`~twitchAPI.types.AuthScope.MODERATOR_READ_AUTOMOD_SETTINGS`
- :const:`~twitchAPI.types.AuthScope.MODERATOR_MANAGE_AUTOMOD_SETTINGS`

****************