Metadata-Version: 2.4
Name: fluxer.py
Version: 0.3.2
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: 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

# fluxer.py

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.

For development:

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

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

## 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`
-   `Webhook`
-   `Embed`
-   `Emoji`

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

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

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

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