Metadata-Version: 2.4
Name: fluxer.py
Version: 0.4.1
Summary: A Python wrapper for the Fluxer API
Author: Emil
License-Expression: MIT
Project-URL: Homepage, https://github.com/akarealemil/fluxer.py
Project-URL: Issues, https://github.com/akarealemil/fluxer.py/issues
Keywords: fluxer,api,chat,bot,websocket
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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: Framework :: AsyncIO
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4.0.0,>=3.9.0
Requires-Dist: emoji>=2.0.0
Provides-Extra: voice
Requires-Dist: livekit>=0.17.0; extra == "voice"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Dynamic: license-file

<div align="center">
<a href="https://github.com/akarealemil/fluxer.py"><img src="https://fluxerusercontent.com/attachments/1471802484305944610/1475241549270843696/fluxerpy.webp" height="281px;" alt="Invite Tracker"/></a>
<br><br>
<a href="https://pypi.org/project/fluxer.py"><img alt="Supported python versions" src="https://img.shields.io/pypi/pyversions/fluxer.py?style=for-the-badge"></a>
<a href="https://pypi.org/project/fluxer.py"><img alt="PyPI version" src="https://img.shields.io/pypi/v/fluxer.py?style=for-the-badge"></a>
<a href="https://github.com/microsoft/pyright"><img alt="Pyright badge" src="https://img.shields.io/badge/pyright-checked-%231674b1?style=for-the-badge"></a>
<br>
<a href="https://github.com/astral-sh/ruff"><img alt="Ruff badge" src="https://img.shields.io/badge/ruff-%23D7FF64?style=for-the-badge&logo=ruff&logoColor=black"></a>
<a href="https://github.com/astral-sh/uv"><img alt="uv" src="https://img.shields.io/badge/uv-%23DE5FE9.svg?style=for-the-badge&logo=uv&logoColor=white"></a>
<br>
<a href="https://fluxer.gg/fluxer-py"><img alt="Join us!" src="https://img.shields.io/badge/Join%20us!-%234641d9?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA1MTIgNTEyIj48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTI1NiAwYzE0MS4zODUgMCAyNTYgMTE0LjYxNSAyNTYgMjU2UzM5Ny4zODUgNTEyIDI1NiA1MTIgMCAzOTcuMzg1IDAgMjU2IDExNC42MTUgMCAyNTYgMFptLTY4LjQ3IDI2Ni4wNTdjLTE1LjU0MyAwLTMwLjMyNCAzLjUwNS00NC4zNDMgMTAuNTE0LTEzLjg2NiA3LjAxLTI1LjE0MyAxOC4yMS0zMy44MjggMzMuNi01LjYxNiAxMC4xMjktOS4zMTggMjIuNDAzLTExLjEwNjEgMzYuODIyLTEuNjU0MyAxMy4zNDEgOS41NzYxIDI0LjIwNyAyMy4wMTgxIDI0LjIwNyAxMy43NzggMCAyNC4wNjUtMTEuNTc0IDI3LjQwMi0yNC45NDEgMS44OTEtNy41NzkgNC45MzktMTMuNTg5IDkuMTQyLTE4LjAzIDguMDc2LTguNTM0IDE4LjI4Ni0xMi44IDMwLjYyOS0xMi44IDguMjI5IDAgMTUuNzcyIDIuMDU3IDIyLjYyOSA2LjE3MSA2Ljg1NyAzLjk2MiAxNS43NzEgMTAuNzQzIDI2Ljc0MiAyMC4zNDMgMTYuNzYyIDE0Ljc4MSAzMS41NDQgMjUuNTI0IDQ0LjM0NCAzMi4yMjggMTIuOCA2LjU1MyAyNi45NzEgOS44MjkgNDIuNTE0IDkuODI5IDE1LjU0MyAwIDMwLjMyNC0zLjUwNSA0NC4zNDMtMTAuNTE0IDE0LjAxOS03LjAxIDI1LjM3MS0xOC4yMSAzNC4wNTctMzMuNiA1LjczOC0xMC4xNjggOS40NDgtMjIuNDk3IDExLjEyOS0zNi45ODcgMS41NDMtMTMuMzAyLTkuNzA0LTI0LjA0Mi0yMy4wOTYtMjQuMDQyLTEzLjg2My4wMDEtMjQuMjAyIDExLjcwNC0yNy44ODggMjUuMDctMS43OTcgNi41MTUtNC41MTIgMTIuMDI1LTguMTQ1IDE2LjUzLTcuNjE5IDkuNDQ4LTE4LjA1NyAxNC4xNzItMzEuMzE0IDE0LjE3Mi04LjIyOSAwLTE1LjY5Ni0xLjk4Mi0yMi40LTUuOTQzLTYuNTUzLTQuMTE1LTE1LjU0My0xMC45NzItMjYuOTcyLTIwLjU3Mi0xNi45MTQtMTQuMTcxLTMxLjc3Mi0yNC42ODUtNDQuNTcyLTMxLjU0My0xMi42NDctNy4wMDktMjYuNzQyLTEwLjUxNC00Mi4yODUtMTAuNTE0Wm0wLTEzOC4wNTdjLTE1LjU0MyAwLTMwLjMyNCAzLjUwNS00NC4zNDMgMTAuNTE0LTEzLjg2NiA3LjAxLTI1LjE0MyAxOC4yMS0zMy44MjggMzMuNi01LjYxNiAxMC4xMjktOS4zMTggMjIuNDAzLTExLjEwNjEgMzYuODIxLTEuNjU0NCAxMy4zNDEgOS41NzYxIDI0LjIwNyAyMy4wMTgxIDI0LjIwOCAxMy43NzggMCAyNC4wNjUtMTEuNTc0IDI3LjQwMi0yNC45NDEgMS44OTEtNy41NzkgNC45MzktMTMuNTg5IDkuMTQyLTE4LjAzMSA4LjA3Ni04LjUzMyAxOC4yODYtMTIuOCAzMC42MjktMTIuOCA4LjIyOSAwIDE1Ljc3MiAyLjA1OCAyMi42MjkgNi4xNzIgNi44NTcgMy45NjIgMTUuNzcxIDEwLjc0MyAyNi43NDIgMjAuMzQzIDE2Ljc2MiAxNC43ODEgMzEuNTQ0IDI1LjUyNCA0NC4zNDQgMzIuMjI4IDEyLjggNi41NTMgMjYuOTcxIDkuODI5IDQyLjUxNCA5LjgyOSAxNS41NDMgMCAzMC4zMjQtMy41MDUgNDQuMzQzLTEwLjUxNCAxNC4wMTktNy4wMSAyNS4zNzEtMTguMjEgMzQuMDU3LTMzLjYgNS43MzgtMTAuMTY4IDkuNDQ4LTIyLjQ5NyAxMS4xMjktMzYuOTg3IDEuNTQzLTEzLjMwMy05LjcwNC0yNC4wNDItMjMuMDk2LTI0LjA0Mi0xMy44NjMgMC0yNC4yMDIgMTEuNzA0LTI3Ljg4OCAyNS4wNy0xLjc5NyA2LjUxNS00LjUxMiAxMi4wMjUtOC4xNDUgMTYuNTMtNy42MTkgOS40NDgtMTguMDU3IDE0LjE3MS0zMS4zMTQgMTQuMTcxLTguMjI5IDAtMTUuNjk2LTEuOTgxLTIyLjQtNS45NDItNi41NTMtNC4xMTUtMTUuNTQzLTEwLjk3Mi0yNi45NzItMjAuNTcyLTE2LjkxNC0xNC4xNzEtMzEuNzcyLTI0LjY4Ni00NC41NzItMzEuNTQzQzIxNy4xNjggMTMxLjUwNSAyMDMuMDczIDEyOCAxODcuNTMgMTI4WiIvPjwvc3ZnPg==&logoColor=white"></a>
</div>

---

A Python API wrapper for [Fluxer](https://fluxer.app).

Build bots and automated clients with a clean, type-safe, and
event-driven architecture.

---

## Features

- Async-first design built on `asyncio`
- REST API support with automatic rate limiting
- WebSocket gateway for real-time events
- Command framework with decorators
- Modular cog system
- Strongly-typed data models
- Structured error handling and retry logic
- Clean separation between low-level `Client` and high-level `Bot`

---

## Installation

```sh
pip install fluxer.py
```

Requires Python 3.10 or higher.

### Voice support

Voice requires `LiveKit` and `ffmpeg`:

``` sh
pip install fluxer.py[voice]
```

or

```sh
uv add fluxer.py --extra voice
```

ffmpeg must be installed separately and available on your `PATH`.

On macOS (assuming you have [Brew](https://brew.sh/)):

``` sh
brew install ffmpeg
```

On Debian/Ubuntu:

``` sh
apt install ffmpeg
```

On Windows: (assuming you have [Chocolatey](https://chocolatey.org/install))
```sh
choco install ffmpeg
```

For development:

```sh
git clone https://github.com/akarealemil/fluxer.py.git
cd fluxer.py
pip install -e .
```

---

## Template

A [batteries-included template](https://github.com/PerpetualPossum/fluxer-py-template) is available to get you started quickly with a new bot project.

------------------------------------------------------------------------

## Quick Start

A simple bot with a ping command:

```py
import fluxer

bot = fluxer.Bot(command_prefix="!", intents=fluxer.Intents.default())

@bot.event
async def on_ready():
    print(f"Bot is ready! Logged in as {bot.user.username}")

@bot.command()
async def ping(ctx):
    await ctx.reply("Pong!")

if __name__ == "__main__":
    TOKEN = "your_bot_token"
    bot.run(TOKEN)
```

---

## Choosing Between Bot and Client

### Bot

Use `Bot` if you need: - Decorator-based commands - Built-in command
parsing - Cog support - Rapid bot development

### Client

Use `Client` if you need: - Full event-driven control - A custom command
framework - Lower-level API interaction - Advanced or specialized
implementations

---

## Architecture Overview

`Bot` extends `Client`, adding a command framework on top of the core
event system.

Core components:

- `HTTPClient` -- Handles REST requests and rate limits
- `Gateway` -- Manages WebSocket connection and event dispatch
- `Client` -- Base event-driven interface
- `Bot` -- High-level command framework
- `Cog` -- Modular command grouping system

---

## Data Models

`fluxer.py` provides strongly-typed models representing Fluxer entities:

-   `Guild`
-   `Channel`
-   `Message`
-   `User`
-   `GuildMember`
-   `VoiceState`
-   `Webhook`
-   `Embed`
-   `Emoji`

Models encapsulate both state and behavior, exposing convenience methods
such as:

- `Message.reply()`
- `Channel.send()`
- `Guild.kick_member()`

---

## Voice

Requires `fluxer.py[voice]` and ffmpeg

``` py
@bot.command()
async def play(ctx, channel_id: int, *, path: str):
    channel = await bot.fetch_channel(str(channel_id))

    async with await channel.connect(bot) as vc:
        await vc.play_file(path)
```

For background playback with an `after` callback:

``` py
async with await channel.connect(bot) as vc:
    vc.play(fluxer.FFmpegPCMAudio("music.mp3"), after=lambda e: print("done"))
    # bot continues handling commands while audio plays
```

Pause and resume mid-playback:

``` py
vc.pause()
vc.resume()
print(vc.is_paused)  # bool
```

`FFmpegPCMAudio` accepts the same options as discord.py's `FFmpegPCMAudio`:

| Parameter | Description |
|---|---|
| `executable` | Path to ffmpeg binary (default: `"ffmpeg"`) |
| `before_options` | Arguments inserted before `-i` (e.g. `"-ss 30"` to seek) |
| `options` | Arguments inserted after the source (e.g. `"-filter:a volume=0.5"`) |
| `sample_rate` | Output sample rate in Hz (default: `48000`) |
| `num_channels` | `1` for mono, `2` for stereo (default: `2`) |

------------------------------------------------------------------------

## Intents

`Intents` determine which events your application receives from the
WebSocket gateway.

Common usage:

```py
fluxer.Intents.default()
fluxer.Intents.all()
```

Limiting intents improves performance and ensures your application
subscribes only to necessary events.

---

## Exceptions

All library exceptions inherit from:

```py
FluxerException
```

Errors include:

- HTTP errors mapped to REST status codes
- Gateway protocol errors
- Connection and retry-related failures

---

## Documentation

Full documentation is available at:

https://deepwiki.com/akarealemil/fluxer.py/1-overview

---

## Contributing

We use `uv` for dependency management.

```sh
git clone https://github.com/akarealemil/fluxer.py.git
cd fluxer.py
uv sync --dev
```

This will create a `.venv` and install development dependencies.
