From 4b98e8941ff914bd526e266373c689c60ce49e9a Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 27 Sep 2010 02:25:09 +0100
Subject: [PATCH] Added some documentation for the hstore adaptation.

---
 doc/src/extras.rst | 24 ++++++++++++++++++++++++
 doc/src/usage.rst  | 10 ++++++++++
 lib/extras.py      | 12 ++++++------
 3 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/doc/src/extras.rst b/doc/src/extras.rst
index 19f055b9..b2f4ea3e 100644
--- a/doc/src/extras.rst
+++ b/doc/src/extras.rst
@@ -86,6 +86,30 @@ Logging cursor
 
 
 
+.. index::
+    pair: hstore; Data types
+    pair: dict; Adaptation
+
+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.
+
+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.
+
+
+.. |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/doc/src/usage.rst b/doc/src/usage.rst
index d3985158..bea38ace 100644
--- a/doc/src/usage.rst
+++ b/doc/src/usage.rst
@@ -186,6 +186,7 @@ argument of the `~cursor.execute()` method::
 
 
 .. index::
+    single: Adaptation
     pair: Objects; Adaptation
     single: Data types; Adaptation
 
@@ -294,6 +295,15 @@ the SQL string that would be sent to the database.
      was necessary to import the `~psycopg2.extensions` module to have it
      registered.
 
+- Python dictionaries are converted into the |hstore|_ data type. See
+  `~psycopg2.extras.register_hstore()` for further details.
+
+  .. |hstore| replace:: :sql:`hstore`
+  .. _hstore: http://www.postgresql.org/docs/9.0/static/hstore.html
+
+  .. versionadded:: 2.2.3
+     the :sql:`hstore` adaptation.
+
 .. index::
     single: Unicode
 
diff --git a/lib/extras.py b/lib/extras.py
index e81aedb1..dc98fdb1 100644
--- a/lib/extras.py
+++ b/lib/extras.py
@@ -620,14 +620,14 @@ def register_hstore(conn_or_curs, globally=False, unicode=False):
     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.
-
-    Raise `~psycopg2.ProgrammingError` if hstore is not installed in the
-    target database.
+    single database you can pass *globally*\=True to have hstore registered
+    on all the connections.
 
     By default the returned dicts have string keys and values: use
-    *unicode*=True to return `unicode` objects instead.
+    *unicode*\=True to return `unicode` objects instead.
+
+    Raise `~psycopg2.ProgrammingError` if the :sql:`hstore` type is not
+    installed in the target database.
     """
     oids = HstoreAdapter.get_oids(conn_or_curs)
     if oids is None: