skeletone 0.1.15

CLI for services template for Python (FastAPI, SQLAlchemy, Alembic)

Skeletone

A minimal, well-toned Python project skeleton and micro-framework for rapid backend development.
Built on top of FastAPI, SQLAlchemy, and Alembic with automated template versioning, advanced logging, and production-ready features.

Features

• 🚀 FastAPI foundation with modern Python async practices
• 🗄️ SQLAlchemy (async) ORM with Alembic migrations
• 🧩 Minimal framework structure with clear folder layout
• 📦 Template management: init, upgrade, downgrade, version lock
• 📄 Patch-based updates between template versions (v1.1.0 to v1.9.0)
• 🔁 Incremental version tracking via skeletone.lock
• 📊 Advanced Request Logging: All incoming API requests logged to database
• 🧾 Batch Logging System with async buffer and periodic flush (v1.4.0+)
• 🛡️ Bulkhead Pattern middleware for concurrency control (v1.9.0+)
• 🔄 Lifespan Management for startup/shutdown tasks
• ⚡ Production-ready - optimized for performance and reliability

What's New in Latest Versions

v1.9.0

• ✨ Bulkhead Middleware: Control max concurrent requests to prevent overload
• 🏗️ Restructured middleware organization

v1.8.0 - v1.7.0

• 📝 Enhanced logging service architecture
• 🔧 Improved lifespan management

v1.6.0 - v1.4.0

• 🚀 Batch Logging: Logs are buffered and flushed periodically for better performance
• ⏱️ Async logging with configurable flush intervals
• 🔄 Graceful shutdown with log flushing

v1.3.0 - v1.1.0

• 📊 Initial request logging to database
• 🏛️ Base project structure with FastAPI + SQLAlchemy

Installation

pip install skeletone

Quick Start

1. Initialize a New Project

mkdir my-awesome-api && cd my-awesome-api
skeletone init

2. Check Available Versions

skeletone versions

3. Upgrade Your Project

skeletone upgrade

4. Rollback if Needed

# Interactive version selection
skeletone downgrade

# Or specify version directly
skeletone downgrade -v v1.2.0

CLI Commands

Command	Description
skeletone init	Initialize new project from latest template
skeletone upgrade	Upgrade to latest template version
skeletone downgrade	Downgrade to a previous template version
skeletone versions	List all available template versions
skeletone help	Show detailed help and usage examples

How It Works

Skeletone is built around a patch-based versioning system:

• Init: Sets up a fresh project from the latest template (currently v1.9.0)
• Upgrade: Applies sequential .patch diffs to upgrade your project
• Downgrade: Applies reverse patches to safely revert
• Track: Saves current version to skeletone.lock

Template Structure

The generated project includes:

your-project/
├── app/
│   ├── models/          # SQLAlchemy models (async)
│   ├── routers/         # FastAPI route handlers
│   ├── dependencies/    # DI system & authorization
│   ├── services/        # Business logic & logging service
│   ├── middlewares/     # Request logging & bulkhead pattern
│   ├── lifespan/        # Startup/shutdown management
│   └── utils/           # Enums, configs, helpers
├── alembic/             # Database migrations
├── config.py            # App settings
├── main.py              # FastAPI application entrypoint
├── requirements.txt     # Dependencies
└── skeletone.lock       # Template version lock file

Key Components

🛡️ Bulkhead Middleware (v1.9.0+)

Prevents system overload by limiting concurrent requests:

app.add_middleware(BulkheadMiddleware, max_concurrent_requests=40, timeout=0)

📊 Advanced Logging System

• Request Logger: Automatically logs all HTTP requests with path, method, status, response time
• Batch Processing: Logs are buffered and flushed periodically for optimal performance
• Database Storage: All logs stored in PostgreSQL for analysis
• Async Everything: Non-blocking logging that doesn't impact response times

🔄 Lifespan Management

Clean startup and shutdown handling:

• Initialize services on startup
• Gracefully close connections on shutdown
• Flush pending logs before termination

Example Workflow

# Create and initialize a new project
mkdir blog-api && cd blog-api
skeletone init

# Do your development work...

# Upgrade to latest version (v1.9.0)
skeletone upgrade

# Check available versions
skeletone versions
# Shows: v1.9.0 (current), v1.8.0, v1.7.0, ... v1.1.0

# Rollback if needed
skeletone downgrade -v v1.1.0

Version Table Example

Available Skeletone Versions
┌─────────┬─────────────┐
│ Version │ Status      │
├─────────┼─────────────┤
│ v1.9.0  │ ✅ Current   │
│ v1.8.0  │             │
│ ...     │             │
│ v1.1.0  │             │
└─────────┴─────────────┘

Best Practices

1. Always commit your code before upgrade/downgrade
2. Review diffs and changes after updating
3. Thoroughly test after version transitions
4. Track your modifications to avoid patch conflicts
5. Configure bulkhead limits based on your server capacity
6. Monitor logs regularly for performance insights

Template Repository

The base template for Skeletone lives here:
👉 https://github.com/yoursteacup/skeletone

Contributing

Contributions are welcome! Please see the GitHub repo for guidelines and issue tracking.

Author

Developer: Zhaxybayev Daulet
GitHub: yoursteacup
Telegram: @yoursteacup