<!-- $PostgreSQL: pgsql/doc/src/sgml/plpython.sgml,v 1.34 2006/10/16 17:28:03 momjian Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/plpython.sgml,v 1.35 2006/10/21 18:33:05 tgl Exp $ -->

<chapter id="plpython">

<title>PL/Python - Python Procedural Language</title>

<para>

The body of a function is simply a Python script. When the function

is called,all unnamedarguments are passed as elementsto the array

<varname>args[]</varname> andnamed argumentsas ordinary variables to the

Python script. The result is returned from the Python code in the usual way,

with <literal>return</literal> or <literal>yield</literal> (in case of

a resultset statement).

is called,itsarguments are passed as elementsof the array

<varname>args[]</varname>;named argumentsare also passed as ordinary

variables to thePython script. The result is returned from the Python code

in the usual way,with <literal>return</literal> or

<literal>yield</literal> (in case ofa resultset statement).

</para>

<para>

the global <varname>args</varname> list. In the

<function>pymax</function> example, <varname>args[0]</varname> contains

whatever was passed in as the first argument and

<varname>args[1]</varname> contains the second argument's value. Alternatively,

one can use named parameters as shown in the example above. This greatly simplifies

the reading and writingof<application>PL/Python</application> code.

<varname>args[1]</varname> contains the second argument's

value. Alternatively,one can use named parameters as shown in the example

above. Useofnamed parameters is usually more readable.

</para>

<para>

<para>

There are multiple ways to return row or composite types from a Python

scripts. In following examplesweassumeto have:

function. The following examples assumewe have:

<programlisting>

CREATE TABLE named_value (

name text,

value integer

);

</programlisting>

or

<programlisting>

CREATE TYPE named_value AS (

name text,

value integer

);

</programlisting>

A composite result can be returned as a:

<variablelist>

<varlistentry>

<term>Sequencetypes (tuple or list), but not<literal>set</literal> (because

<term>Sequencetype (atuple or list, but notasetbecause

it is not indexable)</term>

<listitem>

<para>

Returned sequence objects must have the same number of items as

composite types have fields. Item with index 0 is assigned to the first field

of the composite type, 1 to second and so on. For example:

Returned sequence objects must have the same number of items as the

composite result type has fields. The item with index 0 is assigned to

the first field of the composite type, 1 to the second and so on. For

example:

<programlisting>

CREATE FUNCTION make_pair (name text, value integer)

$$ LANGUAGE plpythonu;

</programlisting>

To return SQL nullin any column, insert <symbol>None</symbol> at

To returnaSQL nullfor any column, insert <symbol>None</symbol> at

the corresponding position.

</para>

</listitem>

<term>Mapping (dictionary)</term>

<listitem>

<para>

Valuefora composite type's column is retrieved from the mapping with

the column name as key. Example:

The valueforeach result type column is retrieved from the mapping

withthe column name as key. Example:

<programlisting>

CREATE FUNCTION make_pair (name text, value integer)

$$ LANGUAGE plpythonu;

</programlisting>

Additional dictionary key/value pairs are ignored. Missing keys are

treated as errors, i.e. to return an SQL null value for any column, insert

Any extra dictionary key/value pairs are ignored. Missing keys are

treated as errors.

To return a SQL null value for any column, insert

<symbol>None</symbol> with the corresponding column name as the key.

</para>

</listitem>

<term>Object (any object providing method <literal>__getattr__</literal>)</term>

<listitem>

<para>

This works the same as a mapping.

Example:

<programlisting>

<para>

A <application>PL/Python</application> function can also return sets of

scalar or composite types. There areserveral ways to achieve this because

the returned object is internally turned into an iterator.For following

examples, let'sassumeto have composite type:

scalar or composite types. There areseveral ways to achieve this because

the returned object is internally turned into an iterator.The following

examplesassumewe have composite type:

<programlisting>

CREATE TYPE greeting AS (

);

</programlisting>

Currently known iterable types are:

A set result can be returned from a:

<variablelist>

<varlistentry>

<term>Sequencetypes (tuple, list, set)</term>

<term>Sequencetype (tuple, list, set)</term>

<listitem>

<para>

<programlisting>

<ulink url="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=1483133&amp;group_id=5470&amp;atid=105470">bug #1483133</ulink>,

some debug versions of Python 2.4

(configured and compiled with option <literal>--with-pydebug</literal>)

are known to crash the <productname>PostgreSQL</productname> server.

are known to crash the <productname>PostgreSQL</productname> server

when using an iterator to return a set result.

Unpatched versions of Fedora 4 contain this bug.

It does not happen in productionversion of Python or on patched

It does not happen in productionversions of Python or on patched

versions of Fedora 4.

</para>

</warning>

</para>

</listitem>

</varlistentry>

</variablelist>

Whenever new iterable types are added to Python language,

<application>PL/Python</application> is ready to use it.

</para>

<para>