Auric

A modern, fully type-safe Discord API wrapper for Python 3.11+

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:

pip install auric

With optional dependencies:

# 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:

pip install git+https://github.com/Auric-Team/auric.git

Requirements: Python 3.11 or higher

Quick Start

Basic Bot

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

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

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

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

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

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:

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 for detailed guidelines.

Development Setup

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
• Discussions: GitHub Discussions

License

MIT License - see LICENSE for details.