TwitchIO

https://twitchio.dev/en/stable/
Admin
TwitchIO is a fully featured, powerful async Python library for the Twitch API and EventSub,...
Tokens:353,337
Snippets:3,546
Trust Score:5.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic AutoClient Setup with Subscriptions

Source: https://twitchio.dev/en/stable/references/conduits/clients.html

This snippet shows a basic setup for AutoClient, initializing it with a list of EventSub subscriptions and then starting the bot within an async context. Ensure all required parameters like client_id, client_secret, and bot_id are provided.

```python
async with Bot(subs=subs, client_id=..., client_secret=..., bot_id=..., prefix=...) as bot:
        await bot.start()
```

--------------------------------

### Install asqlite

Source: https://twitchio.dev/en/stable/getting-started/quickstart.html

Install the asqlite library for asynchronous SQLite database operations, which is used for token storage in this example.

```bash
pip install -U git+https://github.com/Rapptz/asqlite.git

```

--------------------------------

### Initialize and Start TwitchIO Client

Source: https://twitchio.dev/en/stable/exts/commands/bot.html

Demonstrates the basic setup for initializing a TwitchIO client and starting its connection within an asynchronous context. Ensure you replace '...' with your actual client initialization parameters.

```python
import asyncio
import twitchio

async def main() -> None:
    client = twitchio.Client(...)

    async with client:
        await client.start()

```

--------------------------------

### Setup Bot Entry Point

Source: https://twitchio.dev/en/stable/getting-started/quickstart.html

Sets up logging and defines the main asynchronous runner for the bot. This includes database connection, bot initialization, token addition, and starting the bot. Handles KeyboardInterrupt for graceful shutdown.

```python
import logging
import asyncio
import asqlite

import twitchio
from twitchio.ext import commands

LOGGER = logging.getLogger(__name__)

async def setup_database(tdb):
    # Placeholder for actual database setup
    # In a real scenario, this would create tables if they don't exist
    # and return necessary data like tokens and subscription info.
    print("Setting up database...")
    # Example: return dummy data
    return [("token1", "channel1"), ("token2", "channel2")], {"sub1": "info1"}

class Bot(twitchio.ext.commands.Bot):
    def __init__(self, token_database, subs):
        # Placeholder for Bot initialization
        # In a real scenario, this would configure the bot with necessary credentials
        # and settings based on the provided token_database and subs.
        print("Initializing Bot...")
        super().__init__(token="", prefix="!", initial_channels=["channel1", "channel2"])
        self.token_database = token_database
        self.subs = subs

    async def event_ready(self):
        print(f'Logged in as | {self.nick}')
        print(f'User id is | {self.user_id}')

    async def event_message(self, message):
        # Ignore messages sent by the bot itself
        if message.author.id == self.user_id:
            return
        print(f'{message.author.name}: {message.content}')
        await self.handle_commands(message)

    async def add_token(self, token, channel):
        # Placeholder for adding tokens
        print(f"Adding token for channel: {channel}")
        # In a real scenario, this would add the token to the bot's configuration
        # and potentially connect to the channel.
        pass

    async def start(self, load_tokens=True):
        # Placeholder for starting the bot
        print("Starting bot...")
        # In a real scenario, this would initiate the connection to Twitch.
        await super().start(token=None, initial_channels=["channel1", "channel2"])


def main() -> None:
    twitchio.utils.setup_logging(level=logging.INFO)

    async def runner() -> None:
        async with asqlite.create_pool("tokens.db") as tdb:
            tokens, subs = await setup_database(tdb)

            async with Bot(token_database=tdb, subs=subs) as bot:
                for pair in tokens:
                    await bot.add_token(*pair)

                await bot.start(load_tokens=False)

    try:
        asyncio.run(runner())
    except KeyboardInterrupt:
        LOGGER.warning("Shutting down due to KeyboardInterrupt")


if __name__ == "__main__":
    main()

```

--------------------------------

### Setup Logging with twitchio.utils.setup_logging

Source: https://twitchio.dev/en/stable/getting-started/migrating.html

Call this helper function before starting the client to set up logging formatting. If used on the root logger, it only needs to be called once.

```python
import twitchio

twitchio.utils.setup_logging()
```

--------------------------------

### Initialize Bot and Start

Source: https://twitchio.dev/en/stable/_sources/getting-started/quickstart.rst.txt

Sets up logging, initializes the database pool, and starts the Twitch bot. Handles graceful shutdown on KeyboardInterrupt.

```python
import asyncio
import logging

import twitchio
from twitchio.ext import commands, eventsub

import asqlite

LOGGER = logging.getLogger(__name__)


async def setup_database(tdb: asqlite.Pool) -> tuple[list[tuple[str, str]], list[eventsub.ChatMessageSubscription]]:
    """Setup the database and return tokens and subs."""
    tokens = []
    subs = []
    async with tdb.cursor() as cursor:
        await cursor.execute(
            """SELECT user_id, token FROM tokens WHERE bot_token IS NULL OR bot_token = ?""",
            (BOT_TOKEN,)
        )
        row = await cursor.fetchone()
        while row:
            tokens.append((row["user_id"], row["token"]))
            row = await cursor.fetchone()

        # If you want to setup EventSub subscriptions, you can do it here
        # For example, to subscribe to all chat messages for a given user:
        # await cursor.execute("SELECT user_id FROM users")
        # row = await cursor.fetchone()
        # while row:
        #     subs.extend([eventsub.ChatMessageSubscription(broadcaster_user_id=row["user_id"], user_id=BOT_ID)])
        #     row = await cursor.fetchone()

    return tokens, subs


# Our main entry point for our Bot
# Best to setup_logging here, before anything starts
def main() -> None:
    twitchio.utils.setup_logging(level=logging.INFO)

    async def runner() -> None:
        async with asqlite.create_pool("tokens.db") as tdb:
            tokens, subs = await setup_database(tdb)

            async with Bot(token_database=tdb, subs=subs) as bot:
                for pair in tokens:
                    await bot.add_token(*pair)

                await bot.start(load_tokens=False)

    try:
        asyncio.run(runner())
    except KeyboardInterrupt:
        LOGGER.warning("Shutting down due to KeyboardInterrupt")


if __name__ == "__main__":
    main()

```

