Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 38 ยท Projects and Practice

Project: A Configuration Loader

Build a configuration loader step by step: nested typed settings, TOML file plus environment overrides, secrets, production rules, readable startup errors and tests.

In this project you build the configuration layer of a small web service called Shelfie, a bookshelf tracker. The goal is a loader that a team could really use: settings are typed and nested, values come from a TOML file with environment variables on top, secrets stay hidden, production has extra safety rules, and a mistake produces one readable message instead of a stack trace.

You will combine ideas from the settings chapter: BaseSettings, sources, secrets and model validators. Each step is a runnable program and the last one assembles everything.

flowchart LR
    T["config.toml<br/>(defaults for a team)"] --> L["loader"]
    E["environment variables<br/>(per deployment)"] --> L
    L --> V{"validate"}
    V -->|ok| S["Settings object"]
    V -->|errors| M["one readable message<br/>exit code 1"]

Two sources, one validated object, one clear failure path.

Step 1: describe the settings

Start with the shape. Nested groups for the database, the cache and the mail server; a Literal environment name; a secret key.

Python Step 1: the settings model

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

extra="forbid" means a misspelled key in the config file is an error, not an ignored value that you only find out about when a feature mysteriously stays off.

Step 2: read a TOML file

Teams like a committed config.toml for shared defaults. Python 3.11 includes tomllib. Pydantic-settings can read TOML files directly; to keep control of the precedence, this step loads the file by hand and passes it in as the lowest-priority input.

Python Step 2: TOML as defaults

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Priority is now: constructor arguments, then environment variables, then the file, then class defaults. The environment overrides one nested key (port) while the rest of the database group still comes from the file.

Step 3: production rules

A development default must never reach production. Add a model validator that refuses unsafe production configurations.

Python Step 3: refuse unsafe production settings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Collecting all problems into one message lets an operator fix everything in one deploy attempt.

Step 4: readable startup errors

A raw ValidationError is accurate but noisy. Wrap loading in a function that prints one line per problem, mentions the environment variable to set, and returns a non-zero exit status. This is the user interface of your configuration.

Python Step 4: friendly error report

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The report names the environment variable to fix, which is what an operator needs, not the Python field path.

Step 5: test the loader

Configuration code deserves tests: they document the rules and protect them. Each test builds settings with explicit values (init arguments beat the environment) and asserts the outcome.

Python Step 5: tests for the loader

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Ideas to extend it

  • Add a --print-config command that shows the final settings with secrets masked, to help debugging deployments.
  • Read secrets from files in /run/secrets with secrets_dir.
  • Write a Settings.model_json_schema() dump to a file and let your editor validate config.toml against it.
  • Add a reload_settings() that clears the cache for long-running services.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the Settings model use extra="forbid"?

    A typo such as debgu = false would otherwise be dropped, and the real setting would keep its default.
  2. 2. In the layered loader, what is the order of priority?

    The tuple returned by settings_customise_sources lists the sources from highest to lowest priority.
  3. 3. Why does the error report print environment variable names?

    A good error tells the reader what to change, in the vocabulary of their tools.
  4. 4. Where should production safety rules live?

    A model validator checks the whole configuration once when settings are created.

Summary

  • Nested BaseModel groups plus BaseSettings give typed, structured configuration.
  • Layer sources deliberately: arguments, environment, file, defaults.
  • Model validators enforce production safety; SecretStr keeps secrets out of logs.
  • Turn ValidationError into one clear report that names the variable to fix.
  • Test the rules with explicit values.

Next: Project: A Validated API Layer