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 Hstore data type
---------------- ----------------
Python `dict` objects can be converted into the PostgreSQL |hstore|_ data .. versionadded:: 2.2.3
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 The |hstore|_ data type is a key-value store embedded in PostgreSQL. It has
release and the Psycopg adapter uses a more efficient representation if the been available for several server versions but with the release 9.0 it has
new release is detected. 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| replace:: :sql:`hstore`
.. _hstore: http://www.postgresql.org/docs/9.0/static/hstore.html .. _hstore: http://www.postgresql.org/docs/9.0/static/hstore.html
.. autofunction:: register_hstore
.. index:: .. index::
pair: UUID; Data types 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) get_oids = classmethod(get_oids)
def register_hstore(conn_or_curs, globally=False, unicode=False): 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 The function must receive a connection or cursor as the |hstore| oid is
is different in every database. The typecaster will be registered only on different in each database. The typecaster will normally be registered
the connection or cursor passed as argument. If your application uses a only on the connection or cursor passed as argument. If your application
single database you can pass *globally*\=True to have hstore registered uses a single database you can pass *globally*\=True to have the typecaster
on all the connections. registered on all the connections.
By default the returned dicts have string keys and values: use By default the returned dicts will have `str` objects as keys and values:
*unicode*\=True to return `unicode` objects instead. 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 The |hstore| contrib module must be already installed in the database
installed in the target 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) oids = HstoreAdapter.get_oids(conn_or_curs)
if oids is None: if oids is None: