aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md85
1 files changed, 60 insertions, 25 deletions
diff --git a/README.md b/README.md
index 83a5e76..708ad83 100644
--- a/README.md
+++ b/README.md
@@ -5,26 +5,24 @@
[![Python 3.8.0|](https://img.shields.io/badge/python-3.8.0-blue.svg)](https://www.python.org/downloads/release/python-380/)
[![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/)
+[![Build Status](https://travis-ci.com/eugenetriguba/config_file.svg?branch=master)](https://travis-ci.com/eugenetriguba/config_file)
+[![Codecov](https://codecov.io/gh/eugenetriguba/config_file/graph/badge.svg)](https://codecov.io/gh/eugenetriguba/config_file)
> This python package is currently a work in progress and is in a pre-alpha phase. The API is liable to break until v1.
Config File allows you to use the same simple API for manipulating INI, JSON,
YAML, and TOML configuration files. For the time being, it only supports INI.
-## Motivation
-
-With applications I was building, I found myself frequently having to use some sort of configuration folder with an object that modeled the configuration file. I did this to help more easily manipulate my configuration. However, I found myself needing this sort of thing for several different applications and would end up rewriting something similar. So ended up deciding to create a package out of it so I could focus more on the application I was building instead.
-
-## Why not just use configparser, ConfigObj, etc.
-
-I wanted something a bit cleaner to use than configparser. The ini parser uses configparser under the hood, but it provides some niceties such as automatically parsing configuration values into their native types when you retrieve them. However, I also wanted something more flexible, and ini files aren't the only common configuration format. That is why Config File uses an adapter pattern to swap in and out the right parser for various file types you give it. This allows you to use the same API for all of your configuration needs.
-
## Installation
```bash
$ pip install config_file
```
-## Examples
+## Example
+
+The `config_file` package exposes `ConfigFile`, `ParsingError`, and `BaseParser` to the public API.
+
+### Sample Configuration File
`config.ini`
```ini
@@ -35,33 +33,36 @@ today_index = 0
quarter_hours_passed = 0.25
```
-`example.py`
+### Create a ConfigFile
```python
from config_file import ConfigFile
config = ConfigFile("~/.config/test/config.ini")
+```
-# Output your config file as a string
+### Output your config file as a string
+```python
config.stringify()
>>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 0\nquarter_hours_passed = 0.25\n\n'
+```
-# Retrieve values with a section.key format
-config.get("calendar.today")
->>> 'monday'
-
-# Values from the config file are automatically parsed
-config.get("calendar.start_week_on_sunday")
->>> False
-
+### Retrieve values or sections
+A section.key format is used for retrieving and setting values.
+```python
# Values from the config file are automatically parsed
config.get("calendar.start_week_on_sunday")
>>> False
# Unless you don't want them to be parsed
-config.get("calendar.today_index", parse_type=False)
->>> '0'
+config.get("calendar.start_week_on_sunday", parse_type=False)
+>>> 'false'
-# The dot syntax is also used to set values. True is returned on success.
+config.get("calendar")
+>>> {'today': 'monday', 'start_week_on_sunday': False, 'today_index': 0, 'quarter_hours_passed': 0.25}
+```
+
+### Set values
+```python
config.set("calendar.today_index", 20)
>>> True
config.stringify()
@@ -72,24 +73,58 @@ config.set("week.tuesday_index", 2)
>>> True
config.stringify()
>>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n[week]\ntuesday_index = 2\n\n'
+```
-# Delete can delete an entire section or just a key/value pair.
+### Delete sections or key/value pairs.
+```python
config.delete('week')
>>> True
config.stringify()
>>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'
-# Delete can delete an entire section or just a key/value pair.
config.delete('calendar.today')
>>> True
config.stringify()
>>> '[calendar]\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'
+```
+
-# You can also just check if the file has a particular section or key.
+### Check whether you have a particular section or key
+```python
config.has('calendar')
>>> True
+
config.has('week')
>>> False
+
config.has('calendar.start_week_on_sunday')
>>> True
```
+
+### Save when you're done
+The contents are only written back out when you call `save()`.
+```python
+config.save()
+>>> True
+```
+
+### Reset the file back to its original
+
+The current configuration file would be deleted and replaced by a copy of the original.
+By default, since our passed in config file was at path `~/.config/test/config.ini`, `reset()`
+will look for `~/.config/test/config.original.ini`.
+
+```python
+config.reset()
+>>> True
+
+# But you can also specify the original config file explicitly.
+config.reset(original_file_path="~/some_other_directory/this_is_actually_the_original.ini")
+>>> True
+```
+
+## Using your own parser
+
+> This feature is a work in-progress and has not been tested yet.
+
+You can still use config file, even if you don't use one of our supported configuration formats. The `ConfigFile` object swaps in the parser it needs based on the file format. However, the constructor takes in an optional `parser` argument that you can use to supply your own custom parser. The only requirement is that the parser must be a concrete implementation of `BaseParser`.