PL/Python: Improve documentation of nrows() method

Clarify that nrows() is the number of rows processed, versus the
number of rows returned, which can be obtained using len.  Also add
tests about that.

doc/src/sgml/plpython.sgml

@@ -903,6 +903,8 @@ rv = plpy.execute("SELECT * FROM my_table", 5)
 <programlisting>
 foo = rv[i]["my_column"]
 </programlisting>
+      The number of rows returned can be obtained using the built-in
+      <function>len</function> function.
      </para>
 
      <para>
@@ -912,7 +914,10 @@ foo = rv[i]["my_column"]
         <term><literal><function>nrows</function>()</literal></term>
         <listitem>
          <para>
-          Returns the number of rows returned or processed by the query.
+          Returns the number of rows processed by the command.  Note that this
+          is not necessarily the same as the number of rows returned.  For
+          example, an <command>UPDATE</command> command will set this value but
+          won't return any rows (unless <literal>RETURNING</literal> is used).
          </para>
         </listitem>
        </varlistentry>

src/pl/plpython/expected/plpython_spi.out

@@ -150,6 +150,64 @@ CONTEXT:  Traceback (most recent call last):
   PL/Python function "result_metadata_test", line 6, in <module>
     plpy.info(result.colnames())
 PL/Python function "result_metadata_test"
+CREATE FUNCTION result_nrows_test(cmd text) RETURNS int
+AS $$
+result = plpy.execute(cmd)
+return result.nrows()
+$$ LANGUAGE plpythonu;
+SELECT result_nrows_test($$SELECT 1$$);
+ result_nrows_test 
+-------------------
+                 1
+(1 row)
+
+SELECT result_nrows_test($$CREATE TEMPORARY TABLE foo2 (a int, b text)$$);
+ result_nrows_test 
+-------------------
+                 0
+(1 row)
+
+SELECT result_nrows_test($$INSERT INTO foo2 VALUES (1, 'one'), (2, 'two')$$);
+ result_nrows_test 
+-------------------
+                 2
+(1 row)
+
+SELECT result_nrows_test($$UPDATE foo2 SET b = '' WHERE a = 2$$);
+ result_nrows_test 
+-------------------
+                 1
+(1 row)
+
+CREATE FUNCTION result_len_test(cmd text) RETURNS int
+AS $$
+result = plpy.execute(cmd)
+return len(result)
+$$ LANGUAGE plpythonu;
+SELECT result_len_test($$SELECT 1$$);
+ result_len_test 
+-----------------
+               1
+(1 row)
+
+SELECT result_len_test($$CREATE TEMPORARY TABLE foo3 (a int, b text)$$);
+ result_len_test 
+-----------------
+               0
+(1 row)
+
+SELECT result_len_test($$INSERT INTO foo3 VALUES (1, 'one'), (2, 'two')$$);
+ result_len_test 
+-----------------
+               0
+(1 row)
+
+SELECT result_len_test($$UPDATE foo3 SET b= '' WHERE a = 2$$);
+ result_len_test 
+-----------------
+               0
+(1 row)
+
 -- cursor objects
 CREATE FUNCTION simple_cursor_test() RETURNS int AS $$
 res = plpy.cursor("select fname, lname from users")

src/pl/plpython/sql/plpython_spi.sql

@@ -110,6 +110,28 @@ $$ LANGUAGE plpythonu;
 SELECT result_metadata_test($$SELECT 1 AS foo, '11'::text AS bar UNION SELECT 2, '22'$$);
 SELECT result_metadata_test($$CREATE TEMPORARY TABLE foo1 (a int, b text)$$);
 
+CREATE FUNCTION result_nrows_test(cmd text) RETURNS int
+AS $$
+result = plpy.execute(cmd)
+return result.nrows()
+$$ LANGUAGE plpythonu;
+
+SELECT result_nrows_test($$SELECT 1$$);
+SELECT result_nrows_test($$CREATE TEMPORARY TABLE foo2 (a int, b text)$$);
+SELECT result_nrows_test($$INSERT INTO foo2 VALUES (1, 'one'), (2, 'two')$$);
+SELECT result_nrows_test($$UPDATE foo2 SET b = '' WHERE a = 2$$);
+
+CREATE FUNCTION result_len_test(cmd text) RETURNS int
+AS $$
+result = plpy.execute(cmd)
+return len(result)
+$$ LANGUAGE plpythonu;
+
+SELECT result_len_test($$SELECT 1$$);
+SELECT result_len_test($$CREATE TEMPORARY TABLE foo3 (a int, b text)$$);
+SELECT result_len_test($$INSERT INTO foo3 VALUES (1, 'one'), (2, 'two')$$);
+SELECT result_len_test($$UPDATE foo3 SET b= '' WHERE a = 2$$);
+
 
 -- cursor objects