Metadata-Version: 1.0
Name: propdb
Version: 0.3.0
Summary: Property Bag Style Database
Home-page: https://bitbucket.org/daxwilson/propdb
Author: Dax Wilson
Author-email: daxwilson@gmail.com
License: GNU-GPL
Description: Description
        -----------
        The propdb package is a simple database package. It is basically a
        persisting Python dictionary.
        
        Property item name's are dictionary keys and the dictionary values are
        property items. The keys are enforced to be of basestring type whereas
        the values can be anything, almost. The property bag is saved to the file
        system by serializing the dictionary as JSON or by cPickle; therefore,
        the property item values must be able to be seriailized by one of those
        two modules.
        
        Property bag name and location form the path where the bag is saved. If no
        location is set then the current working directory is used. If no name is
        set then a temp name is automatically generated. Property bags
        are created by instantiating a propbag. Property items are created by
        calling add from the bag instance.
        
        If autosave is true then the bag will automatically save when property
        items are added, updated, or dropped. If multiple items need to be added,
        updated, or dropped then suspend autosave before operations
        by calling suspend_autosave(). Resume autosaving once operations are
        completed by calling resume_autosave(). If autosave is false then the bag
        can manually be saved by calling the save() method. Checking the is_dirty
        property on the bag indicates if the bag needs to be saved.
        
        Property items in a property bag can be iterated directly on the instance
        of the bag (e.g. for item in bag).
        
        Property bags can be serialized as JSON or by cPickle by setting the
        "backend" argument when instantiating a bag.
        
        Property bags can be encrypted by setting the secret_key argument.
        The secret_key can be 32 characters in length and AES encryption
        algorithm is used. Note: The M2Crypto must be installed for this
        feature to work.
        
        Property bags can be sync'd if multiple instances of the same bag
        is referenced by other property bags by calling the sync() method.
        If autosync is set to true when instantiating a property bag then
        sync'ing will automatically be done when saving.
        
        Installation
        ------------
        ::
        
        	pip install propdb
        
        Basic Usage
        -----------
        ::
        
        	from propdb.propbag import propbag as bag
        	from propdb.propbag import propitem as item
        	
        	bag1 = bag('bag1')
        	bag1.add('item1')
        	bag1.add(('item2', 'Value as a string', 'item3', 3333))
        	
        	item1 = bag1['item1']
        	item1.value = [1, 2, 3, 4]
        	bag1.set(item1)
        	
        	bag1.set(('item2', 'A new string value'))
        	bag1.set({'item3':12345})
        
        Imports
        -------
        ::
        
        	from propdb.propbag import propbag
        	from propdb.propbag import propitem
        
        Create a new property bag
        -------------------------
        ::
        
        	# all arguments are optional
        	propbag(name, directory, autosave, backend, secret_key)
        
        	# creates a bag with a random name
        	bag1 = propbag()
        
        	# creates a bag named 'mybag' in the current working directory
        	bag2 = propbag('mybag')
        
        	# creates a bag named 'mybag' in the temp folder
        	bag3 = propbag('mybag', 'c:\\temp')
        
        	# creates a bag named 'mybag' where autosave is off and the
        	# backend is pickle
        	bag4 = propbag('mybag', autosave = False, backend = backendformat.pickle)
        	bag4.save()
        
        	# creates an encrypted bag
        	bag5 = propbag(secret_key = 'supersecretpassword')
        	print(bag5.location)
        
        Adding property items
        ---------------------
        Use the propbag.add(items) method to add property item(s) to the bag.
        
        Returns a list of all the added property items.
        
        Adding property items is very flexible. It is acceptable
        to add one or many with one call. It can be just a name, a collection, or a
        property item instance. Adding by list can be name/value pairs or
        a collection of property items. Adding by dictionary uses the key for
        the name and the value for the property item's value.
        ::
        
        	from propdb.propbag import propbag
        
        	# create new bag
        	bag = propbag('mybag')
        
        	# adds a property item with the value set to None
        	bag.add('item1')
        	
        	# by list of name/value pairs
        	bag.add(('item1', 1, 'item2', 2, ...))
        	
        	# by dictionary
        	bag.add({'item1':1, 'item2':2, ...})
        	
        	# by list or propitems
        	bag.add((propitem, propitem, ...))
        	
        	# by propitem
        	bag.add(propitem)
        
        Adding property items with the + and += operators can be done in the
        same exact way as the add method (e.g. propbag + propitem, etc). The
        only difference is that there is no return value when adding by
        operator.
        
        For example:
        ::
        
        	bag + 'item1'
        	bag += ('item1', 1, 'item2', 2, ...)
        
        Updating property items
        -----------------------
        Use propbag.set to update property item(s) in the bag.
        
        Returns a list of all the updated property items.
        
        Updating property items is very flexible. It is acceptable
        to update one or many with one call. It can be a collection or an instance of a
        property item. Updating by list must be by name/value pairs or a collection
        of property items. Updating by dictionary assumes the key to be
        the name and the dictionary value the value of the property item.
        ::
        
        	from propdb.propbag import propbag
        
        	# create new bag
        	bag = propbag('mybag')
        
        	# by list of name/value pairs
        	bag.set(('item1', 1, 'item2', 2, ...))
        	
        	# by dictionary
        	bag.set({'item1':1, 'item2':2, ...})
        	
        	# by list or propitems
        	bag.set((propitem, propitem, ...))
        	
        	# by propitem
        	bag.set(propitem)
        
        Updating property items with the [] operator can be done by
        indexing the property bag with the name of the property item
        and passing in a new value or a property item.
        
        For example:
        ::
        
        	bag['item1'] = value
        	bag[propitem.name] = propitem
        
        Deleting property items
        -----------------------
        Use propbag.drop to delete property item(s) from the bag.
        
        Returns the number of property items dropped.
        
        Dropping property items is very flexible. It is acceptable
        to drop one or many with one call. It can be a single string,
        property item, or list.
        
        Delete one property item by passing the name of the item to delete.
        Passing a list can either be a list of names or property items,
        mixed is acceptable as well (e.g. ('item1', propitem)).
        ::
        
        	from propdb.propbag import propbag
        
        	# create new bag
        	bag = propbag('mybag')
        
        	# drops one property by name
        	bag.drop('item1')
        	
        	# drops one property item by name
        	bag.drop(propitem)
        	
        	# by list of names
        	bag.drop(('item1', 'item2', 'item3', ...))
        	
        	# by list of propitems
        	bag.drop((propitem, propitem, ...))
        
        Dropping property items with the - and -= operators can be done in
        the same exact way as the drop method (e.g. propbag - propitem, etc).
        The only difference is that there is no return value when dropping
        by operator.
        
        For example:
        ::
        
        	bag - 'item1' # drops one property item by name
        	bag -= ('item1', 'item2', 'item3', ...) # via list of names
        
        Sync'ing property items
        -----------------------
        Use propbag.sync to sync changes in a bag if altered by a different
        instance of the same bag.
        
        Setting autosync to true when instantiating a property bag will
        activate this feature automatically.
        ::
        
        	from propdb.propbag import propbag
        
        	# create two bags that point to the same bag
        	bag1 = propbag('mybag')
        	bag2 = propbag('mybag')
        
        	# create property item in bag1
        	bag1.add({'item1':1})
        
        	# sync bag2...bag2 now has item1
        	bag2.sync()
        
        
        Changes
        --------
        
        0.3.0 - Sync and autosync features added to property bags.
        
        0.2.0 - Supports two types of serialization: backendformat.json (default)
        and backendformat.pickle. Supports saving the bag encrypted with M2Crypto.
        
        0.1.4 - Added unittests and fixed a bug when adding by dictionary
        
        <= 0.1.3 - Working out the details of publishing to PyPI
Platform: UNKNOWN
