From d3099184251441370553226912e457129c6c1d2f Mon Sep 17 00:00:00 2001
From: Changaco <changaco@changaco.oy.lc>
Date: Fri, 20 Sep 2019 14:47:29 +0200
Subject: [PATCH] add the new row type to the documentation

---
 doc/src/extras.rst | 35 +++++++++++++++++++++++++++++++++++
 lib/extras.py      | 13 +++----------
 2 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/doc/src/extras.rst b/doc/src/extras.rst
index aa316d2e..5185c73b 100644
--- a/doc/src/extras.rst
+++ b/doc/src/extras.rst
@@ -97,6 +97,10 @@ Real dictionary cursor
 `namedtuple` cursor
 ^^^^^^^^^^^^^^^^^^^^
 
+This type of cursor is especially well suited if you need to fetch and process a
+large number of similar rows at once, because tuples occupy less memory than
+dicts.
+
 .. versionadded:: 2.3
 
 .. autoclass:: NamedTupleCursor
@@ -110,6 +114,37 @@ Real dictionary cursor
         `!NamedTupleConnection`.
 
 
+.. index::
+    pair: Cursor; Row
+
+`Row` cursor
+^^^^^^^^^^^^
+
+This type of cursor is especially well suited if you want rows to be mutable.
+
+The rows support both dict-style and attribute-style lookups and assignments, in
+addition to index-based lookups. However, index-based assigments aren't allowed.
+
+    >>> cur = conn.cursor(cursor_factory=psycopg2.extras.HybridRowCursor)
+    >>> cur.execute("SELECT 1 as key, 'foo' as value")
+    >>> row = cur.fetchone()
+    >>> row[0] == row['key'] == row.key == 1
+    True
+    >>> key, value = row
+    >>> (key, value)
+    (1, 'foo')
+    >>> row.value = 'bar'
+    >>> row.timestamp = '2019-09-20 13:15:22.060537+00'
+    >>> row
+    Row(key=1, value='bar', timestamp='2019-09-20 13:15:22.060537+00')
+
+.. versionadded:: 2.9
+
+.. autoclass:: HybridRowCursor
+
+.. autoclass:: HybridRow
+
+
 .. index::
     pair: Cursor; Logging
 
diff --git a/lib/extras.py b/lib/extras.py
index 36a1ea19..2988640d 100644
--- a/lib/extras.py
+++ b/lib/extras.py
@@ -403,16 +403,9 @@ NamedTupleCursor._cached_make_nt = classmethod(_cached_make_nt)
 class HybridRow(object):
     """A versatile row type.
 
-    This class implements both dict-style and attribute-style lookups and
-    assignments, in addition to index-based lookups. However, index-based
-    assigments aren't allowed.
-
-    Assignments aren't limited to the initial columns, extra attributes can be
-    added.
-
-    Beware that although hybrid rows support dict-style lookups and assigments,
-    they do not have the standard :class:`dict` methods (:meth:`~dict.get`,
-    :meth:`~dict.items`, etc.).
+    Although hybrid rows support item lookups and assigments, they are not
+    instances of the :class:`dict` class and they don't have its methods
+    (:meth:`~dict.get`, :meth:`~dict.items`, etc.).
 
     """