--------------------------------

### Running a TwitchIO Bot with Async Context Manager

Source: https://twitchio.dev/en/stable/_sources/getting-started/migrating.rst.txt

This example demonstrates the recommended modern approach to starting and running a TwitchIO Bot using an async context manager for graceful shutdown and cleanup. It includes setting up logging and handling keyboard interrupts.

```python
import asyncio

from twitchio.ext import commands


class Bot(commands.Bot):

    def __init__(self):
        # Initialise our Bot with our access token, prefix and a list of our bot's commands.
        # For token, you can use the default token provided by TwitchIO, or use your own.
        super().__init__(token="oauth:YOUR_TOKEN", prefix="!", initial_channels=["YOUR_CHANNEL"])

    async def event_ready(self):
        # We are logged in and ready to chat and use commands...
        print(f"Logged in as | {self.nick}")
        print(f"User id is | {self.user_id}")

    async def event_message(self, message):
        # Messages with echo set to True are messages sent by the bot
        # itself, and we do not want to process them to avoid infinite loops.
        if message.echo:
            return

        # Randomly respond to the message with aПривет!
        # await message.channel.send(f"Hello {message.author.name}!")

        # Print the contents of our message to
        # the output window.
        print(message.content)

        # Since we have commands and events with the same name, we
        # will need to make sure we ignore the event message
        # and process the command message instead.
        await self.handle_commands(message)

    @commands.command(name='test')
    async def test_command(self, ctx):
        await ctx.send('test successful')


if __name__ == "__main__":

    async def main() -> None:
        twitchio.utils.setup_logging()

        async with Bot() as bot:
            await bot.start()
    
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        ...
```

--------------------------------

### Routine Start Method Arguments

Source: https://twitchio.dev/en/stable/exts/routines/index.html

The `start()` method accepts arbitrary positional and keyword arguments, which are then passed directly to the routine's callback function. This allows for dynamic data injection when starting a routine.

```python
start(_* args: Any_, _** kwargs: Any_) -> Task[None]
```

--------------------------------

### login

Source: https://twitchio.dev/en/stable/references/conduits/clients.html

Logs the client in and generates or stores an app token. This method is called automatically when using `start()`. It should not be called directly if `start()` is used. It also calls `setup_hook()`.

```APIDOC
## async login(*, token: str | None = None, load_tokens: bool = True, save_tokens: bool = True) -> None

### Description
Method to login the client and generate or store an app token.
This method is called automatically when using `start()`.
You should **NOT** call this method if you are using `start()`.
This method calls `setup_hook()`.

### Parameters
#### Path Parameters
- **token** (str | None) - Optional - An optional app token to use instead of generating one automatically.
- **load_tokens** (bool) - Optional - Indicates whether the `Client` should call `load_tokens()` during login automatically. Defaults to `True`.
- **save_tokens** (bool) - Optional - Indicates whether the `Client` should call `save_tokens()` during the `close()` automatically. Defaults to `True`.

### Notes
If no token is provided, the client will attempt to generate a new app token for you. This is usually preferred as generating a token is inexpensive and does not have rate-limits associated with it.
```

--------------------------------

### Install asqlite for TwitchIO

Source: https://twitchio.dev/en/stable/_sources/getting-started/quickstart.rst.txt

Install the asqlite library, which is recommended for managing tokens and subscriptions in TwitchIO 3.

```shell
pip install -U git+https://github.com/Rapptz/asqlite.git
```

--------------------------------

### start

Source: https://twitchio.dev/en/stable/references/conduits/clients.html

Logs in and runs the Client asynchronously on an existing event loop, blocking until the client is closed. Optionally starts a web adapter and loads/saves tokens.

```APIDOC
## _async _start(_token : str | None = None_, _*_ , _with_adapter : bool = True_, _load_tokens : bool = True_, _save_tokens : bool = True_)

### Description
Method to login and run the Client asynchronously on an already running event loop.
You should not call `login()` if you are using this method as it is called internally for you.
Note
This method blocks asynchronously until the client is closed.

### Parameters
#### Path Parameters
- **token** (_str_ | _None_) – An optional app token to use instead of generating one automatically.
- **with_adapter** (_bool_) – Whether to start and run a web adapter. Defaults to True.
- **load_tokens** (_bool_) – Whether to load tokens from storage. Defaults to True.
- **save_tokens** (_bool_) – Whether to save tokens to storage. Defaults to True.
```

--------------------------------

### start

Source: https://twitchio.dev/en/stable/references/client.html

Starts the client's connection to Twitch services.

```APIDOC
## start

### Description
Starts the client's connection to Twitch services.

### Method
`async start() -> None`
```

--------------------------------

### Client Login Method

Source: https://twitchio.dev/en/stable/exts/commands/autobot.html

Log in the client and manage app tokens. This method is called automatically by `start()` and should not be called directly if `start()` is used. It handles token generation/storage and calls `setup_hook()`.

```python
await bot.login(*, token: str | None = None, load_tokens: bool = True, save_tokens: bool = True)
```

--------------------------------

### Basic Command Example

Source: https://twitchio.dev/en/stable/getting-started/quickstart.html

Demonstrates a simple command structure within a Twitchio bot. This example shows how to define commands like '!give', '!thank', and '!thanks' with user mentions and optional messages.

```python
        !give <@user|user_name> <number> [message]
        !thank <@user|user_name> <number> [message]
        !thanks <@user|user_name> <number> [message]
        """
        msg = f"with message: {message}" if message else ""
        await ctx.send(f"{ctx.chatter.mention} gave {amount} thanks to {user.mention} {msg}")
```

--------------------------------

### _setup_hook

Source: https://twitchio.dev/en/stable/exts/commands/autobot.html

Method called after `login()` has been called but before the client is ready. Intended to be overridden for async setup.

```APIDOC
## _setup_hook

### Description
Method called after `login()` has been called but before the client is ready.
`start()` calls `login()` internally for you, so when using `start()` this method will be called after the client has generated and validated an app token. The client won’t complete start up until this method has completed.
This method is intended to be overriden to provide an async environment for any setup required.
By default, this method does not implement any logic.
```

--------------------------------

### Install TwitchIO for Documentation

Source: https://twitchio.dev/en/stable/_sources/getting-started/installing.rst.txt

Install TwitchIO with documentation-related dependencies. This is typically used when building or updating the project's documentation.

```shell
pip install -U twitchio[docs]
```

--------------------------------

### Client Setup Hook

Source: https://twitchio.dev/en/stable/exts/commands/autobot.html

A coroutine method called after `login()` but before the client is ready. Intended for overriding to provide an async environment for setup tasks. The client startup is blocked until this method completes.

```python
async def _setup_hook() -> None:
    pass
```

--------------------------------

### Bot Login Method

Source: https://twitchio.dev/en/stable/exts/commands/bot.html

Logs in the client and handles app token generation or storage. This is called automatically by `start()` and should not be called manually when using `start()`. It also calls `setup_hook()`.

```python
# This function is a _coroutine_.
Method to login the client and generate or store an app token.
This method is called automatically when using `start()`. You should **NOT** call this method if you are using `start()`.
This method calls `setup_hook()`.
Note
If no token is provided, the client will attempt to generate a new app token for you. This is usually preferred as generating a token is inexpensive and does not have rate-limits associated with it. 

Parameters
    
  * **token** (_str_ | _None_) – An optional app token to use instead of generating one automatically.
  * **load_tokens** (_bool_) – Optional bool which indicates whether the `Client` should call `load_tokens()` during login automatically. Defaults to `True`.
  * **save_tokens** (_bool_) – Optional bool which inicates whether the `Client` should call `save_tokens()` during the `close()` automatically. Defaults to `True`.

```

--------------------------------

### Install TwitchIO for Development

Source: https://twitchio.dev/en/stable/_sources/getting-started/installing.rst.txt

Install TwitchIO with development dependencies included. This is useful for contributing to the library or testing new features.

```shell
pip install -U twitchio[dev]
```

--------------------------------

### Install TwitchIO with Starlette Support

Source: https://twitchio.dev/en/stable/_sources/getting-started/installing.rst.txt

Use this command to install TwitchIO with support for Starlette, a common web framework.

```shell
pip install -U twitchio[starlette]
```

--------------------------------

### twitchio.utils.setup_logging

Source: https://twitchio.dev/en/stable/references/utils.html

A helper function to setup logging for your application.

```APIDOC
## twitchio.utils.setup_logging

### Description
A helper function to setup logging for your application.

### Parameters
#### Path Parameters
- **handler** (logging.Handler | None) - Optional - An optional `logging.Handler` to use. Defaults to `None`, which creates a `logging.StreamHandler` by default.
- **formatter** (logging.Formatter | None) - Optional - An optional `logging.Formatter` to use. Defaults to `None`, 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) - Optional - An optional int indicating the level of logging output. Defaults to `20`, which is `INFO`.
- **root** (bool) - Optional - An optional bool indicating whether logging should be setup on the root logger. When `False`, logging will only be setup for twitchio. Defaults to `True`.

### Returns
- **None**

### Example
```python
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)
```
```

--------------------------------

### Minimal Twitch Bot Example

Source: https://twitchio.dev/en/stable/getting-started/quickstart.html

This example demonstrates connecting to a conduit, subscribing to EventSub events, and handling user authorization. Tokens are stored in '.tio.tokens.json' by default, and subscriptions refresh automatically.

```python
import asyncio
import logging
import random
from typing import TYPE_CHECKING

import asqlite

import twitchio
from twitchio import eventsub
from twitchio.ext import commands


if TYPE_CHECKING:
    import sqlite3


LOGGER: logging.Logger = logging.getLogger("Bot")


```

--------------------------------

### Bot Setup Hook

Source: https://twitchio.dev/en/stable/exts/commands/bot.html

An asynchronous method called after `login()` but before the client is ready. It's intended for custom asynchronous setup logic. The client's startup process waits for this method to complete.

```python
async def _setup_hook() -> None:
    """
    Method called after `login()` has been called but before the client is ready.
    """
    pass
```

--------------------------------

### Install TwitchIO with Prebuilt Wheels

Source: https://twitchio.dev/en/stable/_sources/getting-started/installing.rst.txt

Install TwitchIO using a custom pip index to fetch pre-built wheels. This is recommended for Python versions >= 3.15 to avoid build tool requirements for certain dependencies.

```shell
pip install -U twitchio --extra-index-url https://pip.pythonista.gg
```

--------------------------------

### Start Bot Client

Source: https://twitchio.dev/en/stable/exts/commands/bot.html

Logs in and runs the bot client asynchronously on an existing event loop. This method blocks until the client is closed. It handles token generation and optionally starts a web adapter.

```python
async def _start(_token : str | None = None_, _*_ , _with_adapter : bool = True_, _load_tokens : bool = True_, _save_tokens : bool = True_) -> None:
    """
    Method to login and run the Client asynchronously on an already running event loop.
    """
    pass
```

