aiogram-part 1.0.1

Professional CLI scaffolding tool for aiogram 3.x Telegram bots

🤖 Aiogram Part

Professional CLI scaffolding tool for Telegram bots with aiogram 3.x

5 daqiqada production-ready bot yarating! Database, Redis, Testing, Deployment - hammasi tayyor! 🚀

---

⚡ Quick Start

# Install
pip install aiogram-part

# Create bot with database (SQLite/PostgreSQL/MySQL)
mkdir my-bot && cd my-bot
aiogram-part init-project --with-db --type postgresql

# Setup
cp .env.example .env  # Edit BOT_TOKEN
make install          # Install dependencies

# Run
make run             # Or: docker-compose up -d

Tayyor! Bot ishlayapti! ✅

---

🎯 Features

Feature	Description	Commands
🏗️ Clean Architecture	Scoped handlers (user/admin), services, filters	20+ commands
🗄️ Database	SQLite/PostgreSQL/MySQL + Aerich migrations	init-project --with-db --type
⚡ Redis	Caching & FSM storage with fallback	Auto-configured
🐳 Docker	Database-specific docker-compose	docker-compose up
🧪 Testing	pytest + fixtures + test generator	aiogram-part test
🔍 Health Check	Environment validator with auto-fix	aiogram-part check --fix
📊 Statistics	Project metrics with Rich tables	aiogram-part stats
🌐 Webhook	Setup & status commands	aiogram-part webhook
🚀 Deployment	Systemd service generator	aiogram-part deploy
📝 Logging	Rotating logs with levels	Built-in
🌍 i18n	Multi-language with Babel	aiogram-part i18n
🔒 Type Safe	Pydantic settings + OOP keyboards	All templates

---

📦 Commands

🚀 Project Initialization

# Basic project
aiogram-part init-project

# With database (choose type)
aiogram-part init-project --with-db --type sqlite      # SQLite (default)
aiogram-part init-project --with-db --type postgresql  # PostgreSQL + Docker
aiogram-part init-project --with-db --type mysql       # MySQL + Docker

Creates 38+ directories, 41+ files: handlers, services, filters, keyboards, middlewares, models, tests, Docker configs.

---

🎯 Code Generators

Handlers - Command, Message, Callback

aiogram-part handler user command start          # /start command
aiogram-part handler admin command stats         # Admin-only command
aiogram-part handler user message photo          # Photo messages
aiogram-part handler user callback confirm       # Callback handler

Creates: handlers/{users|admins}/{commands|messages|callbacks}/name.py + auto-registers router

Models - Database models with Tortoise ORM

aiogram-part model User                          # Model only
aiogram-part model Product --with-crud           # Model + CRUD operations

Creates: database/models/name.py + optional database/crud/name.py

Keyboards - OOP Builder pattern

aiogram-part keyboard --scope user --build-keyboard inline menu
aiogram-part keyboard --scope admin --build-keyboard reply settings --str-params status
aiogram-part keyboard --scope common --build-keyboard inline language \
  --str-params lang --int-params user_id

Creates: keyboards/{users|admins|common}/name.py with Builder pattern class

Filters - Custom filters

# Common filters (IsAdmin, IsPremium, etc)
aiogram-part filter --scope common --type common admin

# Callback filters (structured button data)
aiogram-part filter --scope user --type callback product \
  --str-params action --int-params product_id

Creates: filters/{users|admins|common}/{common|callback}/name.py

Middlewares - Request interceptors

aiogram-part middleware --scope user throttling --types message
aiogram-part middleware --scope admin logger --types all
aiogram-part middleware --scope common auth --types message callback_query

Creates: middlewares/{users|admins|common}/name.py

Services - Business logic layer

aiogram-part service --scope user payment        # User payment service
aiogram-part service --scope admin analytics     # Admin analytics
aiogram-part service --scope common notification # Common notification

Creates: services/{users|admins|common}/name.py with service class

States - FSM state machines

aiogram-part state Registration                  # User registration flow
aiogram-part state OrderCheckout                 # Checkout process

Creates: states/name.py with StatesGroup

Validators - Input validation

aiogram-part validator phone --type regex        # Phone number regex
aiogram-part validator email --type custom       # Custom email validator

Creates: utils/validators/name.py

Enums - Database enums

aiogram-part enum UserRole --values admin --values user --values moderator
aiogram-part enum OrderStatus --values pending --values completed

Creates: database/enums/name.py with enum class

---

🗄️ Database Management (Aerich - Prisma-like)

aiogram-part db migrate              # Initialize migrations
aiogram-part db update model         # Auto-detect model changes
aiogram-part db upgrade              # Apply migrations
aiogram-part db downgrade            # Rollback migration
aiogram-part db history              # View migration history
aiogram-part db heads                # Show current version
aiogram-part db reset                # Reset database
aiogram-part db generate description # Generate custom migration
aiogram-part db inspect              # Inspect database schema

---

🧪 Testing & Quality

