DOCSEARCHbyAlgolia
Submit Docs

PaiGram Documentation

website·Indexed 30 days ago

https://docs.paimon.vip

Documentation for PaiGram, including installation, configuration, and deployment via Docker or Podman. It provides guides on writing plugins, utilizing the Bot object for Telegram API calls, managing databases with SQLModel and Alembic, and integrating tools like python-genshin-artifact and gcsim for Genshin Impact damage calculation and DPS simulation.

Tokens
4.7K
Snippets
39
Records
43
Agent score
50%

What's inside PaiGram

  1. Verify Python environment for Paimon

    Ensure that Python 3.8 or higher is installed on your system. Run the version check command in your terminal or command prompt. If Python is not installed, you must install Python 3.8+ to proceed.
    python --version

  2. Compile python-genshin-artifact into a wheel file

    To distribute the module to other projects or environments, use maturin to build a .whl file. This wheel can then be installed via pip in the target environment.
    # Build the wheel to the dist directory
maturin build --out dist

# Install the resulting wheel in another environment
pip install dist/python_genshin_artifact-1.0.0-xxx.whl

  3. Create and activate a Python virtual environment for PaiGram

    Set up a local Python virtual environment to isolate project dependencies. The activation command varies by operating system.
    # Create the virtual environment
python -m venv venv

# Activate on Linux
source venv/bin/activate

# Activate on Windows (CMD)
venv\Scripts\activate.bat

# Activate on Windows (PowerShell)
.\venv\Scripts\Activate.ps1

  4. Create a custom Service in gram_core

    To create a service, define a class in the services folder that inherits from gram_core.base_service.BaseService. Every service must implement two asynchronous methods to manage its lifecycle: initialize and shutdown.
    from gram_core.base_service import BaseService

class TestService(BaseService):
    def __init__(self):
        """do something"""

    async def initialize(self, *args, **kwargs):
        """do something"""

    async def shutdown(self, *args, **kwargs):
        """do something"""

  5. Clone the PaiGram repository and submodules

    To get the PaiGram project locally, clone the repository and initialize all recursive submodules to ensure all dependencies and linked repositories are present.
    git clone https://github.com/PaiGramTeam/PaiGram.git
cd PaiGram
git submodule update --init --recursive

  6. Install Podman and podman-compose

    Install the Podman engine and the podman-compose utility. Installation commands vary by operating system.
    # Install Podman (Debian/Ubuntu)
sudo apt-get -y install podman

# Install podman-compose via pip
pip3 install podman-compose

# Alternative: Install podman-compose on Fedora (>=f31)
sudo dnf install podman-compose

  7. Register standard handlers in a plugin

    Use the core.plugin.handler decorator to register functions as handlers. There are two ways to do this:

    1. Generic approach: Pass the handler class (e.g., CommandHandler) as the first argument, followed by the handler's configuration parameters.
    2. Sub-decorator approach: Use specific helper decorators like @handler.command() for a more concise syntax.
    from core.plugin import Plugin, handler
from telegram import Update
from telegram.ext import CommandHandler, CallbackContext

class TestPlugin(Plugin):
    # Generic approach
    @handler(CommandHandler, command='start', block=False)
    async def start(self, update: Update, context: CallbackContext):
        await update.effective_chat.send_message('hello world!')

    # Sub-decorator approach
    @handler.command(command='help', block=False)
    async def help_command(self, update: Update, context: CallbackContext):
        await update.effective_chat.send_message('Help text')

  8. Deploy PaiGram using Podman Compose

    Follow these steps to clone the project, configure environment variables, and launch the services using podman-compose. Ensure you update the .env file with your specific bot tokens and database credentials.
    # 1. Clone the repository
git clone https://github.com/PaiGramTeam/PaiGram.git
cd PaiGram

# 2. Prepare configuration files
cp .env.example .env
cp docker-compose.gen.yml docker-compose.yml

# 3. Start the containers in detached mode
podman-compose -f docker-compose.yml up -d

  9. Deploy PaiGram using Docker Compose

    Deploy the PaiGram project by cloning the repository, initializing the environment and compose files, and starting the containers in detached mode.
    # 1. Clone the repository
git clone https://github.com/PaiGramTeam/PaiGram.git
cd PaiGram

# 2. Initialize configuration files
cp .env.example .env
cp docker-compose.gen.yml docker-compose.yml

# 3. Start the services
docker-compose up -d

  10. Install python-genshin-artifact via PyPI

    The python-genshin-artifact module can be installed directly from PyPI using pip.
    pip install python-genshin-artifact

  11. Install PaiGram project dependencies

    Install the required dependencies using either Poetry (recommended for full feature set) or pip.
    # Option 1: Using Poetry (installs all extras)
poetry install --extras all

# Option 2: Using pip
pip install -r requirements.txt