--------------------------------

### run

Source: https://twitchio.dev/en/stable/references/client.html

Starts the client and connects to Twitch services. This method is typically used for bots.

```APIDOC
## run

### Description
Starts the client and connects to Twitch services. This method is typically used for bots.

### Method
`def run() -> None`
```

--------------------------------

### Test Command Example

Source: https://twitchio.dev/en/stable/exts/commands/core.html

An example of a command that can only be run by users with elevated status (broadcaster, moderator, or VIP). It demonstrates the use of the `@commands.is_elevated()` decorator.

```APIDOC
## test command

### Description
This command can be run by anyone with broadcaster, moderator OR VIP status.

### Method
`async def test(self, ctx: commands.Context) -> None:`

### Parameters
- `ctx` (commands.Context): The context of the command invocation.

### Response
- `ctx.reply("You are allowed to use this command!")`: Sends a reply message indicating the command was successfully used.

### Raises
- **GuardFailure**: The guard predicate returned `False` and prevented the chatter from using the command.
```

--------------------------------

### Start TwitchIO Client with Async Context Manager

Source: https://twitchio.dev/en/stable/references/client.html

Use this method to start the client within an existing asynchronous event loop. The client will automatically handle login and remain active until the context manager exits.

```python
import asyncio
import twitchio

async def main() -> None:
    client = twitchio.Client(...)

    async with client:
        await client.start()
```

--------------------------------

### Basic AutoClient Setup (Case 1)

Source: https://twitchio.dev/en/stable/references/conduits/clients.html

Demonstrates the most common use case for AutoClient, where the application automatically connects to an existing or new Twitch Conduit. This setup is suitable for applications that need to connect to a new or existing Conduit with minimal intervention. Subscriptions passed to the constructor will be automatically re-subscribed if the application restarts within 72 hours of the conduit going offline.

```python
class Bot(commands.AutoBot):

    def __init__(self, subs: list[twitchio.eventsub.SubscriptionPayload], *args, **kwargs) -> None:
        super().__init__(*args, **kwargs, subscriptions=subs)

    async def event_message(self, payload: twitchio.ChatMessage) -> None:
        print(f"Received Message: {payload}")


async def main() -> None:
    # An example list of subscriptions; you could create this list however you need, e.g. from a database...
    # Subscribe to 3 channels messages...
    # If you require additional subscriptions after restart and 72 hours HAS NOT passed; See: multi_subscribe()

    subs = [
        eventsub.ChatMessageSubscription(broadcaster_user_id=..., user_id=...),
```

--------------------------------

### Start Client Asynchronously

Source: https://twitchio.dev/en/stable/exts/commands/autobot.html

Logs in and runs the client asynchronously on an existing event loop. This method blocks until the client is closed. It automatically calls `login()` and can optionally start a web adapter and load/save tokens.

```python
async def _start(_token : str | None = None_, _*_ , _with_adapter : bool = True_, _load_tokens : bool = True_, _save_tokens : bool = True_) -> None:
    pass
```

--------------------------------

### set_adapter

Source: https://twitchio.dev/en/stable/references/client.html

Sets and starts a new web adapter for the client.

```APIDOC
## set_adapter

### Description
Method which sets and starts a new web adapter which inherits from either `AiohttpAdapter` or `StarlettepAdapter` or implements the `BaseAdapter` specifications.

### Method
`async set_adapter(adapter: BaseAdapter[Any]) -> None`

### Parameters
- **adapter** (BaseAdapter) - Required - The new adapter to assign and start.

### Return Type
None
```

--------------------------------

### listen

Source: https://twitchio.dev/en/stable/_sources/getting-started/migrating.rst.txt

Starts listening for events. This method is typically called after login.

```APIDOC
## listen

### Description
Starts listening for events. This method is typically called after login.

### Method
`twitchio.Client.listen()`
```

--------------------------------

### Get Last Iteration Start Time

Source: https://twitchio.dev/en/stable/exts/routines/index.html

The `last_iteration` property returns a `datetime.datetime` object indicating when the current iteration began. It returns `None` if the routine has not yet started an iteration.

```python
_property _last_iteration _: datetime.datetime | None_
```

--------------------------------

### set_adapter

Source: https://twitchio.dev/en/stable/references/conduits/clients.html

Sets and starts a new web adapter for the client. The adapter must inherit from BaseAdapter or implement its specifications.

```APIDOC
## _async _set_adapter(_adapter : BaseAdapter[Any]_)

### Description
Method which sets and starts a new web adapter which inherits from either `AiohttpAdapter` or `StarlettepAdapter` or implements the `BaseAdapter` specifications.

### Parameters
#### Path Parameters
- **adapter** (`BaseAdapter`) – The new adapter to assign and start.

### Return Type
None
```

--------------------------------

### set_adapter

Source: https://twitchio.dev/en/stable/exts/commands/bot.html

Sets and starts a new web adapter which inherits from either `AiohttpAdapter` or `StarlettepAdapter` or implements the `BaseAdapter` specifications.

```APIDOC
## set_adapter

### Description
Method which sets and starts a new web adapter which inherits from either `AiohttpAdapter` or `StarlettepAdapter` or implements the `BaseAdapter` specifications.

### Parameters
#### Path Parameters
- **adapter** (BaseAdapter) - Required - The new adapter to assign and start.

### Return Type
None
```

--------------------------------

### _set_adapter

Source: https://twitchio.dev/en/stable/exts/commands/autobot.html

Sets and starts a new web adapter which inherits from either `AiohttpAdapter` or `StarlettepAdapter` or implements the `BaseAdapter` specifications.

```APIDOC
## _set_adapter

### Description
Method which sets and starts a new web adapter which inherits from either `AiohttpAdapter` or `StarlettepAdapter` or implements the `BaseAdapter` specifications.

### Parameters
* **adapter** (BaseAdapter) - The new adapter to assign and start.

### Return type
None
```

--------------------------------

### Basic Bot Setup and Execution

Source: https://twitchio.dev/en/stable/exts/commands/bot.html

Sets up logging and runs the bot using an async context manager. Handles KeyboardInterrupt for graceful shutdown.

```python
import logging
import asyncio

import twitchio
from twitchio.ext import commands

LOGGER = logging.getLogger(__name__)


class Bot(commands.Bot):

    def __init__(self):
        # Initialise our Bot with our access token, prefix and a list of our bot commands.
        # You can use `os.environ.get("TWITCH_TOKEN")` to get the token from an environment variable.
        super().__init__(token="YOUR_TMI_TOKEN", prefix="!", initial_channels=["YOUR_CHANNEL"])

    async def event_ready(self):
        # We are logged in and ready to chat and use commands...
        print(f"Logged in as {self.nick}")
        print(f"User id is {self.user_id}")

    async def event_message(self, message):
        # Messages with echo set to True are messages sent by the bot to the channel.
        if message.echo:
            return

        # Default message handler. This is called for every message sent in chat.
        # You can add custom logic here to process messages, or ignore them.
        # For example, to ignore messages from the bot itself:
        # if message.author.name.lower() == self.nick.lower():
        #     return

        # Print the contents of our message to console
        print(f"{message.author.name}: {message.content}")

        # Since we have commands and listeners on the bot, we also need
        # to be able to pass up a copy of the message to our different
        # command classes to be handled. If a command is given, then
        # we get a command object from the message, otherwise we get a
        # regular message object.
        await self.handle_commands(message)

    @commands.command()
    async def hello(self, ctx):
        await ctx.send(f"Hello {ctx.author.name}!")


def main() -> None:
    # Setup logging, this is optional, however a nice to have...
    twitchio.utils.setup_logging(level=logging.INFO)

    async def runner() -> None:
        async with Bot() as bot:
            await bot.start()

    try:
        asyncio.run(runner())
    except KeyboardInterrupt:
        LOGGER.warning("Shutting down due to Keyboard Interrupt...")

main()

```

--------------------------------

### Get TwitchIO Version Information (Linux)

Source: https://twitchio.dev/en/stable/_sources/getting-started/debugging.rst.txt

Execute this command on Linux systems to retrieve the installed TwitchIO version and associated system information.

```bash
python -m twitchio --version
```

--------------------------------

### Get TwitchIO Version Information (Windows)

Source: https://twitchio.dev/en/stable/_sources/getting-started/debugging.rst.txt

Run this command in your Windows environment to display the installed TwitchIO version and other relevant system details.

```bash
py -m twitchio --version
```

--------------------------------

### Setup DEBUG Logging for TwitchIO

Source: https://twitchio.dev/en/stable/_sources/getting-started/debugging.rst.txt

Configure logging to capture detailed debug information for troubleshooting. This should be called once before starting the bot. Be mindful that log files can grow large.

```python3
import logging
import twitchio

handler = logging.FileHandler(filename='twitchio.log', encoding='utf-8', mode='w')
twitchio.utils.setup_logging(level=logging.DEBUG, handler=handler)
```

--------------------------------

### Client Initialization

Source: https://twitchio.dev/en/stable/references/client.html

Initializes a new Client instance with provided credentials and optional configurations.

```APIDOC
## Client Initialization

### Description
Initializes a new Client instance with provided credentials and optional configurations.

### Parameters
- **client_id** (str) - Required - The client ID of the application registered on the Twitch Developer Portal.
- **client_secret** (str) - Required - The client secret associated with the client ID.
- **bot_id** (str | None) - Optional - The User ID associated with the Bot Account for using the bot's own tokens.
- **redirect_uri** (str | None) - Optional - The redirect URI for Twitch OAuth.
- **scopes** (twitchio.Scopes | None) - Optional - Default scopes for Twitch OAuth authentication.
- **session** (aiohttp.ClientSession | None) - Optional - An aioiohttp.ClientSession to use for all HTTP requests.
- **adapter** (twitchio.StarletteAdapter | twitchio.AiohttpAdapter | None) - Optional - The web server adapter for OAuth and EventSub over Webhooks. Defaults to aiohttp.AiohttpAdapter.
- **fetch_client_user** (bool) - Optional - Whether to fetch and cache the client/bot accounts User object. Defaults to True. Requires bot_id to be set.
```

--------------------------------

### Setup DEBUG Logging for TwitchIO

Source: https://twitchio.dev/en/stable/getting-started/debugging.html

Use this function to enable DEBUG level logging for TwitchIO. It's recommended to call this once before starting your bot. Be aware that log files can grow large quickly.

```python
import logging
import twitchio

handler = logging.FileHandler(filename='twitchio.log', encoding='utf-8', mode='w')
twitchio.utils.setup_logging(level=logging.DEBUG, handler=handler)

```

--------------------------------

### Custom Guard Decorator Example

Source: https://twitchio.dev/en/stable/exts/commands/core.html

Defines and applies a custom guard decorator to a command. The predicate checks if the chatter's name starts with 'cool'. Guards are checked after argument parsing but before before_invoke hooks.

```python
def is_cool():
    def predicate(ctx: commands.Context) -> bool:
        return ctx.chatter.name.startswith("cool")

    return commands.guard(predicate)

@is_cool()
@commands.command()
async def cool(self, ctx: commands.Context) -> None:
    await ctx.reply("You are cool...!")

```

--------------------------------

### Implement Bot Commands with Components

Source: https://twitchio.dev/en/stable/getting-started/quickstart.html

Create a MyComponent class to organize bot commands and listeners. This example demonstrates how to listen to messages, define simple commands like 'hi', 'say', 'add', and 'choice', and a more advanced command with argument parsing and aliases.

```python
class MyComponent(commands.Component):
    # An example of a Component with some simple commands and listeners
    # You can use Components within modules for a more organized codebase and hot-reloading.

    def __init__(self, bot: Bot) -> None:
        # Passing args is not required...
        # We pass bot here as an example...
        self.bot = bot

    # An example of listening to an event
    # We use a listener in our Component to display the messages received.
    @commands.Component.listener()
    async def event_message(self, payload: twitchio.ChatMessage) -> None:
        print(f"[{payload.broadcaster.name}] - {payload.chatter.name}: {payload.text}")

    @commands.command()
    async def hi(self, ctx: commands.Context) -> None:
        """Command that replies to the invoker with Hi <name>! 

        !hi
        """
        await ctx.reply(f"Hi {ctx.chatter}!")

    @commands.command()
    async def say(self, ctx: commands.Context, *, message: str) -> None:
        """Command which repeats what the invoker sends.

        !say <message>
        """
        await ctx.send(message)

    @commands.command()
    async def add(self, ctx: commands.Context, left: int, right: int) -> None:
        """Command which adds to integers together.

        !add <number> <number>
        """
        await ctx.reply(f"{left} + {right} = {left + right}")

    @commands.command()
    async def choice(self, ctx: commands.Context, *choices: str) -> None:
        """Command which takes in an arbitrary amount of choices and randomly chooses one.

        !choice <choice_1> <choice_2> <choice_3> ...
        """
        await ctx.reply(f"You provided {len(choices)} choices, I choose: {random.choice(choices)}")

    @commands.command(aliases=["thanks", "thank"])
    async def give(self, ctx: commands.Context, user: twitchio.User, amount: int, *, message: str | None = None) -> None:
        """A more advanced example of a command which has makes use of the powerful argument parsing, argument converters and
        aliases.

        The first argument will be attempted to be converted to a User.
        The second argument will be converted to an integer if possible.
        The third argument is optional and will consume the reast of the message.


```

--------------------------------

### setup_logging

Source: https://twitchio.dev/en/stable/_sources/references/utils.rst.txt

Sets up the logging configuration for the twitchio library.

```APIDOC
## setup_logging

### Description
Configures the basic logging for the twitchio library, allowing users to see library-related messages.

### Function Signature
`twitchio.utils.setup_logging()`
```

--------------------------------

### Example of before_invoke and after_invoke Decorators

Source: https://twitchio.dev/en/stable/exts/commands/core.html

Demonstrates how to use `before_invoke` to set up resources like database connections before a command executes and `after_invoke` to clean them up afterward. These hooks are called even if the command fails, provided argument parsing and guards are successful.

```python
```python
@commands.command()
async def test(ctx: commands.Context) -> None:
    ...

@test.before_invoke
async def test_before(ctx: commands.Context) -> None:
    # Open a database connection for example
    ...

    ctx.connection = connection
    ...

@test.after_invoke
async def test_after(ctx: commands.Context) -> None:
    # Close a database connection for example
    ...

    await ctx.connection.close()
    ...
```
```

--------------------------------

### Load Tokens on Client Startup

Source: https://twitchio.dev/en/stable/references/client.html

Loads tokens when the client starts, typically before setup_hook. This method can be overridden to load tokens from a database or other custom sources.

```python
await client.load_tokens("/path/to/tokens.json")
```

--------------------------------

### setup_hook

Source: https://twitchio.dev/en/stable/exts/commands/bot.html

Method called after `login()` has been called but before the client is ready. This method is intended to be overridden to provide an async environment for any setup required.

```APIDOC
## setup_hook

### Description
Method called after `login()` has been called but before the client is ready.
`start()` calls `login()` internally for you, so when using `start()` this method will be called after the client has generated and validated an app token. The client won’t complete start up until this method has completed.
This method is intended to be overriden to provide an async environment for any setup required.
By default, this method does not implement any logic.
```

--------------------------------

### Charity Campaign Start Event

Source: https://twitchio.dev/en/stable/references/events/events.html

Event dispatched when the broadcaster starts a charity campaign. Requires subscription to EventSub with CharityCampaignStartSubscription.

```APIDOC
## _twitchio.event_charity_campaign_start

### Description
Event dispatched when the broadcaster starts a charity campaign. Corresponds to the Twitch EventSub subscription Charity Campaign Start.
You must subscribe to EventSub with `CharityCampaignStartSubscription` for each required broadcaster to receive this event.

### Parameters
* **payload** (_twitchio.CharityCampaignStart_) – The EventSub payload for this event.
```

--------------------------------

### setup_hook

Source: https://twitchio.dev/en/stable/references/client.html

A hook that is called when the client is ready.

```APIDOC
## setup_hook

### Description
A hook that is called when the client is ready.

### Method
`async setup_hook() -> None`
```

--------------------------------

### login

Source: https://twitchio.dev/en/stable/exts/commands/autobot.html

Logs the client into the Twitch API, generating or storing an application token. This is called automatically by `start()` and should not be called directly if `start()` is used.

```APIDOC
## async def login(*, token: str | None = None, load_tokens: bool = True, save_tokens: bool = True) -> None

### Description
Authenticates the client with the Twitch API. If no token is provided, a new app token is generated. This method also calls `setup_hook()`.

### Parameters
#### token
- **token** (str | None) - Optional - An app token to use for login. If None, a new token is generated.
#### load_tokens
- **load_tokens** (bool) - Optional - Whether to automatically call `load_tokens()` during login. Defaults to True.
#### save_tokens
- **save_tokens** (bool) - Optional - Whether to automatically call `save_tokens()` during `close()`. Defaults to True.
```

--------------------------------

### Group Command Example

Source: https://twitchio.dev/en/stable/getting-started/quickstart.html

Illustrates how to create group commands in Twitchio, allowing for nested sub-commands. This example defines a 'socials' group with a 'discord' sub-command.

```python
    @commands.group(invoke_fallback=True)
    async def socials(self, ctx: commands.Context) -> None:
        """Group command for our social links.

        !socials
        """
        await ctx.send("discord.gg/..., youtube.com/..., twitch.tv/...")

    @socials.command(name="discord")
    async def socials_discord(self, ctx: commands.Context) -> None:
        """Sub command of socials that sends only our discord invite.

        !socials discord
        """
        await ctx.send("discord.gg/...")
```

--------------------------------

### Set a Before Routine Callback

Source: https://twitchio.dev/en/stable/exts/routines/index.html

The `before_routine()` decorator allows you to specify a coroutine that will execute before the main routine starts. Arguments passed to `start()` are also passed to this callback.

```python
before_routine(_func : Callable[[...], Coroutine[Any, Any, Any]]_) -> None
```

--------------------------------

### _start

Source: https://twitchio.dev/en/stable/exts/commands/autobot.html

Logs in and runs the Client asynchronously on an already running event loop. This method blocks asynchronously until the client is closed.

```APIDOC
## _start

### Description
Method to login and run the Client asynchronously on an already running event loop.
You should not call `login()` if you are using this method as it is called internally for you.
Note
This method blocks asynchronously until the client is closed.

### Parameters
* **token** (str | None) - An optional app token to use instead of generating one automatically.
* **with_adapter** (bool) - Whether to start and run a web adapter. Defaults to True.
* **load_tokens** (bool) - Whether to load tokens from storage. Defaults to True.
* **save_tokens** (bool) - Whether to save tokens to storage. Defaults to True.

### Return type
None
```

--------------------------------

### Define and Add a TwitchIO Component

Source: https://twitchio.dev/en/stable/exts/commands/components.html

Example of creating a custom component, adding commands and an event listener, and integrating it with the bot using `setup_hook`.

```python
class Bot(commands.Bot):
    # Do your required __init__ etc first...

    # You can use setup_hook to add components...
    async def setup_hook(self) -> None:
        await self.add_component(MyComponent())

class MyComponent(commands.Component):

    # Some simple commands...
    @commands.command()
    async def hi(self, ctx: commands.Command) -> None:
        await ctx.send(f"Hello {ctx.chatter.mention}!")

    @commands.command()
    async def apple(self, ctx: commands.Command, *, count: int) -> None:
        await ctx.send(f"You have {count} apples?!")

    # An example of using an event listener in a component...
    @commands.Component.listener()
    async def event_message(self, message: twitchio.ChatMessage) -> None:
        print(f"Received Message in component: {message.content}")

    # An example of a before invoke hook that is executed directly before any command in this component...
    async def component_before_invoke(self, ctx: commands.Command) -> None:
        print(f"Processing command in component '{self.name}'.")

```

--------------------------------

### Basic Bot Subclassing with Commands

Source: https://twitchio.dev/en/stable/exts/commands/bot.html

Demonstrates subclassing commands.Bot to create a basic bot. Includes setup for event subscriptions and component loading within the setup_hook. Requires Twitch Developer Portal credentials and appropriate scopes for event subscriptions.

```python
import asyncio
import logging

import twitchio
from twitchio import eventsub
from twitchio.ext import commands

LOGGER: logging.Logger = logging.getLogger("Bot")

class Bot(commands.Bot):

    def __init__(self) -> None:
        super().__init__(client_id="...", client_secret="...", bot_id="...", owner_id="...", prefix="!")

    # Do some async setup, as an example we will load a component and subscribe to some events...
    # Passing the bot to the component is completely optional...
    async def setup_hook(self) -> None:

        # Listen for messages on our channel...
        # You need appropriate scopes, see the docs on authenticating for more info...
        payload = eventsub.ChatMessageSubscription(broadcaster_user_id=self.owner_id, user_id=self.bot_id)
        await self.subscribe_websocket(payload=payload)

        await self.add_component(SimpleCommands(self))
        LOGGER.info("Finished setup hook!")

class SimpleCommands(commands.Component):

    def __init__(self, bot: Bot) -> None:
        self.bot = bot

    @commands.command()
    async def hi(self, ctx: commands.Context) -> None:
        '''Command which sends you a hello.'''
        await ctx.reply(f"Hello {ctx.chatter}!")

    @commands.command()
    async def say(self, ctx: commands.Context, *, message: str) -> None:
        '''Command which repeats what you say: !say I am an apple...'''

```

--------------------------------

### run

Source: https://twitchio.dev/en/stable/exts/commands/bot.html

Logs in the client and creates a continuously running event loop. This method sets up and creates an async environment.

```APIDOC
## run(token: str | None = None, *, with_adapter: bool = True, load_tokens: bool = True, save_tokens: bool = True) -> None

### Description
Method to login the client and create a continuously running event loop. This method will setup and create an async environment for you. You should not call `login()` if you are using this method as it is called internally for you. This method will block until the client is closed.

### Parameters
#### Path Parameters
- **token** (str | None) - Optional - An optional app token to use instead of generating one automatically.
- **with_adapter** (bool) - Optional - Whether to start and run a web adapter. Defaults to True.
- **load_tokens** (bool) - Optional - Indicates whether the `Client` should call `load_tokens()` during `login()` automatically. Defaults to `True`.
- **save_tokens** (bool) - Optional - Indicates whether the `Client` should call `save_tokens()` during the `close()` automatically. Defaults to `True`.

### Example
```python
client = twitchio.Client(...)
client.run()
```
```

