Easily manage your application settings and secrets
Welcome to Stela
Stela were the "information files" of ancient times. This library helps you manage your project settings and secrets with ease, using a simple and consistent approach.
What is Stela?
Stela is a Python library that simplifies how you handle:
- Settings: Non-sensitive values that can be committed to your repository (API URLs, timeouts, etc.)
- Secrets: Sensitive values that should not be committed (passwords, tokens, etc.)
- Environment-specific configurations: Different values for development, testing, and production
TL;DR
- In a new project run
pip install stela - On terminal, run
stela init --default --no-confirm - Uncomment the
MY_SECRETline in.env - Add
from stela import envand runprint(env.MY_SECRET)in your code - Uncomment the
MY_SECRETline in.env.localand get the code again. - Add
export MY_SECRET=memory_valuein your terminal and get the code again.
New to multi-environment setups? Start with the Quick Setup guide: https://megalus.github.io/stela/quick_setup/
Install
pip install stela
Development
# Define your VIRTUAL_ENV location. For example: export VIRTUAL_ENV=$(pwd)
uv sync --active --group dev
make ci
Documentation
For detailed documentation, visit: https://megalus.github.io/stela/
Key Features
- Learn once, use everywhere - Works with any Python project or framework
- Separate settings from secrets - Use multiple dotenv files to organize your configuration
- Environment-specific settings - Easily switch between development, testing, and production environments
- Simple API - Access your settings with
from stela import env - Extensible - Not limited to dotenv files, can load settings from any source (AWS Parameter Store, Vault, etc.)
Quick Start Guide
Step 1: Initialize Your Project
Run the Stela initialization command to set up your project:
stela init --default
This creates four files:
.env- Store your default settings (will be committed to git).env.local- Store your secrets (will be ignored by git).stela- Stela configuration file- Updates
.gitignoreto exclude sensitive files
Step 2: Configure Your Settings and Secrets
Add your settings to .env:
# .env - This file WILL be committed to your repository
# Store default settings and fake credentials here
API_URL="http://localhost:8000"
DB_URL="db://fake_user:fake_password@local_db:0000/name"
Add your real secrets to .env.local:
# .env.local - This file will NOT be committed (ignored by git)
# Store real credentials and secrets here
DB_URL="db://real_user:real_password@real_db:0000/name"
Step 3: Access Your Settings in Code
Use the simple API to access your settings and secrets:
# my_script.py
from stela import env
# Access your settings with dot notation
API_URL = env.API_URL # http://localhost:8000
DATABASE_URL = env.DB_URL # db://real_user:real_password@real_db:0000/name
Stela automatically loads values from .env first, then overrides them with values from .env.local.
Precedence at a glance
When the same key is defined in multiple places, Stela resolves it using this order (top wins):
- Value already present in the process environment (os.environ). Stela will not overwrite existing env vars.
- .env.{environment}.local
- .env.{environment}
- .env.local
- .env
If a key is missing everywhere, Stela raises a StelaValueError by default (configurable).
Environment-Specific Configuration
Stela makes it easy to manage different environments (development, testing, production):
Step 1: Create Environment-Specific Files
Create a file for each environment:
# .env.development
API_URL="http://localhost:8000"
# .env.production
API_URL="https://api.example.com"
Step 2: Set the Environment
Set the STELA_ENV environment variable to specify which environment to use:
# For development
export STELA_ENV=development
# For production
export STELA_ENV=production
Step 3: Access Your Settings
Your code remains the same, but Stela will load the appropriate values:
from stela import env
# Will be "http://localhost:8000" when STELA_ENV=development
# Will be "https://api.example.com" when STELA_ENV=production
API_URL = env.API_URL
Advanced: Custom Data Sources
Stela isn't limited to dotenv files. You can load settings from any source:
Step 1: Configure a Final Loader
Add a final loader in your .stela configuration file:
# .stela
[stela]
final_loader = "path.to.my.final_loader"
Step 2: Create Your Loader Function
# my_loaders.py
from typing import Any
from stela.config import StelaOptions
def final_loader(options: StelaOptions, env_data: dict[str, Any]) -> dict[str, Any]:
"""Load settings from a custom source and merge into env_data.
Args:
options: Stela configuration options (includes current_environment).
env_data: Data already loaded from dotenv files.
Returns:
Updated data dictionary.
"""
# Example: pretend we fetched data from an external source
external = {"API_TIMEOUT": "5", "FEATURE_FLAG": "true"}
# Merge/override values
env_data.update(external)
return env_data
Step 3: Use Your Settings as Usual
from stela import env
# Values can come from dotenv files or your custom source
API_URL = env.API_URL
DB_PASSWORD = env.DB_PASSWORD
API_TIMEOUT = env.API_TIMEOUT # From custom loader
Need Help?
- Documentation: For detailed guides and examples, visit the documentation
- Issues: Found a bug? Have a question? Open an issue
- Contribute: Pull requests are welcome!
1 maintainer
Metadata
1 maintainer
Release files for stela 9.0.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| stela-9.0.6.tar.gz | 113.2 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stela-9.0.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 134.1 kB
Release files / stela-9.0.6.tar.gz
| Download URL | stela-9.0.6.tar.gz |
|---|---|
| Size | 113.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bbf33a4698d35b4838a5ebbf531e32dcc7ed04a7da4f1c925d5ebba430e5d274
|
|
BLAKE2b-256 checksum How to use checksums |
17187e026063f1f352354925becba03cbaf3601d6f77696d25d2852416d1d384
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 25, 2026.
Transparency logRelease files / stela-9.0.6-py3-none-any.whl
| Download URL | stela-9.0.6-py3-none-any.whl |
|---|---|
| Size | 20.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0e0d68e894a69d1b55e4f17faebd27d3268a9a614c98c3225e740b70ca6d7acf
|
|
BLAKE2b-256 checksum How to use checksums |
a3f90131c4d1f74412d9075d9b71fa945d3184ee1bf03fb0778dcd0e75e5234b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 25, 2026.
Transparency logSecurity for stela 9.0.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for stela-9.0.6.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
