sqlite3: Port relevant documentation changes from 3.2

Initial patch by Johannes Vogel. Issue #13491.

Doc/includes/sqlite3/execute_1.py

 import sqlite3
 
-con = sqlite3.connect("mydb")
-
+con = sqlite3.connect(":memory:")
 cur = con.cursor()
+cur.execute("create table people (name_last, age)")
 
 who = "Yeltsin"
 age = 72
 
-cur.execute("select name_last, age from people where name_last=? and age=?", (who, age))
+# This is the qmark style:
+cur.execute("insert into people values (?, ?)", (who, age))
+
+# And this is the named style:
+cur.execute("select * from people where name_last=:who and age=:age", {"who": who, "age": age})
+
 print cur.fetchone()

Doc/includes/sqlite3/execute_2.py

-import sqlite3
-
-con = sqlite3.connect("mydb")
-
-cur = con.cursor()
-
-who = "Yeltsin"
-age = 72
-
-cur.execute("select name_last, age from people where name_last=:who and age=:age",
-    {"who": who, "age": age})
-print cur.fetchone()

Doc/includes/sqlite3/executemany_2.py

 import sqlite3
+import string
 
 def char_generator():
-    import string
-    for c in string.letters[:26]:
+    for c in string.lowercase:
         yield (c,)
 
 con = sqlite3.connect(":memory:")

Doc/includes/sqlite3/rowclass.py

 import sqlite3
 
-con = sqlite3.connect("mydb")
+con = sqlite3.connect(":memory:")
 con.row_factory = sqlite3.Row
 
 cur = con.cursor()
-cur.execute("select name_last, age from people")
+cur.execute("select 'John' as name, 42 as age")
 for row in cur:
-    assert row[0] == row["name_last"]
-    assert row["name_last"] == row["nAmE_lAsT"]
+    assert row[0] == row["name"]
+    assert row["name"] == row["nAmE"]
     assert row[1] == row["age"]
     assert row[1] == row["AgE"]

Doc/includes/sqlite3/text_factory.py

@@ -3,9 +3,6 @@ import sqlite3
 con = sqlite3.connect(":memory:")
 cur = con.cursor()
 
-# Create the table
-con.execute("create table person(lastname, firstname)")
-
 AUSTRIA = u"\xd6sterreich"
 
 # by default, rows are returned as Unicode
@@ -17,7 +14,7 @@ assert row[0] == AUSTRIA
 con.text_factory = str
 cur.execute("select ?", (AUSTRIA,))
 row = cur.fetchone()
-assert type(row[0]) == str
+assert type(row[0]) is str
 # the bytestrings will be encoded in UTF-8, unless you stored garbage in the
 # database ...
 assert row[0] == AUSTRIA.encode("utf-8")
@@ -29,15 +26,15 @@ con.text_factory = lambda x: unicode(x, "utf-8", "ignore")
 cur.execute("select ?", ("this is latin1 and would normally create errors" +
                          u"\xe4\xf6\xfc".encode("latin1"),))
 row = cur.fetchone()
-assert type(row[0]) == unicode
+assert type(row[0]) is unicode
 
 # sqlite3 offers a built-in optimized text_factory that will return bytestring
 # objects, if the data is in ASCII only, and otherwise return unicode objects
 con.text_factory = sqlite3.OptimizedUnicode
 cur.execute("select ?", (AUSTRIA,))
 row = cur.fetchone()
-assert type(row[0]) == unicode
+assert type(row[0]) is unicode
 
 cur.execute("select ?", ("Germany",))
 row = cur.fetchone()
-assert type(row[0]) == str
+assert type(row[0]) is str

Doc/library/sqlite3.rst

@@ -3,7 +3,7 @@
 
 .. module:: sqlite3
    :synopsis: A DB-API 2.0 implementation using SQLite 3.x.
-.. sectionauthor:: Gerhard Häring <gh@ghaering.de>
+.. sectionauthor:: Gerhard Häring <gh@ghaering.de>
 
 
 .. versionadded:: 2.5
