Add documentation why reassigning PL/Python function parameters in the

function body can have undesirable outcomes. (bug #5232)

diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index 01feab8ec1accab9313154b51fe19c10adf664cc..a623f3509bd56889a7017767c70882aa70b89513 100644 (file)
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  PL/Python - Python Procedural Language
@@ -213,6 +213,42 @@ def __plpython_procedure_pymax_23456():
    above.  Use of named parameters is usually more readable.
   
 
+  
+   The arguments are set as global variables.  Because of the scoping
+   rules of Python, this has the subtle consequence that an argument
+   variable cannot be reassigned inside the function to the value of
+   an expression that involves the variable name itself, unless the
+   variable is redeclared as global in the block.  For example, the
+   following won't work:
+
+CREATE FUNCTION pystrip(x text)
+  RETURNS text
+AS $$
+  x = x.strip()  # error
+  return x
+$$ LANGUAGE plpythonu;
+
+   because assigning to x
+   makes x a local variable for the entire block,
+   and so the x on the right-hand side of the
+   assignment refers to a not-yet-assigned local
+   variable x, not the PL/Python function
+   parameter.  Using the global statement, this can
+   be made to work:
+
+CREATE FUNCTION pystrip(x text)
+  RETURNS text
+AS $$
+  global x
+  x = x.strip()  # ok now
+  return x
+$$ LANGUAGE plpythonu;
+
+   But it is advisable not to rely on this implementation detail of
+   PL/Python.  It is better to treat the function parameters as
+   read-only.
+  
+
   
    If an SQL null valuenull value
    sortas="PL/Python">PL/Python is passed to a