From b3fb6aae1201faca1238b3c79e5e95ba57282bf1 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 20 Jun 2020 15:35:05 -0500 Subject: Add more type hints to ConfigFile and lint all files --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b7ef6ef..223f3e7 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ ## About Config File -The Config File project is designed to allow you to easily manipulate your +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. For the time being, it only supports INI and JSON. @@ -49,7 +49,7 @@ from config_file import ConfigFile ORIGINAL_CONFIG_PATH = Path("~/some-project/some-other-config-file.ini") CONFIG_PATH = Path("~/some-project/config.ini") -# Our path can be a string or a Path object. +# 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) @@ -66,7 +66,7 @@ print(config.get("section")) 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 +# 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 @@ -96,7 +96,7 @@ print(config.restore_original(original_file_path=ORIGINAL_CONFIG_PATH)) >>> True # Otherwise, a config.original.ini file will automatically be looked for in the -# current directory (because our configuration file we passed in was +# current directory (because our configuration file we passed in was # named config.ini). print(config.restore_original()) >>> True -- cgit v1.2.3 From ee78049f1e33bcb9894f43d51e44b079edfab91f Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 20 Jun 2020 16:32:23 -0500 Subject: Add types to base parser and update build badge --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 223f3e7..1af08fc 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![Version](https://img.shields.io/pypi/v/config-file)](https://pypi.org/project/config-file/) [![Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://pypi.org/project/black/) [![Documentation Status](https://readthedocs.org/projects/config-file/badge/?version=latest)](https://config-file.readthedocs.io/en/latest/?badge=latest) -[![Build Status](https://travis-ci.com/eugenetriguba/config-file.svg?branch=master)](https://travis-ci.com/eugenetriguba/config-file) +[![Build Status](https://github.com/eugenetriguba/config-file/workflows/Python%20package%20CI/badge.svg?branch=master)](https://github.com/eugenetriguba/config-file/actions/) [![Codecov](https://codecov.io/gh/eugenetriguba/config-file/graph/badge.svg)](https://codecov.io/gh/eugenetriguba/config-file) ## About Config File @@ -102,7 +102,7 @@ print(config.restore_original()) >>> True ``` -## Documentation +## Documentation Full documentation and API reference is available at https://config-file.readthedocs.io -- cgit v1.2.3 From 50403a631179398f7c60c7622029d0bf2d2b4cc3 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 20 Jun 2020 16:33:55 -0500 Subject: Use lowercase action name --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 1af08fc..c7eebda 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![Version](https://img.shields.io/pypi/v/config-file)](https://pypi.org/project/config-file/) [![Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://pypi.org/project/black/) [![Documentation Status](https://readthedocs.org/projects/config-file/badge/?version=latest)](https://config-file.readthedocs.io/en/latest/?badge=latest) -[![Build Status](https://github.com/eugenetriguba/config-file/workflows/Python%20package%20CI/badge.svg?branch=master)](https://github.com/eugenetriguba/config-file/actions/) +[![Build Status](https://github.com/eugenetriguba/config-file/workflows/python%20package%20CI/badge.svg?branch=master)](https://github.com/eugenetriguba/config-file/actions/) [![Codecov](https://codecov.io/gh/eugenetriguba/config-file/graph/badge.svg)](https://codecov.io/gh/eugenetriguba/config-file) ## About Config File -- cgit v1.2.3 From 7568a94560b2381f7d7ba77f2c64473cf6842110 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sun, 19 Jul 2020 13:15:24 -0500 Subject: Add more info on installation with poetry and zsh --- README.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index c7eebda..3a54880 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ JSON, YAML, or TOML. For the time being, it only supports INI and JSON. ## Installation -Config File is available to download through PyPI using pip. +Config File is available to download through PyPI. ```bash $ pip install config-file @@ -29,6 +29,24 @@ If you want to manipulate YAML and TOML, you'll want to download the extras as w $ pip install config-file[yaml, toml] ``` +You can also use Poetry. + +```bash +$ poetry install config-file -E yaml -E toml +``` + +If you use ZSH as your shell, brackets (`[]`) are used for glob matching +and you'll have to put the package name in quotes if you're downloading +the extras too. + +```zsh +% pip install 'config-file[yaml, toml]' + +OR + +% noglob pip install config-file[yaml, toml] +``` + ## Usage Say you have an INI file you want to manipulate. It must have an .ini -- cgit v1.2.3 From 4846966c6a1d337fc3a7958514ca23d06a9da7e0 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sun, 19 Jul 2020 13:19:29 -0500 Subject: Tweak zsh installation info --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 3a54880..bb9a617 100644 --- a/README.md +++ b/README.md @@ -36,14 +36,14 @@ $ poetry install config-file -E yaml -E toml ``` If you use ZSH as your shell, brackets (`[]`) are used for glob matching -and you'll have to put the package name in quotes if you're downloading -the extras too. +so you can work around that if installing extras in one of the following +ways. ```zsh % pip install 'config-file[yaml, toml]' +``` -OR - +```zsh % noglob pip install config-file[yaml, toml] ``` -- cgit v1.2.3 From c476c1ed7065910fddc15ccfe67442c81f777bbf Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sun, 19 Jul 2020 14:59:05 -0500 Subject: Remove zsh info and add extras sub header --- README.md | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index bb9a617..6b3b781 100644 --- a/README.md +++ b/README.md @@ -23,30 +23,20 @@ Config File is available to download through PyPI. $ 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. +You can also use [Poetry](https://python-poetry.org). ```bash $ poetry install config-file -E yaml -E toml ``` -If you use ZSH as your shell, brackets (`[]`) are used for glob matching -so you can work around that if installing extras in one of the following -ways. - -```zsh -% pip install 'config-file[yaml, toml]' -``` - -```zsh -% noglob pip install config-file[yaml, toml] -``` - ## Usage Say you have an INI file you want to manipulate. It must have an .ini -- cgit v1.2.3 From d0acdbfc11ac7ea9efdb9158da62d426421058d8 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sun, 19 Jul 2020 20:47:02 -0500 Subject: Update example with dev changes --- README.md | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 6b3b781..c0fc8a3 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,8 @@ ## 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. For the time being, it only supports INI and JSON. +configuration files with the same simple API whether they are in INI, JSON, +YAML, or TOML. ## Installation @@ -52,6 +52,8 @@ third_key = true Then we can manipulate it as follows. ```python +from pathlib import Path + from config_file import ConfigFile ORIGINAL_CONFIG_PATH = Path("~/some-project/some-other-config-file.ini") @@ -68,7 +70,7 @@ print(config.get("section.first_key", return_type=int)) >>> 5 # This holds true when we retrieve entire sections as well. However, we can -# also recursively parse the entire section is desired. +# 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)) @@ -80,34 +82,28 @@ print(config.get("section.unknown", default=False)) >>> False # Setting, deleting, and checking if a key exists is just as easy. -print(config.set("section.first_key", 10)) ->>> True - -print(config.delete("section.third_key")) ->>> True +config.set("section.first_key", 10) +config.delete("section.third_key") print(config.has("section.third_key")) >>> False # We can also convert the entire configuration file to a string. print(config.stringify()) ->>> '[section]\nfirst_key = 5\nsecond_key = blah\nthird_key = true\n\n' +>>> '[section]\nfirst_key = 10\nsecond_key = blah\n\n' -# Lastly, we need to make sure we save our changes. Nothing is written -# out until we do so. -print(config.save()) ->>> True +# Lastly, we need to make sure we save our changes. +# Nothing is written out until we do so. +config.save() # 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. -print(config.restore_original(original_file_path=ORIGINAL_CONFIG_PATH)) ->>> True +config.restore_original(original_file_path=ORIGINAL_CONFIG_PATH) # 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). -print(config.restore_original()) ->>> True +config.restore_original() ``` ## Documentation -- cgit v1.2.3 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 From 64538efa75db78983db4b764a2731a4154fdcad6 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 1 Aug 2020 11:50:52 -0500 Subject: Remove origin --- README.md | 6 ------ 1 file changed, 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 3900971..2b51ac0 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,6 @@ 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. -- cgit v1.2.3 From 3a6a03805abeb8aa5ab080f79a94d65d02421c7f Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 6 Aug 2020 09:46:04 -0500 Subject: Update README example to remove MissingKeyError --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 2b51ac0..96a27af 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,8 @@ 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. +To use the package, we import in the `ConfigFile` object. This object +is the only thing considered to be part of the public API. 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 @@ -132,11 +133,9 @@ 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: +except KeyError: important_value = 42 ``` -- cgit v1.2.3 From c7a873ba71d1103b66c1cdf93451cb03ddf19832 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Fri, 7 Aug 2020 08:58:26 -0500 Subject: Add information on indexing into ConfigFile --- README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 96a27af..c1d4e9a 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,14 @@ config.get('section') >>> {'num_key': '5', 'str_key': 'blah', 'bool_key': 'true', 'list_key': '[1, 2]'} ``` +Furthermore, you can also index into the `ConfigFile` object +to retrieve keys if that is preferred. + +```python +config['section']['num_key'] +>>> '5' +``` + #### Coercing the return types However, some of these keys are obviously not strings natively. @@ -181,6 +189,20 @@ 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. +Lastly, we can set values using an array notation as well. The underlying +content is all manipulated as a dictionary for every file type. If we wanted +to create a new section, we'd simply set it to be an empty dictionary. + +```python +config['new_section'] = {} +``` + +Which would result to be an empty section: + +```ini +[new_section] +``` + ### Using `delete()` `delete()` allows us to delete entire sections or specific keys. @@ -196,6 +218,12 @@ However, we can also just delete a single key. config.delete('section.num_key') ``` +We can also use the array notation here as well. + +```python +del config['section']['num_key'] +``` + ### Using `has()` `has()` allows us to check whether a given key exists in our file. There -- cgit v1.2.3 From 4f44d7a2063c8dfdffe9d19f2d5bb6979c718bd1 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Fri, 7 Aug 2020 19:30:37 -0500 Subject: Remove docs/ and update readme with more info --- README.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index c1d4e9a..86c0f3d 100644 --- a/README.md +++ b/README.md @@ -37,11 +37,17 @@ You can also use [Poetry](https://python-poetry.org). $ poetry install config-file -E yaml -E toml ``` -## Usage Overview +## Usage For this overview, let's say you have the following `ini` file you want to manipulate. +Do note, however, that the `ini` format is the oddest format that +`ConfigFile` supports in that it has no formal specification and is +not type aware. When retrieving items from the file, it will return +them as strings by default. Others are more type aware and do not +require as much type coercion. + ```ini [section] num_key = 5 @@ -284,17 +290,26 @@ 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` +is named differently than what the default expects, we can utilize the `original_path` keyword argument. ```python -config.restore_original(original_file_path="~/some-project/original-configs/config.ini") +config.restore_original(original_path="~/some-project/original-configs/config.ini") ``` -## Documentation +## Format Versions Supported + +| Format | Specification version supported | +| ------------- | ------------- | +| INI | No official specification. | +| JSON | [RFC 7159](https://tools.ietf.org/html/rfc7159.html) | +| YAML | [v1.2](https://yaml.org/spec/1.2/spec.html) | +| TOML | [v1.0.0-rc.1](https://github.com/toml-lang/toml/releases/tag/v1.0.0-rc.1) | -Full documentation and API reference is available at https://config-file.readthedocs.io +For `ini` and `json`, Python's standard library modules are used. +Regarding `ini`, there is no formal specification so the syntax that configparser +supports is what is supported here. ## License -- cgit v1.2.3 From e1475e2b00bdc62599b6947914e8b389a0307f19 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Fri, 7 Aug 2020 19:38:16 -0500 Subject: Add info on setting with ini --- README.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 86c0f3d..8cbf360 100644 --- a/README.md +++ b/README.md @@ -192,8 +192,20 @@ 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. +different in it's structure and in what it supports. Mostly though, `ini` +is just the odd one. + +If we try the following in `ini`, which does not support subsections or +nested keys, we simply get a single section. + +```python +config.set("section.sub_section.sub_sub_section.key", 5) +``` + +```ini +[section.sub_section.sub_sub_section] +key = 5 +``` Lastly, we can set values using an array notation as well. The underlying content is all manipulated as a dictionary for every file type. If we wanted -- cgit v1.2.3