NYPL · aaronfriedman6 · Mar 25, 2025 · Mar 24, 2025
diff --git a/.python-version b/.python-version
@@ -1 +1 @@
-3.9.16
+3.13.1
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,7 @@
 # Changelog
+## v1.6.5 3/24/25
+- Add capability to return PostgreSQL cursor description
+
 ## v1.6.4 1/30/25
 - Update pyproject.toml to reflect CL changes (since omitted in last release)


diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "nypl_py_utils"
-version = "1.6.4"
+version = "1.6.5"
 authors = [
  { name="Aaron Friedman", email="aaronfriedman@nypl.org" },
 ]

diff --git a/src/nypl_py_utils/classes/postgresql_client.py b/src/nypl_py_utils/classes/postgresql_client.py
@@ -55,14 +55,18 @@ def connect(self, retry_count=0, backoff_factor=5, **kwargs):
                    'Error connecting to {name} database: {error}'.format(
                        name=self.database, error=e)) from None

-    def execute_query(self, query, query_params=None, **kwargs):
+    def execute_query(
+            self, query, return_desc=False, query_params=None, **kwargs):
        """
        Executes an arbitrary query against the given database connection.

        Parameters
        ----------
        query: str
            The query to execute
+        return_desc: bool, optional
+            Whether or not to return the cursor description in addition to the
+            results
        query_params: sequence, optional
            The values to be used in a parameterized query. The values can be
            for a single insert query -- e.g. execute_query(
@@ -92,7 +96,8 @@ def execute_query(self, query, query_params=None, **kwargs):
            else:
                cursor.execute(query, query_params, **kwargs)
            self.conn.commit()
-            return None if cursor.description is None else cursor.fetchall()
+            results = None if cursor.description is None else cursor.fetchall()
+            return (results, cursor.description) if return_desc else results
        except Exception as e:
            self.conn.rollback()
            cursor.close()

diff --git a/tests/test_postgresql_client.py b/tests/test_postgresql_client.py
@@ -50,6 +50,22 @@ def test_execute_read_query(self, mock_pg_conn, test_instance, mocker):
        test_instance.conn.commit.assert_called_once()
        mock_cursor.close.assert_called_once()

+    def test_execute_read_query_with_desc(self, mock_pg_conn, test_instance,
+                                          mocker):
+        test_instance.connect()
+
+        mock_cursor = mocker.MagicMock()
+        mock_cursor.description = [('description', None, None)]
+        mock_cursor.execute.return_value = mock_cursor
+        mock_cursor.fetchall.return_value = [(1, 2, 3), ('a', 'b', 'c')]
+        test_instance.conn.cursor.return_value = mock_cursor
+
+        assert test_instance.execute_query('test query', return_desc=True) == (
+            [(1, 2, 3), ('a', 'b', 'c')], [('description', None, None)])
+        mock_cursor.execute.assert_called_once_with('test query', None)
+        test_instance.conn.commit.assert_called_once()
+        mock_cursor.close.assert_called_once()
+
    def test_execute_write_query(self, mock_pg_conn, test_instance, mocker):
        test_instance.connect()