pg_proboscis 0.9 release

[James William Pye]

On Tue, Jan 08, 2008 at 08:41:06PM +0000, Adrian Klaver wrote:
[CC'ing list]
> A couple of questions.
> 1) I could not seem to find the new release on pgfoundry. Am I jumping the gun?

Nope, not at all. Considering that the project is a set of packages, it is
*way* easier to just distribute it using pypi. I'm in the process of removing
the docs on the main site, so yeah, it's misleading. :(

http://pypi.python.org/pypi?:action=display&name=pg_proboscis&version=0.9

Hrm, it's doesn't appear to have a way to list packages by submitter, but you
can just search for 'pg', and you'll see my packages start with 'pg_'.

I recommend using easy_install. See one of my responses to myself about problems
with the ssl package. (Which I might as well not list as a dependency, but I
planned to implement it soon, so there it is. Trying to contact the ssl package
maintainer so that it can become easy_install friendly.... ;)

Oh, if you don't have "easy_install", you'll probably need to install setuptools.
Well, you'll need it regardless of using easy_install as it uses setuptools.
(ugh, I only rely it for dependency resolution.. hrm..)

> 2) What is the best way to learn  about the new features?

I hate to say so, but poking around in the console and using help(). :(
Also, the tests in postgresql.protocol.greentrunk.test goes over a few of the
features. (d/l source or unzip the egg)

However, it's not really so bad as you can just connect using pb_python:

 pb_python -h localhost -U user -d dbname

This will give you a Python console that has an additional built-in named 'GTX'.
This is an established connection object. Running dir() and help() on the
objects that you create should be somewhat informative.


Some things to look at:

 Connections "autocommit" by default now. I don't believe it did this before.

 Queries ultimately return standard Python objects instead of the rather nasty
 "Postgres type instances" that typical used to keep. 

 Arrays are handled with postgresql.types.array. This implements arrays similar
 to Postgres as opposed to Python; accessing out of bounds indexes returns None.
 (Not sure if this is the right way to go just yet, but using nested tuples or
 lists is *not* the way to go)

 DDL statements return a ResultHandle object. To get the count or the command of
 the statement, you have use the count and command methods on the object:
 
	rh = GTX.Query("INSERT INTO foo VALUES ($1)")(2)
	rh.count()
	rh.command()


 "Transact" should be gone; the 'Transaction' object on the connection manages
 the transaction state of the connection. It includes with-statement support and
 configurable isolation.


 The 'Settings' object replaces the broken 'Parameter' object. I changed the
 name as 'Settings' lends to "SET". Standard dictionary interface to the
 SHOW/SET command.


 COPY is fantastically simplified: 

  for x in GTX.Query("COPY foo TO STDOUT"):
   sys.stdout.write(x)

  GTX.Query("COPY foo FROM STDIN")(sys.stdin)
 
 It uses simple iterators, expecting or giving a single COPY line. Additionally,
 the ResultHandle object has standard file-object interfaces for dealing with
 copies in bulk. `rh.write([line1, line2, ..., linen,])` or `rh.read(10)` for
 COPY to standard out.