arsam
8fb79c6443
Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
Run the full service:
|
|
|
|
```bash
|
|
python3 main.py
|
|
```
|
|
|
|
Run one worker when debugging:
|
|
|
|
```bash
|
|
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.
|