vibetuner
Core Python framework and blessed dependencies for Vibetuner projects
This package provides the complete Python framework and curated dependency set for building modern web applications with Vibetuner. It includes everything from FastAPI and MongoDB integration to authentication, background jobs, and CLI tools.
What is Vibetuner?
Vibetuner is a production-ready scaffolding tool for FastAPI web applications.
This package (vibetuner) is the Python component that provides:
- Complete web application framework built on FastAPI
- Flexible database support: MongoDB (Beanie ODM) or SQL (SQLModel/SQLAlchemy)
- OAuth and magic link authentication out of the box
- Background job processing with Redis + Streaq (optional)
- CLI framework with Typer
- Email services, blob storage, and more
This package is designed to be used within projects generated by the Vibetuner scaffolding tool. For standalone use, you'll need to set up the project structure manually.
Installation
# In a Vibetuner-generated project (automatic)
uv sync
# Add to an existing project
uv add vibetuner
# With development dependencies
uv add vibetuner[dev]
Quick Start
The recommended way to use Vibetuner is via the scaffolding tool:
# Create a new project with all the framework code
uvx vibetuner scaffold new my-project
cd my-project
just dev
This will generate a complete project with:
- Pre-configured FastAPI application
- Authentication system (OAuth + magic links)
- MongoDB models and configuration
- Frontend templates and asset pipeline
- Docker setup for development and production
- CLI commands and background job infrastructure
What's Included
Core Framework (src/vibetuner/)
frontend/: FastAPI app, routes, middleware, authmodels/: User, OAuth, email verification, blob storage modelsservices/: Email (Mailjet), blob storage (S3)tasks/: Background job infrastructurecli/: CLI framework with scaffold, run, db commandsconfig.py: Pydantic settings managementmongo.py: MongoDB/Beanie setup (optional)sqlmodel.py: SQLModel/SQLAlchemy setup (optional)logging.py: Structured logging configuration
Blessed Dependencies
- FastAPI (0.121+): Modern, fast web framework
- Beanie: Async MongoDB ODM with Pydantic (optional)
- SQLModel + SQLAlchemy: SQL databases - PostgreSQL, MySQL, SQLite (optional)
- Authlib: OAuth 1.0/2.0 client
- Granian: High-performance ASGI server
- Redis + Streaq: Background task processing (optional)
- Typer: CLI framework
- Rich: Beautiful terminal output
- Loguru: Structured logging
- Pydantic: Data validation and settings
See pyproject.toml for the complete dependency list.
CLI Tools
When installed, provides the vibetuner command:
# Create new project from template
vibetuner scaffold new my-project
vibetuner scaffold new my-project --defaults
# Update existing project
vibetuner scaffold update
# Database management (SQLModel)
vibetuner db create-schema # Create SQL database tables
# Run development server (in generated projects)
vibetuner run dev frontend
vibetuner run dev worker
# Run production server (in generated projects)
vibetuner run prod frontend
vibetuner run prod worker
Development Dependencies
The [dev] extra includes all tools needed for development:
- Ruff: Fast linting and formatting
- Babel: i18n message extraction
- pre-commit: Git hooks (prek is a fast pre-commit drop-in replacement)
- Type stubs: For aioboto3, authlib, PyYAML
- And more...
Usage in Generated Projects
In a Vibetuner-generated project, import from vibetuner:
# Use core models
from vibetuner.models import UserModel, OAuthAccountModel
# Use services
from vibetuner.services.email import EmailService
# Use configuration
from vibetuner.config import settings
# Extend core routes
from vibetuner.frontend import app
# Add your routes
@app.get("/api/hello")
async def hello():
return {"message": "Hello World"}
Documentation
For complete documentation, guides, and examples, see the main Vibetuner repository:
Package Ecosystem
Vibetuner consists of four packages that work together:
- vibetuner (this package): Python framework and dependencies
- @alltuner/vibetuner: JavaScript/CSS build dependencies (tailwind, daisyui, htmx, etc.)
- @alltuner/vibetuner-jinja:
npm-shipped mirror of this package's frontend jinja templates, pulled
in transitively by
@alltuner/vibetunerso tailwind can scan them at frontend build time without shelling out to Python (no direct install needed) - Scaffolding template: Copier template for project generation
All four are version-locked and tested together to ensure compatibility.
Contributing
Contributions welcome! See the main repository for contribution guidelines:
License
MIT License - Copyright (c) 2025 All Tuner Labs, S.L.
See LICENSE for details.
Links
- Main Repository: https://github.com/alltuner/vibetuner
- Documentation: https://vibetuner.alltuner.com/
- Issues: https://github.com/alltuner/vibetuner/issues
- PyPI: https://pypi.org/project/vibetuner/
- npm Package: https://www.npmjs.com/package/@alltuner/vibetuner
1 maintainer
Release files for vibetuner 12.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vibetuner-12.0.0.tar.gz | 209.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vibetuner-12.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 468.3 kB
Release files / vibetuner-12.0.0.tar.gz
| Download URL | vibetuner-12.0.0.tar.gz |
|---|---|
| Size | 209.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e3cedc46dffa59b8924b5dfa6fefc90dd773075d8a5b9e69fe697fb48dcef71c
|
|
BLAKE2b-256 checksum How to use checksums |
c47c8a4488d56d7ba4a2fb090be651d6d034974ae2d0360d66bd2d26066b4937
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / vibetuner-12.0.0-py3-none-any.whl
| Download URL | vibetuner-12.0.0-py3-none-any.whl |
|---|---|
| Size | 258.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
74bbfde702fad8d425e700e52f7a7da8639ef24ae4cb937f60489054e6f660a4
|
|
BLAKE2b-256 checksum How to use checksums |
cf5c7a9f1552b50bfde2b2c1c167c72547618b78bab5469a42a4313ea0cf2700
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
