diff --git a/.github/workflows/quality.yaml b/.github/workflows/quality.yaml index f52df19..3f18cdb 100644 --- a/.github/workflows/quality.yaml +++ b/.github/workflows/quality.yaml @@ -42,6 +42,11 @@ jobs: with: python-version: ${{ matrix.python-version }} + - name: "Install uv" + uses: astral-sh/setup-uv@v6 + with: + enable-cache: true + - name: Install dependencies run: uv sync --no-managed-python --no-python-downloads diff --git a/README.md b/README.md index be54d2b..1d34c3c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
-

Discord Progress Bar

+

dismoji

@@ -12,8 +12,7 @@ -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.
@@ -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 ``` - -> [!NOTE] -> The package is currently in pre-release. - ## Quick Start - -> [!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! 🥳" ``` - -> [!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. - - -> [!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 - - -> [!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` - - -> [!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 - -> [!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