chronicle.nixg.ru/telegram-archiver/DEVELOPMENT.md

Telegram Archiver - Development Configuration

Virtual Environment Setup

This project uses uv for virtual environment and package management.

Setup (First Time)

# Create virtual environment
uv venv

# Activate virtual environment
# Windows (PowerShell):
.venv\Scripts\Activate.ps1

# Windows (cmd):
.venv\Scripts\activate

# macOS / Linux:
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

# Or install from pyproject.toml (recommended for development):
uv pip install -e ".[dev]"

Running the Application

CLI Mode

# Activate venv first
python -m telegram-archiver --channel dedinit

# Or with options:
python -m telegram-archiver -c dedinit -l 10 -o ./test-archive

API Mode

# Start the server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Open browser to http://localhost:8000/docs for Swagger UI

Development Tools

Linting

ruff check .
ruff format .

Type Checking

mypy app/

Testing

# Create tests directory first
mkdir tests
touch tests/__init__.py

# Run tests
pytest
pytest --cov=app

Pre-commit Hooks

# Install pre-commit hooks
pre-commit install

# Run all hooks manually
pre-commit run --all-files

Code Quality Checklist

Before committing:

• ruff check . passes
• mypy app/ passes (or has explicit ignores)
• Tests pass: pytest
• Manual test: CLI or API works
• .env file NOT committed (check .gitignore)
• .session files NOT committed (check .gitignore)

Troubleshooting

Import errors:

# Make sure venv is activated
# Reinstall dependencies
uv pip install -r requirements.txt

Telethon auth issues:

# Delete session file and re-authenticate
rm telegram-archiver.session
# Run again, will prompt for code

Port already in use:

# Use different port
uvicorn app.main:app --port 8001