# Module: `utils.pickleshare`

PickleShare - a small ‘shelve’ like datastore with concurrency support

Like shelve, a PickleShareDB object acts like a normal dictionary. Unlike shelve, many processes can access the database simultaneously. Changing a value in database is immediately visible to other processes accessing the same database.

Concurrency is possible because the values are stored in separate files. Hence the “database” is a directory where all files are governed by PickleShare.

Example usage:

    from pickleshare import *
    db = PickleShareDB('~/testpickleshare')
    db.clear()
    print "Should be empty:",db.items()
    db['hello'] = 15
    db['aku ankka'] = [1,2,313]
    db['paths/are/ok/key'] = [1,(5,46)]
    print db.keys()
    del db['aku ankka']

This module is certainly not ZODB, but can be used for low-load (non-mission-critical) situations where tiny code size trumps the advanced features of a “real” object database.

Installation guide: easy_install pickleshare

Author: Ville Vainio <vivainio@gmail.com> License: MIT open source license.

## 2 Classes

class `IPython.utils.pickleshare.``PickleShareDB`(root)

  Bases: `_abcoll.MutableMapping`

  The main ‘connection’ object for PickleShare database

  `__init__`(root)

    Return a db object that will manage the specied directory

  `getlink`(folder)

    Get a convenient link for accessing items

  `hcompress`(hashroot)

    Compress category ‘hashroot’, so hset is fast again

    hget will fail if fast_only is True for compressed items (that were hset before hcompress).

  `hdict`(hashroot)

    Get all data contained in hashed category ‘hashroot’ as dict

  `hget`(hashroot, key, default=<object object>, fast_only=True)

    hashed get

  `hset`(hashroot, key, value)

    hashed set

  `keys`(globpat=None)

    All keys in DB, or all keys matching a glob

  `uncache`(*items)

    Removes all, or specified items from cache

    Use this after reading a large amount of large objects to free up memory, when you won’t be needing the objects for a while.

  `waitget`(key, maxwaittime=60)

    Wait (poll) for a key to get a value

    Will wait for maxwaittime seconds before raising a KeyError. The call exits normally if the key field in db gets a value within the timeout period.

    Use this for synchronizing different processes or for ensuring that an unfortunately timed “db[‘key’] = newvalue” operation in another process (which causes all ‘get’ operation to cause a KeyError for the duration of pickling) won’t screw up your program logic.

class `IPython.utils.pickleshare.``PickleShareLink`(db, keydir)

  A shortdand for accessing nested PickleShare data conveniently.

  Created through PickleShareDB.getlink(), example:

      lnk = db.getlink('myobjects/test')
      lnk.foo = 2
      lnk.bar = lnk.foo + 5

  `__init__`(db, keydir)

## 2 Functions

`IPython.utils.pickleshare.``gethashfile`(key)

`IPython.utils.pickleshare.``main`()