PL/Python should build portably now, if you can get over the fact that

there's no shared libpython.  Test suite works as well. Also, add some
documentation.

config/python.m4

 #
 # Autoconf macros for configuring the build of Python extension modules
 #
-# $Header: /cvsroot/pgsql/config/python.m4,v 1.1 2000/06/10 18:01:35 petere Exp $
+# $Header: /cvsroot/pgsql/config/python.m4,v 1.2 2001/05/12 17:49:32 petere Exp $
 #
 
-# PGAC_PROG_PYTHON
+# PGAC_PATH_PYTHON
 # ----------------
 # Look for Python and set the output variable `PYTHON'
 # to `python' if found, empty otherwise.
-AC_DEFUN([PGAC_PROG_PYTHON],
-[AC_CHECK_PROG(PYTHON, python, python)])
+AC_DEFUN([PGAC_PATH_PYTHON],
+[AC_PATH_PROG(PYTHON, python)
+if test x"$PYTHON" = x""; then
+  AC_MSG_ERROR([Python not found])
+fi
+])
+
+
+# _PGAC_CHECK_PYTHON_DIRS
+# -----------------------
+# Determine the name of various directory of a given Python installation.
+AC_DEFUN([_PGAC_CHECK_PYTHON_DIRS],
+[AC_REQUIRE([PGAC_PATH_PYTHON])
+python_version=`${PYTHON} -c "import sys; print sys.version[[:3]]"`
+python_prefix=`${PYTHON} -c "import sys; print sys.prefix"`
+python_execprefix=`${PYTHON} -c "import sys; print sys.exec_prefix"`
+python_configdir="${python_execprefix}/lib/python${python_version}/config"
+python_moduledir="${python_prefix}/lib/python${python_version}"
+python_includedir="${python_prefix}/include/python${python_version}"
+python_dynlibdir="${python_execprefix}/lib/python${python_version}/lib-dynload"
+
+AC_SUBST(python_version)[]dnl
+AC_SUBST(python_prefix)[]dnl
+AC_SUBST(python_execprefix)[]dnl
+AC_SUBST(python_configdir)[]dnl
+AC_SUBST(python_moduledir)[]dnl
+AC_SUBST(python_includedir)[]dnl
+AC_SUBST(python_dynlibdir)[]dnl
+])# _PGAC_CHECK_PYTHON_DIRS
 
 
-# PGAC_PATH_PYTHONDIR
-# -------------------
-# Finds the names of various install dirs and helper files
-# necessary to build a Python extension module.
+# PGAC_CHECK_PYTHON_MODULE_SETUP
+# ------------------------------
+# Finds things required to build a Python extension module, in
+# particular the makefile.
 #
 # It would be nice if we could check whether the current setup allows
 # the build of the shared module. Future project.
