From f90048609b7a7f9182b8a9bfe73eaef5f096f8ee Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Wed, 29 Jul 2020 23:52:12 -0500 Subject: Revise `get` section for readme docs --- README.md | 139 +++++++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 111 insertions(+), 28 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index c0fc8a3..e0e3fe0 100644 --- a/README.md +++ b/README.md @@ -37,49 +37,132 @@ 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 recognzied 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. + +#### 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 -# 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) +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. -# 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)) +```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-existant 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 already know what you want to be the fallback case +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. -# 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 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 # Setting, deleting, and checking if a key exists is just as easy. config.set("section.first_key", 10) -- cgit v1.2.3 From 5c1164535aa8eafca4725549efa63719836cd6bd Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 30 Jul 2020 00:04:39 -0500 Subject: Add package creation rationale --- README.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index e0e3fe0..414d69f 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 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. @@ -98,8 +104,8 @@ config.get('section') #### 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 +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. @@ -124,7 +130,7 @@ config.get('section.num_key', parse_types=True) >>> 5 ``` -#### Handling non-existant keys +#### 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. @@ -140,7 +146,7 @@ except MissingKeyError: important_value = 42 ``` -However, the `get` method comes with a `default` keyword argument that we +However, the `get` method comes with a `default` keyword argument that we can utilze for this purpose. ```python @@ -148,8 +154,7 @@ config.get('section.i_do_not_exist', default=42) >>> 42 ``` -This can be handy if you already know what you want to be the fallback case -if you have a default for a particular configuration value. +This can be handy if you have a default for a particular configuration value. ### Using `set()` -- cgit v1.2.3 From 82bfa4299f51a47f7ebc629f93fffc1b4eaf9d84 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 30 Jul 2020 00:08:21 -0500 Subject: Add rest of sections (without content) to readme --- README.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 414d69f..45c0dd7 100644 --- a/README.md +++ b/README.md @@ -167,22 +167,19 @@ config.set('section.num_key', 6) The method does not return anything, since there is nothing useful to return. +### 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") +### Using `has()` -print(config.has("section.third_key")) ->>> False -# We can also convert the entire configuration file to a string. -print(config.stringify()) ->>> '[section]\nfirst_key = 10\nsecond_key = blah\n\n' +### Using `stringify()` -# Lastly, we need to make sure we save our changes. -# Nothing is written out until we do so. -config.save() + +### Using `save()` + + +### Using `restore_original()` # 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. @@ -192,7 +189,7 @@ config.restore_original(original_file_path=ORIGINAL_CONFIG_PATH) # current directory (because our configuration file we passed in was # named config.ini). config.restore_original() -``` + ## Documentation -- cgit v1.2.3 From b84d8c1562ec362f30c6868ce5d52c515456bc7c Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 30 Jul 2020 00:09:08 -0500 Subject: Update code to be inside code block --- README.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 45c0dd7..04d4090 100644 --- a/README.md +++ b/README.md @@ -181,6 +181,7 @@ useful to return. ### Using `restore_original()` +```python # 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) @@ -189,6 +190,7 @@ config.restore_original(original_file_path=ORIGINAL_CONFIG_PATH) # current directory (because our configuration file we passed in was # named config.ini). config.restore_original() +``` ## Documentation -- cgit v1.2.3 From 633facbbd9db0be86be88ffc95996038a68db4fa Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 30 Jul 2020 00:20:20 -0500 Subject: Add `has`, `delete`, and `set` usage --- README.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 04d4090..f7067e4 100644 --- a/README.md +++ b/README.md @@ -165,13 +165,63 @@ config.set('section.num_key', 6) ``` The method does not return anything, since there is nothing -useful to return. +useful to return. If someone goes wrong where it is unable to set +the value, an exception will be raised instead. + +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. 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 `stringify()` -- cgit v1.2.3 From 5dd82bef4cb56bc788f94688e6daaf825c89d313 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 30 Jul 2020 09:38:07 -0500 Subject: Finish `save()`, `stringify()`, and `restore_original()` docs in readme --- README.md | 46 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 35 insertions(+), 11 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index f7067e4..312adfd 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,8 @@ 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. +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. @@ -182,8 +183,9 @@ 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. See the [full documentation](#Documentation) for -more information there. +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()` @@ -223,25 +225,47 @@ 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. -### Using `save()` +```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()` -```python -# 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) +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()`. -# 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). +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 -- cgit v1.2.3 From fbbb1636a7998cad6ec4e060e833c7e8e2efd2be Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 30 Jul 2020 09:40:23 -0500 Subject: Fix strike throughed paths in `restore_original()` --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 312adfd..511e2a0 100644 --- a/README.md +++ b/README.md @@ -252,8 +252,8 @@ config.stringify() 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". +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() -- cgit v1.2.3 From 8c10767e474dde5617b63abdddf5f3c903db6216 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 30 Jul 2020 09:46:38 -0500 Subject: Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 511e2a0..6d2e276 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ 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 +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 -- cgit v1.2.3 From 5f00e1b77214b542fddbac61619d4d8afeeb81d8 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 30 Jul 2020 12:53:14 -0500 Subject: Fix typos and reword some paragraphs --- README.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 6d2e276..3900971 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ for the package to recognize it and use the correct parser for it. 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 +Any home tildes `~` in the string or `Path` are recognized and converted to the full path for us. ```python @@ -165,9 +165,10 @@ 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 +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`. +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. @@ -217,8 +218,8 @@ config.has('does_not_exist') ``` 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. +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) @@ -228,8 +229,8 @@ config.has('str_key', wild=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. +to the filesystem until we call `save()`. This is to avoid unnecessary write +calls after each operation until we actually need to save. ```python config.delete('section.list_key') @@ -238,8 +239,10 @@ config.save() ### Using `stringify()` -`stringify()` allows us to show us our internal configuration file, with -any changes we've made, as a string. +`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() @@ -252,15 +255,16 @@ config.stringify() 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`, +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 it is or it is named differently, we can -utilize the `original_file_path` keyword argument. +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") -- cgit v1.2.3