Usage

To use inicheck in a project you will need to create a master config file for all your configuration files to be checked against. To get started with writing a master configuration file see Master Configuration File.

Command Line

A First Use Example:

Once the Master file is created, create a config file and check it! Consider the following example. Lets say the Master Configuration file contains one section and one recipe like:

[settings]

  username:
          default = guest

  age:
        type = int,
        description = users age

  job_class:
            default = grunt,
            options = [grunt middleman exec],
            description = class of the users job to limit access

[settings_recipe]

    trigger:
	    has_section=settings

    settings:
    	apply_defaults = True

To make a simple configuration file we need to create the file and fill out whatever entries are important to the specific user:

[settings]
  username: coolman15

Now to check what the user just entered into their config:

inicheck -f config.ini -c master.ini

If you do not get any errors then you have just checked your first config file!

To see how inicheck interpreted your config file add the -w option to the aboved command. This will output the file the way inicheck sees it. Opening it up will show all the entries are filled out.

For more info see Command Line tools.

Aiming to be User Proof

For a further demo, let’s say the our user think themselves funny and enters the following into their configuration file:

age: nunya!
job_class: king

inicheck will produce errors and report them in the following manner:

Configuration File Status Report:
==========================================================================
ERRORS:

Section              Item          Message
--------------------------------------------------------------------------
settings             age                Expecting int received str
settings             job_class          Not a valid option

This takes alot of issues out of the hands of the developer so they can focus more on functionality rather than the sometimes erratic behavior of users.

For information take a look at Command Line tools.

For a Project

Using inicheck for your project is a great way to save on repeated code and reduce insane amounts of check of types, whether something exists, etc…

Getting a Config File

Once the user has filled out a configuration file, inicheck can bring in the information via a UserConfig object by using the following at a minimum:

from inicheck.tools import get_user_config

ucfg = get_user_config(filename, module=str_module_name, checking_later=True)

CAUTION: Using the checking later flag will allow inicheck to pass over issues that would raise exceptions so that the developer can inform the user of the issues with their config file at the same time. This can be dangerous if the developer does not follow up with the functions check_config and print_config_report.

To get the config and check it and report the warnings and errors to the screen:

from inicheck.tools import get_user_config, check_config, print_config_report

ucfg = get_user_config(filename, module=str_module_name, checking_later=True)
warnings, errors = check_config(ucfg)
print_config_report(warnings, errors)
To learn more see checkout the functions documentation:

Installing a Master Configuration File

Once you have made a master configuration file, the easiest way to use it for your own project is to add its file path as a module attribute. inicheck currently looks for attributes when a module is requested:

  • __core_config__
  • __recipes__

If both are found inicheck will combine them and create a large master configuration file. Below is an example of how to add these attributes to your module.

# Add the following to the packages's __init__.py file
import os
__core_config__ = os.path.abspath(os.path.dirname(__file__) + '/master.ini')

# If you have enough recipes to keep the files separate you can add:
__recipes__ = os.path.abspath(os.path.dirname(__file__) + '/recipes.ini')

Once this is done make sure you add the file(s) to whatever package inclusions you need. Here is an example of how to include them in your setup.py

# In a setup.py, under the setup class initializer
package_data={'mymodule':['./master.ini',
                    './recipes.ini']},

Custom Configuration File Headers

inicheck has multiple ways to output your configuration file once inicheck as interpreted it. It is nice to use these because they are clean and it often serves as a placemark on some settings used for some event/task. Developers can provide custom headers. We have seen this functionality used for:

  • Datetime stamping configuration file creation
  • Marking with relevant software version numbers or git hashes.
  • Links to source code or documentation

To add this to your project, simply add:

__config_header__ = some.function()

where “some.function()” would be a custom function that returns a string of content to write to the top of you configuration file.

Here are some examples of this in action:

Custom Configuration File Section Titles

A less critical feature but still nice for producing self describing configuration files is having custom section headers.

To add this to your project, simply add the following attribute with a dictionary containing corresponding sections with the messages desired:

__config_titles__ = {"Setup": "This is the setup section"}

The result is a config file with a section preceeded by:

#######################################################################
# This Is The Setup Section
#######################################################################

[setup]
# configuration stuff..

The following is a good example of how this looks in a project: