From ad6ee8a5a436d7c765e1a800a8784027326fe3b5 Mon Sep 17 00:00:00 2001 From: Catalin Iacob 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; Utility Functions The plpy module also provides the functions - plpy.debug(msg), - plpy.log(msg), - plpy.info(msg), - plpy.notice(msg), - plpy.warning(msg), - plpy.error(msg), and - plpy.fatal(msg).elogin PL/Python + plpy.raise_debug(*args, **kwargs), + plpy.raise_log(*args, **kwargs), + plpy.raise_info(*args, **kwargs), + plpy.raise_notice(*args, **kwargs), + plpy.raise_warning(*args, **kwargs), + plpy.raise_error(*args, **kwargs), and + plpy.raise_fatal(*args, **kwargs).elogin PL/Python + They accept these positional or keyword arguments: + message [, detail [, hint [, sqlstate [, schema [, table [, column [, datatype [, constraint ]]]]]]]]. plpy.error and plpy.fatal actually raise a Python exception which, if uncaught, propagates out to the calling query, causing @@ -1355,8 +1357,8 @@ $$ LANGUAGE plpythonu; raise plpy.Error(msg) and raise plpy.Fatal(msg) are equivalent to calling - plpy.error and - plpy.fatal, respectively. + plpy.raise_error(msg) and + plpy.raise_fatal(msg), 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; - The plpy module also provides the functions - plpy.raise_debug(args), - plpy.raise_log(args), - plpy.raise_info(args), - plpy.raise_notice(args), - plpy.raise_warning(args), - plpy.raise_error(args), and - plpy.raise_fatal(args).elogin PL/Python - plpy.raise_error and - plpy.raise_fatal actually raise a Python exception - which, if uncaught, propagates out to the calling query, causing - the current transaction or subtransaction to be aborted. - raise plpy.Error(msg) and - raise plpy.Fatal(msg) are - equivalent to calling - plpy.raise_error and - plpy.raise_fatal, 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 - and - configuration - variables. See for more information. - These functions allows to using keyword parameters: - [ message [, detail [, hint [, sqlstate [, schema [, table [, column [, datatype [, constraint ]]]]]]]]]. + For backward compatibility, the plpy module provides the + deprecated functions + plpy.debug(msg), + plpy.log(msg), + plpy.info(msg), + plpy.notice(msg), + plpy.warning(msg), + plpy.error(msg), and + plpy.fatal(msg). + They work similarly to their raise counterparts except they only support + a message argument. If multiple arguments are + passed, they are bundled in a tuple whose string representation is sent + as message. -- 2.7.0