Bug Fixes

Now supports Python 3.3! The major difference was in the pickle library.
pickle used strings in python 2.7, and bytes in python 3. All pickled objects
are now using a string format in EasySettings, with the help of 3 little conversion
functions. You will never have to use these functions, they’re really internal used
only. But if you want to see how to return a string from pickle.dumps() in python 3,
look at the safe_pickle_str() function. To load from a string, instead of bytes, in
python 3’s pickle.loads(), look at safe_pickle_obj().

The non-string saving method has been enhanced so debug printing will be
‘prettier’. Example of ‘debug printing’ settings:

Examples

Example of Easy Settings basic usage:

#!/usr/bin/env python
# --------------- Creation ----------------
from easysettings import easysettings
settings = easysettings.easysettings("myconfigfile.conf")
# configfile_exists() checks for existing config, and creates one if needed.
# ** this function is called automatically now when a filename is passed to easysettings. **
# if you wish to disable it, just do: settings = easysettings.easysettings() and set
# settings.configfile later.
# ------------- Basic Functions -----------
# set without saving
settings.set("username", "cjw")
settings.set("firstrun", False)
print settings.get("username")
# this results in "cjw"
# check if file is saved
if not settings.is_saved():
print "you haven't saved the settings to disk yet."
# ...settings are still available even if they haven't
# been saved to disk
# save
settings.save()
# you may also set & save in one line...
settings.setsave("homedir", "/myuserdir")

# compare two settings objects
settings2 = easysettings.easysettings('myconfigfile2.conf')
if settings.compare_opts(settings2):
print "these have the same exact options, values may differ"
if settings.compare_vals(settings2):
print "these have the exact same values, options may differ"
if settings == settings2:
print "these have the exact same settings/values"
# can also be written as settings.compare_settings(settings2)
# if you like typing.. :)
if settings > settings2:
print "settings has more options than settings2"
# all of them work ==, !=, <=, >= , > , <
# ... the < > features are based on amount of options.
# the = features are based on option names and values.

Features

Easy Settings has the basic features you would expect out of a settings module,
and it’s very easy to use. If your project needs to save simple settings without
the overhead and complication of other modules then this is for you. Save, load, set, &
get are very easy to grasp. The more advanced features are there for you to use,
but don’t get in the way. Settings, options, & values can be listed, searched,
detected, removed, & cleared.

Easy Settings uses a dictionary to store settings before writing to disk, so you can
also access settings like a dictionary object using easysettings.settings. The
setsave() function will save every time you set an option, and is_saved() will
tell you whether or not the file has been saved to disk yet. Code is documented for a
newbie, so a help('EasySettings') in the python console will get you started.

The search_query argument in the list functions lets you find settings, options, and values by search string:

Non-string types were added, so any type that can be pickled can be used as an
option’s value. This includes all the major types like int, long, float, boolean, and list.
All of these values will be retrieved as the same type that was set:

You can setup an auto load of the whole easysettings instance using the
new pickle features like this:

from easysettings import easysettings
es = easysettings.easysettings().load_pickle('myconfigfile.pkl')
if es is None:
# first time run, need to make an easysettings object.
es = easysettings.easysettings() # uses default configfile if none is passed
es.name = "My Project"
es.version = "1.0"
es.set("firstrun", False)
es.save_pickle()
else:
# pickle file was found, everything from the last save_pickle() was loaded.
print "Loaded name, version, configfile, and all settings/options/values"
# now all you need to do is make sure to save_pickle() before your program exits,
# everything you set in easysettings will be retrieved next time.
# This is expirimental, and not really needed right now because you can pickle your
# own settings object without these functions. The functions are there for possible
# future purposes.

Errors are more descriptive and can be caught using their proper names:

Automatic Creation:

If you pass a file name to easysettings(), the configfile_exists() function is called. This
function will create a blank config file if the file doesn’t exist, otherwise it will return True.
To use the ‘automatic creation’ do this:

settings = easysettings.easysettings('myconfigfile.conf')
# if file exists, all settings were loaded.
# if file did not exist, it was created.
# No permissions, disk-full, and other errors are still possible of course
# depending on the machine, or the current directory permissions.

You can disable the ‘automatic creation’ features by not passing a file name, and loading seperately
like this:

settings = easysettings.easysettings()
settings.configfile = 'myconfigfile.conf'
# file has not been created or loaded.
# file must exist before calling 'load_file'
if settings.load_file():
# all settings were loaded.
else:
# unable to load file for some reason.

This will work in the same way to disable the automatic creation:

settings = easysettings.easysettings()
# file has not been created or loaded.
# file 'myconfigfile.conf' must exist before calling load_file()
if settings.load_file('myconfigfile.conf'):
# file was loaded.
# settings.configfile was set by the load_file() function
else:
# file could not be loaded.

To check if the file exists without creating it automatically you can do this:

if not settings.configfile_exists(False):
print 'config file does not exist, and was not created.'
# I actually prefer the os.path.isfile() method if you're not going to automatically
# create the file.
import os.path
if not os.path.isfile(settings.configfile):
print 'config file does not exist, and was not created.'