From 425417d4989c4d576171b1dee24cd79dfb85a302 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 21 Oct 2006 18:33:05 +0000 Subject: [PATCH] Editorial improvements for recent plpython doc updates. --- doc/src/sgml/plpython.sgml | 69 ++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 36 deletions(-) diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml index 4a118ebd67..23e2dfeba9 100644 --- a/doc/src/sgml/plpython.sgml +++ b/doc/src/sgml/plpython.sgml @@ -1,4 +1,4 @@ - + PL/Python - Python Procedural Language @@ -61,11 +61,11 @@ $$ 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). + is called, its arguments are passed as elements of the array + args[]; named arguments are also passed 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). @@ -101,9 +101,9 @@ def __plpython_procedure_pymax_23456(): 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. + args[1] contains the second argument's + value. Alternatively, one can use named parameters as shown in the example + above. Use of named parameters is usually more readable. @@ -161,31 +161,27 @@ $$ LANGUAGE plpythonu; There are multiple ways to return row or composite types from a Python - scripts. In following examples we assume to have: + function. The following examples assume we have: -CREATE TABLE named_value ( - name text, - value integer -); - - or - CREATE TYPE named_value AS ( name text, value integer ); + A composite result can be returned as a: + - Sequence types (tuple or list), but not set (because + Sequence type (a tuple or list, but not a set because it is not indexable) - 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: CREATE FUNCTION make_pair (name text, value integer) @@ -196,7 +192,7 @@ AS $$ $$ LANGUAGE plpythonu; - To return SQL null in any column, insert None at + To return a SQL null for any column, insert None at the corresponding position. @@ -206,8 +202,8 @@ $$ LANGUAGE plpythonu; Mapping (dictionary) - Value for a composite type's column is retrieved from the mapping with - the column name as key. Example: + The value for each result type column is retrieved from the mapping + with the column name as key. Example: CREATE FUNCTION make_pair (name text, value integer) @@ -217,8 +213,9 @@ AS $$ $$ 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 + Any extra dictionary key/value pairs are ignored. Missing keys are + treated as errors. + To return a SQL null value for any column, insert None with the corresponding column name as the key. @@ -228,6 +225,7 @@ $$ LANGUAGE plpythonu; Object (any object providing method __getattr__) + This works the same as a mapping. Example: @@ -261,9 +259,9 @@ $$ LANGUAGE plpythonu; 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: + scalar or composite types. There are several ways to achieve this because + the returned object is internally turned into an iterator. The following + examples assume we have composite type: CREATE TYPE greeting AS ( @@ -272,10 +270,11 @@ CREATE TYPE greeting AS ( ); - Currently known iterable types are: + A set result can be returned from a: + - Sequence types (tuple, list, set) + Sequence type (tuple, list, set) @@ -341,9 +340,10 @@ $$ LANGUAGE plpythonu; bug #1483133, some debug versions of Python 2.4 (configured and compiled with option --with-pydebug) - are known to crash the PostgreSQL server. + are known to crash the PostgreSQL server + when using an iterator to return a set result. Unpatched versions of Fedora 4 contain this bug. - It does not happen in production version of Python or on patched + It does not happen in production versions of Python or on patched versions of Fedora 4. @@ -351,9 +351,6 @@ $$ LANGUAGE plpythonu; - - Whenever new iterable types are added to Python language, - PL/Python is ready to use it.