README.md
1# envs
2Easy access of environment variables from Python with support for booleans, strings, lists, tuples, integers, floats, and dicts.
3
4## Use Case
5
6If you need environment variables for your settings but need an easy way of using Python objects instead of just strings. For example, if you need a list of strings.
7
8## Features
9
10- CLI to convert settings
11- CLI to list and check environment variables
12- Use strings, lists, tuples, integers, floats or dicts. **IMPORTANT:** When setting the variables in your environmenet (ex. in .env file) wrap them in single or double quotes (ex. `"['some','list']"`)
13
14[](https://travis-ci.org/capless/envs)
15
16## Quick Start
17### Install
18#### Install without CLI Requirements
19
20```commandline
21pip install envs
22```
23#### Install with CLI Requirements
24
25```commandline
26pip install envs["cli"]
27```
28### Run Convert Settings
29
30**IMPORTANT:** Don't name this file the same as the original module (you have added the imports back yet).
31```commandline
32envs convert_settings --settings-file your.settings.module
33```
34
35### Copy and Paste the Imports and Logic Code From Original File
36
37Envs does not copy and paste your imports from your original code, so you have to do this manually.
38
39### Run List Envs
40
41This tells you what envs have default v
42```commandline
43envs list_envs --settings-file your.settings.module
44```
45## General API
46
47```python
48from envs import env
49
50env('SOMEVAR','default value for that var',var_type='string',allow_none=True)
51```
52
53### Strings
54
55**Environment Variable Example:** SECRET_KEY='adfadfadfafasf'
56```python
57>>>from envs import env
58
59>>>env('SECRET_KEY','default secret key here')
60'adfadfadfafasf'
61```
62
63### Lists
64**Environment Variable Example:** SERVER_NAMES="['coastal','inland','western']"
65```python
66>>>from envs import env
67
68>>>env('SERVER_NAMES',var_type='list')
69['coastal','inland','western']
70```
71
72### Tuples
73**Environment Variable Example:** SERVER_NAMES="('coastal','inland','western')"
74
75```python
76>>>from envs import env
77
78>>>env('SERVER_NAMES',var_type='tuple')
79('coastal','inland','western')
80```
81
82### Dicts
83**Environment Variable Example:** DATABASE="{'USER':'name','PASSWORD':'password'}"
84
85```python
86>>>from envs import env
87
88>>>env('DATABASE',var_type='dict')
89{'USER':'name','PASSWORD':'password'}
90```
91
92### Integers
93
94**Environment Variable Example:** NO_SERVERS=12
95```python
96>>>from envs import env
97
98>>>env('NO_SERVERS',var_type='integer')
9912
100```
101
102### Floats
103
104**Environment Variable Example:** INDEX_WEIGHT=0.9
105```python
106>>>from envs import env
107
108>>>env('INDEX_WEIGHT',var_type='float')
1090.9
110```
111
112### Booleans
113**Environment Variable Example:** USE_PROFILE=false
114```python
115>>>from envs import env
116
117>>>env('USE_PROFILE',var_type='boolean')
118False
119```
120
121### Decimals
122**Environment Variable Example:** HALF_SEVEN=3.5
123```python
124>>> from envs import env
125
126>>> env('HALF_SEVEN', var_type='decimal')
127Decimal('3.5')
128```
129
130## Command Line Utils
131
132**IMPORTANT:** All of the command arguments will fallback to becoming prompts if not set when calling the commands.
133
134### Convert Module (convert_module)
135
136Converts an existing settings file so it uses envs. **IMPORTANT:** This command does not copy your **import** stataements to the new module.
137
138#### Arguments
139
140- **settings-file:** - Dot notated import string for settings file
141
142```commandline
143envs convert_module --settings-file your.settings
144```
145
146### List Envs (list_envs)
147
148Shows a list of env instances set in a settings file.
149
150- **settings-file:** - Dot notated import string for settings file
151- **keep-result:** - Keep the .env_results file generated by this command (**default:** False)
152
153```commandline
154envs list_envs --settings-file your.settings --keep-result False
155```
156
157### Check Envs (check_envs)
158
159Make sure that the defined envs with no default value have a value set in the environment. This command will raise an **EnvsValueException** if there is environment variable that should be set that is not. This command is meant for use with a CI/CD tool as a way to halt the build if there isn't a value for an environment variable.
160
161- **settings-file:** - Dot notated import string for settings file
162
163```commandline
164envs check_envs --settings-file your.settings
165```
166
167### Author
168
169**Twitter:**:[@brianjinwright](https://twitter.com/brianjinwright)
170**Github:** [bjinwright](https://github.com/bjinwright)
171
){kind=link}