auric 0.0.1

A modern, feature-rich Discord API wrapper for Python

Auric

A modern, feature-rich Discord API wrapper for Python.

Auric provides an intuitive and powerful interface for building Discord bots. Built with type safety and developer experience in mind, it offers a clean, Pythonic API that feels natural to work with.

Why Auric?

After working with various Discord libraries, we built Auric to solve common pain points:

• Type Safety: Full type hints throughout the codebase for better IDE support and fewer runtime errors
• Intuitive API: Natural, Pythonic design that follows common patterns you already know
• Built-in Collectors: Wait for reactions, messages, or interactions without extra dependencies
• Rich Builders: Fluent interfaces for embeds, components, commands, and more
• Smart Caching: Efficient resource management with automatic cache sweeping
• Production Ready: Battle-tested patterns and comprehensive error handling

Quick Start

Install Auric:

pip install auric

Create your first bot:

from auric import Client, Intents, Embed

client = Client(intents=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.channel.send('Pong!')
    
    elif message.content == '!hello':
        embed = Embed(title='Hello!', description='Nice to meet you')
        embed.set_color(0x5865F2)
        await message.channel.send(embed=embed)

client.run('YOUR_BOT_TOKEN')

Key Features

Slash Commands & Interactions

Modern Discord bots use slash commands. Auric makes them simple:

from auric.builders import SlashCommandBuilder, EmbedBuilder

@client.slash_command
async def greet(interaction, name: str):
    """Greet someone by name"""
    embed = (EmbedBuilder()
        .set_title(f'Hello, {name}!')
        .set_description('Welcome to the server')
        .set_color(0x5865F2)
        .build())
    
    await interaction.reply(embed=embed)

Rich Components

Build interactive UIs with buttons and select menus:

from auric.builders import ActionRowBuilder, ButtonBuilder, ButtonStyle

row = (ActionRowBuilder()
    .add_button(ButtonBuilder()
        .set_label('Click me!')
        .set_style(ButtonStyle.PRIMARY)
        .set_custom_id('click_button'))
    .build())

await message.channel.send('Choose an option:', components=[row])

# Wait for button click
interaction = await client.wait_for('interaction_create', 
    check=lambda i: i.data.get('custom_id') == 'click_button',
    timeout=60.0)

await interaction.reply('Button clicked!')

Message Collectors

Easily collect messages, reactions, or interactions:

from auric.collectors import MessageCollector

collector = MessageCollector(client, channel)
collector.filter = lambda m: not m.author.bot and len(m.content) > 0

# Collect up to 10 messages or timeout after 60 seconds
messages = await collector.collect(max=10, timeout=60.0)
print(f'Collected {len(messages)} messages')

Smart Caching

Auric manages cache automatically, but you can customize it:

# Enable automatic cache sweeping
client.sweepers.sweep_messages(
    interval=1800,  # Clean every 30 minutes
    lifetime=3600   # Remove messages older than 1 hour
)

# Sweep multiple caches at once
client.sweepers.sweep_all()

Documentation

• Documentation Index - Complete documentation navigation
• Getting Started - Set up your first bot
• Slash Commands - Building modern commands
• API Reference - Complete API documentation

Feature Comparison

Auric includes features from popular Discord libraries, with a focus on developer experience:

Feature	Auric	Notes
Slash Commands	✅	Full support with builders
Context Menus	✅	User and message commands
Buttons	✅	All styles, URLs, and custom IDs
Select Menus	✅	All 5 types (string, user, role, mentionable, channel)
Modals	✅	Text inputs with validation
Auto-completion	✅	For slash command options
Message Collectors	✅	Built-in, no extra packages
Voice Support	✅	Connect, play, record
Webhooks	✅	Create, edit, execute
Threads	✅	Create, manage, archive
Scheduled Events	✅	Full CRUD operations
Auto-moderation	✅	Rules and actions
Cache Sweeping	✅	Automatic memory management

Examples

Check out the example bot in the documentation:

• Simple Bot - Complete working example

Contributing

We welcome contributions! Whether it's:

• Bug reports and feature requests
• Documentation improvements
• Code contributions
• Example bots

Please read our Contributing Guide before submitting pull requests.

Community

• Discord Server: Join our community
• GitHub Issues: Report bugs or request features
• Discussions: Ask questions and share ideas

Requirements

• Python 3.11 or higher
• aiohttp for async HTTP requests
• python-dotenv for environment variables (optional)

Voice support requires additional dependencies:

pip install auric[voice]

License

Auric is released under the MIT License. See LICENSE for details.

Acknowledgments

Auric is inspired by excellent libraries in the Discord ecosystem, including discord.py, discord.js, and hikari. We're grateful to their maintainers for paving the way.

---

Built with ❤️ by the Auric team. Questions? Open an issue or join our Discord.