From c415440faa67c488fd2a5d8fc0977cbd660c4a90 Mon Sep 17 00:00:00 2001 From: Berker Peksag Date: Sun, 12 Jun 2016 13:41:47 +0300 Subject: [PATCH] Issue #27188: Fix various sqlite3 documentation errors * Connection.execute* methods don't create intermediate cursor objects * Fix description of seq_of_parameters parameter * Clarify that Warning is sqlite3.Warning * sql_script parameter of Cursor.executescript() doesn't accept bytes * Add missing tests * Fix various markup errors Initial patch by Dave Sawyer. --- Doc/library/sqlite3.rst | 37 +++++++++++++++++++------------------ Lib/sqlite3/test/dbapi.py | 12 ++++++++++++ 2 files changed, 31 insertions(+), 18 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 3bba9355626..ae4c7c49ccf 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -309,25 +309,26 @@ Connection Objects call :meth:`commit`. If you just close your database connection without calling :meth:`commit` first, your changes will be lost! - .. method:: execute(sql, [parameters]) + .. method:: execute(sql[, parameters]) - This is a nonstandard shortcut that creates an intermediate cursor object by - calling the cursor method, then calls the cursor's :meth:`execute - ` method with the parameters given. + This is a nonstandard shortcut that creates a cursor object by calling + the :meth:`~Connection.cursor` method, calls the cursor's + :meth:`~Cursor.execute` method with the *parameters* given, and returns + the cursor. + .. method:: executemany(sql[, parameters]) - .. method:: executemany(sql, [parameters]) - - This is a nonstandard shortcut that creates an intermediate cursor object by - calling the cursor method, then calls the cursor's :meth:`executemany - ` method with the parameters given. + This is a nonstandard shortcut that creates a cursor object by + calling the :meth:`~Connection.cursor` method, calls the cursor's + :meth:`~Cursor.executemany` method with the *parameters* given, and + returns the cursor. .. method:: executescript(sql_script) - This is a nonstandard shortcut that creates an intermediate cursor object by - calling the cursor method, then calls the cursor's :meth:`executescript - ` method with the parameters given. - + This is a nonstandard shortcut that creates a cursor object by + calling the :meth:`~Connection.cursor` method, calls the cursor's + :meth:`~Cursor.executescript` method with the given *sql_script*, and + returns the cursor. .. method:: create_function(name, num_params, func) @@ -533,7 +534,7 @@ Cursor Objects A :class:`Cursor` instance has the following attributes and methods. - .. method:: execute(sql, [parameters]) + .. method:: execute(sql[, parameters]) Executes an SQL statement. The SQL statement may be parameterized (i. e. placeholders instead of SQL literals). The :mod:`sqlite3` module supports two @@ -545,7 +546,7 @@ Cursor Objects .. literalinclude:: ../includes/sqlite3/execute_1.py :meth:`execute` will only execute a single SQL statement. If you try to execute - more than one statement with it, it will raise a Warning. Use + more than one statement with it, it will raise an ``sqlite3.Warning``. Use :meth:`executescript` if you want to execute multiple SQL statements with one call. @@ -553,8 +554,8 @@ Cursor Objects .. method:: executemany(sql, seq_of_parameters) Executes an SQL command against all parameter sequences or mappings found in - the sequence *sql*. The :mod:`sqlite3` module also allows using an - :term:`iterator` yielding parameters instead of a sequence. + the sequence *seq_of_parameters*. The :mod:`sqlite3` module also allows + using an :term:`iterator` yielding parameters instead of a sequence. .. literalinclude:: ../includes/sqlite3/executemany_1.py @@ -569,7 +570,7 @@ Cursor Objects at once. It issues a ``COMMIT`` statement first, then executes the SQL script it gets as a parameter. - *sql_script* can be an instance of :class:`str` or :class:`bytes`. + *sql_script* can be an instance of :class:`str`. Example: diff --git a/Lib/sqlite3/test/dbapi.py b/Lib/sqlite3/test/dbapi.py index 04649fc5492..04d04794c79 100644 --- a/Lib/sqlite3/test/dbapi.py +++ b/Lib/sqlite3/test/dbapi.py @@ -250,6 +250,11 @@ class CursorTests(unittest.TestCase): row = self.cu.fetchone() self.assertEqual(row[0], "Hu\x00go") + def CheckExecuteNonIterable(self): + with self.assertRaises(ValueError) as cm: + self.cu.execute("insert into test(id) values (?)", 42) + self.assertEqual(str(cm.exception), 'parameters are of unsupported type') + def CheckExecuteWrongNoOfArgs1(self): # too many parameters try: @@ -725,6 +730,13 @@ class ExtensionTests(unittest.TestCase): raised = True self.assertEqual(raised, True, "should have raised an exception") + def CheckCursorExecutescriptAsBytes(self): + con = sqlite.connect(":memory:") + cur = con.cursor() + with self.assertRaises(ValueError) as cm: + cur.executescript(b"create table test(foo); insert into test(foo) values (5);") + self.assertEqual(str(cm.exception), 'script argument must be unicode.') + def CheckConnectionExecute(self): con = sqlite.connect(":memory:") result = con.execute("select 5").fetchone()[0]