starlette/docs/config.md

Starlette encourages a strict separation of configuration from code, following the twelve-factor pattern.

Configuration should be stored in environment variables, or in a ".env" file that is not committed to source control.

app.py:

from starlette.applications import Starlette
from starlette.config import Config
from starlette.datastructures import DatabaseURL, Secret

# Config will be read from environment variables and/or ".env" files.
config = Config(".env")

DEBUG = config('DEBUG', cast=bool, default=False)
DATABASE_URL = config('DATABASE_URL', cast=DatabaseURL)
SECRET_KEY = config('SECRET_KEY', cast=Secret)

app = Starlette()
app.debug = DEBUG
...

.env:

# Don't commit this to source control.
# Eg. Include ".env" in your `.gitignore` file.
DEBUG=True
DATABASE_URL=postgresql://localhost/myproject
SECRET_KEY=43n080musdfjt54t-09sdgr

Configuration precedence

The order in which configuration values are read is:

• From an environment variable.
• From the ".env" file.
• The default value given in config.

If none of those match, then config(...) will raise an error.

Secrets

For sensitive keys, the Secret class is useful, since it prevents the value from leaking out into tracebacks or logging.

To get the value of a Secret instance, you must explicitly cast it to a string. You should only do this at the point at which the value is used.

>>> from myproject import settings
>>> print(settings.SECRET_KEY)
Secret('**********')
>>> str(settings.SECRET_KEY)
'98n349$%8b8-7yjn0n8y93T$23r'

Similarly, the URL and DatabaseURL class will hide any password component in their representations.

>>> from myproject import settings
>>> print(settings.DATABASE_URL)
DatabaseURL('postgresql://admin:**********@192.168.0.8/my-application')
>>> str(settings.SECRET_KEY)
'postgresql://admin:Fkjh348htGee4t3@192.168.0.8/my-application'

Reading or modifying the environment

In some cases you might want to read or modify the environment variables programmatically. This is particularly useful in testing, where you may want to override particular keys in the environment.

Rather than reading or writing from os.environ, you should use Starlette's environ instance. This instance is a mapping onto the standard os.environ that additionally protects you by raising an error if any environment variable is set after the point that it has already been read by the configuration.

If you're using pytest, then you can setup any initial environment in tests/conftest.py.

tests/conftest.py:

from starlette.config import environ

environ['TESTING'] = 'TRUE'

A full example

Structuring large applications can be complex. You need proper separation of configuration and code, database isolation during tests, separate test and production databases, etc...

Here we'll take a look at a complete example, that demonstrates how we can start to structure an application.

First, let's keep our settings, our database table definitions, and our application logic separated:

myproject/settings.py:

from starlette.config import Config
from starlette.datastructures import DatabaseURL, Secret

config = Config(".env")

DEBUG = config('DEBUG', cast=bool, default=False)
TESTING = config('TESTING', cast=bool, default=False)
SECRET_KEY = config('SECRET_KEY', cast=Secret)

DATABASE_URL = config('DATABASE_URL', cast=DatabaseURL)
if TESTING:
    DATABASE_URL = DATABASE_URL.replace(database='test_' + DATABASE_URL.database)

myproject/tables.py:

import sqlalchemy

# Database table definitions.
metadata = sqlalchemy.MetaData()

organisations = sqlalchemy.Table(
    ...
)

myproject/app.py

from starlette.applications import Starlette
from starlette.middleware.database import DatabaseMiddleware
from starlette.middleware.session import SessionMiddleware
from myproject import settings


app = Starlette()

app.debug = settings.DEBUG

app.add_middleware(
    SessionMiddleware,
    secret_key=settings.SECRET_KEY,
)
app.add_middleware(
    DatabaseMiddleware,
    database_url=settings.DATABASE_URL,
    rollback_on_shutdown=settings.TESTING
)

@app.route('/', methods=['GET'])
async def homepage(request):
    ...

Now let's deal with our test configuration. We'd like to create a new test database every time the test suite runs, and drop it once the tests complete. We'd also like to ensure

tests/conftest.py:

from starlette.config import environ
from starlette.testclient import TestClient
from sqlalchemy import create_engine
from sqlalchemy_utils import database_exists, create_database

# This line would raise an error if we use it after 'settings' has been imported.
environ['TESTING'] = 'TRUE'

from myproject import settings
from myproject.app import app
from myproject.tables import metadata


@pytest.fixture(autouse=True, scope="session")
def setup_test_database():
    """
    Create a clean test database every time the tests are run.
    """
    url = str(settings.DATABASE_URL)
    engine = create_engine(url)
    assert not database_exists(url), 'Test database already exists. Aborting tests.'
    create_database(url)             # Create the test database.
    metadata.create_all(engine)      # Create the tables.
    yield                            # Run the tests.
    drop_database(url)               # Drop the test database.


@pytest.fixture()
def client():
    """
    Make a 'client' fixture available to test cases.
    """
    # Our fixture is created within a context manager. This ensures that
    # application startup and shutdown run for every test case.
    #
    # Because we've configured the DatabaseMiddleware with `rollback_on_shutdown`
    # we'll get a complete rollback to the initial state after each test case runs.
    with TestClient(app) as test_client:
        yield test_client