From 0f48e0675134eccd905eaf696a03c1e8cc85eab4 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Mon, 16 Apr 2012 11:30:32 +0300
Subject: [PATCH] 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                |  7 ++-
 src/pl/plpython/expected/plpython_spi.out | 58 +++++++++++++++++++++++
 src/pl/plpython/sql/plpython_spi.sql      | 22 +++++++++
 3 files changed, 86 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index a39438836fd..cc5c7efbe00 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/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>
diff --git a/src/pl/plpython/expected/plpython_spi.out b/src/pl/plpython/expected/plpython_spi.out
index f3709aeb882..631a1a44255 100644
--- a/src/pl/plpython/expected/plpython_spi.out
+++ b/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")
diff --git a/src/pl/plpython/sql/plpython_spi.sql b/src/pl/plpython/sql/plpython_spi.sql
index d8457ce98c5..ce218e93b6d 100644
--- a/src/pl/plpython/sql/plpython_spi.sql
+++ b/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
 
-- 
GitLab