PyPo

Copyright (c) 2003 Jonathan Gardner - Licensed under the terms of the GNU General Public License (GPL)

INTRODUCTION

PyPo is an onion-skin thick layer on libpq for PostgreSQL. It can be used for the foundation for other database wrappers, or as a database wrapper itself.

It currently supports about 80% of the functions provided by libpq.

PyPo is pronounced "pipe-oh". The "py" is from Python, and the "Po" is from "PostgreSQL". If you want to pronounce it a different way, that's your right.

To give you an example of how it is written, examine the code for one of the hundreds of routines:

   static PyObject *
   pypo_PQstatus(PyObject *self, PyObject *args)
   {
       pypo_PGconn *conn;

       if (!PyArg_ParseTuple(args, "O!", &pypo_PGconnType, &conn))
           return NULL;

       return Py_BuildValue("i", (int)PQstatus(conn->ptr));
   }

It can't get any simpler than that: Parse the arguments, call the function, then build a return value, and return it.

The functions are called thusly from python:

   from pypo import *

   ...

   status = PQstatus(conn)

INSTALLATION

Installing pypo is done with the setup.py script. If you are using GCC, you may want to tweak the environment variables LD_LIBRARY_PATH and C_INCLUDE_PATH to point to wherever your PostgreSQL 7.4 lib/ and include/ directories live. You can run the pg_config program to discover where these should be. (If you know how to automate this in the setup.py script, please let me know.)

DOWNLOAD

PyPo is available at http://jonathangardner.net/projects/pypo. This is a git archive so you can either clone it (git clone http://jonathangardner.net/projects/pypo/.git pypo) or just download the compiled package at http://jonathangardner.net/projects/pypo/dist/pypo-0.1.0a2.tar.gz.

USAGE

To use pypo, familiarize yourself with chapters 27 and 28 of the PostgreSQL 7.4 Documentation. While the calls are slightly modified from their C counterparts to make them accessible from Python, the general concepts are still intact. Read the documentation for each function to understand how they are used from Python.

Interfaces to deprecated functions are not provided. They are deprecated, so new code should not use them. This will make transitioning away from them when they are removed remarkably easy. (This accounts for some of the 20% of unsupported features of libpq.)

WHAT TO USE IT FOR

While the pypo module by itself is of limited usefulness, it can be the foundation for various database interface modules. You can build directly on top of it for maximum speed. Or you can write a Python DB-API compliant module. Or you can write your own database API.

BUGS

I am not an expert C programmer. I am worried that I have numerous memory leaks and code paths that will lead to segfaults. I am also concerned because I may not have the Python reference ownership concept correct.

If you are a expert C programmer and skilled with either the PostgreSQL libpq interface, or the Python C API, then I would encourage you to examine the code and find any problems.

LICENSE

PyPo is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

PyPo is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with PyPo; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Why did I choose this license? I believe that all software should be free, just like all knowledge and information should be free. This license ensures that no one can take my software and make it less free. That is the restrictive part.

Jonathan Gardner <jgardner@jonathangardner.net>