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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
ruff check .
ruff format .
```

#### Type Checking

```bash
mypy app/
```

#### Testing

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

# Run tests
pytest
pytest --cov=app
```

#### Pre-commit Hooks

```bash
# 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:**
```bash
# Make sure venv is activated
# Reinstall dependencies
uv pip install -r requirements.txt
```

**Telethon auth issues:**
```bash
# Delete session file and re-authenticate
rm telegram-archiver.session
# Run again, will prompt for code
```

**Port already in use:**
```bash
# Use different port
uvicorn app.main:app --port 8001
```