Metadata-Version: 2.4
Name: disagreement
Version: 0.4.0
Summary: A Python library for the Discord API.
Author-email: Slipstream <me@slipstreamm.dev>
License: BSD 3-Clause
Project-URL: Homepage, https://github.com/Slipstreamm/disagreement
Project-URL: Issues, https://github.com/Slipstreamm/disagreement/issues
Keywords: discord,api,bot,async,aiohttp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4.0.0,>=3.9.0
Requires-Dist: PyNaCl<2.0.0,>=1.5.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=1.0.0; extra == "test"
Requires-Dist: hypothesis>=6.132.0; extra == "test"
Provides-Extra: dev
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Dynamic: license-file

# Disagreement

A Python library for interacting with the Discord API, with a focus on bot development.

## Features

- Internationalization helpers
- Hybrid context for commands
- Built-in rate limiting
- Asynchronous design using `aiohttp`
- Gateway and HTTP API clients
- Slash command framework
- Message component helpers
- Built-in caching layer
- Experimental voice support
- Helpful error handling utilities

## Installation

```bash
python -m pip install -U pip
pip install disagreement
# or install from source for development
pip install -e .
```

Requires Python 3.10 or newer.

To run the example scripts, you'll need the `python-dotenv` package to load
environment variables. Install the development extras with:

```bash
pip install "disagreement[dev]"
```

## Basic Usage

```python
import asyncio
import os

import disagreement
from disagreement.ext import commands
from dotenv import load_dotenv
load_dotenv()


class Basics(commands.Cog):
    def __init__(self, client: disagreement.Client) -> None:
        super().__init__(client)

    @commands.command()
    async def ping(self, ctx: commands.CommandContext) -> None:
        await ctx.reply(f"Pong! Gateway Latency: {self.client.latency_ms} ms.")


token = os.getenv("DISCORD_BOT_TOKEN")
if not token:
    raise RuntimeError("DISCORD_BOT_TOKEN environment variable not set")

intents = disagreement.GatewayIntent.default() | disagreement.GatewayIntent.MESSAGE_CONTENT
client = disagreement.Client(token=token, command_prefix="!", intents=intents, mention_replies=True)
async def main() -> None:
    client.add_cog(Basics(client))
    await client.run()


if __name__ == "__main__":
    asyncio.run(main())
```

### Global Error Handling

To ensure unexpected errors don't crash your bot, you can enable the library's
global error handler:

```python
import disagreement

disagreement.setup_global_error_handler()
```

Call this early in your program to log unhandled exceptions instead of letting
them terminate the process.

### Configuring Logging

Use :func:`disagreement.logging_config.setup_logging` to configure logging for
your bot. The helper accepts a logging level and an optional file path.

```python
import logging
from disagreement.logging_config import setup_logging

setup_logging(logging.INFO)
# Or log to a file
setup_logging(logging.DEBUG, file="bot.log")
```

### HTTP Session Options

Pass additional keyword arguments to ``aiohttp.ClientSession`` using the
``http_options`` parameter when constructing :class:`disagreement.Client`:

```python
client = disagreement.Client(
    token=token,
    http_options={"proxy": "http://localhost:8080"},
)
```

These options are forwarded to ``HTTPClient`` when it creates the underlying
``aiohttp.ClientSession``. You can specify a custom ``connector`` or any other
session parameter supported by ``aiohttp``.

### Default Allowed Mentions

Specify default mention behaviour for all outgoing messages when constructing the client:

```python
client = disagreement.Client(
    token=token,
    allowed_mentions={"parse": [], "replied_user": False},
)
```

This dictionary is used whenever ``send_message`` is called without an explicit
``allowed_mentions`` argument.

### Defining Subcommands with `AppCommandGroup`

```python
from disagreement.ext.app_commands import AppCommandGroup, slash_command
from disagreement.ext.app_commands.context import AppCommandContext

settings_group = AppCommandGroup("settings", "Manage settings")
admin_group = AppCommandGroup("admin", "Admin settings", parent=settings_group)


@slash_command(name="show", description="Display a setting.", parent=settings_group)
async def show(ctx: AppCommandContext, key: str):
    ...


@slash_command(name="set", description="Update a setting.", parent=admin_group)
async def set_setting(ctx: AppCommandContext, key: str, value: str):
    ...
```
## Fetching Guilds

Use `Client.fetch_guild` to retrieve a guild from the Discord API if it
isn't already cached. This is useful when working with guild IDs from
outside the gateway events.

```python
guild = await client.fetch_guild("123456789012345678")
roles = await client.fetch_roles(guild.id)
```

## Sharding

To run your bot across multiple gateway shards, pass ``shard_count`` when creating
the client:

```python
client = disagreement.Client(token=BOT_TOKEN, shard_count=2)
```

If you want the library to determine the recommended shard count automatically,
use ``AutoShardedClient``:

```python
client = disagreement.AutoShardedClient(token=BOT_TOKEN)
```

See `examples/sharded_bot.py` for a full example.

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

See the [docs](docs/) directory for detailed guides on components, slash commands, caching, and voice features.

## License

This project is licensed under the BSD 3-Clause license. See the [LICENSE](LICENSE) file for details.

