# Auric
> A modern, fully type-safe Discord API wrapper for Python 3.11+
[](https://pypi.org/project/auric/)
[](https://pypi.org/project/auric/)
[](https://github.com/Auric-Team/auric/blob/main/LICENSE)
[](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.
Raw data
{
"_id": null,
"home_page": null,
"name": "auric",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "discord, discord-api, discord-bot, bot, api, wrapper, async, asyncio",
"author": null,
"author_email": "Auric Team <auric.bot@proton.me>",
"download_url": "https://files.pythonhosted.org/packages/19/b4/eb4133b1bde60567b7de1d02c2c9ede7eb33fe6d9e836f5df184664ec581/auric-0.0.3.tar.gz",
"platform": null,
"description": "# Auric\r\n\r\n> A modern, fully type-safe Discord API wrapper for Python 3.11+\r\n\r\n[](https://pypi.org/project/auric/)\r\n[](https://pypi.org/project/auric/)\r\n[](https://github.com/Auric-Team/auric/blob/main/LICENSE)\r\n[](https://pypi.org/project/auric/)\r\n\r\nAuric 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.\r\n\r\n**Key characteristics:**\r\n- Full type hints with mypy strict mode support\r\n- Async/await architecture using aiohttp\r\n- Comprehensive Discord API v10 coverage\r\n- Built-in collectors, builders, and utilities\r\n- Plugin system for modular bot organization\r\n\r\n## Features\r\n\r\n**Core Functionality**\r\n- Application commands (slash, user, message context menus)\r\n- Message components (buttons, select menus, modals)\r\n- Voice connections and audio streaming\r\n- Thread and forum channel support\r\n- Auto-moderation rules and filters\r\n- Scheduled events and stage instances\r\n- Guild templates and discovery\r\n- Application subscriptions and monetization\r\n\r\n**Developer Tools**\r\n- Fluent builder pattern for embeds, commands, and components\r\n- Message and component collectors with timeout handling\r\n- Plugin architecture for code organization\r\n- Intelligent caching with configurable strategies\r\n- Automatic sharding for large bots\r\n- Comprehensive error handling and rate limit management\r\n\r\n**Performance**\r\n- Optional orjson for faster JSON parsing\r\n- aiodns for improved DNS resolution\r\n- Connection pooling and request batching\r\n- Memory-efficient caching system\r\n\r\n## Installation\r\n\r\nInstall from PyPI:\r\n\r\n```bash\r\npip install auric\r\n```\r\n\r\nWith optional dependencies:\r\n\r\n```bash\r\n# Voice support (PyNaCl)\r\npip install auric[voice]\r\n\r\n# Performance optimizations (orjson, aiodns)\r\npip install auric[speed]\r\n\r\n# All optional dependencies\r\npip install auric[voice,speed]\r\n```\r\n\r\nDevelopment version:\r\n\r\n```bash\r\npip install git+https://github.com/Auric-Team/auric.git\r\n```\r\n\r\n**Requirements:** Python 3.11 or higher\r\n\r\n## Quick Start\r\n\r\n### Basic Bot\r\n\r\n```python\r\nimport auric\r\n\r\nclient = auric.Client(intents=auric.Intents.default())\r\n\r\n@client.event\r\nasync def on_ready():\r\n print(f\"Logged in as {client.user.username}\")\r\n\r\n@client.event\r\nasync def on_message(message):\r\n if message.author.bot:\r\n return\r\n \r\n if message.content == \"!ping\":\r\n await message.reply(\"Pong!\")\r\n\r\nclient.run(\"YOUR_BOT_TOKEN\")\r\n```\r\n\r\n### Slash Commands\r\n\r\n```python\r\nimport auric\r\nfrom auric.builders import EmbedBuilder\r\n\r\nclient = auric.Client(intents=auric.Intents.default())\r\n\r\n@client.slash_command(name=\"greet\", description=\"Greet a user\")\r\nasync def greet(interaction: auric.Interaction, username: str):\r\n embed = (\r\n EmbedBuilder()\r\n .set_title(f\"Hello, {username}!\")\r\n .set_color(0x5865F2)\r\n .build()\r\n )\r\n await interaction.reply(embed=embed)\r\n\r\nclient.run(\"YOUR_BOT_TOKEN\")\r\n```\r\n\r\n### Interactive Components\r\n\r\n```python\r\nfrom auric.builders import ButtonBuilder, ActionRowBuilder\r\n\r\n@client.slash_command(name=\"vote\", description=\"Create a poll\")\r\nasync def vote(interaction: auric.Interaction):\r\n yes_btn = ButtonBuilder().set_label(\"Yes\").set_custom_id(\"vote_yes\").build()\r\n no_btn = ButtonBuilder().set_label(\"No\").set_custom_id(\"vote_no\").build()\r\n row = ActionRowBuilder().add_component(yes_btn).add_component(no_btn).build()\r\n \r\n await interaction.reply(\"Vote now:\", components=[row])\r\n\r\n@client.event\r\nasync def on_interaction(interaction):\r\n if interaction.type == auric.InteractionType.COMPONENT:\r\n if interaction.data.custom_id.startswith(\"vote_\"):\r\n choice = interaction.data.custom_id.split(\"_\")[1]\r\n await interaction.reply(f\"You voted: {choice}\", ephemeral=True)\r\n```\r\n\r\n## Advanced Usage\r\n\r\n### Using Collectors\r\n\r\n```python\r\nfrom auric.collectors import MessageCollector\r\n\r\n@client.slash_command(name=\"quiz\", description=\"Start a quiz\")\r\nasync def quiz(interaction: auric.Interaction):\r\n await interaction.reply(\"What is 2 + 2? (You have 30 seconds)\")\r\n \r\n collector = MessageCollector(\r\n client,\r\n channel=interaction.channel,\r\n filter=lambda m: m.author == interaction.user,\r\n max_messages=1,\r\n timeout=30.0\r\n )\r\n \r\n async for message in collector:\r\n if message.content == \"4\":\r\n await message.reply(\"Correct!\")\r\n else:\r\n await message.reply(\"Wrong answer!\")\r\n```\r\n\r\n### Plugin System\r\n\r\n```python\r\nfrom auric.plugins import Plugin\r\n\r\nclass ModerationPlugin(Plugin):\r\n def __init__(self, client):\r\n super().__init__(client)\r\n \r\n @Plugin.listener()\r\n async def on_message(self, message):\r\n if self.check_spam(message):\r\n await message.delete()\r\n await message.channel.send(f\"{message.author.mention}, please don't spam!\")\r\n \r\n def check_spam(self, message):\r\n # Your spam detection logic\r\n return False\r\n\r\n# Load the plugin\r\nclient.load_plugin(ModerationPlugin)\r\n```\r\n\r\n### Auto-Sharding\r\n\r\n```python\r\nfrom auric.core import AutoShardedClient\r\n\r\nclient = AutoShardedClient(intents=auric.Intents.default())\r\n\r\n@client.event\r\nasync def on_ready():\r\n print(f\"Bot ready with {client.shard_count} shards\")\r\n for shard_id, shard in client.shards.items():\r\n print(f\"Shard {shard_id}: {len(shard.guilds)} guilds\")\r\n```\r\n\r\n## Documentation\r\n\r\nThe library is fully type-hinted and includes comprehensive docstrings. Use your IDE's autocomplete or Python's built-in help:\r\n\r\n```python\r\nhelp(auric.Client)\r\nhelp(auric.EmbedBuilder)\r\nhelp(auric.Intents)\r\n```\r\n\r\nFull documentation site coming soon.\r\n\r\n## Contributing\r\n\r\nContributions are welcome. Please follow these steps:\r\n\r\n1. Fork the repository\r\n2. Create a feature branch: `git checkout -b feature-name`\r\n3. Make your changes with appropriate tests\r\n4. Run linters: `black auric` and `flake8 auric`\r\n5. Commit: `git commit -m \"Description of changes\"`\r\n6. Push and create a pull request\r\n\r\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\r\n\r\n### Development Setup\r\n\r\n```bash\r\ngit clone https://github.com/Auric-Team/auric.git\r\ncd auric\r\n\r\npython -m venv venv\r\nsource venv/bin/activate # Windows: venv\\Scripts\\activate\r\n\r\npip install -e \".[dev]\"\r\npytest\r\n```\r\n\r\n## Project Status\r\n\r\nAuric is in active development (v0.0.2). The API may change between minor versions until v1.0.0.\r\n\r\n**Current focus:**\r\n- Stabilizing core API\r\n- Expanding test coverage\r\n- Documentation improvements\r\n- Performance optimization\r\n\r\n## Support\r\n\r\n- Issues: [GitHub Issues](https://github.com/Auric-Team/auric/issues)\r\n- Discussions: [GitHub Discussions](https://github.com/Auric-Team/auric/discussions)\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](LICENSE) for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern, powerful, and type-safe Discord API wrapper for Python",
"version": "0.0.3",
"project_urls": {
"Bug Tracker": "https://github.com/Auric-Team/auric/issues",
"Changelog": "https://github.com/Auric-Team/auric/blob/main/CHANGELOG.md",
"Discord": "https://discord.gg/auric",
"Documentation": "https://github.com/Auric-Team/auric/blob/main/docs/INDEX.md",
"Homepage": "https://github.com/Auric-Team/auric",
"Repository": "https://github.com/Auric-Team/auric"
},
"split_keywords": [
"discord",
" discord-api",
" discord-bot",
" bot",
" api",
" wrapper",
" async",
" asyncio"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e5363dff23c2cc07920111d52f35ad51023cba22822b2e12b8445ce759b8d99a",
"md5": "02c8523e1f297cb1c5545f57b3876ef7",
"sha256": "69a9f636896899f530db48a53b500dd0631426861ad5fa6fb3110146fe7127f4"
},
"downloads": -1,
"filename": "auric-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "02c8523e1f297cb1c5545f57b3876ef7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 299804,
"upload_time": "2025-11-02T13:18:06",
"upload_time_iso_8601": "2025-11-02T13:18:06.760950Z",
"url": "https://files.pythonhosted.org/packages/e5/36/3dff23c2cc07920111d52f35ad51023cba22822b2e12b8445ce759b8d99a/auric-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "19b4eb4133b1bde60567b7de1d02c2c9ede7eb33fe6d9e836f5df184664ec581",
"md5": "62f237a700b5b768f95b2dc7e2b3ee35",
"sha256": "cff2c1a6f5c585434d5afc8452fa0eafb822de937516ba57c95af1ef77eb130c"
},
"downloads": -1,
"filename": "auric-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "62f237a700b5b768f95b2dc7e2b3ee35",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 235498,
"upload_time": "2025-11-02T13:18:08",
"upload_time_iso_8601": "2025-11-02T13:18:08.270548Z",
"url": "https://files.pythonhosted.org/packages/19/b4/eb4133b1bde60567b7de1d02c2c9ede7eb33fe6d9e836f5df184664ec581/auric-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-02 13:18:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Auric-Team",
"github_project": "auric",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.9.0"
]
]
},
{
"name": "orjson",
"specs": [
[
">=",
"3.9.0"
]
]
}
],
"lcname": "auric"
}
JSON
