API — configaro 0.9.7 documentation

# API

configaro is provided as a single module.

It has a spartan set of three APIs:

- `configaro.init()`
- `configaro.get()`
- `configaro.put()`

It also has several error classes:

- `configaro.ConfigaroError`
- `configaro.ConfigNotFoundError`
- `configaro.ConfigNotValidError`
- `configaro.NotInitializedError`
- `configaro.PropertyNotFoundError`
- `configaro.PropertyNotScalarError`
- `configaro.UpdateNotValidError`

Note

At the moment, the configaro API documentation built and hosted by Read the Docs is not being correctly generated. When building as a Read the Docs build process, Sphinx is unable to generate the full API docs, as the automodule directive is unable to find the configaro module, even though the proper directory has been added to `sys.argv` in `docs/source/conf.py`.

To build and view the API docs:

    $ git clone https://github.com/mojochao/configaro.git
    $ cd configaro
    $ pip3 install -e '.[dev]'
    $ python3 setup.py build_sphinx
    $ cd build/sphinx/html
    $ python3 -m http.server
    $ open http://0.0.0.0:8000/

I will continue to investigate, and hopefully resolve, this soon.

configaro is a Python 3 configuration library that’s music to your ears.

It has been created with the following design goals in mind:

> - provide a single file library with minimal dependencies
> - provide one with a simple, expressive API that is easy to use and gets out of your way
> - provide one that allows for hierarchical config data supporting dot-addressable access
> - provide one that allows for defaults and locals config modules
> - provide one with complete test coverage
> - provide one with complete documentation

If this sounds appealing to you, take a look:

    import configaro as cfg

    # Initialize the library with the name of the package containing your defaults.py config module
    cfg.init('mypkg.config')

    # Get the entire config object
    config = cfg.get()
    print(config)  # prints "{'greeting': 'Hello', 'subject': 'World'}"

    # Config object provide attribute access style in addition to dict access style.
    print('f{config.greeting}, {config.subject}!')  # prints "Hello, World!"

    # Config objects may be updated quite flexibly as well.
    cfg.put(greeting='Goodbye', subject='Folks'}
    cfg.put({'greeting': 'Goodbye', 'subject': 'Folks'})
    cfg.put('greeting=Goodbye subject=Folks')

I have zero interest in supporting Python 2 at this point. If you are still using Python 2 then move along – there’s nothing to see here.

exception `configaro.` `ConfigaroError`(message)

  Base library exception class.

exception `configaro.` `ConfigNotFoundError`(path)

  Config module not found error.

exception `configaro.` `ConfigNotValidError`(path)

  Config module does not contain a ‘config’ attribute of ‘dict’ type error.

exception `configaro.` `NotInitializedError`

  Config object not initialized error.

exception `configaro.` `PropertyNotFoundError`(data, prop_name)

  Config property not found error.

exception `configaro.` `PropertyNotScalarError`(data, prop_name)

  Config property not scalar error.

exception `configaro.` `UpdateNotValidError`(update)

  Config update not valid error.

`configaro.` `get`(*prop_names, **kwargs)

  Get config values.

  The config object must be initialized before use.

  If no prop_names are provided, returns the config root config object:

      config = get()

  If one property name is provided, returns that sub config object:

      prop = get('prop')

  If multiple property names are provided, returns a tuple of sub config objects:

      prop1, prop2 = get('prop1', 'prop2')

  Multiple property names can also be provided in a single string argument as well:

      prop1, prop2 = get('prop1 prop2')

  If a property name is not found, configaro.PropertyNotFoundError is raised, unless a default keyword argument is provided:

      prop = get('prop', default=None)

  Parameters: | prop_names (List[str]) – config property names kwargs (Dict[str, Any]) – config get keyword args
  Returns: | property values
  Return type: | Tuple[munch.Munch]
  Raises: | `configaro.NotInitialized` – if library has not been initialized `configaro.PropertyNotFoundError` – if a property in prop_names is not found

`configaro.` `init`(config_package, locals_path=None, locals_env_var=None)

  Initialize the config object.

  The config object must be initialized before use and is built from one or two config modules. A config module is simply any Python module with a module attribute named config. The config object loaded from the defaults config module, as well as any locals config module found.

  The defaults config module is always loaded. The required config_package argument is used to define the package in which the defaults config module, named `defaults.py`, is loaded from:

      init('my_pkg.config')

  The locals config module is loaded, next if it exists, from the following locations, in precedence order from highest to lowest:

      - one found at path specified by locals env var
      - one found at path specified by locals path
      - one found in config package

  If no other options are provided, the locals config module will be loaded, if it exists, from the config_package.

  If the optional locals_path argument is provided it will be used, if it exists, instead of any `locals.py` config module in the config package:

      init('my_pkg.config', locals_path='/path/to/my/alternatively_named_locals.py')

  If the optional locals_env_var argument is provided it will be used as a an environment variable configuring the path of the locals config module to load, if the module exists:

      init('my_pkg.config', locals_env_var='MY_PKG_CONFIG_LOCALS')

  If the locals_env_var argument is not provided the `CONFIGARO_LOCALS` environment variable name will be used instead.

  Repeated initialization has no effect. You can not re-initialize with different values.

  Parameters: | config_package (str) – package containing defaults and locals config modules locals_path (str) – path to locals config module locals_env_var (str) – name of environment variable providing path to locals config module

`configaro.` `put`(*args, **kwargs)

  Put config values.

  The config object must be initialized before use.

  This function supports many expressive styles of usage.

  The entire config object can be updated with a single dict data argument:

      put({'prop_a': True, 'prop_b': 23})

  Similarly, any sub config object can be updated with a string property and dict data argument:

      put(prop={'prop_a': True, 'prop_b': 23})
      put('nested.prop', {'prop_a': True, 'prop_b': 23})

  Updates can also be specified by `name=value` update strings. If one or more string arguments are passed, the updates described by those update strings will be applied to the config object:

      put('prop_a=True')
      put('prop_b=23')

  Update strings allow hierarchical configs to be updated:

      put('prop.nested=awesome')

  You can also batch up multiple updates in a single update string:

      put('prop_a=True prop.nested=awesome')

  If you are updating root config properties you can simply use keyword arguments:

      put(prop_a=True, prop_d={'greeting': 'Hello', 'subject': 'world'})

  Parameters: | args (Dict | str | List[str]) – config dict object or one or more ‘some.knob=value’ update strings kwargs (Dict[str, Any]) – config update keyword args
  Raises: | `configaro.NotInitializedError` – if library has not been initialized `configaro.PropertyNotScalarError` – if property is not a scalar `configaro.UpdateNotValidError` – if update string is not valid