Settings and Environment Variables#

In many cases, your application may require external settings or configurations, such as a broker connection or database credentials.

To manage these settings effectively, it's common to provide them through environment variables that can be read by the application.

Pydantic Settings#

Fortunately, Pydantic provides a useful utility for handling settings coming from environment variables with Pydantic: Settings management.

Install pydantic-settings#

First, install the pydantic-settings package:

pip install pydantic-settings

Create the Settings Object#

Import BaseSettings from Pydantic and create a subclass, similar to what you would do with a Pydantic model.

Just like with Pydantic models, you declare class attributes with type annotations and can use all the same validation features and tools, including different data types and additional validations with Field().

1
2
3
4
5
6
7
8
9

from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    url: str = ""
    queue: str = "test-queue"


settings = Settings()

1
2
3
4
5
6
7
8
9

from pydantic import BaseSettings


class Settings(BaseSettings):
    url: str = ""
    queue: str = "test-queue"


settings = Settings()

When you create an instance of that Settings class (in this case, in the settings object), Pydantic will read the environment variables in a case-insensitive way. For example, an upper-case variable APP_NAME will still be read for the attribute app_name.

It will also convert and validate the data, so when you use that settings object, you will have data of the type you declared (e.g. items_per_user will be an int).

Using the settings#

Now you can use the new settings object in your application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

import os

from pydantic_settings import BaseSettings

from faststream import FastStream
from faststream.rabbit import RabbitBroker


class Settings(BaseSettings):
    url: str
    queue: str = "test-queue"


settings = Settings(_env_file=os.getenv("ENV", ".env"))

broker = RabbitBroker(settings.url)
app = FastStream(broker)


@broker.subscriber(settings.queue)
async def handler(msg):
    ...

Running the Application#

You can run the application while passing the configuration parameters as environment variables. For example, you could set an URL:

URL="amqp://guest:guest@localhost:5672" faststream run serve:app

Reading a .env File#

If you have many settings that may change frequently, especially in different environments, it might be useful to store them in a file and then read them as if they were environment variables.

This practice is common enough that it has a name; these environment variables are typically placed in a file named .env, commonly referred to as a "dotenv" file.

Pydantic supports reading from these types of files using an external library. You can learn more at Pydantic Settings: Dotenv (.env) support.

The .env File#

You can create a .env file with contents like this:

URL="amqp://guest:guest@localhost:5672"
QUEUE="test-queue"

Reading Settings from .env#

Then update your config.py as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

import os

from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    url: str
    queue: str = "test-queue"


settings = Settings(_env_file=os.getenv("ENV", ".env"))

This way, you can specify different .env files directly from your terminal, which can be extremely helpful for various testing and production scenarios.

Choosing the .env File at Startup#

Now you can run the apllication with different .env files like so:

ENV=.local.env faststream run serve:app

Or, for a production environment:

ENV=.production.env faststream run serve:app

Or even for a test environment:

ENV=.test.env pytest