psycopg/psycopg2
1
1
Fork 0
mirror of https://github.com/psycopg/psycopg2.git synced 2025-01-31 09:24:07 +03:00
Code Issues Packages Projects Releases Wiki Activity

Hstore documentation improved.

Browse Source
This commit is contained in:
Daniele Varrazzo 2010-09-28 00:33:34 +01:00
parent 4b98e8941f
commit 01ec120aa8
2 changed files with 28 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/src/extras.rst
View File

@ -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

24
lib/extras.py
View File

@ -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: