auric 0.0.3
A modern, powerful, and type-safe Discord API wrapper for Python
License: MIT
Requires Python: >=3.11
Keywords: discord, discord-api, discord-bot, bot, api, wrapper, async, asyncio

# Auric

> A modern, fully type-safe Discord API wrapper for Python 3.11+

[![PyPI](https://img.shields.io/pypi/v/auric?style=flat-square)](https://pypi.org/project/auric/)
[![Python](https://img.shields.io/pypi/pyversions/auric?style=flat-square)](https://pypi.org/project/auric/)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/Auric-Team/auric/blob/main/LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/auric?style=flat-square)](https://pypi.org/project/auric/)

Auric is an asynchronous Python library for Discord bot development. It combines modern Python features with a clean, intuitive API to make bot creation straightforward and maintainable.

**Key characteristics:**
- Full type hints with mypy strict mode support
- Async/await architecture using aiohttp
- Comprehensive Discord API v10 coverage
- Built-in collectors, builders, and utilities
- Plugin system for modular bot organization

## Features

**Core Functionality**
- Application commands (slash, user, message context menus)
- Message components (buttons, select menus, modals)
- Voice connections and audio streaming
- Thread and forum channel support
- Auto-moderation rules and filters
- Scheduled events and stage instances
- Guild templates and discovery
- Application subscriptions and monetization

**Developer Tools**
- Fluent builder pattern for embeds, commands, and components
- Message and component collectors with timeout handling
- Plugin architecture for code organization
- Intelligent caching with configurable strategies
- Automatic sharding for large bots
- Comprehensive error handling and rate limit management

**Performance**
- Optional orjson for faster JSON parsing
- aiodns for improved DNS resolution
- Connection pooling and request batching
- Memory-efficient caching system

## Installation

Install from PyPI:

```bash
pip install auric
```

With optional dependencies:

```bash
# Voice support (PyNaCl)
pip install auric[voice]

# Performance optimizations (orjson, aiodns)
pip install auric[speed]

# All optional dependencies
pip install auric[voice,speed]
```

Development version:

```bash
pip install git+https://github.com/Auric-Team/auric.git
```

**Requirements:** Python 3.11 or higher

## Quick Start

### Basic Bot

```python
import auric

client = auric.Client(intents=auric.Intents.default())

@client.event
async def on_ready():
    print(f"Logged in as {client.user.username}")

@client.event
async def on_message(message):
    if message.author.bot:
        return
    
    if message.content == "!ping":
        await message.reply("Pong!")

client.run("YOUR_BOT_TOKEN")
```

### Slash Commands

```python
import auric
from auric.builders import EmbedBuilder

client = auric.Client(intents=auric.Intents.default())

@client.slash_command(name="greet", description="Greet a user")
async def greet(interaction: auric.Interaction, username: str):
    embed = (
        EmbedBuilder()
        .set_title(f"Hello, {username}!")
        .set_color(0x5865F2)
        .build()
    )
    await interaction.reply(embed=embed)

client.run("YOUR_BOT_TOKEN")
```

### Interactive Components

```python
from auric.builders import ButtonBuilder, ActionRowBuilder

@client.slash_command(name="vote", description="Create a poll")
async def vote(interaction: auric.Interaction):
    yes_btn = ButtonBuilder().set_label("Yes").set_custom_id("vote_yes").build()
    no_btn = ButtonBuilder().set_label("No").set_custom_id("vote_no").build()
    row = ActionRowBuilder().add_component(yes_btn).add_component(no_btn).build()
    
    await interaction.reply("Vote now:", components=[row])

@client.event
async def on_interaction(interaction):
    if interaction.type == auric.InteractionType.COMPONENT:
        if interaction.data.custom_id.startswith("vote_"):
            choice = interaction.data.custom_id.split("_")[1]
            await interaction.reply(f"You voted: {choice}", ephemeral=True)
```

## Advanced Usage

### Using Collectors

```python
from auric.collectors import MessageCollector

@client.slash_command(name="quiz", description="Start a quiz")
async def quiz(interaction: auric.Interaction):
    await interaction.reply("What is 2 + 2? (You have 30 seconds)")
    
    collector = MessageCollector(
        client,
        channel=interaction.channel,
        filter=lambda m: m.author == interaction.user,
        max_messages=1,
        timeout=30.0
    )
    
    async for message in collector:
        if message.content == "4":
            await message.reply("Correct!")
        else:
            await message.reply("Wrong answer!")
```

### Plugin System

```python
from auric.plugins import Plugin

class ModerationPlugin(Plugin):
    def __init__(self, client):
        super().__init__(client)
    
    @Plugin.listener()
    async def on_message(self, message):
        if self.check_spam(message):
            await message.delete()
            await message.channel.send(f"{message.author.mention}, please don't spam!")
    
    def check_spam(self, message):
        # Your spam detection logic
        return False

# Load the plugin
client.load_plugin(ModerationPlugin)
```

### Auto-Sharding

```python
from auric.core import AutoShardedClient

client = AutoShardedClient(intents=auric.Intents.default())

@client.event
async def on_ready():
    print(f"Bot ready with {client.shard_count} shards")
    for shard_id, shard in client.shards.items():
        print(f"Shard {shard_id}: {len(shard.guilds)} guilds")
```

## Documentation

The library is fully type-hinted and includes comprehensive docstrings. Use your IDE's autocomplete or Python's built-in help:

```python
help(auric.Client)
help(auric.EmbedBuilder)
help(auric.Intents)
```

Full documentation site coming soon.

## Contributing

Contributions are welcome. Please follow these steps:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes with appropriate tests
4. Run linters: `black auric` and `flake8 auric`
5. Commit: `git commit -m "Description of changes"`
6. Push and create a pull request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

### Development Setup

```bash
git clone https://github.com/Auric-Team/auric.git
cd auric

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -e ".[dev]"
pytest
```

## Project Status

Auric is in active development (v0.0.2). The API may change between minor versions until v1.0.0.

**Current focus:**
- Stabilizing core API
- Expanding test coverage
- Documentation improvements
- Performance optimization

## Support

- Issues: [GitHub Issues](https://github.com/Auric-Team/auric/issues)
- Discussions: [GitHub Discussions](https://github.com/Auric-Team/auric/discussions)

## License

MIT License - see [LICENSE](LICENSE) for details.