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

Improved adaptation documentation

Browse Source 
Documented __conform__() and prepare().
This commit is contained in:
Daniele Varrazzo 2011-02-10 01:44:37 +00:00
parent 7a058403ca
commit 9c81f6c186
1 changed files with 26 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
doc/src/advanced.rst
View File

@ -89,14 +89,33 @@ by the `psycopg2.extensions.adapt()` function.
The `~cursor.execute()` method adapts its arguments to the The `~cursor.execute()` method adapts its arguments to the
`~psycopg2.extensions.ISQLQuote` protocol. Objects that conform to this `~psycopg2.extensions.ISQLQuote` protocol. Objects that conform to this
protocol expose a `!getquoted()` method returning the SQL representation protocol expose a `!getquoted()` method returning the SQL representation
of the object as a string. of the object as a string (the method must return `!bytes` in Python 3).
Optionally the conform object may expose a
`~psycopg2.extensions.ISQLQuote.prepare()` method.
The easiest way to adapt an object to an SQL string is to register an adapter There are two basic ways to have a Python object adapted to SQL:
function via the `~psycopg2.extensions.register_adapter()` function. The
adapter function must take the value to be adapted as argument and return a - the object itself is conform, or knows how to make itself conform. Such
conform object. A convenient object is the `~psycopg2.extensions.AsIs` object must expose a `__conform__()` method that will be called with the
wrapper, whose `!getquoted()` result is simply the `!str()`\ ing protocol object as argument. The object can check that the protocol is
conversion of the wrapped object. `!ISQLQuote`, in which case it can return `!self` (if the object also
implements `!getquoted()`) or a suitable wrapper object. This option is
viable if you are the author of the object and if the object is specifically
designed for the database (i.e. having Psycopg as a dependency and polluting
its interface with the required methods doesn't bother you). For a simple
example you can take a look to the source code for the
`psycopg2.extras.Inet` object.
- If implementing the `!ISQLQuote` interface directly in the object is not an
option, you can use an adaptation function, taking the object to be adapted
as argument and returning a conforming object. The adapter must be
registered via the `~psycopg2.extensions.register_adapter()` function. A
simple example wrapper is the `!psycopg2.extras.UUID_adapter` used by the
`~psycopg2.extras.register_uuid()` function.
A convenient object to write adapters is the `~psycopg2.extensions.AsIs`
wrapper, whose `!getquoted()` result is simply the `!str()`\ ing conversion of
the wrapped object.
.. index:: .. index::
single: Example; Types adaptation single: Example; Types adaptation