PostgreSQL 8.2beta1 Documentation | ||||
---|---|---|---|---|
Prev | Fast Backward | Chapter 39. PL/Python - Python Procedural Language | Fast Forward | Next |
Functions in PL/Python are declared via the standard CREATE FUNCTION syntax:
CREATE FUNCTION funcname (argument-list) RETURNS return-type AS $$ # PL/Python function body $$ LANGUAGE plpythonu;
The body of a function is simply a Python script. When the function is called, all unnamed arguments are passed as elements to the array args[] and named arguments as ordinary variables to the Python script. The result is returned from the Python code in the usual way, with return or yield (in case of a resultset statement).
For example, a function to return the greater of two integers can be defined as:
CREATE FUNCTION pymax (a integer, b integer) RETURNS integer AS $$ if a > b: return a return b $$ LANGUAGE plpythonu;
The Python code that is given as the body of the function definition is transformed into a Python function. For example, the above results in
def __plpython_procedure_pymax_23456(): if a > b: return a return b
assuming that 23456 is the OID assigned to the function by PostgreSQL.
The PostgreSQL function parameters are available in
the global args list. In the
pymax
example, args[0] contains
whatever was passed in as the first argument and
args[1] contains the second argument's value. Alternatively,
one can use named parameters as shown in the example above. This greatly simplifies
the reading and writing of PL/Python code.
If an SQL null value is passed to a function, the argument value will appear as None in Python. The above function definition will return the wrong answer for null inputs. We could add STRICT to the function definition to make PostgreSQL do something more reasonable: if a null value is passed, the function will not be called at all, but will just return a null result automatically. Alternatively, we could check for null inputs in the function body:
CREATE FUNCTION pymax (a integer, b integer) RETURNS integer AS $$ if (a is None) or (b is None): return None if a > b: return a return b $$ LANGUAGE plpythonu;
As shown above, to return an SQL null value from a PL/Python function, return the value None. This can be done whether the function is strict or not.
Composite-type arguments are passed to the function as Python mappings. The element names of the mapping are the attribute names of the composite type. If an attribute in the passed row has the null value, it has the value None in the mapping. Here is an example:
CREATE TABLE employee ( name text, salary integer, age integer ); CREATE FUNCTION overpaid (e employee) RETURNS boolean AS $$ if e["salary"] > 200000: return True if (e["age"] < 30) and (e["salary"] > 100000): return True return False $$ LANGUAGE plpythonu;
There are multiple ways to return row or composite types from a Python scripts. In following examples we assume to have:
CREATE TABLE named_value ( name text, value integer );
or
CREATE TYPE named_value AS ( name text, value integer );
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:
CREATE FUNCTION make_pair (name text, value integer) RETURNS named_value AS $$ return [ name, value ] # or alternatively, as tuple: return ( name, value ) $$ LANGUAGE plpythonu;
To return SQL null in any column, insert None at the corresponding position.
Value for a composite type's column is retrieved from the mapping with the column name as key. Example:
CREATE FUNCTION make_pair (name text, value integer) RETURNS named_value AS $$ return { "name": name, "value": value } $$ LANGUAGE plpythonu;
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 None with the corresponding column name as the key.
Example:
CREATE FUNCTION make_pair (name text, value integer) RETURNS named_value AS $$ class named_value: def __init__ (self, n, v): self.name = n self.value = v return named_value(name, value) # or simply class nv: pass nv.name = name nv.value = value return nv $$ LANGUAGE plpythonu;
If you do not provide a return value, Python returns the default None. PL/Python translates Python's None into the SQL null value.
A PL/Python function can also return sets of scalar or composite types. There are serveral ways to achieve this because the returned object is internally turned into an iterator. For following examples, let's assume to have composite type:
CREATE TYPE greeting AS ( how text, who text );
Currently known iterable types are:
CREATE FUNCTION greet (how text) RETURNS SETOF greeting AS $$ # return tuple containing lists as composite types # all other combinations work also return ( [ how, "World" ], [ how, "PostgreSQL" ], [ how, "PL/Python" ] ) $$ LANGUAGE plpythonu;
CREATE FUNCTION greet (how text) RETURNS SETOF greeting AS $$ class producer: def __init__ (self, how, who): self.how = how self.who = who self.ndx = -1 def __iter__ (self): return self def next (self): self.ndx += 1 if self.ndx == len(self.who): raise StopIteration return ( self.how, self.who[self.ndx] ) return producer(how, [ "World", "PostgreSQL", "PL/Python" ]) $$ LANGUAGE plpythonu;
CREATE FUNCTION greet (how text) RETURNS SETOF greeting AS $$ for who in [ "World", "PostgreSQL", "PL/Python" ]: yield ( how, who ) $$ LANGUAGE plpythonu;
Warning |
Currently, due to Python bug #1483133, some debug versions of Python 2.4 (configured and compiled with option --with-pydebug) are known to crash the PostgreSQL server. Unpatched versions of Fedora 4 contain this bug. It does not happen in production version of Python or on patched versions of Fedora 4. |
Whenever new iterable types are added to Python language, PL/Python is ready to use it.
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 session. Use with care.
Each function gets its own execution environment in the
Python interpreter, so that global data and function arguments from
myfunc
are not available to
myfunc2
. The exception is the data in the
GD dictionary, as mentioned above.