From 01ec120aa8a31d09112091c528e82421c3994849 Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Tue, 28 Sep 2010 00:33:34 +0100 Subject: [PATCH] Hstore documentation improved. --- doc/src/extras.rst | 23 ++++++++++++++--------- lib/extras.py | 24 ++++++++++++++---------- 2 files changed, 28 insertions(+), 19 deletions(-) diff --git a/doc/src/extras.rst b/doc/src/extras.rst index b2f4ea3e..834bd942 100644 --- a/doc/src/extras.rst +++ b/doc/src/extras.rst @@ -93,22 +93,27 @@ Logging cursor Hstore data type ---------------- -Python `dict` objects can be converted into the PostgreSQL |hstore|_ data -type. Only dictionaries with string/unicode keys and values are supported. -None are also allowed as values. +.. versionadded:: 2.2.3 -The |hstore| type has received a lot of improvements in the PostgreSQL 9.0 -release and the Psycopg adapter uses a more efficient representation if the -new release is detected. +The |hstore|_ data type is a key-value store embedded in PostgreSQL. It has +been available for several server versions but with the release 9.0 it has +been greatly improved in capacity and usefulness with the addiction of many +functions. It supports GiST or GIN indexes allowing search by keys or +key/value pairs as well as regular BTree indexes for equality, uniqueness etc. +Psycopg can convert Python `dict` objects to and from |hstore| structures. +Only dictionaries with string/unicode keys and values are supported. `None` +is also allowed as value. Psycopg uses a more efficient |hstore| +representation when dealing with PostgreSQL 9.0 but previous server versions +are supportes as well. By default the adapter/typecaster are disabled: they +can be enabled using the `register_hstore()` function. + +.. autofunction:: register_hstore .. |hstore| replace:: :sql:`hstore` .. _hstore: http://www.postgresql.org/docs/9.0/static/hstore.html -.. autofunction:: register_hstore - - .. index:: pair: UUID; Data types diff --git a/lib/extras.py b/lib/extras.py index dc98fdb1..902f4609 100644 --- a/lib/extras.py +++ b/lib/extras.py @@ -615,19 +615,23 @@ WHERE typname = 'hstore' and nspname = 'public'; get_oids = classmethod(get_oids) def register_hstore(conn_or_curs, globally=False, unicode=False): - """Register adapter/typecaster for dict/hstore reading/writing. + """Register adapter and typecaster for `dict`\-\ |hstore| conversions. - The function must receive a connection or cursor as the :sql:`hstore` oid - is different in every database. The typecaster will be registered only on - the connection or cursor passed as argument. If your application uses a - single database you can pass *globally*\=True to have hstore registered - on all the connections. + The function must receive a connection or cursor as the |hstore| oid is + different in each database. The typecaster will normally be registered + only on the connection or cursor passed as argument. If your application + uses a single database you can pass *globally*\=True to have the typecaster + registered on all the connections. - By default the returned dicts have string keys and values: use - *unicode*\=True to return `unicode` objects instead. + By default the returned dicts will have `str` objects as keys and values: + use *unicode*\=True to return `unicode` objects instead. When adapting a + dictionary both `str` and `unicode` keys and values are handled (the + `unicode` values will be converted according to the current + `~connection.encoding`). - Raise `~psycopg2.ProgrammingError` if the :sql:`hstore` type is not - installed in the target database. + The |hstore| contrib module must be already installed in the database + (executing the ``hstore.sql`` script in your ``contrib`` directory). + Raise `~psycopg2.ProgrammingError` if the type is not found. """ oids = HstoreAdapter.get_oids(conn_or_curs) if oids is None: