From ad6ee8a5a436d7c765e1a800a8784027326fe3b5 Mon Sep 17 00:00:00 2001
From: Catalin Iacob <iacobcatalin@gmail.com>
Date: Tue, 2 Feb 2016 07:29:27 +0100
Subject: [PATCH 3/3] Improve docs

Write about the new preferred functions first and about the old ones
mention only how they behave differently and discourage their use.
---
 doc/src/sgml/plpython.sgml | 59 +++++++++++++++++++---------------------------
 1 file changed, 24 insertions(+), 35 deletions(-)

diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index 705413e..a215f0a 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1341,13 +1341,15 @@ $$ LANGUAGE plpythonu;
   <title>Utility Functions</title>
   <para>
    The <literal>plpy</literal> module also provides the functions
-   <literal>plpy.debug(<replaceable>msg</>)</literal>,
-   <literal>plpy.log(<replaceable>msg</>)</literal>,
-   <literal>plpy.info(<replaceable>msg</>)</literal>,
-   <literal>plpy.notice(<replaceable>msg</>)</literal>,
-   <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>
+   <literal>plpy.raise_debug(<replaceable>*args, **kwargs</>)</literal>,
+   <literal>plpy.raise_log(<replaceable>*args, **kwargs</>)</literal>,
+   <literal>plpy.raise_info(<replaceable>*args, **kwargs</>)</literal>,
+   <literal>plpy.raise_notice(<replaceable>*args, **kwargs</>)</literal>,
+   <literal>plpy.raise_warning(<replaceable>*args, **kwargs</>)</literal>,
+   <literal>plpy.raise_error(<replaceable>*args, **kwargs</>)</literal>, and
+   <literal>plpy.raise_fatal(<replaceable>*args, **kwargs</>)</literal>.<indexterm><primary>elog</><secondary>in PL/Python</></indexterm>
+   They accept these positional or keyword arguments:
+   <literal><replaceable>message</replaceable> [, <replaceable>detail</replaceable> [, <replaceable>hint</replaceable> [, <replaceable>sqlstate</replaceable>  [, <replaceable>schema</replaceable>  [, <replaceable>table</replaceable>  [, <replaceable>column</replaceable>  [, <replaceable>datatype</replaceable>  [, <replaceable>constraint</replaceable> ]]]]]]]]</literal>.
    <function>plpy.error</function> and
    <function>plpy.fatal</function> actually raise a Python exception
    which, if uncaught, propagates out to the calling query, causing
@@ -1355,8 +1357,8 @@ $$ LANGUAGE plpythonu;
    <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.
+   <function>plpy.raise_error(<replaceable>msg</>)</function> and
+   <function>plpy.raise_fatal(<replaceable>msg</>)</function>, respectively.
    The other functions only generate messages of different
    priority levels.
    Whether messages of a particular priority are reported to the client,
@@ -1367,32 +1369,19 @@ $$ LANGUAGE plpythonu;
   </para>
 
   <para>
-   The <literal>plpy</literal> module also provides the functions
-   <literal>plpy.raise_debug(<replaceable>args</>)</literal>,
-   <literal>plpy.raise_log(<replaceable>args</>)</literal>,
-   <literal>plpy.raise_info(<replaceable>args</>)</literal>,
-   <literal>plpy.raise_notice(<replaceable>args</>)</literal>,
-   <literal>plpy.raise_warning(<replaceable>args</>)</literal>,
-   <literal>plpy.raise_error(<replaceable>args</>)</literal>, and
-   <literal>plpy.raise_fatal(<replaceable>args</>)</literal>.<indexterm><primary>elog</><secondary>in PL/Python</></indexterm>
-   <function>plpy.raise_error</function> and
-   <function>plpy.raise_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.raise_error</function> and
-   <function>plpy.raise_fatal</function>, respectively.
-   The other functions only 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
-   <xref linkend="guc-log-min-messages"> and
-   <xref linkend="guc-client-min-messages"> configuration
-   variables. See <xref linkend="runtime-config"> for more information.
-   These functions allows to using keyword parameters:
-   <literal>[ <replaceable>message</replaceable> [, <replaceable>detail</replaceable> [, <replaceable>hint</replaceable> [, <replaceable>sqlstate</replaceable>  [, <replaceable>schema</replaceable>  [, <replaceable>table</replaceable>  [, <replaceable>column</replaceable>  [, <replaceable>datatype</replaceable>  [, <replaceable>constraint</replaceable> ]]]]]]]]]</literal>.
+   For backward compatibility, the <literal>plpy</literal> module provides the
+   deprecated functions
+   <literal>plpy.debug(<replaceable>msg</>)</literal>,
+   <literal>plpy.log(<replaceable>msg</>)</literal>,
+   <literal>plpy.info(<replaceable>msg</>)</literal>,
+   <literal>plpy.notice(<replaceable>msg</>)</literal>,
+   <literal>plpy.warning(<replaceable>msg</>)</literal>,
+   <literal>plpy.error(<replaceable>msg</>)</literal>, and
+   <literal>plpy.fatal(<replaceable>msg</>)</literal>.
+   They work similarly to their raise counterparts except they only support
+   a <replaceable>message</replaceable> argument. If multiple arguments are
+   passed, they are bundled in a tuple whose string representation is sent
+   as <replaceable>message</replaceable>.
   </para>
 
   <para>
-- 
2.7.0