@@ -82,7 +82,7 @@ This example uses the iterator form::
    >>> c = conn.cursor()
    >>> c.execute('select * from stocks order by price')
    >>> for row in c:
-   ...    print row
+   ...     print row
    ...
    (u'2006-01-05', u'BUY', u'RHAT', 100, 35.14)
    (u'2006-03-28', u'BUY', u'IBM', 1000, 45.0)
@@ -237,7 +237,6 @@ Connection Objects
    supplied, this must be a custom cursor class that extends
    :class:`sqlite3.Cursor`.
 
-
 .. method:: Connection.commit()
 
    This method commits the current transaction. If you don't call this method,
@@ -357,8 +356,6 @@ Connection Objects
 
 .. method:: Connection.set_progress_handler(handler, n)
 
-   .. versionadded:: 2.6
-
    This routine registers a callback. The callback is invoked for every *n*
    instructions of the SQLite virtual machine. This is useful if you want to
    get called from SQLite during long-running operations, for example to update
@@ -367,29 +364,31 @@ Connection Objects
    If you want to clear any previously installed progress handler, call the
    method with :const:`None` for *handler*.
 
+   .. versionadded:: 2.6
 
-.. method:: Connection.enable_load_extension(enabled)
 
-   .. versionadded:: 2.7
+.. method:: Connection.enable_load_extension(enabled)
 
    This routine allows/disallows the SQLite engine to load SQLite extensions
    from shared libraries.  SQLite extensions can define new functions,
    aggregates or whole new virtual table implementations.  One well-known
    extension is the fulltext-search extension distributed with SQLite.
 
-   .. literalinclude:: ../includes/sqlite3/load_extension.py
+   Loadable extensions are disabled by default. See [#f1]_.
 
-   Loadable extensions are disabled by default. See [#f1]_
+   .. versionadded:: 2.7
 
-.. method:: Connection.load_extension(path)
+   .. literalinclude:: ../includes/sqlite3/load_extension.py
 
-   .. versionadded:: 2.7
+.. method:: Connection.load_extension(path)
 
    This routine loads a SQLite extension from a shared library.  You have to
    enable extension loading with :meth:`enable_load_extension` before you can
    use this routine.
 
-   Loadable extensions are disabled by default. See [#f1]_
+   Loadable extensions are disabled by default. See [#f1]_.
+
+   .. versionadded:: 2.7
 
 .. attribute:: Connection.row_factory
 
@@ -473,14 +472,10 @@ Cursor Objects
    kinds of placeholders: question marks (qmark style) and named placeholders
    (named style).
 
-   This example shows how to use parameters with qmark style:
+   Here's an example of both styles:
 
    .. literalinclude:: ../includes/sqlite3/execute_1.py
 
-   This example shows how to use the named style:
-
-   .. literalinclude:: ../includes/sqlite3/execute_2.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
    :meth:`executescript` if you want to execute multiple SQL statements with one
@@ -633,7 +628,8 @@ Now we plug :class:`Row` in::
    ['date', 'trans', 'symbol', 'qty', 'price']
    >>> r['qty']
    100.0
-   >>> for member in r: print member
+   >>> for member in r:
+   ...     print member
    ...
    2006-01-05
    BUY

Misc/ACKS

@@ -879,6 +879,7 @@ Kannan Vijayan
 Kurt Vile
 Norman Vine
 Frank Visser
+Johannes Vogel
 Niki W. Waibel
 Wojtek Walczak
 Charles Waldman

Misc/NEWS

@@ -613,7 +613,8 @@ Tests
 Documentation
 -------------
 
-- Issue #13995: Fix errors in sqlite3's Cursor.rowcount documentation
+- Issues #13491 and #13995: Fix many errors in sqlite3 documentation.
+  Initial patch for #13491 by Johannes Vogel.
 
 - Issue #13402: Document absoluteness of sys.executable.