Metadata-Version: 2.5
Name: pulse-voice
Version: 2.0.0
Summary: Official async SDK for Pulse bots and integrations: REST, gateway, slash commands, interactions, embeds, components and webhooks.
Project-URL: Homepage, https://pulse.shadowforge.fr/developpeurs/pulse-py
Project-URL: Documentation, https://pulse.shadowforge.fr/developpeurs/docs
Project-URL: Community, https://discord.gg/zEj6NRWzjq
Author: Shadow Forge
License-Expression: MIT
License-File: LICENSE
Keywords: asyncio,bot,gateway,pulse,pulse-voice,sdk,slash-commands,webhooks
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Natural Language :: French
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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 :: Communications :: Chat
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: aiohttp<4,>=3.9
Provides-Extra: interactions
Requires-Dist: cryptography>=42; extra == 'interactions'
Provides-Extra: test
Requires-Dist: cryptography>=42; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# pulse.py (`pulse-voice` on PyPI)

The official async Python SDK for [Pulse](https://pulse.shadowforge.fr) bots and integrations.

Le SDK officiel et asynchrone pour écrire des bots Pulse en Python. Documentation complète en
français : <https://pulse.shadowforge.fr/developpeurs/pulse-py>.

- Python 3.9+, asyncio and aiohttp, fully typed (`py.typed`)
- REST client with per-bucket rate limits, `Retry-After` handling and retries
- Gateway: heartbeats, zombie detection, resume, reconnection with backoff, intents
- Events with decorators: `@client.event async def on_message_create(message): ...`
- Slash commands with `@client.command`, context menus, buttons, select menus, modals, autocomplete
- `Embed` builder with Pulse's limits checked before sending
- `Webhook` for incoming webhooks, `interactions_app` for an HTTP interactions endpoint

## Install

```bash
pip install pulse-voice
python -m pip install pulse-voice      # same thing, with the pip of this Python
py -m pip install pulse-voice          # Windows
poetry add pulse-voice
uv add pulse-voice
pipenv install pulse-voice
pip install -U pulse-voice             # upgrade
```

The distribution is called `pulse-voice`; the import name is `pulse` (`import pulse`). For HTTP interactions
(signature checks), install the extra: `pip install "pulse-voice[interactions]"`.

## Quick start

Create an application in the [developer portal](https://pulse.shadowforge.fr/developpeurs/portail),
add a bot, copy its token, then:

```python
import os
import pulse

client = pulse.Client(intents=pulse.Intents.default() | pulse.Intents.MESSAGE_CONTENT)

@client.event
async def on_ready():
    print(f"Connected as {client.user.username}")

@client.event
async def on_message_create(message: pulse.Message):
    if message.author.bot:
        return
    if message.content == "!ping":
        await message.reply("pong")

client.run(os.environ["PULSE_TOKEN"])
```

## Slash commands

```python
@client.command(
    description="Le bot répète ta phrase",
    options=[pulse.Option.string("texte", "Quoi dire", required=True)],
)
async def dire(interaction: pulse.Interaction, texte: str):
    await interaction.reply(texte)

@client.event
async def on_ready():
    await client.sync_commands(hub_id=os.environ.get("PULSE_HUB_ID"))  # None: global commands
```

## Webhooks

```python
import asyncio, os, pulse

async def main():
    async with pulse.Webhook.from_url(os.environ["PULSE_WEBHOOK_URL"]) as hook:
        await hook.send("Build OK", username="CI", embed=pulse.Embed(title="Vert", color="#3ddc97"))

asyncio.run(main())
```

## Errors and rate limits

API errors raise `pulse.PulseAPIError` with `status`, `code` (for example `MISSING_PERMISSIONS`) and
a French `message`. 429 answers are retried after `Retry-After`. Handler errors go to
`on_error(event, error)` when you define it.

## Examples

See [`examples/`](./examples): a ping bot, a slash command bot with a button and a modal, a webhook script.

## License

MIT
