More on Documentation.

[James William Pye]

On Aug 28, 2008, at 12:25 PM, Aron Roberts wrote:

> I am quite interested in trying out this package but I feel that I am
> perhaps a bit too stupid to use it.

Nah, it needs better docs. I don't really care for epydoc, so I was  
venturing out to create my own. It's been met with mild success.  
Really, the primary thing that's missing is making the package  
documentation more browsable and providing references to external  
package documentation(just one big HTML file atm, so not very useable).

Perhaps an ``examples`` chapter in the pg_proboscis documentation  
would clear this all up...

> I am used to DB-API 2.0 but very
> willing to use the Green Trunk interface in order to get the COPY
> functionality.

Considering the DB-API 2.0 interface is built using greentrunk, you  
can access the greentrunk connection directly to get the easy COPY  
interface. (the `greentrunk` attribute on a DB-API 2.0 connection  
object.)

> I can connect and get results from simple queries but I am unclear as
> to how I am supposed to use a ResultHandle object for a COPY.

It follows the iterator protocol, so when you are copying data out,  
you can just iterate over the ResultHandle object. Or, if you want to  
read in chunks, you can use the ``read(n)`` method.

For copying data in, you'll normally use the write method.

However, for connection-to-connection copies, you can just pass the  
COPY TO STDOUT query to the COPY TO STDIN query:

 >>> dst.query("COPY tablename FROM STDIN")(src.query("COPY tablename  
FROM STDOUT"))

If you are dealing with writing to the ResultHandle directly(via  
``write([])``), you'll need to ``close()`` when you are done.  
Otherwise it will raise an exception when you try to use the  
connection(ie, COPY's have an exclusive hold on the connection while  
they are running.)

> Are there any examples anywhere?

Few. I think there is an example of the COPY usage in the release  
announcement emails..

(Just search for COPY)
http://mail.python.org/pipermail/python-announce-list/2008-June/006715.html

(You've probably already seen this....)
http://python.projects.postgresql.org/doc/pg_proboscis-1.0.2.html#postgresql.interface.proboscis.tracenull.ResultHandle


Hope this helps.