--------------------------------

### Database Setup for Tokens

Source: https://twitchio.dev/en/stable/getting-started/quickstart.html

Provides a function to set up an SQLite database table for storing user tokens and refresh tokens. It also demonstrates fetching existing tokens and generating EventSub subscriptions based on stored user IDs.

```python
async def setup_database(db: asqlite.Pool) -> tuple[list[tuple[str, str]], list[eventsub.SubscriptionPayload]]:
    # Create our token table, if it doesn't exist..
    # You should add the created files to .gitignore or potentially store them somewhere safer
    # This is just for example purposes...

    query = """CREATE TABLE IF NOT EXISTS tokens(user_id TEXT PRIMARY KEY, token TEXT NOT NULL, refresh TEXT NOT NULL)"""
    async with db.acquire() as connection:
        await connection.execute(query)

        # Fetch any existing tokens...
        rows: list[sqlite3.Row] = await connection.fetchall("SELECT * from tokens")

        tokens: list[tuple[str, str]] = []
        subs: list[eventsub.SubscriptionPayload] = []

        for row in rows:
            tokens.append((row["token"], row["refresh"]))

            if row["user_id"] == BOT_ID:
                continue

            subs.extend([eventsub.ChatMessageSubscription(broadcaster_user_id=row["user_id"], user_id=BOT_ID)])

    return tokens, subs
```

--------------------------------

### setup_hook

Source: https://twitchio.dev/en/stable/_sources/getting-started/migrating.rst.txt

Sets up a hook for a specific event.

```APIDOC
## setup_hook

### Description
Sets up a hook for a specific event.

### Method
`twitchio.Client.setup_hook(event: str, hook: callable)`

### Parameters
#### Path Parameters
- **event** (str) - Required - The name of the event to hook into.
- **hook** (callable) - Required - The function to be called when the event occurs.
```

--------------------------------

### ShieldModeBegin

Source: https://twitchio.dev/en/stable/_sources/references/eventsub/eventsub_models.rst.txt

Represents the start of Shield Mode.

```APIDOC
## ShieldModeBegin

### Description
Represents the start of Shield Mode.

### Attributes
This model inherits attributes from its parent class.
```

--------------------------------

### HypeTrainBegin

Source: https://twitchio.dev/en/stable/_sources/references/eventsub/eventsub_models.rst.txt

Represents the start of a Hype Train.

```APIDOC
## HypeTrainBegin

### Description
Represents the start of a Hype Train.

### Attributes
This model inherits attributes from its parent class.
```

--------------------------------

### run

Source: https://twitchio.dev/en/stable/references/conduits/clients.html

Logs the client in and creates a continuously running event loop. This method sets up and creates an async environment. It blocks until the client is closed.

```APIDOC
## run(*, token: str | None = None, with_adapter: bool = True, load_tokens: bool = True, save_tokens: bool = True) -> None

### Description
Method to login the client and create a continuously running event loop.
The behaviour of this method is similar to `start()` but instead of being used in an already running async environment, this method will setup and create an async environment for you.
You should not call `login()` if you are using this method as it is called internally for you.
This method will block until the client is closed.

### Parameters
#### Path Parameters
- **token** (str | None) - Optional - An optional app token to use instead of generating one automatically.
- **with_adapter** (bool) - Whether to start and run a web adapter. Defaults to True.
- **load_tokens** (bool) - Optional - Indicates whether the `Client` should call `load_tokens()` during `login()` automatically. Defaults to `True`.
- **save_tokens** (bool) - Optional - Indicates whether the `Client` should call `save_tokens()` during the `close()` automatically. Defaults to `True`.

### Important
You can not use this method in an already running async event loop. See: `start()` for starting the client in already running async environments.
```

--------------------------------

### CharityCampaignStart

Source: https://twitchio.dev/en/stable/_sources/references/eventsub/eventsub_models.rst.txt

Represents the start of a charity campaign.

```APIDOC
## CharityCampaignStart

### Description
Represents the start of a charity campaign.

### Attributes
This model inherits attributes from its parent class.
```

--------------------------------

### run

Source: https://twitchio.dev/en/stable/exts/commands/autobot.html

Logs in the client and creates a continuously running event loop. This method sets up and creates an async environment, and should not be called if `login()` is used. It blocks until the client is closed.

```APIDOC
## run

### Description
Method to login the client and create a continuously running event loop. The behaviour of this method is similar to `start()` but instead of being used in an already running async environment, this method will setup and create an async environment for you. You should not call `login()` if you are using this method as it is called internally for you. This method will block until the client is closed.

### Parameters
#### Path Parameters
- **token** (str | None) - Optional - An optional app token to use instead of generating one automatically.
- **with_adapter** (bool) - Optional - Whether to start and run a web adapter. Defaults to True.
- **load_tokens** (bool) - Optional - Optional bool which indicates whether the `Client` should call `load_tokens()` during `login()` automatically. Defaults to `True`.
- **save_tokens** (bool) - Optional - Optional bool which inicates whether the `Client` should call `save_tokens()` during the `close()` automatically. Defaults to `True`.

### Examples
```python
client = twitchio.Client(...)
client.run()
```
```

--------------------------------

### Define and Start a Limited Iteration Routine

Source: https://twitchio.dev/en/stable/exts/routines/index.html

Use the @routines.routine decorator to define a coroutine as a routine. Specify the interval using `delta` and the number of times it should run using `iterations`. The routine is then started with `my_routine.start()` passing any required arguments.

```python
@routines.routine(delta=datetime.timedelta(minutes=1), iterations=3)
async def my_routine(hello: str) -> None:
    print(f"Hello {hello}")

my_routine.start("World!")
```
Tokens:
Raw