1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
|
# Config File
> Modify configuration files of various formats with the same simple API

[](https://pypi.org/project/config-file/)
[](https://pypi.org/project/black/)
[](https://config-file.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/eugenetriguba/config-file/actions/)
[](https://codecov.io/gh/eugenetriguba/config-file)
## About Config File
The Config File project is designed to allow you to easily manipulate your
configuration files with the same simple API whether they are in INI, JSON,
YAML, or TOML.
The code for this package grew origically out of developing command
line tools in Python. I had felt like I was writing similar code over and over
again to abstract away Python's configparser so it was a little nicer to work with
for my uses. Therefore, I had ended up making a package out of it and adding a lot more
niceties, polish, and flexibility to it so others may find it useful as well.
## Installation
Config File is available to download through PyPI.
```bash
$ pip install config-file
```
### Installing Extras
If you want to manipulate YAML and TOML, you'll want to download the extras as well.
```bash
$ pip install config-file[yaml, toml]
```
You can also use [Poetry](https://python-poetry.org).
```bash
$ poetry install config-file -E yaml -E toml
```
## Usage Overview
For this overview, let's say you have the following `ini` file
you want to manipulate.
```ini
[section]
num_key = 5
str_key = blah
bool_key = true
list_key = [1, 2]
[second_section]
dict_key = { "another_num": 5 }
```
It must have a `.ini` extension in order
for the package to recognize it and use the correct parser for it.
### Setting up ConfigFile
To use the package, we import in the `ConfigFile` object.
We can set it up by giving it a string or `pathlib.Path` as the argument.
Any home tildes `~` in the string or `Path` are recognzied and converted
to the full path for us.
```python
from config_file import ConfigFile
config = ConfigFile("~/some-project/config.ini")
```
### Using `get()`
A recurring pattern you'll see here is that all methods that
need to specify something inside your configuration file will
do so using a dot syntax.
#### Retrieving keys and sections
So to retrieve our `num_key`, we'd specify the heading and the
key separated by a dot. All values will then be retrieved as
strings.
```python
config.get('section.num_key')
>>> '5'
```
While we can retrieves keys, we can also retrieve the entire
section, which will be returned back to us as a dictionary.
```python
config.get('section')
>>> {'num_key': '5', 'str_key': 'blah', 'bool_key': 'true', 'list_key': '[1, 2]'}
```
#### Coercing the return types
However, some of these keys are obviously not strings natively.
If we are retrieving a particular value of a key, we may want to
coerce it right away without doing clunky type conversions after
each time we retrieve a value. To do this, we can utilize the
`return_type` keyword argument.
```python
config.get('section.num_key', return_type=int)
>>> 5
```
Sometimes we don't have structures quite that simple though. What
if we wanted all the values in `section` coerced? For that, we can
utilize a `parse_types` keyword argument.
```python
config.get('section', parse_types=True)
>>> {'num_key': 5, 'str_key': 'blah', 'bool_key': True, 'list_key': [1, 2]}
```
It also works for regular keys.
```python
config.get('section.num_key', parse_types=True)
>>> 5
```
#### Handling non-existent keys
Sometimes we want to retrieve a key but are unsure of if it will exist.
There are two ways we could handle that.
The first is the one we're used to seeing: catch the error.
```python
from config_file import MissingKeyError
try:
important_value = config.get('section.i_do_not_exist')
except MissingKeyError:
important_value = 42
```
However, the `get` method comes with a `default` keyword argument that we
can utilze for this purpose.
```python
config.get('section.i_do_not_exist', default=42)
>>> 42
```
This can be handy if you have a default for a particular configuration value.
### Using `set()`
We can use `set()` to set a existing key's value.
```python
config.set('section.num_key', 6)
```
The method does not return anything, since there is nothing
useful to return. If someone goes wrong where it is unable to set
the value, an exception will be raised instead. This is the case
for most methods on `ConfigFile`.
With `set()`, we can also create and set keys that don't exist yet.
```python
config.set('new_section.new_key', 'New key value!')
```
Would then result in the following section being added to our original file:
```ini
[new_section]
new_key = New key value!
```
The exact behavior of how these new keys or sections are added are a bit
dependent on the file format we're using, since every format is a little
different in it's structure and in what it supports. See the
[full documentation](#Documentation) for more information there.
### Using `delete()`
`delete()` allows us to delete entire sections or specific keys.
```python
config.delete('section')
```
Would result in the entire section being removed from our configuration file.
However, we can also just delete a single key.
```python
config.delete('section.num_key')
```
### Using `has()`
`has()` allows us to check whether a given key exists in our file. There
are two ways to use `has()`.
The first is using the dot syntax.
```python
config.has('section.str_key')
>>> True
config.has('does_not_exist')
>>> False
```
This will check if our specific key or section exists. However, we can
also just check in general if a given key exists anywhere in our file
with the `wild` keyword argument.
```python
config.has('str_key', wild=True)
>>> True
```
### Using `save()`
For any changes we make to our configuration file, they are not written out
to the file on our filesystem until we call `save()`. This is to avoid
unnecessary write calls to our filesystem until we need to.
```python
config.delete('section.list_key')
config.save()
```
### Using `stringify()`
`stringify()` allows us to show us our internal configuration file, with
any changes we've made, as a string.
```python
config.stringify()
>>> '[section]\nnum_key = 5\nstr_key = blah\nbool_key = true\nlist_key = [1, 2]\n\n[second_section]\ndict_key = { "another_num": 5 }\n\n'
```
### Using `restore_original()`
If we have a initial configuration file state, we could keep a copy of that
initial file and restore back to it whenever needed using `restore_original()`.
By default, if we created our `ConfigFile` with the path of `~/some-project/config.ini`,
`restore_original()` will look for our original file at `~/some-project/config.original.ini`.
```python
config.restore_original()
```
However, if we have a specific path elsewhere that it is or it is named differently, we can
utilize the `original_file_path` keyword argument.
```python
config.restore_original(original_file_path="~/some-project/original-configs/config.ini")
```
## Documentation
Full documentation and API reference is available at https://config-file.readthedocs.io
## License
The [MIT](https://github.com/eugenetriguba/config-file/blob/master/LICENSE) License.
|