2.8 KiB
Repository Guidelines
Project Structure & Module Organization
This repository contains a Python Telegram bot. bot.py is the entry point and registers command, text, photo, image-document, and inline handlers. handlers/ contains Telegram-facing command and update handlers, grouped by feature (admin.py, chat.py, inline.py, help.py). services/ contains external integrations and shared business logic such as AI calls, auth persistence, and saved runtime settings. utils/ contains reusable helpers for context, formatting, chunking, and Persian-language handling. Runtime state and credentials live in .env, settings.json, authorized_users.json, and *.session files; do not treat these as source assets.
Build, Test, and Development Commands
Create an isolated environment before installing dependencies:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Run the bot locally with:
python bot.py
Use .env.example as the template for required environment variables, then set TELEGRAM_TOKEN, GOOGLE_API_KEY, and OWNER_ID in .env. Runtime choices such as active provider, model, public mode, system prompt, and per-user settings are saved in settings.json.
Coding Style & Naming Conventions
Follow idiomatic Python with 4-space indentation, clear function names, and small modules organized by responsibility. Handler functions use the cmd_<command> pattern for commands, such as cmd_ping or cmd_setmodel; keep new command names consistent with the registered Telegram command. Prefer async functions for Telegram callbacks and service calls. Keep configuration values centralized in config.py rather than scattering os.getenv calls.
Testing Guidelines
No test suite is currently present. For new behavior, add focused pytest tests under a future tests/ directory and name files test_<module>.py. Prioritize pure helpers in utils/ and service logic that can be tested without Telegram network access. Until tests exist, validate changes by running python bot.py with a development bot token and exercising the affected command or message path.
Commit & Pull Request Guidelines
The local .git directory has no usable history, so no existing commit convention is available. Use concise imperative commit messages, for example Add image OCR command or Fix auth file reload handling. Pull requests should include a short summary, configuration changes, manual test steps, and screenshots or chat transcripts when user-visible Telegram behavior changes.
Security & Configuration Tips
Never commit .env, session files, API keys, bot tokens, or real user authorization data. Keep .env.example updated when adding configuration. Treat authorized_users.json as local runtime state unless a sanitized fixture is intentionally needed for tests.