Tel-S3/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This is a small Python service for moving files from a Telegram bot to S3 through rclone.

• main.py starts both worker processes with the current Python interpreter.
• telebot.py receives Telegram messages, downloads media or URLs, and writes queue/status files.
• rub.py consumes queued tasks and uploads documents to S3 with rclone copyto.
• requirements.txt pins runtime dependencies.
• Runtime directories such as downloads/ and queue/ are created automatically; do not commit them.
• .env stores local secrets and session configuration; keep it private.

There is currently no dedicated tests/ directory or packaged module layout.

Build, Test, and Development Commands

Set up dependencies:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Run the full service:

python3 main.py

Run one worker when debugging:

python3 telebot.py
python3 rub.py

No build step is required. Before running, create .env with API_ID, API_HASH, and BOT_TOKEN. rclone must have a configured coaxys remote.

Coding Style & Naming Conventions

Use Python 3 style with 4-space indentation. Keep functions small and side effects explicit, especially around writes to queue/ and downloads/. Existing names use snake_case for functions and variables, uppercase constants for paths and limits, and Path objects for filesystem locations.

Prefer structured JSON handling over manual string manipulation. Preserve UTF-8 reads/writes with ensure_ascii=False because status messages include Persian text.

Testing Guidelines

There is no test framework configured yet. For new logic, add focused pytest tests under tests/, named like test_queue_manager.py or test_safe_filename.py. Mock Telegram, rclone, network calls, and filesystem writes where possible.

Until tests exist, manually verify by running python3 main.py, sending a small file to the bot, and checking that queue status advances and rclone ls coaxys:coaxys --s3-no-check-bucket shows the object.

Commit & Pull Request Guidelines

Local Git history is not readable in this checkout, so no project-specific commit convention can be inferred. Use concise imperative messages, for example Add queue cancellation tests.

Pull requests should include a short summary, configuration notes, manual test steps, and screenshots or logs when behavior changes. Link related issues and call out changes affecting credentials, sessions, or queue files.

Security & Configuration Tips

Never commit .env, rclone config, downloaded user files, queue state, or generated ZIP archives. Treat bot tokens, Telegram API credentials, and S3 keys as secrets. Redact chat IDs, tokens, URLs, and remote names from shared logs.