[Python-checkins] cpython (3.5): Issue #27188: Fix various sqlite3 documentation errors

Sun Jun 12 06:42:00 EDT 2016

https://hg.python.org/cpython/rev/a825aee0721f
changeset: 101938:a825aee0721f
branch: 3.5
parent: 101936:09b4850cee9f
user: Berker Peksag <berker.peksag at gmail.com>
date: Sun Jun 12 13:41:47 2016 +0300
summary:
 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.
files:
 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
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -309,25 +309,26 @@
 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
- <Cursor.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
- <Cursor.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
- <Cursor.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 @@
 
 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 @@
 .. 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 @@
 .. 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 @@
 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
--- a/Lib/sqlite3/test/dbapi.py
+++ b/Lib/sqlite3/test/dbapi.py
@@ -250,6 +250,11 @@
 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 @@
 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]
-- 
Repository URL: https://hg.python.org/cpython
