From 425417d4989c4d576171b1dee24cd79dfb85a302 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
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 4a118ebd67f..23e2dfeba9d 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1,4 +1,4 @@
-<!-- $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>
@@ -61,11 +61,11 @@ $$ LANGUAGE plpythonu;
<para>
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
- <varname>args[]</varname> and named arguments as 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, its arguments are passed as elements of the array
+ <varname>args[]</varname>; 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 <literal>return</literal> or
+ <literal>yield</literal> (in case of a resultset statement).
</para>
<para>
@@ -101,9 +101,9 @@ def __plpython_procedure_pymax_23456():
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 writing of <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. Use of named parameters is usually more readable.
</para>
<para>
@@ -161,31 +161,27 @@ $$ LANGUAGE plpythonu;
<para>
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:
<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>Sequence types (tuple or list), but not <literal>set</literal> (because
+ <term>Sequence type (a tuple or list, but not a set because
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)
@@ -196,7 +192,7 @@ AS $$
$$ LANGUAGE plpythonu;
</programlisting>
- To return SQL null in any column, insert <symbol>None</symbol> at
+ To return a SQL null for any column, insert <symbol>None</symbol> at
the corresponding position.
</para>
</listitem>
@@ -206,8 +202,8 @@ $$ LANGUAGE plpythonu;
<term>Mapping (dictionary)</term>
<listitem>
<para>
- 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:
<programlisting>
CREATE FUNCTION make_pair (name text, value integer)
@@ -217,8 +213,9 @@ AS $$
$$ 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>
@@ -228,6 +225,7 @@ $$ LANGUAGE plpythonu;
<term>Object (any object providing method <literal>__getattr__</literal>)</term>
<listitem>
<para>
+ This works the same as a mapping.
Example:
<programlisting>
@@ -261,9 +259,9 @@ $$ LANGUAGE plpythonu;
<para>
A <application>PL/Python</application> 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:
<programlisting>
CREATE TYPE greeting AS (
@@ -272,10 +270,11 @@ CREATE TYPE greeting AS (
);
</programlisting>
- Currently known iterable types are:
+ A set result can be returned from a:
+
<variablelist>
<varlistentry>
- <term>Sequence types (tuple, list, set)</term>
+ <term>Sequence type (tuple, list, set)</term>
<listitem>
<para>
<programlisting>
@@ -341,9 +340,10 @@ $$ LANGUAGE plpythonu;
<ulink url="http://sourceforge.net/tracker/index.php?func=detail&aid=1483133&group_id=5470&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 production version of Python or on patched
+ It does not happen in production versions of Python or on patched
versions of Fedora 4.
</para>
</warning>
@@ -351,9 +351,6 @@ $$ LANGUAGE plpythonu;
</listitem>
</varlistentry>
</variablelist>
-
- Whenever new iterable types are added to Python language,
- <application>PL/Python</application> is ready to use it.
</para>
<para>
--
GitLab