Paillat-dev/dismoji
1
0
Fork 0
mirror of https://github.com/Paillat-dev/dismoji.git synced 2026-01-02 00:56:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update quality.yaml to include uv installation step and modify README.md for library name and description

Browse Source
This commit is contained in:
Paillat
2025-05-04 00:27:03 +02:00
parent d1548b6e8a
commit a714f4d53c
2 changed files with 32 additions and 267 deletions
Download Patch File Download Diff File Expand all files Collapse all files

294
README.md
View File

@@ -1,5 +1,5 @@
<div align="center">
<h1>Discord Progress Bar</h1>
<h1>dismoji</h1>
<!-- badges -->
@@ -12,8 +12,7 @@
<!-- end badges -->
A Python library for creating customizable progress bars with Discord emojis in your
Discord bot messages.
A Python library for converting Discord emoji names to their Unicode equivalents.
</div>
@@ -22,295 +21,60 @@ Discord bot messages.
- [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)
- [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.
dismoji is a lightweight Python library that provides a simple way to convert Discord
emoji names to their Unicode equivalents. With just a single function call, you can
transform text containing Discord-style emoji codes (like `:smile:`) into text with
actual Unicode emoji characters (like "😄").
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
This library uses
[Paillat-dev/discord-emojis](https://github.com/Paillat-dev/discord-emojis) as the
source for Discord emoji names and aliases.
## Installation
```bash
pip install discord-progress-bar --pre
pip install dismoji
```
<!-- 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
import dismoji
# 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")
# Convert Discord emoji names to Unicode emojis
text = "Hello, :wave: I'm excited! :partying_face:"
converted_text = dismoji.emojize(text)
print(converted_text) # Output: "Hello, 👋 I'm excited! 🥳"
```
<!-- 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)
- **Simple API**: Just one function to remember - `dismoji.emojize()`
- **Discord Compatible**: Supports Discord's emoji naming conventions
- **Comprehensive**: Includes all standard emojis available on Discord
- **Type Safe**: Fully type-annotated for better IDE integration
- **Zero Dependencies**: Lightweight with no external dependencies
- **Fast**: Optimized for quick emoji replacement
## Getting Help
If you encounter issues or have questions about discord-progress-bar:
If you encounter issues or have questions about dismoji:
- **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.
[Submit a bug report or feature request](https://github.com/Paillat-dev/dismoji/issues)
- **Discord Support**: Join the [Pycord Official Server](https://discord.gg/pycord) and
mention `@paillat`
## Development
@@ -319,7 +83,7 @@ If you encounter issues or have questions about discord-progress-bar:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run linter, formatter and type checker: `ruff check .`,`ruff format .`,
4. Run linter, formatter and type checker: `ruff check .`, `ruff format .`,
`basedpyright .`
5. Submit a pull request
@@ -330,10 +94,6 @@ If you encounter issues or have questions about discord-progress-bar:
- **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