Skip to main content
Welcome to Tasteful! This guide will help you create your first Tasteful application in just a few minutes. By the end, you’ll have a working web API with a health check endpoint.

​
Prerequisites

Before you begin, make sure you have:
  • Python 3.9 or higher installed on your system
  • Poetry for dependency management (recommended) or pip
We strongly recommend using Poetry for Python dependency management. If you don’t have it installed, visit poetry.eustace.io for installation instructions.

​
Step 1: Create a New Project

First, create a new directory for your project and navigate to it: 
mkdir my-tasteful-app
cd my-tasteful-app

​
Step 2: Initialize Your Project

Initialize a new Poetry project: 
poetry init
Follow the interactive prompts. You can use the default values for most options. When asked about dependencies, you can skip them for now - we’ll add Tasteful next.

​
Step 3: Install Tasteful

Add Tasteful as a dependency to your project: 
poetry add tasteful
This will install Tasteful and all its required dependencies, including FastAPI and Uvicorn.

​
Step 4: Create Your First Flavor

Create the basic project structure: 
mkdir app
touch app/main.py
mkdir app/flavors
mkdir app/flavors/hello_flavor.py
Now, let’s create your first flavor. Create a file app/flavors/hello_flavor.py: 
from tasteful.base_flavor import BaseFlavor, BaseController, BaseService
from tasteful.decorators.controller import Get


class HelloService(BaseService):
    
    def greet(self, name: str = "World"):
        """Generate a greeting message."""
        return {"message": f"Hello, {name}! Welcome to Tasteful 😋"}


class HelloController(BaseController):
    """Controller for greeting endpoints."""
    
    def __init__(self, hello_service: HelloService):
        super().__init__(prefix="/hello", tags=["greetings"])
        self.hello_service = hello_service

    @Get("/")
    def say_hello(self):
        """Say hello to the world."""
        return self.hello_service.greet()
    
    @Get("/{name}")
    def say_hello_to(self, name: str):
        """Say hello to a specific person."""
        return self.hello_service.greet(name)


class HelloFlavor(BaseFlavor):
    """A simple flavor for greeting users."""
    
    def __init__(self):
        super().__init__(
            controller=HelloController,
            services=[HelloService],
            repositories=[],  # No repositories needed for this simple example
            config=None
        )

​
Step 5: Create Your Application

Now create your main application file in app/main.py: 
from fastapi import FastAPI
from tasteful.tasteful_application import TastefulApp
from .flavors.hello_flavor import HelloFlavor


def create_app() -> FastAPI:
    """Create and configure the Tasteful application."""
    
    app = TastefulApp(
        title="My First Tasteful App",
        version="1.0.0",
        flavors=[
            HelloFlavor # Your custom flavor instance
        ],
        authentication_backends=[],  # No auth for now
    )
    
    return app.app


# This is what Uvicorn will look for
app = create_app()

​
Step 6: Run Your Application

Start your development server: 
poetry run uvicorn app.main:app --reload
Your Tasteful application is now running! Open your browser and visit:

​
Step 7: Explore the API Documentation

Tasteful automatically generates interactive API documentation powered by FastAPI. Visit http://127.0.0.1:8000/docs to see your API endpoints and test them directly in the browser.

​
What You’ve Built

Congratulations! You’ve created a Tasteful application with:
  • ✅ Modular architecture using Flavors
  • ✅ Dependency injection with Services
  • ✅ Automatic API documentation

​
Next Steps

Now that you have a working Tasteful application, you can:

Learn About Architecture

Understand Tasteful’s modular design philosophy

Explore Flavors

Deep dive into creating powerful, reusable components

Add Authentication

Secure your application with authentication backends

Database Integration

Connect to databases using repositories and dependency injection

​
Troubleshooting

​
Common Issues

Port Already in Use
  • Change the port with: uvicorn app.main:app --reload --port 8001
Poetry Command Not Found
  • Install Poetry from python-poetry.org
  • Or use pip: pip install tasteful (though Poetry is recommended)

​
Getting Help