pghstore — PostgreSQL hstore formatter

This small module implements a formatter and a loader for hstore, one of PostgreSQL supplied modules, that stores simple key-value pairs.

>>> dumps({u'a': u'1'})
'"a"=>"1"'
>>> loads('"a"=>"1"')
{u'a': u'1'}
>>> src = [('pgsql', 'mysql'), ('python', 'php'), ('gevent', 'nodejs')]
>>> loads(dumps(src), return_type=list)
[(u'pgsql', u'mysql'), (u'python', u'php'), (u'gevent', u'nodejs')]

You can easily install the package from PyPI by using pip or easy_install:

$ pip install pghstore
pghstore.dump(obj, file, key_map=None, value_map=None, encoding='utf-8')

Similar to dumps() except it writes the result into the passed file object instead of returning it.

>>> import StringIO
>>> f = StringIO.StringIO()
>>> dump({u'a': u'1'}, f)
>>> f.getvalue()
'"a"=>"1"'
Parameters:
  • obj – a mapping object to dump
  • file – a file object to write into
  • key_map – an optional mapping function that takes a non-string key and returns a mapped string key
  • value_map – an optional mapping function that takes a non-string value and returns a mapped string value
  • encoding – a string encode to use
pghstore.dumps(obj, key_map=None, value_map=None, encoding='utf-8', return_unicode=False)

Converts a mapping object as PostgreSQL hstore format.

>>> dumps({u'a': u'1 "quotes"'})
'"a"=>"1 \\"quotes\\""'
>>> dumps([('key', 'value'), ('k', 'v')])
'"key"=>"value","k"=>"v"'

It accepts only strings as keys and values except None for values. Otherwise it will raise TypeError:

>>> dumps({'null': None})
'"null"=>NULL'
>>> dumps([('a', 1), ('b', 2)])
Traceback (most recent call last):
  ...
TypeError: value 1 of key 'a' is not a string

Or you can pass key_map and value_map parameters to workaround this:

>>> dumps([('a', 1), ('b', 2)], value_map=str)
'"a"=>"1","b"=>"2"'

By applying these options, you can store any other Python objects than strings into hstore values:

>>> try:
...    import json
... except ImportError:
...    import simplejson as json
>>> dumps([('a', range(3)), ('b', 2)], value_map=json.dumps)
'"a"=>"[0, 1, 2]","b"=>"2"'
>>> import pickle
>>> dumps([('a', range(3)), ('b', 2)],
...       value_map=pickle.dumps)  
'"a"=>"...","b"=>"..."'

It returns a UTF-8 encoded string, but you can change the encoding:

>>> dumps({'surname': u'\ud64d'})
'"surname"=>"\xed\x99\x8d"'
>>> dumps({'surname': u'\ud64d'}, encoding='utf-32')
'"surname"=>"\xff\xfe\x00\x00M\xd6\x00\x00"'

If you set return_unicode to True, it will return unicode instead of str (byte string):

>>> dumps({'surname': u'\ud64d'}, return_unicode=True)
u'"surname"=>"\ud64d"'
Parameters:
  • obj – a mapping object to dump
  • key_map – an optional mapping function that takes a non-string key and returns a mapped string key
  • value_map – an optional mapping function that takes a non-string value and returns a mapped string value
  • encoding – a string encode to use
  • return_unicode (bool) – returns an unicode string instead byte str. False by default
Returns:

a hstore data

Return type:

basestring

pghstore.load(file, encoding='utf-8')

Similar to loads() except it reads the passed file object instead of a string.

pghstore.loads(string, encoding='utf-8', return_type=<type 'dict'>)

Parses the passed hstore format string to a Python mapping object.

>>> loads('a=>1')
{u'a': u'1'}

If you want to load a hstore value as any other type than dict set return_type parameter. Note that the constructor has to take an iterable object.

>>> loads('a=>1, b=>2', return_type=list)
[(u'a', u'1'), (u'b', u'2')]
>>> loads('"return_type"=>"tuple"', return_type=tuple)
((u'return_type', u'tuple'),)
Parameters:
  • string (basestring) – a hstore format string
  • encoding – an encoding of the passed string. if the string is an unicode string, this parameter will be ignored
  • return_type – a map type of return value. default is dict
Returns:

a parsed map. its type is decided by return_type parameter

pghstore.version — Version data

You can find the current version in the command line interface:

$ python -m wand.version
1.0.0

New in version 1.0.0.

pghstore.version.VERSION = '1.0.0'

(basestring) The version string e.g. '0.9.2'.

pghstore.version.VERSION_INFO = (1, 0, 0)

(tuple) The version tuple e.g. (0, 9, 2).

Open source

This module is initially written by Hong Minhee (pghstore._native — original Python version) and Robert Kajic (pghstore._speedups — optimized C version).

Distributed under MIT License.

You can find the source code from the GitHub repository:

$ git clone git://github.com/dahlia/pghstore.git

To report bugs or request features use the issue tracker.

Build Status