YASCP
=====

This is Yet Another Simple Configuration Parser module for INI style configurations files.

Installation
------------

``pip install yascp``

``easy_install yascp``

USAGE
-----

A sample configuration is looking like this and is saved in file called example.conf:

::

 [database]
 login = user
 password = topsecret
 host = example.com
 port = 3306

 [backend_api]
 login = api_user
 password = api_password
 url = http://example.com:9080

In scripts
^^^^^^^^^^

The constructor takes only two arguments - first one is the name or absoluthe path to the configuration file (see below "Configuration File" for more details on this) and a dictionary of default values which will be parsed before any actual configuration file is read. If same section and option is found in a configuration file then the default will be overwritten.
Until version 2.6 KEY and VALUE could be separated by the '=' sign only but from 2.7 third argument may be passed on to specify the delimiter and it can be anything. Default is still '=' if not specified.

::

 import yascp
 config = yascp.parser.Parser(configuration_file_name = 'example.conf', defaults = {'extra.port':'666'}, delimiter = '=')

 login      = config.database.username
 password   = config.database.password
 host       = config.database.host
 port       = config.database.port

 print config.backend_api.url
 print config.extra.port

There is a convenience method available to print off all of the configuration parsed.

So running:
::

 config.print_all()

would print to the screen following:

::

 backend_api.url = http://example.com:9080
 backend_api.password = api_password
 backend_api.login = api_user
 extra.port = 666
 database.host = example.com
 database.port = 3306
 database.login = user
 database.password = topsecret


**Notice**: *Everything is a string. The module does not distinguish any type of data and so the developer should know where an integer for example is expected an perform all required tests/handle possible errors.*

In command line
^^^^^^^^^^^^^^^

::

 parser.py [path to/name of an INI config file] [section.option to be fetched]

The script takes two arguments

The first argument is the name of a configuration file  or full path to one (see below for "Configuration File" section for more details).

The second argument may be "--list-all" to obtain a list of all available options
or a key of specific option to get value for this option only (run first with
"--list-all" to see what exactly can be used here).

If an option doesn't belong to any of the sections in the configuration file
then it should be addresses with "default" section, i.e:

::

 default.[myoption]

Sample usage:

::

 python parser.py /tmp/example.conf --print-all
 backend_api.url = http://example.com:9080
 backend_api.password = api_password
 backend_api.login = api_user
 database.host = example.com
 database.port = 3306
 database.login = user
 database.password = topsecret

Knowing now what options are avaialbe you can fetch only this that you need:

::

 python parser.py /tmp/example.conf backend_api.url
 http://example.com:9080

Configuration File
------------------

If absolute path is provided to a configuration file then only that file is read but
if only a name of configuration file is given then the script will attempt to read
a file by that name in following locations and order:

#. /etc/[config file name]
#. ~/[config file name]
#. directory from which the script has been ran.

**Notice**: If more than one configuration file is present then the duplicated options set for example in a configuratioin file saved in /etc/ will be overwritten by those in user's home direcotry and so on.

Changelog
---------

2.7
^^^
- extended functionality - now a separator can be parser when used as a module so from now on KEY and VALUE can be separated by = as usual but also space character, tab character or anything else

2.6
^^^
- fixed a "hidden" issue with infinite recursion within __getattr__ method; this didn't affect the functionality though

2.5
^^^
- introduced proper access point from shell via script **yascp_parser.py** (available from PATH after installation)
- introduced possibility to execute the module by a direct call, i.e. **python -m yascp**