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.
This commit is contained in:
Peter Eisentraut 2001-05-12 17:49:32 +00:00
parent 02549a2d2c
commit bbc3920fe9
12 changed files with 738 additions and 498 deletions

View File

@ -1,50 +1,88 @@
#
# 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_PATH_PYTHONDIR
# -------------------
# Finds the names of various install dirs and helper files
# necessary to build a Python extension module.
# _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_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_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"
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)
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

861
configure vendored

File diff suppressed because it is too large Load Diff

View File

@ -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

View File

@ -1,4 +1,4 @@
<!-- $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">

152
doc/src/sgml/plpython.sgml Normal file
View File

@ -0,0 +1,152 @@
<!-- $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>

View File

@ -1,5 +1,5 @@
<!--
$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;[

View File

@ -1,5 +1,5 @@
# -*-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@

View File

@ -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

View File

@ -1,42 +1,36 @@
# $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)
# Python 2 seems to want libdb.
#SHLIB_LINK += -ldb2
# 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.
# version 2.x
ifneq (,$(findstring 2.,$(python_version)))
EXTRA_MODULES = array cmath errno math md5 operator pcre sha time
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)
# version 1.x
ifneq (,$(findstring 1.,$(python_version)))
EXTRA_MODULES = arraymodule cmathmodule errnomodule mathmodule md5module operator shamodule timemodule
endif
SHLIB_LINK += $(addprefix $(python_dynlibdir)/, $(addsuffix $(DLSUFFIX), $(EXTRA_MODULES)))
include $(top_srcdir)/src/Makefile.shlib

View File

@ -1,9 +1,25 @@
<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>
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.

View File

@ -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');

View File

@ -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