mirror of
https://github.com/Paillat-dev/discord-progress-bar.git
synced 2026-01-02 09:06:21 +00:00
Paillat-dev
0e0ce97026
Adjusted the limitations section for clarity and updated emoji limits to reflect current app-wide constraints. Removed the local testing setup section, likely to streamline the README and focus on essential information.
344 lines
11 KiB
Markdown
344 lines
11 KiB
Markdown
<div align="center">
|
|
<h1>Discord Progress Bar</h1>
|
|
|
|
<!-- badges -->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[](https://results.pre-commit.ci/latest/github/Paillat-dev/discord-progress-bar/main)
|
|
|
|
<!-- end badges -->
|
|
|
|
A Python library for creating customizable progress bars with Discord emojis in your
|
|
Discord bot messages.
|
|
|
|
</div>
|
|
|
|
## Table of Contents
|
|
|
|
- [Overview](#overview)
|
|
- [Installation](#installation)
|
|
- [Quick Start](#quick-start)
|
|
- [Core Concepts](#core-concepts)
|
|
- [How It Works](#how-it-works)
|
|
- [Key Components](#key-components)
|
|
- [Features](#features)
|
|
- [Type Safety](#type-safety)
|
|
- [Usage Examples](#usage-examples)
|
|
- [Basic Progress Bar](#basic-progress-bar)
|
|
- [Different Progress Bar States](#different-progress-bar-states)
|
|
- [Custom Progress Bar Length](#custom-progress-bar-length)
|
|
- [Configuration](#configuration)
|
|
- [Bot Configuration](#bot-configuration)
|
|
- [Progress Bar Manager Initialization](#progress-bar-manager-initialization)
|
|
- [Custom Progress Bar Styles](#custom-progress-bar-styles)
|
|
- [Limitations](#limitations)
|
|
- [Getting Help](#getting-help)
|
|
- [Development](#development)
|
|
- [Local Testing](#local-testing)
|
|
- [Contributing](#contributing)
|
|
- [License](#license)
|
|
|
|
## Overview
|
|
|
|
Discord Progress Bar is a Python library that allows you to create visually appealing
|
|
progress bars in your Discord bot messages using custom emojis. It provides a simple API
|
|
to generate progress bars of different styles and lengths, making it easy to display
|
|
progress, loading states, or completion percentages in your Discord applications.
|
|
|
|
Built on:
|
|
|
|
- [py-cord](https://github.com/Pycord-Development/pycord) - A modern, easy-to-use,
|
|
feature-rich, and async-ready API wrapper for Discord
|
|
- Custom Discord emojis - Used to create visually consistent progress bar segments
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install discord-progress-bar --prerelease=allow
|
|
```
|
|
|
|
<!-- prettier-ignore -->
|
|
> [!NOTE]
|
|
> The package is currently in pre-release.
|
|
|
|
## Quick Start
|
|
|
|
<!-- quick-start -->
|
|
<!-- prettier-ignore -->
|
|
> [!TIP]
|
|
> Create beautiful progress bars in your Discord bot with just a few lines of code!
|
|
|
|
```python
|
|
import discord
|
|
from discord_progress_bar import ProgressBarManager
|
|
|
|
# Create a Discord bot with emoji caching enabled
|
|
bot = discord.Bot(cache_app_emojis=True)
|
|
|
|
progress_bar_manager = None
|
|
progress_bar = None
|
|
|
|
@bot.event
|
|
async def on_ready():
|
|
"""Initialize the ProgressBarManager when the bot is ready."""
|
|
global progress_bar_manager, progress_bar
|
|
|
|
# Initialize the progress bar manager
|
|
progress_bar_manager = await ProgressBarManager(bot)
|
|
# Get a progress bar with the "green" style
|
|
progress_bar = await progress_bar_manager.progress_bar("green")
|
|
|
|
@bot.slash_command()
|
|
async def show_progress(ctx, percent: float = 0.5):
|
|
"""Display a progress bar with the specified percentage."""
|
|
|
|
await ctx.respond(f"Progress: {progress_bar.partial(percent)}")
|
|
|
|
# Run your bot
|
|
bot.run("YOUR_TOKEN")
|
|
```
|
|
|
|
<!-- prettier-ignore -->
|
|
> [!NOTE]
|
|
> For a complete example, check the [examples directory](/examples).
|
|
|
|
## Core Concepts
|
|
|
|
### How It Works
|
|
|
|
Discord Progress Bar works by using custom Discord emojis to create visually appealing
|
|
progress bars in your bot messages. Here's how it works:
|
|
|
|
1. **Progress Bar Structure**: Each progress bar consists of multiple emoji segments:
|
|
|
|
- Left edge (filled or empty)
|
|
- Middle sections (filled or empty)
|
|
- Right edge (filled or empty)
|
|
|
|
2. **Emoji Management**: The `ProgressBarManager` class handles:
|
|
|
|
- Loading existing emojis from your bot
|
|
- Creating new emojis from URLs or files if needed
|
|
- Providing the appropriate emojis to the `ProgressBar` class
|
|
|
|
3. **Progress Bar Rendering**: The `ProgressBar` class handles:
|
|
|
|
- Rendering full progress bars (100%)
|
|
- Rendering empty progress bars (0%)
|
|
- Rendering partial progress bars (any percentage)
|
|
|
|
4. **Default Styles**: The library comes with a default "green" style, but you can
|
|
create custom styles by providing your own emoji images.
|
|
|
|
### Key Components
|
|
|
|
- **ProgressBarManager**: Initializes with your Discord bot and manages emoji resources
|
|
- **ProgressBar**: Renders progress bars with different percentages
|
|
- **ProgressBarPart**: Enum defining the different parts of a progress bar (LEFT_EMPTY,
|
|
LEFT_FILLED, etc.)
|
|
- **Default Bars**: Pre-configured progress bar styles that can be used out of the box
|
|
|
|
## Features
|
|
|
|
- **Easy Integration**: Seamlessly integrates with Discord bots built using py-cord
|
|
- **Customizable Progress Bars**: Create progress bars with different styles and lengths
|
|
- **Default Styles**: Comes with a pre-configured "green" style ready to use
|
|
- **Custom Styles**: Create your own progress bar styles using custom emoji images
|
|
- **Flexible Rendering**: Render progress bars at any percentage (0-100%)
|
|
- **Async Support**: Fully supports asynchronous operations for Discord bots
|
|
- **Emoji Management**: Automatically handles emoji creation and management
|
|
|
|
### Type Safety
|
|
|
|
Discord Progress Bar is fully type-annotated and type-safe. It uses `basedpyright` for
|
|
type checking.
|
|
|
|
<!-- prettier-ignore -->
|
|
> [!NOTE]
|
|
> While Discord Progress Bar itself is fully typed, the underlying py-cord library has limited type annotations, which may affect type checking in some areas.
|
|
|
|
## Usage Examples
|
|
|
|
### Basic Progress Bar
|
|
|
|
```python
|
|
@discord.slash_command()
|
|
async def show_progress(self, ctx: discord.ApplicationContext, percent: float = 0.5) -> None:
|
|
"""Display a progress bar with the specified percentage."""
|
|
# Get a progress bar with the default "green" style
|
|
progress_bar = await self.progress_bar_manager.progress_bar("green", length=10)
|
|
# Render the progress bar at the specified percentage
|
|
await ctx.respond(f"Progress: {progress_bar.partial(percent)}")
|
|
```
|
|
|
|
### Different Progress Bar States
|
|
|
|
```python
|
|
@discord.slash_command()
|
|
async def show_progress_states(self, ctx: discord.ApplicationContext) -> None:
|
|
"""Display different progress bar states."""
|
|
progress_bar = await self.progress_bar_manager.progress_bar("green", length=10)
|
|
|
|
# Empty progress bar (0%)
|
|
empty = progress_bar.empty()
|
|
|
|
# Partial progress bar (50%)
|
|
half = progress_bar.partial(0.5)
|
|
|
|
# Full progress bar (100%)
|
|
full = progress_bar.full()
|
|
|
|
await ctx.respond(f"Empty: {empty}\nHalf: {half}\nFull: {full}")
|
|
```
|
|
|
|
### Custom Progress Bar Length
|
|
|
|
```python
|
|
@discord.slash_command()
|
|
async def show_different_lengths(self, ctx: discord.ApplicationContext) -> None:
|
|
"""Display progress bars with different lengths."""
|
|
# Short progress bar (5 segments)
|
|
short_bar = await self.progress_bar_manager.progress_bar("green", length=5)
|
|
|
|
# Medium progress bar (10 segments)
|
|
medium_bar = await self.progress_bar_manager.progress_bar("green", length=10)
|
|
|
|
# Long progress bar (20 segments)
|
|
long_bar = await self.progress_bar_manager.progress_bar("green", length=20)
|
|
|
|
await ctx.respond(
|
|
f"Short (5): {short_bar.partial(0.7)}\n"
|
|
f"Medium (10): {medium_bar.partial(0.7)}\n"
|
|
f"Long (20): {long_bar.partial(0.7)}"
|
|
)
|
|
```
|
|
|
|
For more examples, check the [examples directory](/examples) in the repository.
|
|
|
|
## Configuration
|
|
|
|
### Bot Configuration
|
|
|
|
When creating your Discord bot, make sure to enable emoji caching:
|
|
|
|
```python
|
|
bot = discord.Bot(cache_app_emojis=True)
|
|
```
|
|
|
|
This is required for the `ProgressBarManager` to properly load and manage emojis.
|
|
|
|
### Progress Bar Manager Initialization
|
|
|
|
Initialize the `ProgressBarManager` after your bot is ready:
|
|
|
|
```python
|
|
@discord.Cog.listener()
|
|
async def on_ready(self) -> None:
|
|
self.progress_bar_manager = await ProgressBarManager(self.bot)
|
|
```
|
|
|
|
### Custom Progress Bar Styles
|
|
|
|
You can create custom progress bar styles by providing your own emoji images:
|
|
|
|
#### From URLs
|
|
|
|
```python
|
|
from discord_progress_bar import ProgressBarPart
|
|
|
|
# Define URLs for each part of the progress bar
|
|
custom_style = {
|
|
ProgressBarPart.LEFT_EMPTY: "https://example.com/left_empty.png",
|
|
ProgressBarPart.LEFT_FILLED: "https://example.com/left_filled.png",
|
|
ProgressBarPart.MIDDLE_EMPTY: "https://example.com/middle_empty.png",
|
|
ProgressBarPart.MIDDLE_FILLED: "https://example.com/middle_filled.png",
|
|
ProgressBarPart.RIGHT_EMPTY: "https://example.com/right_empty.png",
|
|
ProgressBarPart.RIGHT_FILLED: "https://example.com/right_filled.png",
|
|
}
|
|
|
|
# Create emojis from URLs
|
|
await self.progress_bar_manager.create_emojis_from_urls("custom_style", custom_style)
|
|
```
|
|
|
|
#### From Files
|
|
|
|
```python
|
|
import pathlib
|
|
from discord_progress_bar import ProgressBarPart
|
|
|
|
# Define file paths for each part of the progress bar
|
|
custom_style = {
|
|
ProgressBarPart.LEFT_EMPTY: pathlib.Path("path/to/left_empty.png"),
|
|
ProgressBarPart.LEFT_FILLED: pathlib.Path("path/to/left_filled.png"),
|
|
ProgressBarPart.MIDDLE_EMPTY: pathlib.Path("path/to/middle_empty.png"),
|
|
ProgressBarPart.MIDDLE_FILLED: pathlib.Path("path/to/middle_filled.png"),
|
|
ProgressBarPart.RIGHT_EMPTY: pathlib.Path("path/to/right_empty.png"),
|
|
ProgressBarPart.RIGHT_FILLED: pathlib.Path("path/to/right_filled.png"),
|
|
}
|
|
|
|
# Create emojis from files
|
|
await self.progress_bar_manager.create_emojis_from_files("custom_style", custom_style)
|
|
```
|
|
|
|
## Limitations
|
|
|
|
<!-- prettier-ignore -->
|
|
> [!WARNING]
|
|
> Please be aware of the following limitations:
|
|
>
|
|
> - **Python Version**: Supports Python 3.12 only
|
|
> - **Discord Bot Framework**: Currently only supports py-cord, not discord.py or other Discord API wrappers
|
|
> - **Emoji Limits**: Subject to Discord's app emoji limits (2'000 emojis per app - should be plenty for most use cases)
|
|
> - **Pre-release Status**: This package is currently in alpha stage and may have unexpected behaviors or breaking changes in future versions
|
|
> - **Custom Styles**: Creating custom styles requires providing all six emoji parts (LEFT_EMPTY, LEFT_FILLED, MIDDLE_EMPTY, MIDDLE_FILLED, RIGHT_EMPTY, RIGHT_FILLED)
|
|
|
|
## Getting Help
|
|
|
|
If you encounter issues or have questions about discord-progress-bar:
|
|
|
|
- **GitHub Issues**:
|
|
[Submit a bug report or feature request](https://github.com/Paillat-dev/discord-progress-bar/issues)
|
|
- **Discord Support**:
|
|
- For py-cord related questions: Join the
|
|
[Pycord Official Server](https://discord.gg/pycord)
|
|
- For discord-progress-bar specific help: Join the
|
|
[Pycord Official Server](https://discord.gg/pycord) and mention `@paillat`
|
|
|
|
<!-- prettier-ignore -->
|
|
> [!TIP]
|
|
> Before asking for help, check if your question is already answered in the [examples directory](/examples) or existing GitHub issues.
|
|
|
|
## Development
|
|
|
|
### Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Run linter, formatter and type checker: `ruff check .`,`ruff format .`,
|
|
`basedpyright .`
|
|
5. Submit a pull request
|
|
|
|
**Development Tools**:
|
|
|
|
- **uv**: For dependency management
|
|
- **Ruff**: For linting and formatting
|
|
- **HashiCorp Copywrite**: For managing license headers
|
|
- **basedpyright**: For type checking
|
|
|
|
<!-- prettier-ignore -->
|
|
> [!CAUTION]
|
|
> This is an early-stage project and may have unexpected behaviors or bugs. Please report any issues you encounter.
|
|
|
|
## License
|
|
|
|
MIT License - Copyright (c) 2025 Paillat-dev
|
|
|
|
---
|
|
|
|
Made with ❤ by Paillat-dev
|