<p align="center">
<img src="docs/images/stela.png" alt="Stela" />
</p>
<p align="center">
<em>Easily manage your application settings and secrets</em>
</p>
<p align="center">
<a href="https://pypi.org/project/stela/" target="_blank">
<img alt="PyPI" src="https://img.shields.io/pypi/v/stela"/></a>
<a href="https://github.com/megalus/stela/actions" target="_blank">
<img alt="Build" src="https://github.com/megalus/stela/workflows/tests/badge.svg"/></a>
<a href="https://www.python.org" target="_blank">
<img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/stela"/></a>
<a href="https://github.com/megalus/stela/blob/main/LICENSE" target="_blank">
<img alt="License" src="https://img.shields.io/github/license/megalus/stela"/></a>
</p>
## Welcome to Stela
[Stela](https://en.wikipedia.org/wiki/Stele) 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
1. In a new project run `pip install stela`
2. On terminal, run `stela init --default --no-confirm`
3. Uncomment the `MY_SECRET` line in `.env`
4. Add `from stela import env` and run `print(env.MY_SECRET)` in your code
5. Uncomment the `MY_SECRET` line in `.env.local` and get the code again.
6. Add `export MY_SECRET=memory_value` in 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
```shell
pip install stela
```
### Documentation
For detailed documentation, visit: https://megalus.github.io/stela/
### Key Features
1. **Learn once, use everywhere** - Works with any Python project or framework
2. **Separate settings from secrets** - Use multiple dotenv files to organize your configuration
3. **Environment-specific settings** - Easily switch between development, testing, and production environments
4. **Simple API** - Access your settings with `from stela import env`
5. **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:
```bash
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 `.gitignore` to exclude sensitive files
### Step 2: Configure Your Settings and Secrets
Add your settings to `.env`:
```ini
# .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`:
```ini
# .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:
```python
# 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):
1. Value already present in the process environment (os.environ). Stela will not overwrite existing env vars.
2. .env.{environment}.local
3. .env.{environment}
4. .env.local
5. .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:
```ini
# .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:
```bash
# 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:
```python
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:
```ini
# .stela
[stela]
final_loader = "path.to.my.final_loader"
```
### Step 2: Create Your Loader Function
```python
# 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
```python
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](https://megalus.github.io/stela/)
- **Issues**: Found a bug? Have a question? [Open an issue](https://github.com/megalus/stela/issues)
- **Contribute**: Pull requests are welcome!
Raw data
{
"_id": null,
"home_page": "https://github.com/megalus/stela",
"name": "stela",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "settings, configuration, parser, dotenv, environment",
"author": "Chris Maillefaud",
"author_email": "chrismaille@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/fa/b3/6c07297719332e418f5a5d0680a67facd217627dd87627671b3b85b83202/stela-8.1.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"docs/images/stela.png\" alt=\"Stela\" />\n</p>\n<p align=\"center\">\n<em>Easily manage your application settings and secrets</em>\n</p>\n<p align=\"center\">\n<a href=\"https://pypi.org/project/stela/\" target=\"_blank\">\n<img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/stela\"/></a>\n<a href=\"https://github.com/megalus/stela/actions\" target=\"_blank\">\n<img alt=\"Build\" src=\"https://github.com/megalus/stela/workflows/tests/badge.svg\"/></a>\n<a href=\"https://www.python.org\" target=\"_blank\">\n<img alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/stela\"/></a>\n<a href=\"https://github.com/megalus/stela/blob/main/LICENSE\" target=\"_blank\">\n<img alt=\"License\" src=\"https://img.shields.io/github/license/megalus/stela\"/></a>\n</p>\n\n## Welcome to Stela\n\n[Stela](https://en.wikipedia.org/wiki/Stele) were the \"information\nfiles\" of ancient times. This library helps you manage your project\nsettings and secrets with ease, using a simple and consistent approach.\n\n### What is Stela?\n\nStela is a Python library that simplifies how you handle:\n- **Settings**: Non-sensitive values that can be committed to your repository (API URLs, timeouts, etc.)\n- **Secrets**: Sensitive values that should not be committed (passwords, tokens, etc.)\n- **Environment-specific configurations**: Different values for development, testing, and production\n\n### TL;DR\n\n1. In a new project run `pip install stela`\n2. On terminal, run `stela init --default --no-confirm`\n3. Uncomment the `MY_SECRET` line in `.env`\n4. Add `from stela import env` and run `print(env.MY_SECRET)` in your code\n5. Uncomment the `MY_SECRET` line in `.env.local` and get the code again.\n6. Add `export MY_SECRET=memory_value` in your terminal and get the code again.\n\nNew to multi-environment setups? Start with the Quick Setup guide: https://megalus.github.io/stela/quick_setup/\n\n### Install\n\n```shell\npip install stela\n```\n\n### Documentation\n\nFor detailed documentation, visit: https://megalus.github.io/stela/\n\n### Key Features\n\n1. **Learn once, use everywhere** - Works with any Python project or framework\n2. **Separate settings from secrets** - Use multiple dotenv files to organize your configuration\n3. **Environment-specific settings** - Easily switch between development, testing, and production environments\n4. **Simple API** - Access your settings with `from stela import env`\n5. **Extensible** - Not limited to dotenv files, can load settings from any source (AWS Parameter Store, Vault, etc.)\n\n\n## Quick Start Guide\n\n### Step 1: Initialize Your Project\n\nRun the Stela initialization command to set up your project:\n\n```bash\nstela init --default\n```\n\nThis creates four files:\n- `.env` - Store your default settings (will be committed to git)\n- `.env.local` - Store your secrets (will be ignored by git)\n- `.stela` - Stela configuration file\n- Updates `.gitignore` to exclude sensitive files\n\n### Step 2: Configure Your Settings and Secrets\n\nAdd your settings to `.env`:\n\n```ini\n# .env - This file WILL be committed to your repository\n# Store default settings and fake credentials here\nAPI_URL=\"http://localhost:8000\"\nDB_URL=\"db://fake_user:fake_password@local_db:0000/name\"\n```\n\nAdd your real secrets to `.env.local`:\n\n```ini\n# .env.local - This file will NOT be committed (ignored by git)\n# Store real credentials and secrets here\nDB_URL=\"db://real_user:real_password@real_db:0000/name\"\n```\n\n### Step 3: Access Your Settings in Code\n\nUse the simple API to access your settings and secrets:\n\n```python\n# my_script.py\nfrom stela import env\n\n# Access your settings with dot notation\nAPI_URL = env.API_URL # http://localhost:8000\nDATABASE_URL = env.DB_URL # db://real_user:real_password@real_db:0000/name\n```\n\nStela automatically loads values from `.env` first, then overrides them with values from `.env.local`.\n\n### Precedence at a glance\n\nWhen the same key is defined in multiple places, Stela resolves it using this order (top wins):\n1. Value already present in the process environment (os.environ). Stela will not overwrite existing env vars.\n2. .env.{environment}.local\n3. .env.{environment}\n4. .env.local\n5. .env\n\nIf a key is missing everywhere, Stela raises a StelaValueError by default (configurable).\n\n## Environment-Specific Configuration\n\nStela makes it easy to manage different environments (development, testing, production):\n\n### Step 1: Create Environment-Specific Files\n\nCreate a file for each environment:\n\n```ini\n# .env.development\nAPI_URL=\"http://localhost:8000\"\n\n# .env.production\nAPI_URL=\"https://api.example.com\"\n```\n\n### Step 2: Set the Environment\n\nSet the `STELA_ENV` environment variable to specify which environment to use:\n\n```bash\n# For development\nexport STELA_ENV=development\n\n# For production\nexport STELA_ENV=production\n```\n\n### Step 3: Access Your Settings\n\nYour code remains the same, but Stela will load the appropriate values:\n\n```python\nfrom stela import env\n\n# Will be \"http://localhost:8000\" when STELA_ENV=development\n# Will be \"https://api.example.com\" when STELA_ENV=production\nAPI_URL = env.API_URL\n```\n\n## Advanced: Custom Data Sources\n\nStela isn't limited to dotenv files. You can load settings from any source:\n\n### Step 1: Configure a Final Loader\n\nAdd a final loader in your `.stela` configuration file:\n\n```ini\n# .stela\n[stela]\nfinal_loader = \"path.to.my.final_loader\"\n```\n\n### Step 2: Create Your Loader Function\n\n```python\n# my_loaders.py\nfrom typing import Any\nfrom stela.config import StelaOptions\n\n\ndef final_loader(options: StelaOptions, env_data: dict[str, Any]) -> dict[str, Any]:\n \"\"\"Load settings from a custom source and merge into env_data.\n\n Args:\n options: Stela configuration options (includes current_environment).\n env_data: Data already loaded from dotenv files.\n\n Returns:\n Updated data dictionary.\n \"\"\"\n # Example: pretend we fetched data from an external source\n external = {\"API_TIMEOUT\": \"5\", \"FEATURE_FLAG\": \"true\"}\n\n # Merge/override values\n env_data.update(external)\n return env_data\n```\n\n### Step 3: Use Your Settings as Usual\n\n```python\nfrom stela import env\n\n# Values can come from dotenv files or your custom source\nAPI_URL = env.API_URL\nDB_PASSWORD = env.DB_PASSWORD\nAPI_TIMEOUT = env.API_TIMEOUT # From custom loader\n```\n\n## Need Help?\n\n- **Documentation**: For detailed guides and examples, visit [the documentation](https://megalus.github.io/stela/)\n- **Issues**: Found a bug? Have a question? [Open an issue](https://github.com/megalus/stela/issues)\n- **Contribute**: Pull requests are welcome!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Organize your project settings and secrets with ease",
"version": "8.1.1",
"project_urls": {
"Homepage": "https://github.com/megalus/stela",
"Repository": "https://github.com/megalus/stela"
},
"split_keywords": [
"settings",
" configuration",
" parser",
" dotenv",
" environment"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "218d1baed29c7cbff1d646c9e724f387a911dfd3027f2a709c99930597b187fa",
"md5": "58f16abd30abd7cd438cadbc3864b3b8",
"sha256": "acc49a8933a7ccd7aa68be2367b94706d15f7371f8b57760d1e31768c579d810"
},
"downloads": -1,
"filename": "stela-8.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "58f16abd30abd7cd438cadbc3864b3b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 20733,
"upload_time": "2025-09-02T22:46:30",
"upload_time_iso_8601": "2025-09-02T22:46:30.556792Z",
"url": "https://files.pythonhosted.org/packages/21/8d/1baed29c7cbff1d646c9e724f387a911dfd3027f2a709c99930597b187fa/stela-8.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fab36c07297719332e418f5a5d0680a67facd217627dd87627671b3b85b83202",
"md5": "6ed1e76ed3895ad73096cd5d6ba5bc96",
"sha256": "9d2dc37287c47685b18a2043142fd45d8887e03c2ae8caaaa220eb7b66717d2c"
},
"downloads": -1,
"filename": "stela-8.1.1.tar.gz",
"has_sig": false,
"md5_digest": "6ed1e76ed3895ad73096cd5d6ba5bc96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 17631,
"upload_time": "2025-09-02T22:46:31",
"upload_time_iso_8601": "2025-09-02T22:46:31.914650Z",
"url": "https://files.pythonhosted.org/packages/fa/b3/6c07297719332e418f5a5d0680a67facd217627dd87627671b3b85b83202/stela-8.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 22:46:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "megalus",
"github_project": "stela",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "stela"
}
JSON
