aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorEugene Triguba <eugenetriguba@gmail.com>2020-08-01 08:57:17 -0500
committerEugene Triguba <eugenetriguba@gmail.com>2020-08-01 08:57:17 -0500
commitba655e72f74bc488cb8e5988766fef8f5dd45bcc (patch)
treef967eb203b0a6e389022c5383a7eb23414059051 /README.md
parentAdd name to security workflow (diff)
parentFix wording of docstring in missing dependency error (diff)
downloadconfig-file-ba655e72f74bc488cb8e5988766fef8f5dd45bcc.zip
Merge branch 'dev' into dev
Diffstat (limited to 'README.md')
-rw-r--r--README.md251
1 files changed, 208 insertions, 43 deletions
diff --git a/README.md b/README.md
index c0fc8a3..3900971 100644
--- a/README.md
+++ b/README.md
@@ -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