{"id":13758497,"url":"https://github.com/Teekeks/pyTwitchAPI","last_synced_at":"2025-05-10T08:30:29.737Z","repository":{"id":37203098,"uuid":"249525207","full_name":"Teekeks/pyTwitchAPI","owner":"Teekeks","description":"A Python 3.7 compatible implementation of the Twitch API, EventSub, PubSub and Chat","archived":false,"fork":false,"pushed_at":"2025-04-28T08:57:30.000Z","size":2091,"stargazers_count":268,"open_issues_count":13,"forks_count":39,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-28T10:05:46.093Z","etag":null,"topics":["eventsub","helix-api","oauth","pubsub","python","twitch","twitch-api","twitch-chat","twitch-eventsub","twitch-helix","twitch-helix-webhooks","twitch-pubsub","twitch-tv","twitchapi","userauthenticator","webhook"],"latest_commit_sha":null,"homepage":"https://pytwitchapi.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Teekeks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-23T19:30:51.000Z","updated_at":"2025-04-28T08:57:34.000Z","dependencies_parsed_at":"2022-07-16T23:16:18.136Z","dependency_job_id":"1661dee6-0daf-4618-9760-12f37fa59dfe","html_url":"https://github.com/Teekeks/pyTwitchAPI","commit_stats":{"total_commits":1143,"total_committers":21,"mean_commits":54.42857142857143,"dds":0.05249343832021003,"last_synced_commit":"e81d6c63d7b7ec2758031505f677bca5682b747c"},"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Teekeks%2FpyTwitchAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Teekeks%2FpyTwitchAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Teekeks%2FpyTwitchAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Teekeks%2FpyTwitchAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Teekeks","download_url":"https://codeload.github.com/Teekeks/pyTwitchAPI/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253389415,"owners_count":21900756,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eventsub","helix-api","oauth","pubsub","python","twitch","twitch-api","twitch-chat","twitch-eventsub","twitch-helix","twitch-helix-webhooks","twitch-pubsub","twitch-tv","twitchapi","userauthenticator","webhook"],"created_at":"2024-08-03T13:00:31.315Z","updated_at":"2025-05-10T08:30:29.722Z","avatar_url":"https://github.com/Teekeks.png","language":"Python","readme":"# Python Twitch API\n\n[![PyPI version](https://img.shields.io/pypi/v/twitchAPI.svg)](https://pypi.org/project/twitchAPI/) [![Downloads](https://static.pepy.tech/badge/twitchapi)](https://pepy.tech/project/twitchapi) [![Python version](https://img.shields.io/pypi/pyversions/twitchAPI)](https://pypi.org/project/twitchAPI/) [![Twitch API version](https://img.shields.io/badge/twitch%20API%20version-Helix-brightgreen)](https://dev.twitch.tv/docs/api) [![Documentation Status](https://readthedocs.org/projects/pytwitchapi/badge/?version=latest)](https://pytwitchapi.readthedocs.io/en/latest/?badge=latest)\n\n\nThis is a full implementation of the Twitch Helix API, EventSub and Chat in python 3.7+.\n\n\n## Installation\n\nInstall using pip:\n\n```pip install twitchAPI```\n\n## Documentation and Support\n\nA full API documentation can be found [on readthedocs.org](https://pytwitchapi.readthedocs.io/en/stable/index.html).\n\nFor support please join the [Twitch API discord server](https://discord.gg/tu2Dmc7gpd)\n\n## Usage\n\n### Basic API calls\n\nSetting up an Instance of the Twitch API and get your User ID:\n\n```python\nfrom twitchAPI.twitch import Twitch\nfrom twitchAPI.helper import first\nimport asyncio\n\nasync def twitch_example():\n    # initialize the twitch instance, this will by default also create a app authentication for you\n    twitch = await Twitch('app_id', 'app_secret')\n    # call the API for the data of your twitch user\n    # this returns a async generator that can be used to iterate over all results\n    # but we are just interested in the first result\n    # using the first helper makes this easy.\n    user = await first(twitch.get_users(logins='your_twitch_user'))\n    # print the ID of your user or do whatever else you want with it\n    print(user.id)\n\n# run this example\nasyncio.run(twitch_example())\n```\n\n### Authentication\n\nThe Twitch API knows 2 different authentications. App and User Authentication.\nWhich one you need (or if one at all) depends on what calls you want to use.\n\nIt's always good to get at least App authentication even for calls where you don't need it since the rate limits are way better for authenticated calls.\n\n**Please read the docs for more details and examples on how to set and use Authentication!**\n\n#### App Authentication\n\nApp authentication is super simple, just do the following:\n\n```python\nfrom twitchAPI.twitch import Twitch\ntwitch = await Twitch('my_app_id', 'my_app_secret')\n```\n\n### User Authentication\n\nTo get a user auth token, the user has to explicitly click \"Authorize\" on the twitch website. You can use various online services to generate a token or use my build in Authenticator.\nFor my Authenticator you have to add the following URL as a \"OAuth Redirect URL\": ```http://localhost:17563```\nYou can set that [here in your twitch dev dashboard](https://dev.twitch.tv/console).\n\n\n```python\nfrom twitchAPI.twitch import Twitch\nfrom twitchAPI.oauth import UserAuthenticator\nfrom twitchAPI.type import AuthScope\n\ntwitch = await Twitch('my_app_id', 'my_app_secret')\n\ntarget_scope = [AuthScope.BITS_READ]\nauth = UserAuthenticator(twitch, target_scope, force_verify=False)\n# this will open your default browser and prompt you with the twitch verification website\ntoken, refresh_token = await auth.authenticate()\n# add User authentication\nawait twitch.set_user_authentication(token, target_scope, refresh_token)\n```\n\nYou can reuse this token and use the refresh_token to renew it:\n\n```python\nfrom twitchAPI.oauth import refresh_access_token\nnew_token, new_refresh_token = await refresh_access_token('refresh_token', 'client_id', 'client_secret')\n```\n\n### AuthToken refresh callback\n\nOptionally you can set a callback for both user access token refresh and app access token refresh.\n\n```python\nfrom twitchAPI.twitch import Twitch\n\nasync def user_refresh(token: str, refresh_token: str):\n    print(f'my new user token is: {token}')\n\nasync def app_refresh(token: str):\n    print(f'my new app token is: {token}')\n\ntwitch = await Twitch('my_app_id', 'my_app_secret')\ntwitch.app_auth_refresh_callback = app_refresh\ntwitch.user_auth_refresh_callback = user_refresh\n```\n\n## EventSub\n\nEventSub lets you listen for events that happen on Twitch.\n\nThe EventSub client runs in its own thread, calling the given callback function whenever an event happens.\n\nThere are multiple EventSub transports available, used for different use cases.\n\nSee here for more info about EventSub in general and the different Transports, including code examples: [on readthedocs](https://pytwitchapi.readthedocs.io/en/stable/modules/twitchAPI.eventsub.html)\n\n\n## Chat\n\nA simple twitch chat bot.\nChat bots can join channels, listen to chat and reply to messages, commands, subscriptions and many more.\n\nA more detailed documentation can be found [here on readthedocs](https://pytwitchapi.readthedocs.io/en/stable/modules/twitchAPI.chat.html)\n\n### Example code for a simple bot\n\n```python\nfrom twitchAPI.twitch import Twitch\nfrom twitchAPI.oauth import UserAuthenticator\nfrom twitchAPI.type import AuthScope, ChatEvent\nfrom twitchAPI.chat import Chat, EventData, ChatMessage, ChatSub, ChatCommand\nimport asyncio\n\nAPP_ID = 'my_app_id'\nAPP_SECRET = 'my_app_secret'\nUSER_SCOPE = [AuthScope.CHAT_READ, AuthScope.CHAT_EDIT]\nTARGET_CHANNEL = 'teekeks42'\n\n\n# this will be called when the event READY is triggered, which will be on bot start\nasync def on_ready(ready_event: EventData):\n    print('Bot is ready for work, joining channels')\n    # join our target channel, if you want to join multiple, either call join for each individually\n    # or even better pass a list of channels as the argument\n    await ready_event.chat.join_room(TARGET_CHANNEL)\n    # you can do other bot initialization things in here\n\n\n# this will be called whenever a message in a channel was send by either the bot OR another user\nasync def on_message(msg: ChatMessage):\n    print(f'in {msg.room.name}, {msg.user.name} said: {msg.text}')\n\n\n# this will be called whenever someone subscribes to a channel\nasync def on_sub(sub: ChatSub):\n    print(f'New subscription in {sub.room.name}:\\\\n'\n          f'  Type: {sub.sub_plan}\\\\n'\n          f'  Message: {sub.sub_message}')\n\n\n# this will be called whenever the !reply command is issued\nasync def test_command(cmd: ChatCommand):\n    if len(cmd.parameter) == 0:\n        await cmd.reply('you did not tell me what to reply with')\n    else:\n        await cmd.reply(f'{cmd.user.name}: {cmd.parameter}')\n\n\n# this is where we set up the bot\nasync def run():\n    # set up twitch api instance and add user authentication with some scopes\n    twitch = await Twitch(APP_ID, APP_SECRET)\n    auth = UserAuthenticator(twitch, USER_SCOPE)\n    token, refresh_token = await auth.authenticate()\n    await twitch.set_user_authentication(token, USER_SCOPE, refresh_token)\n\n    # create chat instance\n    chat = await Chat(twitch)\n\n    # register the handlers for the events you want\n\n    # listen to when the bot is done starting up and ready to join channels\n    chat.register_event(ChatEvent.READY, on_ready)\n    # listen to chat messages\n    chat.register_event(ChatEvent.MESSAGE, on_message)\n    # listen to channel subscriptions\n    chat.register_event(ChatEvent.SUB, on_sub)\n    # there are more events, you can view them all in this documentation\n\n    # you can directly register commands and their handlers, this will register the !reply command\n    chat.register_command('reply', test_command)\n\n\n    # we are done with our setup, lets start this bot up!\n    chat.start()\n\n    # lets run till we press enter in the console\n    try:\n        input('press ENTER to stop\\n')\n    finally:\n        # now we can close the chat bot and the twitch api client\n        chat.stop()\n        await twitch.close()\n\n\n# lets run our setup\nasyncio.run(run())\n```\n","funding_links":[],"categories":["Libraries"],"sub_categories":["Python"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTeekeks%2FpyTwitchAPI","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTeekeks%2FpyTwitchAPI","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTeekeks%2FpyTwitchAPI/lists"}