classification
Title: Clean up the sqlite3 docs
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.snow, ezio.melotti, ghaering, python-dev, rhettinger, zach.ware
Priority: normal Keywords: patch

Created on 2012-06-14 15:19 by zach.ware, last changed 2014-04-01 17:23 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
issue15067_2.7_dead_pep.patch zach.ware, 2012-11-02 03:39 Patch to remove PEP 246 mention from 2.7
issue15067_2.7_sql_capitalization.patch zach.ware, 2012-11-02 03:40 Patch to make SQL capitalization consistent in 2.7 review
issue15067_3.2_updates.patch zach.ware, 2012-11-02 03:41 Patch to bring 3.2+ docs more in line with 2.7 (and remove PEP 246 mention) review
issue15067_3.2_sql_capitalization.patch zach.ware, 2012-11-02 03:45 Patch to make SQL capitalization consistent in 3.2+ review
Messages (7)
msg162797 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2012-06-14 15:19
See: http://hg.python.org/cpython/file/d31e83497c5a/Doc/library/sqlite3.rst#l708

PEP 246 is headed by: 
"""
Rejection Notice

    I'm rejecting this PEP.  Something much better is about to happen;
    it's too early to say exactly what, but it's not going to resemble
    the proposal in this PEP too closely so it's better to start a new
    PEP.  GvR.
"""

I don't know what the "something much better" was/is, so I have no idea how that line in the docs should be replaced, but I don't think the PEP 246 reference is valid.

Thanks,

Zach
msg162812 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2012-06-14 18:28
At the time it referred to generic functions (a la PEP 3124: Overloading, Generic Functions, Interfaces, and Adaptation).  However, ultimately it was Abstract Base Classes (PEP 3119) that slid into this space.
msg174440 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2012-11-01 19:06
Coming back to this 5 months later and looking into it myself, I find that the sqlite3 docs really need a bit of a cleanup all around, especially in all three 3.x branches.  Several minor changes were made by Raymond Hettinger in d229032dc213 and a few subsequent changesets 6 months ago in the 2.7 branch, but none of those ever made it to 3.x. (Raymond, those changes in the past are why I made you nosy on this one)

To address the offending sentence that brought this issue about in the first place, after rereading it and thinking about it some more, what's there does make sense: this module uses the recipe of PEP 246, regardless of that PEP's status.  However, I don't think it's helpful to mention it in the documentation, as it kind of gives the impression that "this feature was rejected for the whole of Python, but this stdlib module goes ahead and does it anyway."  For that reason, I propose to just drop that two-line paragraph entirely.  Everything about that feature still makes sense without that paragraph, even though the 'protocol' bit seems a bit weird. I wonder though, should that feature be deprecated on the basis of using a rejected PEP as well as TOOWTDI violation (or should I open another issue to that effect anyway)?

In the same vein as Raymond's earlier 2.7 changes (namely the SQL cleanup and capitalization he did), the 2.7 patch I've attached goes through and does the same for all of the included scripts in Doc/includes/sqlite3 as well as removing the bit about PEP 246.

The 3.2 patch does everything in the 2.7 patch, plus bringing the 3.2 docs in line with the 2.7 docs.

I do have a question, though; the footnote about enabling loadable extensions is different in the 2.7 and 3.2 docs.  Which one is right, or are both right for their respective versions?

Thanks,

Zach
msg174444 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2012-11-01 19:10
I failed to mention, the 3.2 patch also removes the line (and comment) about "db_row based solutions" since it seems from a quick Google search that "db_row" is a library created back in the 2.2 days that I didn't quickly see a 3.x version for.  Also, the comment made it seem like that line wouldn't be missed too much anyway :).  I left it in the 2.7 version though; as I assume it would be reasonably easy to get db_row to work with 2.7 if someone wanted to.
msg174457 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-01 19:50
I think it would be better to keep the capitalization of the queries separate from the rest of the patch.
msg174487 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2012-11-02 03:45
Ok then, here's the split patches.  3.2_updates does have a few SQL capitalization changes, but most of those are already present in 2.7, and splitting out the rest would be more work than it's worth, I think.
msg215333 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-04-01 17:23
New changeset 2e13f0d49b8e by Zachary Ware in branch '2.7':
Issue #15067: Remove reference to a rejected PEP.
http://hg.python.org/cpython/rev/2e13f0d49b8e

New changeset 4a2dabac976d by Zachary Ware in branch '3.4':
Issue #15067: Port 2.7 sqlite3 docs to 3.4
http://hg.python.org/cpython/rev/4a2dabac976d

New changeset 2c7ebb930b64 by Zachary Ware in branch 'default':
Closes #15067: Merge port of 2.7 sqlite3 docs.
http://hg.python.org/cpython/rev/2c7ebb930b64
History
Date User Action Args
2014-04-01 17:23:02python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg215333

resolution: fixed
stage: patch review -> resolved
2013-01-03 15:23:55zach.waresetfiles: - sqlite3_cleanup_3.2.patch
2013-01-03 15:23:49zach.waresetfiles: - sqlite3_cleanup_2.7.patch
2012-11-02 03:45:08zach.waresetfiles: + issue15067_3.2_sql_capitalization.patch

messages: + msg174487
2012-11-02 03:41:03zach.waresetfiles: + issue15067_3.2_updates.patch
2012-11-02 03:40:18zach.waresetfiles: + issue15067_2.7_sql_capitalization.patch
2012-11-02 03:39:50zach.waresetfiles: + issue15067_2.7_dead_pep.patch
2012-11-01 19:50:15ezio.melottisetnosy: + ezio.melotti
messages: + msg174457

type: enhancement
stage: patch review
2012-11-01 19:10:56zach.waresetmessages: + msg174444
2012-11-01 19:06:37zach.waresetfiles: + sqlite3_cleanup_3.2.patch
2012-11-01 19:06:05zach.waresetfiles: + sqlite3_cleanup_2.7.patch


versions: + Python 3.4
keywords: + patch
nosy: + rhettinger
title: sqlite3 docs reference PEP 246, which was rejected -> Clean up the sqlite3 docs
messages: + msg174440
2012-06-14 18:28:28eric.snowsetnosy: + eric.snow
messages: + msg162812
2012-06-14 15:19:07zach.warecreate