Metadata-Version: 2.1
Name: objconf
Version: 0.3.0
Summary: Object configuration for Python projects
Home-page: https://github.com/milosta/objconf
Author: Miloslav Stanek
Author-email: milostanek@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: pyaml
Provides-Extra: tests
Requires-Dist: pytest ; extra == 'tests'
Requires-Dist: flake8 ; extra == 'tests'

# Objconf - Object Configuration for Python
[![Build Status](https://app.travis-ci.com/milosta/objconf.svg?branch=master)](https://app.travis-ci.com/milosta/objconf)
## What is objconf?
Objconf provides object configuration for Python.
It allows accessing the configuration values as attributes of a configuration object.

Unlike Python built-in configparser, all values have a type. Objconf also supports transformation
and validation of values. For example, you can tell objconf to transform relative path to absolute
and verify that the file exists.

Here is an example of what would this simple configuration object look like:

```python
import objconf, os

class AppConfig(objconf.Config):
    key_path = objconf.Attribute(
        str,
        transformer=lambda x: os.path.abspath(x),
        validator=lambda x: os.path.isfile(x))
```

Supported configuration formats:
- YAML
- JSON
- Python ini-like configparser format


## Installation
Objconf can be installed using pip:
```bash
python3 -m pip install objconf 
```

## Documentation

### Config class
`Config` is a base class for your configuration class.
Inherit from Config when defining configuration for your application.
```python
from objconf import Config, Attribute
import io

# Define the configuration
class AppConfig(Config):
    simple_string_attr = Attribute(str)
    int_attr_with_default = Attribute(int, default=5)
    bool_attr_different_key = Attribute(bool, key='actual_bool_key')
    int_over_ten = Attribute(int, validator=lambda x: x > 10)
    upper_str_attr = Attribute(str, transformer=str.upper)

# Load the configuration
yaml_config = '''
simple_string_attr: string_value
actual_bool_key: True
int_over_ten: 42
upper_str_attr: lower
'''
app_config = AppConfig.load_yaml(io.StringIO(yaml_config))

# Use the configuration
print(app_config.int_attr_with_default)  # 5
print(app_config.upper_str_attr)  # 'LOWER'
```

#### Loading configuration
The configuration is loaded during creation of the `Config` instance that defines
the configuration values for your application. The instance is created by calling the corresponding
factory method:
```
load_<format>(stream: TextIO, extra_vals: ExtraVals = ExtraVals.WARNING) -> 'Config'
```

Arguments:
- `stream`: A file-like object containing configuration values in the corresponding
  format. (Except `load_dict`, it takes a dictionary
  and  all other loading methods use it internally.)
- `extra_vals`: It specifies behavior when encountering an undefined attribute in the configuration.
  Defaults to _warning_, other options are _ignore_ and _error_.

The loading functions take also other arguments specific for the configuration format
and modifying the behaviour of underlying parser.

``load_yaml`` - Load configuration from YAML

``load_json`` - Load configuration from JSON

``load_ini`` - Load configuration from python ini-like configparser format


### Attributes
Attribute stores the value in the owning class (Config) instance.
Constructor has the following parameters:
- ``type_``: The only required parameter - type of the attribute
    (`bool`, `str`, `int`, `list`(if supported), …).
    It is a callable that converts the value to the correct type.
    Some types might not be supported; e.g. the Python ini-like format
    does not support lists by default.
- ``default``: Default value to use if not present in the configuration file.
- ``key``: Specify key in configuration file if different from attribute name.
- ``validator``: Callable that takes the configuration value and checks whether 
    it is valid - return `True`, otherwise return `False`.
- ``transformer``: Transform the value from configuration file. This happens
    after the type conversion but before the validation.
    Can be used for example for transforming paths
    (expanding user home dire, changing relative paths to absolute, …).

## Tests
Objconf uses tox to run the tests.
```bash
python3 -m pip install tox
python3 -m tox
```