-AC_DEFUN([PGAC_PATH_PYTHONDIR],
-[AC_REQUIRE([PGAC_PROG_PYTHON])
-[if test "${PYTHON+set}" = set ; then
-  python_version=`${PYTHON} -c "import sys; print sys.version[:3]"`
-  python_prefix=`${PYTHON} -c "import sys; print sys.prefix"`
-  python_execprefix=`${PYTHON} -c "import sys; print sys.exec_prefix"`
-  python_configdir="${python_execprefix}/lib/python${python_version}/config"
-  python_moduledir="${python_prefix}/lib/python${python_version}"
-  python_extmakefile="${python_configdir}/Makefile.pre.in"]
-
-  AC_MSG_CHECKING(for Python extension makefile)
-  if test -f "${python_extmakefile}" ; then
-    AC_MSG_RESULT(found)
-  else
-    AC_MSG_RESULT(no)
-    AC_MSG_ERROR(
-[The Python extension makefile was expected at \`${python_extmakefile}\'
-but does not exist. This means the Python module cannot be built automatically.])
-  fi
-
-  AC_SUBST(python_version)
-  AC_SUBST(python_prefix)
-  AC_SUBST(python_execprefix)
-  AC_SUBST(python_configdir)
-  AC_SUBST(python_moduledir)
-  AC_SUBST(python_extmakefile)
+AC_DEFUN([PGAC_CHECK_PYTHON_MODULE_SETUP],
+[AC_REQUIRE([_PGAC_CHECK_PYTHON_DIRS])
+AC_MSG_CHECKING([for makefile to build Python module])
+python_makefile_pre_in="${python_configdir}/Makefile.pre.in"
+
+if test -f "${python_makefile_pre_in}" ; then
+  AC_MSG_RESULT([${python_makefile_pre_in}])
 else
-  AC_MSG_ERROR([Python not found])
-fi])# PGAC_PATH_PYTHONDIR
+  AC_MSG_RESULT(no)
+  AC_MSG_ERROR(
+[The file
+    ${python_makefile_pre_in}
+required to build Python modules does not exist.  Make sure that you have
+a full Python installation and that this is the right location.])
+fi
+
+AC_SUBST(python_makefile_pre_in)[]dnl
+])# PGAC_CHECK_PYTHON_MODULE_SETUP
+
+
+# PGAC_CHECK_PYTHON_EMBED_SETUP
+# -----------------------------
+# Courtesy of the INN 2.3.1 package...
+AC_DEFUN([PGAC_CHECK_PYTHON_EMBED_SETUP],
+[AC_REQUIRE([_PGAC_CHECK_PYTHON_DIRS])
+AC_MSG_CHECKING([how to link an embedded Python application])
+
+_python_libs=`grep '^LIBS=' $python_configdir/Makefile | sed 's/^.*=//'`
+_python_libc=`grep '^LIBC=' $python_configdir/Makefile | sed 's/^.*=//'`
+_python_libm=`grep '^LIBM=' $python_configdir/Makefile | sed 's/^.*=//'`
+_python_liblocalmod=`grep '^LOCALMODLIBS=' $python_configdir/Makefile | sed 's/^.*=//'`
+_python_libbasemod=`grep '^BASEMODLIBS=' $python_configdir/Makefile | sed 's/^.*=//'`
+
+pgac_tab="	" # tab character
+python_libspec=`echo X"-L$python_configdir $_python_libs $_python_libc $_python_libm -lpython$python_version $_python_liblocalmod $_python_libbasemod" | sed -e 's/^X//' -e "s/[[ $pgac_tab]][[ $pgac_tab]]*/ /g"`
+
+AC_MSG_RESULT([${python_libspec}])
+
+AC_SUBST(python_libspec)[]dnl
+])# PGAC_CHECK_PYTHON_EMBED_SETUP

configure.in

@@ -409,11 +409,8 @@ AC_SUBST(with_perl)
 # Optionally build Python interface module
 #
 AC_MSG_CHECKING([whether to build Python modules])
-PGAC_ARG_BOOL(with, python, no, [  --with-python           build Python interface module],
-[AC_MSG_RESULT(yes)
-PGAC_PROG_PYTHON
-PGAC_PATH_PYTHONDIR],
-[AC_MSG_RESULT(no)])
+PGAC_ARG_BOOL(with, python, no, [  --with-python           build Python interface module])
+AC_MSG_RESULT([$with_python])
 AC_SUBST(with_python)
 
 #
@@ -659,6 +656,12 @@ if test "$with_tk" = yes; then
     test -z "$WISH" && AC_MSG_ERROR(['wish' is required for Tk support])
 fi
 
+if test "$with_python" = yes; then
+  PGAC_PATH_PYTHON
+  PGAC_CHECK_PYTHON_MODULE_SETUP
+  PGAC_CHECK_PYTHON_EMBED_SETUP
+fi
+
 
 ##
 ## Libraries

doc/src/sgml/filelist.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.10 2001/05/08 19:14:52 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.11 2001/05/12 17:49:32 petere Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -75,6 +75,7 @@
 <!entity xoper      SYSTEM "xoper.sgml">
 <!entity xtypes     SYSTEM "xtypes.sgml">
 <!entity plperl     SYSTEM "plperl.sgml">
+<!entity plpython   SYSTEM "plpython.sgml">
 <!entity plsql      SYSTEM "plsql.sgml">
 <!entity pltcl      SYSTEM "pltcl.sgml">
 

doc/src/sgml/plpython.sgml

+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.1 2001/05/12 17:49:32 petere Exp $ -->
+
+<chapter id="plpython">
+ <title>PL/Python - Python Procedural Language</title>
+
+ <note>
+  <para>
+   This chapter is not fully developed yet.
+  </para>
+ </note>
+
+ <sect1 id="plpython-install">
+  <title>Installation</title>
+
+  <para>
+   ... needs to be worked out.
+  </para>
+ </sect1>
+
+ <sect1 id="plpython-using">
+  <title>Using</title>
+
+  <para>
+   There are sample functions in
+   <filename>plpython_function.sql</filename>.  The Python code you
+   write gets transformed into a function.  E.g.,
+<programlisting>
+CREATE FUNCTION myfunc(text) RETURNS text AS
+'return args[0]'
+LANGUAGE 'plpython';
+</programlisting>
+
+   gets transformed into
+
+<programlisting>
+def __plpython_procedure_myfunc_23456():
+	return args[0]
+</programlisting>
+
+   where 23456 is the Oid of the function.
+  </para>
+
+  <para>
+   If you do not provide a return value, Python returns the default
+   <symbol>None</symbol> which may or may not be what you want.  The
+   language module translates Python's None into SQL NULL.
+  </para>
+
+  <para>
+   PostgreSQL function variables are available in the global
+   <varname>args</varname> list.  In the <function>myfunc</function>
+   example, args[0] contains whatever was passed in as the text
+   argument.  For <literal>myfunc2(text, int4)</literal>, args[0]
+   would contain the text variable and args[1] the int4 variable.
+  </para>
+
+  <para>
+   The global dictionary SD is available to store data between
+   function calls.  This variable is private static data.  The global
+   dictionary GD is public data, available to all python functions
+   within a backend.  Use with care.  When the function is used in a
+   trigger, the triggers tuples are in TD["new"] and/or TD["old"]
+   depending on the trigger event.  Return 'None' or "OK" from the
+   python function to indicate the tuple is unmodified, "SKIP" to
+   abort the event, or "MODIFIED" to indicate you've modified the
+   tuple.  If the trigger was called with arguments they are available
+   in TD["args"][0] to TD["args"][(n -1)]
+  </para>
+
+  <para>
+   Each function gets its own restricted execution object in the
+   Python interpreter, so that global data and function arguments from
+   <function>myfunc</function> are not available to
+   <function>myfunc2</function>.  The exception is the data in the GD
+   dictionary, as mentioned above.
+  </para>
+
+  <para>
+   The PL/Python language module automatically imports a Python module
+   called <literal>plpy</literal>.  The functions and constants in
+   this module are available to you in the Python code as
+   <literal>plpy.<replaceable>foo</replaceable></literal>.  At present
+   <literal>plpy</literal> implements the functions
+   <literal>plpy.error("msg")</literal>,
+   <literal>plpy.fatal("msg")</literal>,
+   <literal>plpy.debug("msg")</literal>, and
+   <literal>plpy.notice("msg")</literal>.  They are mostly equivalent
+   to calling <literal>elog(<replaceable>LEVEL</>, "msg")</literal>,
+   where <replaceable>LEVEL</> is DEBUG, ERROR, FATAL or NOTICE.
+   <function>plpy.error</function> and <function>plpy.fatal</function>
+   actually raise a Python exception which, if uncaught, causes the
+   PL/Python module to call <literal>elog(ERROR, msg)</literal> when
+   the function handler returns from the Python interpreter.  Long
+   jumping out of the Python interpreter is probably not good.
+   <literal>raise plpy.ERROR("msg")</literal> and <literal>raise
+   plpy.FATAL("msg")</literal> are equivalent to calling
+   <function>plpy.error</function> or <function>plpy.fatal</function>.
+  </para>
+
+  <para>
+   Additionally, the plpy module provides two functions called
+   <function>execute</function> and <function>prepare</function>.
+   Calling <function>plpy.execute</function> with a query string, and
+   an optional limit argument, causes that query to be run, and the
+   result returned in a result object.  The result object emulates a
+   list or dictionary object.  The result object can be accessed by
+   row number, and field name.  It has these additional methods:
+   <function>nrows()</function> which returns the number of rows
+   returned by the query, and <function>status</function> which is the
+   <function>SPI_exec</function> return variable.  The result object
+   can be modified.
+
+<programlisting>
+rv = plpy.execute("SELECT * FROM my_table", 5)
+</programlisting>
+   returns up to 5 rows from my_table.  Ff my_table has a column
+   my_field it would be accessed as
+<programlisting>
+foo = rv[i]["my_field"]
+</programlisting>
+   The second function <function>plpy.prepare</function> is called
+   with a query string, and a list of argument types if you have bind
+   variables in the query.
+<programlisting>
+plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ])
+</programlisting>
+   text is the type of the variable you will be passing as $1.  After
+   preparing you use the function <function>plpy.execute</function> to
+   run it.
+<programlisting>
+rv = plpy.execute(plan, [ "name" ], 5)
+</programlisting>
+   The limit argument is optional in the call to
+   <function>plpy.execute</function>.
+  </para>
+
+  <para>
+   When you prepare a plan using the PL/Python module it is
+   automatically saved.  Read the SPI documentation (<xref
+   linkend="spi">) for a description of what this means.  The take
+   home message is if you do
+<programlisting>
+plan = plpy.prepare("SOME QUERY")
+plan = plpy.prepare("SOME OTHER QUERY")
+</programlisting>
+   you are leaking memory, as I know of no way to free a saved plan.
+   The alternative of using unsaved plans it even more painful (for
+   me).
+  </para>
+ </sect1>
+
+</chapter>

doc/src/sgml/programmer.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.36 2001/05/08 19:14:52 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.37 2001/05/12 17:49:32 petere Exp $
 
 PostgreSQL Programmer's Guide.
 -->
@@ -84,6 +84,7 @@ Disable it until we put in some info.
   &plsql;
   &pltcl;
   &plperl;
+  &plpython;
  </part>
 
 <![%single-book;[

src/Makefile.global.in

 # -*-makefile-*-
-# $Header: /cvsroot/pgsql/src/Makefile.global.in,v 1.126 2001/05/09 20:19:30 momjian Exp $
+# $Header: /cvsroot/pgsql/src/Makefile.global.in,v 1.127 2001/05/12 17:49:32 petere Exp $
 
 #------------------------------------------------------------------------------
 # All PostgreSQL makefiles include this file and use the variables it sets,
@@ -118,8 +118,12 @@ MULTIBYTE	= @MULTIBYTE@
 enable_shared	= @enable_shared@
 enable_rpath	= @enable_rpath@
 
-python_extmakefile = @python_extmakefile@
-python_moduledir = @python_moduledir@
+python_version		= @python_version@
+python_includedir	= @python_includedir@
+python_makefile_pre_in	= @python_makefile_pre_in@
+python_moduledir	= @python_moduledir@
+python_libspec		= @python_libspec@
+python_dynlibdir	= @python_dynlibdir@
 
 krb_srvtab = @krb_srvtab@
 

src/interfaces/python/GNUmakefile

@@ -4,7 +4,7 @@
 #
 # Written by Peter Eisentraut  <peter_e@gmx.net>
 #
-# $Header: /cvsroot/pgsql/src/interfaces/python/Attic/GNUmakefile,v 1.6 2001/03/25 19:44:03 petere Exp $
+# $Header: /cvsroot/pgsql/src/interfaces/python/Attic/GNUmakefile,v 1.7 2001/05/12 17:49:32 petere Exp $
 #
 #-------------------------------------------------------------------
 
@@ -22,7 +22,7 @@ libpq-all:
 Makefile: Setup.in Makefile.pre.in
 	$(MAKE) -f Makefile.pre.in boot srcdir=$(srcdir) VPATH=$(srcdir)
 
-Makefile.pre.in: $(python_extmakefile)
+Makefile.pre.in: $(python_makefile_pre_in)
 	cp $< $@
 
 Setup.in: Setup.in.raw

src/pl/plpython/Makefile

-# $Header: /cvsroot/pgsql/src/pl/plpython/Makefile,v 1.4 2001/05/12 01:30:30 petere Exp $
+# $Header: /cvsroot/pgsql/src/pl/plpython/Makefile,v 1.5 2001/05/12 17:49:32 petere Exp $
 
 subdir = src/pl/plpython
 top_builddir = ../../..
 include $(top_builddir)/src/Makefile.global
 
-# These things ought to go into $(top_srcdir)/config/python.m4 sometime.
 
-PYTHON_VERSION := $(shell $(PYTHON) -c  'import sys; print sys.version[:3]')
-PYTHON_INCLUDE := $(shell $(PYTHON) -c 'import sys; print sys.prefix')/include/python$(PYTHON_VERSION)
-
-override CPPFLAGS := -I$(srcdir) -I$(PYTHON_INCLUDE) $(CPPFLAGS)
-
-PYTHON_LIB := $(shell $(PYTHON) -c 'import sys; print sys.exec_prefix')/lib/python$(PYTHON_VERSION)
+override CPPFLAGS := -I$(srcdir) -I$(python_includedir) $(CPPFLAGS)
 
 NAME = plpython
 SO_MAJOR_VERSION = 0
 SO_MINOR_VERSION = 0
 OBJS = plpython.o
 
-# This static version might work on most ELF systems...
-SHLIB_LINK += $(PYTHON_LIB)/config/libpython$(PYTHON_VERSION).a
-# ...otherwise you need a shared version, but you need to build that yourself.
-#SHLIB_LINK += -lpython$(PYTHON_VERSION)
 
-# Python uses this.  Should become a configure check.
-SHLIB_LINK += -lpthread
+SHLIB_LINK += $(python_libspec)
+
+# If you have not patched the dynamic loader files as described in the
+# README you will have to link these in manually.  You may have to add
+# more modules.  If you have patched the loader, override
+# EXTRA_MODULES to be empty.
 
-# Python 2 seems to want libdb.
-#SHLIB_LINK += -ldb2
+# version 2.x
+ifneq (,$(findstring 2.,$(python_version)))
+EXTRA_MODULES = array cmath errno math md5 operator pcre sha time
+endif
 
+# version 1.x
+ifneq (,$(findstring 1.,$(python_version)))
+EXTRA_MODULES = arraymodule cmathmodule errnomodule mathmodule md5module operator shamodule timemodule
+endif
 
-# Hopefully you won't need this utter crap.  But if you can't patch
-# the appropriate dynloader file, try this.  You may have to add other
-# modules.
-#
-#DLDIR=$(PYTHON_LIB)/lib-dynload
-#DLHACK=$(DLDIR)/arraymodule.so $(DLDIR)/timemodule.so $(DLDIR)/cmathmodule.so $(DLDIR)/errnomodule.so $(DLDIR)/mathmodule.so $(DLDIR)/md5module.so $(DLDIR)/operator.so $(DLDIR)/shamodule.so
-#SHLIB_LINK += $(DLDIR)
+SHLIB_LINK += $(addprefix $(python_dynlibdir)/, $(addsuffix $(DLSUFFIX), $(EXTRA_MODULES)))
 
 include $(top_srcdir)/src/Makefile.shlib
 

src/pl/plpython/TODO

-<html>
-<head><title>TODO</title></head>
-<body bgcolor="white">
-In no special order<br>
-<li>allow arrays as function arguments and return values (almost done).
-<li>more and better documentation.
-<li>improve/automate configuration.
-<li>???
-</body>
\ No newline at end of file
+In no particular order...
+
+* Allow arrays as function arguments and return values.  (almost done)
+
+* Create a new restricted execution class that will allow me to pass
+  function arguments in as locals.  Passing them as globals means
+  functions cannot be called recursively.
+
+* Functions cache the input and output functions for their arguments,
+  so the following will make PostgreSQL unhappy:
+
+    create table users (first_name text, last_name text);
+    create function user_name(user) returns text as 'mycode' language 'plpython';
+    select user_name(user) from users;
+    alter table add column user_id integer;
+    select user_name(user) from users;
+
+  You have to drop and create the function(s) each time its arguments
+  are modified (not nice), or don't cache the input and output functions
+  (slower?), or check if the structure of the argument has been
+  altered (is this possible, easy, quick?) and recreate cache.
+
+* Better documentation
+
+* Add a DB-API compliant interface on top of the SPI interface.

src/pl/plpython/feature.expected

@@ -53,12 +53,12 @@ select import_test_two(users) from users where fname = 'willem';
  sha hash of willemdoe is 3cde6b574953b0ca937b4d76ebc40d534d910759
 (1 row)
 
-select argument_test_one(users, fname, lname) from users where lname = 'doe';
+select argument_test_one(users, fname, lname) from users where lname = 'doe' order by 1;
                                   argument_test_one                                  
 -------------------------------------------------------------------------------------
- willem doe => {'fname': 'willem', 'userid': 3, 'lname': 'doe', 'username': 'w_doe'}
- john doe => {'fname': 'john', 'userid': 2, 'lname': 'doe', 'username': 'johnd'}
  jane doe => {'fname': 'jane', 'userid': 1, 'lname': 'doe', 'username': 'j_doe'}
+ john doe => {'fname': 'john', 'userid': 2, 'lname': 'doe', 'username': 'johnd'}
+ willem doe => {'fname': 'willem', 'userid': 3, 'lname': 'doe', 'username': 'w_doe'}
 (3 rows)
 
 select nested_call_one('pass this along');

src/pl/plpython/plpython_test.sql

@@ -26,7 +26,7 @@ select import_test_two(users) from users where fname = 'willem';
 
 -- test multiple arguments
 --
-select argument_test_one(users, fname, lname) from users where lname = 'doe';
+select argument_test_one(users, fname, lname) from users where lname = 'doe' order by 1;
 
 
 -- spi and nested calls