Test Generator

aiogram-part test --type handler start           # Handler test
aiogram-part test --type service payment         # Service test
aiogram-part test --type generic utils           # Generic test

Creates: tests/{handlers|services}/test_name.py with pytest fixtures

Environment Checker

aiogram-part check                               # Check project health
aiogram-part check --fix                         # Auto-fix issues

Checks: dependencies, .env file, migrations, Python version

Project Statistics

aiogram-part stats                               # Rich table with metrics

Shows: handlers, services, models, filters, middlewares, states, files, LOC

---

🌐 Deployment & Operations

Webhook Management

aiogram-part webhook setup https://bot.example.com  # Configure webhook
aiogram-part webhook status                          # Check status

Systemd Service

aiogram-part deploy --user botuser --python /path/to/python3

Generates systemd service file for Linux servers

Multi-language Support

aiogram-part i18n                                # Setup i18n + Babel

Creates: locales/ + middleware + Makefile commands

---

📁 Project Structure

bot/
├── handlers/
│   ├── users/                # User handlers
│   │   ├── commands/         # /start, /help
│   │   ├── messages/         # Text, photo messages
│   │   └── callbacks/        # Callback queries
│   ├── admins/              # Admin-only handlers
│   └── errors/              # Error handlers
├── services/
│   ├── users/               # User business logic
│   ├── admins/              # Admin business logic
│   └── common/              # Shared services
├── filters/
│   ├── users/               # User filters
│   ├── admins/              # Admin filters
│   └── common/              # Shared filters
├── keyboards/
│   ├── users/               # User keyboards (OOP)
│   ├── admins/              # Admin keyboards
│   └── common/              # Shared keyboards
├── middlewares/
│   ├── users/               # User middlewares
│   ├── admins/              # Admin middlewares
│   └── common/              # Global middlewares
├── database/
│   ├── models/              # Tortoise ORM models
│   ├── crud/                # CRUD operations
│   ├── enums/               # Database enums
│   └── migrations/          # Aerich migrations
├── states/                  # FSM states
├── utils/
│   ├── validators/          # Input validators
│   ├── decorators/          # Custom decorators
│   └── formatters/          # Data formatters
├── tests/
│   ├── handlers/            # Handler tests
│   ├── services/            # Service tests
│   └── conftest.py          # pytest fixtures
├── core/                    # Bot initialization
├── config/                  # Settings & logging
├── locales/                 # i18n translations
├── docker-compose.yml       # Database + Redis
├── Dockerfile               # Bot container
├── Makefile                 # Dev commands
└── .env.example             # Environment template

---

💡 Quick Examples

E-commerce Bot

aiogram-part init-project --with-db --type postgresql
aiogram-part model Product --with-crud
aiogram-part model Order --with-crud
aiogram-part enum OrderStatus --values pending --values paid --values shipped
aiogram-part service --scope user payment
aiogram-part handler user command catalog
aiogram-part keyboard --scope user --build-keyboard inline products --int-params page
aiogram-part filter --scope user --type callback product --str-params action --int-params product_id
aiogram-part test --type handler catalog

Multi-language Bot

aiogram-part init-project --with-db
aiogram-part i18n
aiogram-part model User --with-crud
aiogram-part state Registration
aiogram-part handler user command start
aiogram-part keyboard --scope common --build-keyboard inline language --int-params user_id
aiogram-part validator phone --type regex
make translate

Admin Panel Bot

aiogram-part init-project --with-db
aiogram-part filter --scope common --type common admin
aiogram-part handler admin command stats
aiogram-part handler admin command users
aiogram-part service --scope admin analytics
aiogram-part keyboard --scope admin --build-keyboard inline admin_panel
aiogram-part test --type service analytics

More examples: EXAMPLES.md

---

🛠️ Development Workflow

# Setup
make install          # Install dependencies
make dev             # Install dev tools

# Development
make run             # Run bot locally
make test            # Run tests
aiogram-part check   # Health check
aiogram-part stats   # View project stats

# Database
aiogram-part db update model    # Detect changes
aiogram-part db upgrade         # Apply migrations
aiogram-part db history         # View history

# Production
aiogram-part webhook setup https://bot.example.com
aiogram-part deploy --user botuser
docker-compose up -d

---

🐳 Docker Deployment

# SQLite (no external database needed)
docker-compose up -d

# PostgreSQL (recommended for production)
aiogram-part init-project --with-db --type postgresql
cp .env.example .env
docker-compose up -d  # Starts bot + postgres + redis

# View logs
docker-compose logs -f bot

---

📚 Documentation

• 📖 Full README - Complete documentation
• 💡 Examples - Real bot examples
• ❓ FAQ - Common questions📄 License

MIT © Sattorbek

---

🔗 Links

• 📦 PyPI
• 🐙 GitHub
• 📚 Aiogram Docs

---

⭐ Star on GitHub • 📖 Documentation • 💡 Examples

Made with ❤️ for aiogram community