diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 251 |
1 files changed, 208 insertions, 43 deletions
@@ -15,6 +15,12 @@ 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 organically 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. @@ -37,75 +43,234 @@ You can also use [Poetry](https://python-poetry.org). $ poetry install config-file -E yaml -E toml ``` -## Usage +## Usage Overview -Say you have an INI file you want to manipulate. It must have an .ini -extension in order for the package to recognize it. +For this overview, let's say you have the following `ini` file +you want to manipulate. ```ini [section] -first_key = 5 -second_key = blah -third_key = true +num_key = 5 +str_key = blah +bool_key = true +list_key = [1, 2] + +[second_section] +dict_key = { "another_num": 5 } ``` -Then we can manipulate it as follows. +It must have a `.ini` extension in order +for the package to recognize it and use the correct parser for it. -```python -from pathlib import Path +### 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 recognized and converted +to the full path for us. + +```python from config_file import ConfigFile -ORIGINAL_CONFIG_PATH = Path("~/some-project/some-other-config-file.ini") -CONFIG_PATH = Path("~/some-project/config.ini") +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. -# Our path can be a string or a Path object. -# The "~" will be automatically expanded to the full path for us. -config = ConfigFile(CONFIG_PATH) +#### Retrieving keys and sections -# All the types will be retrieved as strings unless specified otherwise. -print(config.get("section.first_key")) ->>> "5" -print(config.get("section.first_key", return_type=int)) +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 +``` -# This holds true when we retrieve entire sections as well. However, we can -# also recursively parse the entire section if desired. -print(config.get("section")) ->>> {'first_key': '5', 'second_key': 'blah', 'third_key': 'true'} -print(config.get("section", parse_types=True)) ->>> {'first_key': 5, 'second_key': 'blah', 'third_key': True} +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. -# Sometimes we want to retrieve a key but don't know whether or not -# it will be set. In that case, we can set a default. -print(config.get("section.unknown", default=False)) ->>> False +```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 something 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`, such as `delete()` or `save()`, +where there would be no useful return value to utilize. + +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()` -# Setting, deleting, and checking if a key exists is just as easy. -config.set("section.first_key", 10) -config.delete("section.third_key") +`delete()` allows us to delete entire sections or specific keys. -print(config.has("section.third_key")) +```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 check in general if a given key or sections exists anywhere in our +file with the `wild` keyword argument. + +```python +config.has('str_key', wild=True) +>>> True +``` + +### Using `save()` -# We can also convert the entire configuration file to a string. -print(config.stringify()) ->>> '[section]\nfirst_key = 10\nsecond_key = blah\n\n' +For any changes we make to our configuration file, they are not written out +to the filesystem until we call `save()`. This is to avoid unnecessary write +calls after each operation until we actually need to save. -# Lastly, we need to make sure we save our changes. -# Nothing is written out until we do so. +```python +config.delete('section.list_key') config.save() +``` + +### Using `stringify()` + +`stringify()` shows us our configuration file, with any changes we've made, +as a string. `stringify()` will always show us our latest changes since it +is stringify-ing our internal representation of the configuration file, not +just the file we've read in. + +```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' +``` + -# If we have, say, a default config file and a user config file, we can easily -# restore default one. We can specify the file path to it. -config.restore_original(original_file_path=ORIGINAL_CONFIG_PATH) +### Using `restore_original()` -# Otherwise, a config.original.ini file will automatically be looked for in the -# current directory (because our configuration file we passed in was -# named config.ini). +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` object 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 this original configuration file is or it +is named differently than what the default expects, 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 |