# envappconfig
envappconfig is intended to provide simple configuration via environment variables, in the same spirit as argparse, which can be useful when developing and deploying [12-factor apps](https://12factor.net).
Features:
* Autogenerates usage output if an environment variable is missing
* Default settings for missing environment variables
* Functions that transform the environment variable string to the value type you need
* Environment variable prefixes
## Basic example
```python
from envappconfig import EnvAppConfig
env = EnvAppConfig(description='Amazing app')
env.add_env('port', default=1234, transform=int, help='The listen port')
env.add_env('mirror', help='The URL to mirror')
config = env.configure()
# Returns PORT from os.environ transformed to an int,
# or 1234 if PORT does not exist.
config.port
# Returns MIRROR from os.environ,
# or displays usage at env.configure()
# if MIRROR does not exist, then exits.
config.mirror
```
## Adding a prefix
If all the environment variables for the app have the same prefix, it can be specified with the `prefix` parameter.
```python
from envappconfig import EnvAppConfig
env = EnvAppConfig(prefix='MYAPP', description='Amazing app')
env.add_env('port', default=1234, transform=int, help='The listen port')
env.add_env('mirror', help='The URL to mirror')
config = env.configure()
# Returns MYAPP_PORT from os.environ transformed to an int,
# or 1234 if MYAPP_PORT does not exist.
config.port
# Returns MYAPP_MIRROR from os.environ,
# or displays usage at env.configure()
# if MYAPP_MIRROR does not exist, then exits.
config.mirror
```
## Custom transforms
The `transform` parameter can be used to specify normal transforms, like `int` or `float` (the default is `str`), but it can also take custom transform functions. The transform function must take a single parameter, which will be filled in with the string value from the environment variable.
```python
env = EnvAppConfig(description='Amazing app')
# Double the timeout specified in the TIMEOUT environment variable,
# or default to 60.
env.add_env('timeout', default=60, transform=lambda x: int(x) * 2, help='Timeout in seconds')
...
```
## Adding more config values
Additional config values can be added to an existing namespace, which can be helpful when there's a config value that needs to be calculated based on other config values.
```python
from envappconfig import EnvAppConfig
env = EnvAppConfig(description='Amazing app')
env.add_env('bind', help='IP address to bind to')
env.add_env('port', default=1234, transform=int, help='The listen port')
config = env.configure()
config.listen = f'{config.bind}:{config.port}'
# Returns the combined bind:port string.
config.listen
```
## Command Line
There are a couple options for using envappconfig at the command line (eg. when testing).
### Prefix
If you've only got a couple environment variables to set, just put them before the command:
```sh
PORT=9999 NAME=foo python3 script_using_envappconfig.py
```
### dotenv
If you have more environment variables to set, consider using `dotenv`. First put your environment variables in a file named `.env`:
```sh
PORT=9999
NAME=foo
```
Then call `dotenv` as follows, which will load up the variables from `.env` for this command:
```sh
dotenv run -- python3 script_using_envappconfig.py
```
You can install the `dotenv` command line tool with:
```sh
python3 -m pip install "python-dotenv[cli]"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/spectriclabs/envappconfig",
"name": "envappconfig",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Spectric Labs",
"author_email": "foss@spectric.com",
"download_url": "https://files.pythonhosted.org/packages/32/6d/c2ffcd4ff79196e1f23416fe0ae9975dbad31435b98e739274031a70b699/envappconfig-2023.198.827.tar.gz",
"platform": null,
"description": "# envappconfig\n\nenvappconfig is intended to provide simple configuration via environment variables, in the same spirit as argparse, which can be useful when developing and deploying [12-factor apps](https://12factor.net).\n\nFeatures:\n* Autogenerates usage output if an environment variable is missing\n* Default settings for missing environment variables\n* Functions that transform the environment variable string to the value type you need\n* Environment variable prefixes\n\n## Basic example\n\n```python\nfrom envappconfig import EnvAppConfig\n\nenv = EnvAppConfig(description='Amazing app')\nenv.add_env('port', default=1234, transform=int, help='The listen port')\nenv.add_env('mirror', help='The URL to mirror')\nconfig = env.configure()\n\n# Returns PORT from os.environ transformed to an int,\n# or 1234 if PORT does not exist.\nconfig.port\n\n# Returns MIRROR from os.environ,\n# or displays usage at env.configure()\n# if MIRROR does not exist, then exits.\nconfig.mirror\n```\n\n## Adding a prefix\n\nIf all the environment variables for the app have the same prefix, it can be specified with the `prefix` parameter.\n\n```python\nfrom envappconfig import EnvAppConfig\n\nenv = EnvAppConfig(prefix='MYAPP', description='Amazing app')\nenv.add_env('port', default=1234, transform=int, help='The listen port')\nenv.add_env('mirror', help='The URL to mirror')\nconfig = env.configure()\n\n# Returns MYAPP_PORT from os.environ transformed to an int,\n# or 1234 if MYAPP_PORT does not exist.\nconfig.port\n\n# Returns MYAPP_MIRROR from os.environ,\n# or displays usage at env.configure()\n# if MYAPP_MIRROR does not exist, then exits.\nconfig.mirror\n```\n\n## Custom transforms\n\nThe `transform` parameter can be used to specify normal transforms, like `int` or `float` (the default is `str`), but it can also take custom transform functions. The transform function must take a single parameter, which will be filled in with the string value from the environment variable.\n\n```python\nenv = EnvAppConfig(description='Amazing app')\n\n# Double the timeout specified in the TIMEOUT environment variable,\n# or default to 60.\nenv.add_env('timeout', default=60, transform=lambda x: int(x) * 2, help='Timeout in seconds')\n...\n```\n\n## Adding more config values\n\nAdditional config values can be added to an existing namespace, which can be helpful when there's a config value that needs to be calculated based on other config values.\n\n```python\nfrom envappconfig import EnvAppConfig\n\nenv = EnvAppConfig(description='Amazing app')\nenv.add_env('bind', help='IP address to bind to')\nenv.add_env('port', default=1234, transform=int, help='The listen port')\nconfig = env.configure()\nconfig.listen = f'{config.bind}:{config.port}'\n\n# Returns the combined bind:port string.\nconfig.listen\n```\n\n## Command Line\n\nThere are a couple options for using envappconfig at the command line (eg. when testing).\n\n### Prefix\n\nIf you've only got a couple environment variables to set, just put them before the command:\n\n```sh\nPORT=9999 NAME=foo python3 script_using_envappconfig.py\n```\n\n### dotenv\n\nIf you have more environment variables to set, consider using `dotenv`. First put your environment variables in a file named `.env`:\n\n```sh\nPORT=9999\nNAME=foo\n```\n\nThen call `dotenv` as follows, which will load up the variables from `.env` for this command:\n\n```sh\ndotenv run -- python3 script_using_envappconfig.py\n```\n\nYou can install the `dotenv` command line tool with:\n\n```sh\npython3 -m pip install \"python-dotenv[cli]\"\n```\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Simple app configuration via environment variables, in the spirit of argparse.",
"version": "2023.198.827",
"project_urls": {
"Homepage": "https://github.com/spectriclabs/envappconfig"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ff6ebb2b89677a23d75b68c125defa3c8cfaa60057f444982f633834317b796c",
"md5": "285a6a52a6274568ae1452a27b2e7afc",
"sha256": "939862b49d7db73aa325a7b6aaf1caf086ef0ba589c082e7be4ba711242d8327"
},
"downloads": -1,
"filename": "envappconfig-2023.198.827-py3-none-any.whl",
"has_sig": false,
"md5_digest": "285a6a52a6274568ae1452a27b2e7afc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 8236,
"upload_time": "2023-07-17T13:47:59",
"upload_time_iso_8601": "2023-07-17T13:47:59.366659Z",
"url": "https://files.pythonhosted.org/packages/ff/6e/bb2b89677a23d75b68c125defa3c8cfaa60057f444982f633834317b796c/envappconfig-2023.198.827-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "326dc2ffcd4ff79196e1f23416fe0ae9975dbad31435b98e739274031a70b699",
"md5": "d38a3ae953b5200d87452c0499d3d3fc",
"sha256": "8df0ca49760fb0645fee0e8967989588a55494533d4b0ec626e0317f28e051a4"
},
"downloads": -1,
"filename": "envappconfig-2023.198.827.tar.gz",
"has_sig": false,
"md5_digest": "d38a3ae953b5200d87452c0499d3d3fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 7494,
"upload_time": "2023-07-17T13:48:00",
"upload_time_iso_8601": "2023-07-17T13:48:00.920980Z",
"url": "https://files.pythonhosted.org/packages/32/6d/c2ffcd4ff79196e1f23416fe0ae9975dbad31435b98e739274031a70b699/envappconfig-2023.198.827.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-17 13:48:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "spectriclabs",
"github_project": "envappconfig",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "envappconfig"
}
JSON
