Skip to main content

A simple module for handling configurations and config files

Project description

# ConfigReader

[![Travis-CI](https://img.shields.io/travis/giantas/pyconfigreader.svg?maxAge=2592001)](https://travis-ci.org/giantas/pyconfigreader)
[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/5f3132cafe78478dbdeb081b53d3661d)](https://www.codacy.com/app/giantas/pyconfigreader?utm_source=github.com&utm_medium=referral&utm_content=giantas/pyconfigreader&utm_campaign=Badge_Coverage)
[![Issues](https://img.shields.io/github/issues-raw/giantas/pyconfigreader/website.svg)](https://github.com/giantas/pyconfigreader/issues)

A configuration file handler for the most basic stuff in ini files that will get you up and running in no time.

`ConfigReader` uses Python's ConfigParser to parse config files.

***PS***: This is just to get you working on other stuff and not focus on config files. If you need advanced features head to [Python's ConfigParser](https://docs.python.org/3/library/configparser.html).

# Usage

## Installation
```
$ pip install pyconfigreader
```

## Setting Values

`ConfigReader` creates a default `main` section in which key-value pairs are inserted if no section is specified.

```python
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
config.set('version', '2') # Saved to section `main`
config.set('Key', 'Value', section='Section') # Creates a section `Section` on-the-fly
config.set('name', 'main')
```

By default, changes are not immediately written to the file on disk but are kept in memory.
`commit=True` writes the changes to the file on disk.

```python
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
config.set('okay', 'True', commit=True)
```

## Getting values

Getting values only requires specifying the key. If the key does not exist then None is returned. No exception is raised.

```python
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
name = config.get('name')
okay = config.get('okay')
section = config.get('Key', section='Section') # Get from the section `Section`

agency = config.get('agency') # agency is None, it doesn't exist

print(config.sections) # Get a list of sections

key, value, section = config.search('config') # Search for the parameters of a value. Returns a tuple

help(config)
config.close() # Don't forget to close the file object
```

Sometimes, if a key is not available a return value may be added
```python
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
name = config.get('country', default='Kenya') # Returns Kenya since key was not available in config file
config.close()
```

The return value, by default, is not saved to file but this can be enabled by setting default_commit=True
```python
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
name = config.get('name', default='Kenya', default_commit=True)
config.close()
```

Any call to `commit` saves all the in-memory changes to the file on disk.

## Options

Options can be remove permanently

```python
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
config.remove_option('reader') # the reader option is always set by default
# or config.remove_key('reader')
config.set('name', 'first', section='Details')
config.remove_option('name', section='Details')
config.close()
```

## Sections
Sections are created when keys and values are added to them.

```python
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
config.set('name', 'first', section='Details') # Save key `name` with value `first` in section `Details`
config.close()
```

Sections can be removed explicitly.
```python
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
config.set('name', 'first', section='Details') # Creates section `Details`
config.remove_section('Details') # Removes section `Details` plus all the keys and values
config.close()
```

Section items can be acquired as dictionary values
```python
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
config.set('name', 'first', section='Details')

config.get_items('Details')
# OrderedDict([('name', 'first')])
config.close()
```

## Environment Variables
Configuration values can be save to the environment (`os.environ`)

```python
import os
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
config.set('name', 'first', section='Details')
config.to_env()
os.environ['DETAILS_NAME']
# first
os.environ['MAIN_READER']
# configreader
config.close()
```

The environment keys are formed from the section name and the key name.

## Saving

Changes are not written to disk unless `commit` is set to True.

Another alternative is calling `to_file`

```python
from pyconfigreader import ConfigReader
config = ConfigReader(filename='config.ini')
config.set('name', 'first', section='Details')
config.to_file()
config.close()
```

As a context, the changes are saved when the object is closed.

```python
from pyconfigreader import ConfigReader
with ConfigReader(filename='config.ini') as config:
config.set('name', 'first', section='Details')
```

The contents of the config file can also be dumped to a JSON file.
```python
from pyconfigreader import ConfigReader
reader = ConfigReader()
reader.set('name', 'first', section='Details')
with open('config.json', 'w') as f:
reader.to_json(f)

reader.close()
```

A lot more on `help(config)`

# More
Docs to come :)

# License
Distributed under [MIT](LICENSE)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyconfigreader-0.2.2.tar.gz (7.6 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page