Welcome to Stela¶
Stela were the "information files" of ancient times. This library aims to simplify your project configurations, proposing an opinionated way to manage your project using dotenv files, or using any source you need.
Motivation¶
Working with environment variables vs project settings and secrets can be confusing for newcomers. Stela helps you separate concerns and keep a clear mental model.
- Sometimes we need to define a default value for a secret, like a database url, to run unit tests.
- Sometimes, we need to set different values for a setting, like an API url, for different environments.
- Sometimes, we use dotenv on local development, but need to use other services, like vaults or secret managers, to retrieve these same settings and secrets on production.
This library was created to help simplify this process, by providing a single interface to access all data from multiple dotenv files, or if you need, from your custom logic to retrieve your project settings and secrets from another source.
About settings and secrets
In this documentation we talk a lot about these two concepts. We mean:
settings
: Any non-sensitive value, which can differ between environments. This data can be safely committed to your project. Examples: API URLs, timeout values, etc.secrets
: Any sensitive value, which you must not commit to your project. Examples: tokens, passwords, etc.
Why another library?¶
There are a lot of good libraries to work with project settings:
- python-dotenv - One of the most popular. In fact, we use it under the hood to load the dotenv files.
- python-decouple - Another good one, this library together with Dynaconf and Plaster were the main inspirations for this project until version 5.x
- Pydantic - A very powerful solution for data validation. They provide a Settings Management tool, which is a good solution for that environment.
Why use Stela?¶
Our key features:
- Learn once, use everywhere. Stela aims to be easily used in any Python project or Framework.
- Separate settings, secrets, and environments. Instead of using a single dotenv file to store all your settings, we use multiple dotenv files, one for each environment. This way, you can split secrets from settings, and you can have different values for the same environment variable in different environments.
- Easy to implement. Use the command
stela init
to initialize your project and configure.env
and.gitignore
files. - Easy to use. To access your configuration, just include
from stela import env
in your code. Simple as that. - One Interface, Any Source. You're not limited to dotenv files. Create your custom logic to import data from any source you need.
How it fits your workflow¶
flowchart TD
ST[In your app:
from stela import env
] --> A
subgraph All[Reading .env files]
A[.env] -->|is override by, if exists| B[.env.local]
end
B --> A1{STELA_ENV
is set?}
A1 -- Yes --> C[.env.environment]
A1 -- No --> A2
subgraph Environment [Override previous data]
C[.env.environment] -->|is override by, if exists| E[.env.environment.local]
end
E --> A2{Custom Loader
exists?}
A2 -- Yes --> F[Custom Loader]
A2 -- No --> G
F[Custom Loader] -->|final override| G
G[Get from:
env.MY_SECRET]
See Quick Setup to get started fast: Quick Setup.
Install¶
Currently this project supports:
- Python 3.11, 3.12 and 3.13