On Wed, Nov 10, 2010 at 16:07, Euler Taveira de Oliveira <[email protected]> wrote: > Sure. But bear in mind that we don't usually backpatch documentation unless > there is incorrect information; improvement belongs to HEAD.
Yeah, it is quite incorrect (as you can see by comparing test results from 1st post with the documentation). Attached is a documentation patch that will apply to PostgreSQL 8.1 - 8.4 Regards, Marti
From 190d58287b750ad7492485faaf829f262b93e39e Mon Sep 17 00:00:00 2001 From: Marti Raudsepp <[email protected]> Date: Sun, 14 Nov 2010 11:24:43 +0200 Subject: [PATCH] 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 4944b8a..d567f10 100644 --- a/doc/src/sgml/plpython.sgml +++ b/doc/src/sgml/plpython.sgml @@ -428,16 +428,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 @@ -536,6 +527,25 @@ $$ LANGUAGE plpythonu; <literal>struct</>, <literal>time</>, <literal>whrandom</>, and <literal>zlib</>. </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> ]]> -- 1.7.3.2
-- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
