From a9a83614624760d5adc4d0d31f9daa245b88cd72 Mon Sep 17 00:00:00 2001
From: Marti Raudsepp <marti@juffo.org>
Date: Tue, 9 Nov 2010 18:19:50 +0200
Subject: [PATCH 1/2] Document current PL/Python exception raising semantics

---
 doc/src/sgml/plpython.sgml |   30 ++++++++++++++++++++----------
 1 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index 9fc8808..320faab 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -950,16 +950,7 @@ $$ LANGUAGE plpythonu;
    <literal>plpy.warning(<replaceable>msg</>)</literal>,
    <literal>plpy.error(<replaceable>msg</>)</literal>, and
    <literal>plpy.fatal(<replaceable>msg</>)</literal>.<indexterm><primary>elog</><secondary>in PL/Python</></indexterm>
-   <function>plpy.error</function> and
-   <function>plpy.fatal</function> actually raise a Python exception
-   which, if uncaught, propagates out to the calling query, causing
-   the current transaction or subtransaction to be aborted.
-   <literal>raise plpy.Error(<replaceable>msg</>)</literal> and
-   <literal>raise plpy.Fatal(<replaceable>msg</>)</literal> are
-   equivalent to calling
-   <function>plpy.error</function> and
-   <function>plpy.fatal</function>, respectively.
-   The other functions only generate messages of different
+   These functions generate messages of different
    priority levels.
    Whether messages of a particular priority are reported to the client,
    written to the server log, or both is controlled by the
@@ -967,6 +958,25 @@ $$ LANGUAGE plpythonu;
    <xref linkend="guc-client-min-messages"> configuration
    variables. See <xref linkend="runtime-config"> for more information.
   </para>
+
+  <para>
+   The <function>plpy.error</function> function actually raises a Python
+   exception which propagates out to the calling query, causing the current
+   transaction or subtransaction to be aborted.  If multiple calls are made,
+   only the last message is reported.  The exception has caveats: these errors
+   cannot be silenced by an except block, and Python exceptions raised in
+   except blocks will not be reported.  The <function>plpy.fatal</function>
+   function immediately aborts execution and terminates the client connection.
+  </para>
+
+  <para>
+   To raise catchable errors, use
+   <literal>raise plpy.Error(<replaceable>msg</>)</literal>,
+   <literal>raise plpy.Fatal(<replaceable>msg</>)</literal> or native Python
+   exceptions.  These have Python exception semantics.  However, an unhandled
+   <literal>plpy.Fatal</literal> will still cause a PostgreSQL ERROR message to
+   be emitted.
+  </para>
  </sect1>
 
  <sect1 id="plpython-envar">
-- 
1.7.3.2