Add documentation about configuration and env vars

[alexmitelman]

In this pull request I add a new documentation page that describes the way to work with environment variables.

Related to this #190 and this #399 issues.

[codecov]

Codecov Report

Merging #1118 into master will not change coverage by %.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##            master     #1118   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          224       225    +1     
  Lines         6728      6733    +5     
=========================================
+ Hits          6728      6733    +5     

Impacted Files	Coverage Δ
...ts/test_tutorial/test_metadata/test_tutorial001.py	100.00% <100.00%> (ø)
tests/test_tutorial/test_settings/test_app02.py	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6e1cd45...9f9e2eb. Read the comment docs.

[tiangolo]

Thanks for starting this! 🚀 🍰

I have been intending to add these docs for awhile 😅 So I updated it with what I had in mind and to include a couple of extra explanations.

Thanks for your contribution! 🎉 🍰

[leosussan]

Question to @alexmitelman : any benefit to using Pydantic vs. Starlette's baked-in configuration stuff?

[alexmitelman]

Question to @alexmitelman : any benefit to using Pydantic vs. Starlette's baked-in configuration stuff?

IMHO, Starlette solution looks more low level, while using Pydantic you just declare class as usual.
Let's compare:

Starlette

from starlette.config import Config


config = Config(".env")

DEBUG = config('DEBUG', cast=bool, default=False)

Pydantic

from pydantic import BaseSettings


class Settings(BaseSettings):
    debug: bool = False

    class Config:
        env_file = '.env'

[leosussan]

@alexmitelman that's a description of syntax, not a functional differentiation. It also does not really explain the strengths / benefits of that syntactical difference, or if there is one.

I've now used both. IMO - given FastAPI's reliance on simplicity, I think Starlette's setup should be the preferred structure for the following three reasons:

1. Starlette's config does not require the installation of a secondary dependency (Pydantic requires python-dotenv).
2. Starlette's config caches the variable by default (no need for a custom lru_cache implementation).
3. Starlette's suggested config.py file structure - simple, flat - is consistent with the .env file format.

That said - I've very recently taken to using Pydantic for settings management in larger projects for the following three reasons:

1. Pydantic is better for codebases with multiple runtimes (it wouldn't make sense to install Starlette on a worker just to gain access to its' config class for the sake of code sharing).
2. Pydantic lends itself well to the creation of constructed globals (e.g. DATABASE_URI as the combination of DATABASE_PORT, DATABASE_HOST, etc etc).
3. Pydantic has a much larger library of data types to cast / validate globals against.

Those three reasons are compelling (don't get me wrong, Pydantic is amazing; I use it in everything) but I'd imagine the first three would make Starlette's config preferable in most situations.

[mths0x5f]

I was surprised by this change, @leosussan summarized what I needed to know.