Return Row for CursorResult.inserted_primary_key

The tuple returned by :attr:`.CursorResult.inserted_primary_key` is now a
:class:`_result.Row` object with a named tuple interface on top of the
existing tuple interface.

Fixes: #3314
Change-Id: I85677ef60d8329648f368bf497f634758f4e087b

2 files changed, 33 insertions, 17 deletions

diff --git a/lib/sqlalchemy/engine/cursor.py b/lib/sqlalchemy/engine/cursor.py
index 6fcd18b49..ff9dd0d6a 100644
--- a/lib/sqlalchemy/engine/cursor.py
+++ b/lib/sqlalchemy/engine/cursor.py
@@ -1413,22 +1413,28 @@ class BaseCursorResult(object):
     def inserted_primary_key(self):
         """Return the primary key for the row just inserted.
 
-        The return value is a list of scalar values
-        corresponding to the list of primary key columns
-        in the target table.
+        The return value is a :class:`_result.Row` object representing
+        a named tuple of primary key values in the order in which the
+        primary key columns are configured in the source
+        :class:`_schema.Table`.
 
-        This only applies to single row :func:`_expression.insert`
+        .. versionchanged:: 1.4.8 - the
+           :attr:`_engine.CursorResult.inserted_primary_key`
+           value is now a named tuple via the :class:`_result.Row` class,
+           rather than a plain tuple.
+
+        This accessor only applies to single row :func:`_expression.insert`
         constructs which did not explicitly specify
-        :meth:`_expression.Insert.returning`.
-
-        Note that primary key columns which specify a
-        server_default clause,
-        or otherwise do not qualify as "autoincrement"
-        columns (see the notes at :class:`_schema.Column`), and were
-        generated using the database-side default, will
-        appear in this list as ``None`` unless the backend
-        supports "returning" and the insert statement executed
-        with the "implicit returning" enabled.
+        :meth:`_expression.Insert.returning`.    Support for multirow inserts,
+        while not yet available for most backends, would be accessed using
+        the :attr:`_engine.CursorResult.inserted_primary_key_rows` accessor.
+
+        Note that primary key columns which specify a server_default clause, or
+        otherwise do not qualify as "autoincrement" columns (see the notes at
+        :class:`_schema.Column`), and were generated using the database-side
+        default, will appear in this list as ``None`` unless the backend
+        supports "returning" and the insert statement executed with the
+        "implicit returning" enabled.
 
         Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
         statement is not a compiled expression construct
diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index 9aa747056..8eefa10d1 100644
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -1235,7 +1235,10 @@ class SQLCompiler(Compiled):
         )
 
     @util.memoized_property
+    @util.preload_module("sqlalchemy.engine.result")
     def _inserted_primary_key_from_lastrowid_getter(self):
+        result = util.preloaded.engine_result
+
         key_getter = self._key_getters_for_crud_column[2]
         table = self.statement.table
 
@@ -1253,14 +1256,16 @@ class SQLCompiler(Compiled):
         else:
             proc = None
 
+        row_fn = result.result_tuple([col.key for col in table.primary_key])
+
         def get(lastrowid, parameters):
             if proc is not None:
                 lastrowid = proc(lastrowid)
 
             if lastrowid is None:
-                return tuple(getter(parameters) for getter, col in getters)
+                return row_fn(getter(parameters) for getter, col in getters)
             else:
-                return tuple(
+                return row_fn(
                     lastrowid if col is autoinc_col else getter(parameters)
                     for getter, col in getters
                 )
@@ -1268,7 +1273,10 @@ class SQLCompiler(Compiled):
         return get
 
     @util.memoized_property
+    @util.preload_module("sqlalchemy.engine.result")
     def _inserted_primary_key_from_returning_getter(self):
+        result = util.preloaded.engine_result
+
         key_getter = self._key_getters_for_crud_column[2]
         table = self.statement.table
 
@@ -1281,8 +1289,10 @@ class SQLCompiler(Compiled):
             for col in table.primary_key
         ]
 
+        row_fn = result.result_tuple([col.key for col in table.primary_key])
+
         def get(row, parameters):
-            return tuple(
+            return row_fn(
                 getter(row) if use_row else getter(parameters)
                 for getter, use_row in getters
             )