Installation

Get Tasteful up and running on your system in minutes.

Prerequisites

Before installing Tasteful, ensure you have:

Python 3.8+ (Python 3.11+ recommended)
Poetry (for dependency management) or pip
Git (for cloning examples and contributing)

Check Python Version
Install Poetry

python --version
# Should output Python 3.8 or higher

curl -sSL https://install.python-poetry.org | python3 -
# Or via pip:
pip install poetry

Install Tasteful

Using Poetry (Recommended)

For new projects, use the Tasteful CLI to generate a project template:

# Install the CLI tool
pip install tasteful-cli

# Create a new project
tasteful new my-project

# Navigate to your project
cd my-project

# Install dependencies
poetry install

Using pip

For existing projects or minimal installations:

# Core framework
pip install tasteful-core

# With built-in flavors (recommended)
pip install tasteful-core[flavors]

# Development dependencies
pip install tasteful-core[dev]

Development Installation

To contribute to Tasteful or work with the latest features:

# Clone the repository
git clone https://github.com/heka-ai/tasteful.git
cd tasteful

# Install in development mode
poetry install

# Or with pip
pip install -e .

Verify Installation

Create a simple test application to verify everything works:

from tasteful import TastefulApp
from tasteful.flavors import IdentityFlavor

app = TastefulApp(
    title="Test Application",
    version="1.0.0",
    flavors=[IdentityFlavor],
    authentication_backends=[]
)

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app.app, host="0.0.0.0", port=8000)

Visit http://localhost:8000/docs to see the automatic API documentation, or http://localhost:8000/identity/me to test the identity endpoint.

Project Structure

A typical Tasteful project structure:

my-project/
├── pyproject.toml          # Poetry configuration
├── main.py                 # Application entry point
├── config/
│   ├── __init__.py
│   └── settings.py         # Application configuration
├── flavors/
│   ├── __init__.py
│   ├── user/
│   │   ├── __init__.py
│   │   ├── flavor.py       # User flavor definition
│   │   ├── services.py     # Business logic
│   │   └── models.py       # Data models
│   └── order/
│       ├── __init__.py
│       ├── flavor.py
│       └── services.py
├── tests/
│   ├── __init__.py
│   ├── test_user.py
│   └── test_order.py
└── README.md

Configuration

Environment Variables

Configure your application using environment variables:

# .env file
DATABASE_URL=postgresql://user:pass@localhost/mydb
REDIS_URL=redis://localhost:6379
SECRET_KEY=your-secret-key-here
DEBUG=true
ACTIVE_FLAVORS=user,order,payment

Configuration File

Create a config/settings.py file using Tasteful’s BaseConfig:

from tasteful.base_flavor import BaseConfig
from pydantic import Field

class AppConfig(BaseConfig):
    """Application configuration with automatic environment variable loading."""
    
    database_url: str = "sqlite:///./test.db"
    redis_url: str = "redis://localhost:6379"
    secret_key: str = Field(default="change-me-in-production", min_length=32)
    debug: bool = False
    active_flavors: str = "identity,user"

# Configuration is automatically loaded from environment variables
# and .env files thanks to BaseConfig
settings = AppConfig()

For comprehensive configuration patterns, see the Configuration Management Guide.

Database Setup

SQLAlchemy Integration

For database integration, install SQLAlchemy support:

# With PostgreSQL
pip install tasteful-core[postgres]

# With MySQL
pip install tasteful-core[mysql]

# With SQLite (included)
pip install tasteful-core[sqlite]

Example database configuration with BaseConfig:

from tasteful.base_flavor import BaseConfig
from tasteful.repositories import BaseRepository
from pydantic import Field

class DatabaseConfig(BaseConfig):
    """Database configuration."""
    
    database_url: str = Field(
        default="sqlite:///./app.db",
        description="Database connection URL"
    )
    echo: bool = Field(
        default=False,
        description="Enable SQL query logging"
    )

class UserRepository(BaseRepository):
    def __init__(self, config: DatabaseConfig):
        super().__init__(
            database_url=config.database_url,
            echo=config.echo
        )

Migrations with Alembic

Set up database migrations:

# Initialize Alembic
alembic init migrations

# Create a migration
alembic revision --autogenerate -m "Create user table"

# Apply migrations
alembic upgrade head

Docker Setup

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# Install Poetry
RUN pip install poetry

# Copy dependency files
COPY pyproject.toml poetry.lock ./

# Install dependencies
RUN poetry config virtualenvs.create false \
    && poetry install --no-dev

# Copy application code
COPY . .

# Expose port
EXPOSE 8000

# Run application
CMD ["python", "main.py"]

Docker Compose

# docker-compose.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis

  db:
    image: postgres:13
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:6-alpine

volumes:
  postgres_data:

IDE Setup

VS Code

Recommended VS Code extensions:

// .vscode/extensions.json
{
  "recommendations": [
    "ms-python.python",
    "ms-python.pylint",
    "ms-python.black-formatter",
    "charliermarsh.ruff",
    "ms-python.mypy-type-checker"
  ]
}

PyCharm

Open the project directory
Configure Poetry interpreter: Settings > Project > Python Interpreter > Add > Poetry Environment
Enable type checking: Settings > Editor > Inspections > Python > Type checker

Next Steps

Quick Start Tutorial

Build your first Tasteful application

Core Concepts

Learn about flavors, services, and architecture

Built-in Flavors

Explore ready-to-use functionality

Troubleshooting

Common Issues

ImportError: No module named 'tasteful'

Ensure you’ve installed Tasteful in your current Python environment:

pip list | grep tasteful
# Should show tasteful-core and any extensions

Port already in use

Change the port in your main.py or kill the process using port 8000:

# Find process using port 8000
lsof -i :8000

# Kill process
kill -9 <PID>

Database connection errors

Verify your database is running and the connection string is correct:

# For PostgreSQL
psql -h localhost -U user -d myapp

# For SQLite
sqlite3 test.db ".tables"

Need help? Check our GitHub issues or browse the community discussions.

Get started

Documentation Index

​Installation

​Prerequisites

​Install Tasteful

​Using Poetry (Recommended)

​Using pip

​Development Installation

​Verify Installation

​Project Structure

​Configuration

​Environment Variables

​Configuration File

​Database Setup

​SQLAlchemy Integration

​Migrations with Alembic

​Docker Setup

​Dockerfile

​Docker Compose

​IDE Setup

​VS Code

​PyCharm

​Next Steps

Quick Start Tutorial

Core Concepts

Built-in Flavors

​Troubleshooting

​Common Issues

Installation

Prerequisites

Install Tasteful

Using Poetry (Recommended)

Using pip

Development Installation

Verify Installation

Project Structure

Configuration

Environment Variables

Configuration File

Database Setup

SQLAlchemy Integration

Migrations with Alembic

Docker Setup

Dockerfile

Docker Compose

IDE Setup

VS Code

PyCharm

Next Steps

Troubleshooting

Common Issues