From df038f94a1efa94a2837f2a499a80b5c70db82d0 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 16 Aug 2025 12:25:08 -0400 Subject: Move usage to mkdocs --- README.md | 347 +++++---------------------------------------- config_file/config_file.py | 21 ++- docs/usage.md | 283 ++++++++++++++++++++++++++++++++++++ mkdocs.yaml | 7 +- 4 files changed, 328 insertions(+), 330 deletions(-) create mode 100644 docs/usage.md diff --git a/README.md b/README.md index 8d2e03b..45c366e 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,35 @@ -# Config File - -> Simple manipulation of ini, json, yaml, or toml files - -![Python Version](https://img.shields.io/pypi/pyversions/config-file.svg) -[![Version](https://img.shields.io/pypi/v/config-file)](https://pypi.org/project/config-file/) -[![Build Status](https://builds.sr.ht/~eugenetriguba/config-file.svg)](https://builds.sr.ht/~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. - -## Installation +

+ Config File +

+ +

+ + Simple manipulation of ini, json, yaml, or toml files + +

+ +

+ Python Version + Version + Build Status +

+ +

+ 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. +

+ +## Quick start Config File is available to download through PyPI. @@ -28,304 +45,10 @@ If you want to manipulate YAML and TOML, you'll want to download the extras as w $ pip install config-file[yaml, toml] ``` -## 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 -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. 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 -to the full path for us. - -```python -from config_file import ConfigFile - -config = ConfigFile("~/some-project/config.ini") -``` - -#### Handling ConfigFile Initialization Errors - -```python -from config_file import ConfigFile, ParsingError - -try: - config = ConfigFile("~/some-file.ini") -except ParsingError: - print("could not parse the file") -except ValueError: - print("extension that isn't supported was used or is a directory") -except FileNotFoundError: - print("file does not exist") -``` - -### 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]'} -``` - -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. -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 -try: - important_value = config.get('section.i_do_not_exist') -except KeyError: - 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. 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 -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. - -```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') -``` - -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 -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()` - -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. - -```python -config.delete('section.list_key') -config.save() -``` - -### Stringifying our ConfigFile - -To retrieve the file as a string, with any changes we've made, we can use the -built-in `str()` method on the ConfigFile. This 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 -str(config) ->>> '[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` 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_path` -keyword argument. - -```python -config.restore_original(original_path="~/some-project/original-configs/config.ini") -``` - - -## 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) | - -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. +For detailed documentation, visit +[config-file.readthedocs.io](https://config-file.readthedocs.io/) ## License The [MIT](https://github.com/eugenetriguba/config-file/blob/main/LICENSE) License. + diff --git a/config_file/config_file.py b/config_file/config_file.py index b5083ff..eba2c11 100644 --- a/config_file/config_file.py +++ b/config_file/config_file.py @@ -1,6 +1,6 @@ from pathlib import Path from shutil import copyfile -from typing import Any, Union +from typing import Any, Callable, Union from config_file.config_file_path import ConfigFilePath from config_file.parsers.parse_value import parse_value @@ -9,13 +9,11 @@ from config_file.utils import Default class ConfigFile: def __init__(self, file_path: Union[str, Path]) -> None: - """ - Stores the config file path and expands it if needed, reads in - the file contents, and determines what parser should be used for - the given file. + """Stores the config file path and reads the file contents. Args: - file_path: The path to your configuration file. + file_path: Path to the configuration file. Supports tilde + (~) expansion for home directory. Raises: ValueError: If the specified file path does not have an extension @@ -56,7 +54,7 @@ class ConfigFile: self, key: str, parse_types: bool = False, - return_type: Any = None, + return_type: Union[Callable[[Any], Any], None] = None, default: Any = Default(None), ) -> Any: """ @@ -66,13 +64,12 @@ class ConfigFile: key: The key to retrieve. parse_types: Automatically parse ints, floats, booleans, dicts, and lists. This recursively parses all types in whatever you're - retrieving, not just a single type. - - e.g. If you are retrieving a section, all values in that - section will be parsed. - + retrieving, not just a single type. For example, if you are + retrieving a section, all values in that section will be + parsed. return_type: The type to coerce the return value to. default: The default value to return if the value of the key is empty. + If not specified, a KeyError will be raised if the key does not exist. Returns: The value of the key. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..8d6b8b4 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,283 @@ +# 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 +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. 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 +to the full path for us. + +```python +from config_file import ConfigFile + +config = ConfigFile("~/some-project/config.ini") +``` + +### Handling ConfigFile Initialization Errors + +```python +from config_file import ConfigFile, ParsingError + +try: + config = ConfigFile("~/some-file.ini") +except ParsingError: + print("could not parse the file") +except ValueError: + print("extension that isn't supported was used or is a directory") +except FileNotFoundError: + print("file does not exist") +``` + +## 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]'} +``` + +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. +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 +try: + important_value = config.get('section.i_do_not_exist') +except KeyError: + 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. 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 +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. + +```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') +``` + +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 +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()` + +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. + +```python +config.delete('section.list_key') +config.save() +``` + +## Stringifying our ConfigFile + +To retrieve the file as a string, with any changes we've made, we can use the +built-in `str()` method on the ConfigFile. This 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 +str(config) +>>> '[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` 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_path` +keyword argument. + +```python +config.restore_original(original_path="~/some-project/original-configs/config.ini") +``` diff --git a/mkdocs.yaml b/mkdocs.yaml index 8248813..3285070 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -23,11 +23,6 @@ nav: - Home: index.md - Getting Started: - Installation: installation.md - # - Quick Start: quick-start.md - # - User Guide: - # - Basic Usage: usage/basic-usage.md - # - Advanced Features: usage/advanced-features.md - # - Error Handling: usage/error-handling.md + - Usage: usage.md - API Reference: api-reference.md - Supported Formats: supported-formats.md - # - License: license.md -- cgit v1.2.3