Background tasks

FastAPI provides built-in support for background tasks, which is very useful for offloading work that can be done asynchronously, such as sending emails, processing data, or interacting with external services without holding up the main request/response cycle. This helps in keeping the API responsive and performant.

Background Tasks with FastAPI

Basic Usage

Import BackgroundTasks
FastAPI provides the BackgroundTasks class for defining tasks that should run in the background.
```
from fastapi import FastAPI, BackgroundTasks
```
Define a Background Task Function
The background task function can be any callable (function or class with a __call__ method). This function will execute asynchronously after the response is sent.
```
def write_log(message: str):
    with open("log.txt", "a") as log_file:
        log_file.write(f"{message}\n")
```
In this example, write_log is a function that appends a message to a log file. This is a simple task that you want to run in the background.
Add Background Tasks to Endpoints
You can add background tasks to your endpoint by including BackgroundTasks in the parameters of the endpoint function.
```
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

@app.post("/items/")
async def create_item(name: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, f"Item {name} was created.")
    return {"message": f"Item {name} created successfully!"}
```
- The background_tasks.add_task() method schedules the write_log function to run in the background after the response is sent.
- You can pass any number of arguments to add_task(), which will be used to call the task function.

Example: Sending Emails

Sending emails is a common background task in web applications. Let’s see how to set up such a task with FastAPI.

Define the Background Task
Assume you have a function to send an email. This function could be more complex and involve interacting with an email service or SMTP server.

def send_email(to: str, subject: str, body: str):
    # Simulate sending an email (e.g., connect to an SMTP server and send the email)
    with open("emails.log", "a") as email_log:
        email_log.write(f"To: {to}\nSubject: {subject}\n\n{body}\n\n")

This function logs the email to a file instead of sending it for simplicity.

Add the Task to an Endpoint
You can schedule the email to be sent in the background after the response is returned to the client.

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

@app.post("/send-email/")
async def send_email_endpoint(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, email, "Welcome!", "Thank you for signing up!")
    return {"message": "Email will be sent soon"}

This endpoint accepts an email address and schedules the send_email function to run in the background.

Running the Application
Start the application with Uvicorn:
```
uvicorn main:app --reload
```
When you send a POST request to /send-email/, FastAPI will immediately return the response while the email is being "sent" in the background.

Example Project

Here’s a complete example demonstrating background tasks:

Project Structure
```
fastapi_project/
│
├── main.py
├── log.txt
└── emails.log
```
- log.txt will store log messages.
- emails.log will store email logs.

main.py

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def write_log(message: str):
    with open("log.txt", "a") as log_file:
        log_file.write(f"{message}\n")

def send_email(to: str, subject: str, body: str):
    with open("emails.log", "a") as email_log:
        email_log.write(f"To: {to}\nSubject: {subject}\n\n{body}\n\n")

@app.post("/items/")
async def create_item(name: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, f"Item {name} was created.")
    return {"message": f"Item {name} created successfully!"}

@app.post("/send-email/")
async def send_email_endpoint(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, email, "Welcome!", "Thank you for signing up!")
    return {"message": "Email will be sent soon"}

The /items/ endpoint logs a message about the item creation.
The /send-email/ endpoint schedules sending an email.

Testing the Application
- Start the FastAPI server.
- Use a tool like curl or Postman to send POST requests to the endpoints.
- Check log.txt and emails.log to see the results of the background tasks.

Advanced Background Tasks

For more complex scenarios, you might need more advanced solutions. Here are a few options:

Using Celery for Distributed Tasks
If you need to manage complex background jobs, such as distributed task queues, Celery is a popular choice. It works well with FastAPI for handling tasks that might take a long time or need to be processed in parallel.

# tasks.py
from celery import Celery

celery_app = Celery('tasks', broker='redis://localhost:6379/0')

@celery_app.task
def send_email(to: str, subject: str, body: str):
    # Code to send email
    pass

In FastAPI, you would call this task:

from fastapi import FastAPI
from tasks import send_email

app = FastAPI()

@app.post("/send-email/")
async def send_email_endpoint(email: str):
    send_email.delay(email, "Welcome!", "Thank you for signing up!")
    return {"message": "Email will be sent soon"}

Celery uses a message broker (like Redis) to manage task distribution and scheduling.

Using BackgroundTask for Inline Tasks
For lightweight background tasks, FastAPI’s BackgroundTasks is often sufficient. However, for more elaborate control or if tasks need to interact with your main application logic, you might consider a different architecture, like integrating a task queue or using threading/asyncio for parallelism.

Conclusion

FastAPI’s background tasks provide a simple and efficient way to handle asynchronous processing. Whether you’re logging information, sending emails, or performing other background operations, FastAPI makes it easy to keep your main API responsive while managing additional workloads behind the scenes. For more complex requirements, integrating with task queues like Celery can offer more advanced capabilities.

FastapiServing HTML and Static files

FastapiWebsockets