TG_autoposter/docs/DEVELOPMENT.md

Development Setup Guide

Prerequisites

• Python 3.11+
• Docker & Docker Compose
• PostgreSQL 15 (or use Docker)
• Redis 7 (or use Docker)
• Git

Local Development (Without Docker)

1. Clone Repository

git clone https://github.com/yourusername/TG_autoposter.git
cd TG_autoposter

2. Create Virtual Environment

# Using venv
python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Or using poetry
poetry env use python3.11
poetry shell

3. Install Dependencies

# Using pip
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Or using poetry
poetry install

4. Setup Environment Variables

cp .env.example .env
# Edit .env with your actual values
nano .env

Required variables:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
ADMIN_ID=your_telegram_id

5. Setup Database

# Create database
createdb tg_autoposter

# Run migrations
alembic upgrade head

6. Run Bot

# Terminal 1: Start Redis
redis-server

# Terminal 2: Start Celery Worker
celery -A app.celery_config worker --loglevel=info

# Terminal 3: Start Celery Beat (Scheduler)
celery -A app.celery_config beat --loglevel=info

# Terminal 4: Start Bot
python -m app

7. Development with Docker

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Access services:
# - Bot: Running in container
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379
# - Flower (Celery monitoring): http://localhost:5555

Code Style & Linting

# Format code with black
black app/

# Sort imports with isort
isort app/

# Lint with flake8
flake8 app/

# Type checking with mypy
mypy app/ --ignore-missing-imports

# Run all checks
make lint

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=app

# Run specific test file
pytest tests/test_handlers.py

# Run in watch mode
pytest-watch

# Run async tests
pytest -v --asyncio-mode=auto

Database Migrations

# Create new migration
alembic revision --autogenerate -m "Add new column"

# Apply migrations
alembic upgrade head

# Rollback to previous migration
alembic downgrade -1

# Show migration history
alembic current
alembic history

Debugging

Enable Debug Logging

# In .env
LOG_LEVEL=DEBUG

# Or set at runtime
export LOG_LEVEL=DEBUG
python -m app

Using pdb

import pdb; pdb.set_trace()

Using VS Code Debugger

Create .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Bot",
            "type": "python",
            "request": "launch",
            "module": "app",
            "justMyCode": true,
            "env": {
                "LOG_LEVEL": "DEBUG"
            }
        }
    ]
}

Celery Debugging

# Run worker in foreground with verbose output
celery -A app.celery_config worker -l debug --pool=solo

# Inspect tasks
celery -A app.celery_config inspect active

# View task stats
celery -A app.celery_config inspect stats

Common Commands

# Make targets
make help              # Show all available commands
make up                # Start Docker containers
make down              # Stop Docker containers
make logs              # View Docker logs
make test              # Run tests
make lint              # Run linters
make fmt               # Format code
make shell             # Open Python shell with app context

# Docker commands
docker-compose up -d   # Start services in background
docker-compose logs -f # Follow logs
docker-compose exec bot bash  # Shell into bot container
docker-compose down    # Stop and remove containers
docker-compose ps      # List running services

# Celery commands
celery -A app.celery_config worker --loglevel=info
celery -A app.celery_config beat
celery -A app.celery_config flower
celery -A app.celery_config inspect active_queues

Useful Development Tips

1. Hot Reload

For faster development, you can use watchdog:

pip install watchdog[watchmedo]
watchmedo auto-restart -d app/ -p '*.py' -- python -m app

2. Interactive Shell

# Django-like shell with app context
python -c "from app import *; import code; code.interact(local=locals())"

# Or use ipython
pip install ipython
python -m app shell

3. Database Browser

# pgAdmin web interface (already in docker-compose)
# Access at http://localhost:5050
# Login with PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD

# Or use psql
psql -h localhost -U postgres -d tg_autoposter

4. Monitor Celery Tasks

# Open Flower dashboard
open http://localhost:5555

# Or monitor from CLI
watch -n 1 'celery -A app.celery_config inspect active'

5. Create Test Data

python -c "
import asyncio
from app.db import get_session
from app.models import Group

async def create_test_group():
    async with get_session() as session:
        group = Group(chat_id=123456, title='Test Group')
        session.add(group)
        await session.commit()

asyncio.run(create_test_group())
"

Troubleshooting

PostgreSQL Connection Issues

# Check if PostgreSQL is running
docker-compose ps postgres

# Check logs
docker-compose logs postgres

# Restart
docker-compose restart postgres

Redis Connection Issues

# Check if Redis is running
docker-compose ps redis

# Check Redis connectivity
redis-cli ping

# Flush database (WARNING: clears all data)
redis-cli FLUSHDB

Celery Worker Issues

# Check active workers
celery -A app.celery_config inspect active_workers

# View pending tasks
celery -A app.celery_config inspect reserved

# Revoke a task
celery -A app.celery_config revoke <task_id>

# Clear queue
celery -A app.celery_config purge

Bot Not Responding

# Check bot logs
docker-compose logs bot

# Verify bot token in .env
echo $TELEGRAM_BOT_TOKEN

# Test API connection
python -c "
from pyrogram import Client
app = Client('test')
# This will verify API credentials
"

Contributing

1. Create feature branch: git checkout -b feature/my-feature
2. Make changes and test locally
3. Format code: make fmt
4. Run tests: make test
5. Run linters: make lint
6. Commit with message: git commit -m "feat: add my feature"
7. Push and create Pull Request

Resources

• Telegram Bot API Docs
• Pyrogram Documentation
• Telethon Documentation
• Celery Documentation
• APScheduler Documentation
• SQLAlchemy Async

Getting Help

• Check existing issues and discussions
• Review documentation in /docs folder
• Look at examples in /examples folder
• Check logs for error messages
• Ask in project discussions

License

MIT License - see LICENSE file for details