classification
Title: sqlite3 execute* methods return value not documented
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Dave Sawyer, SilentGhost, berker.peksag, docs@python, ghaering, python-dev
Priority: normal Keywords:

Created on 2016-06-02 21:53 by Dave Sawyer, last changed 2016-06-12 10:44 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
execdoc_patch1.txt Dave Sawyer, 2016-06-02 21:53
issue27188_patch2.txt Dave Sawyer, 2016-06-07 00:34
Messages (7)
msg266964 - (view) Author: Dave Sawyer (Dave Sawyer) * Date: 2016-06-02 21:53
The three execute methods of the connection object return the created cursor. The term "intermediate" implies the cursor is totally handled by the execute method, not that the user will get ownership of the object. 

When the user doesn't call close() on the returned cursor right away, they hold a lock on the database until the object is garbage collected.
msg267392 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2016-06-05 06:34
Thanks for the patch, Dave. For whatever reason it doesn't seem to apply cleanly to the current tip, would you mind preparing a new patch that does?
msg267440 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-05 17:26
Could you also change the function signatures from

    .. method:: execute(sql, [parameters])

to

    .. method:: execute(sql[, parameters])

and document that parameters should be list (or sequence or iterable -- I'm a the airport now so I can't check what is the correct term)?

I'm not a native speaker but this sentence sounds a bit weird to me:

    This is a nonstandard shortcut that creates a cursor object by calling the cursor method, calls the cursor's :meth:`execute <Cursor.execute>` [...]

Perhaps it can be changed to


    This is a nonstandard shortcut that creates a cursor object by calling the cursor's :meth:`execute <Cursor.execute>` method [...]

Also, please change the following usages

    :meth:`execute <Cursor.execute>`

with

    :meth:`~Cursor.execute`
msg267573 - (view) Author: Dave Sawyer (Dave Sawyer) * Date: 2016-06-07 00:34
Updated optional parameters. Fixed executescript which takes a single parameter. The English is correct - one needs to looks at the verbs to be sure they match in tense and number. Like "He OPENS the fridge, GRABS the milk, and DRINKS it." This method CREATES a cursor, CALLS the method, and RETURNS the cursor.
msg267574 - (view) Author: Dave Sawyer (Dave Sawyer) * Date: 2016-06-07 00:39
No problem. I did a pull and reposted with additional fixes suggested by
Berker and one copy/paste error I spotted.

On Sat, Jun 4, 2016 at 11:34 PM, SilentGhost <report@bugs.python.org> wrote:

>
> SilentGhost added the comment:
>
> Thanks for the patch, Dave. For whatever reason it doesn't seem to apply
> cleanly to the current tip, would you mind preparing a new patch that does?
>
> ----------
> assignee:  -> docs@python
> components: +Documentation
> nosy: +SilentGhost, berker.peksag, docs@python, ghaering
> stage:  -> patch review
> type: enhancement -> behavior
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue27188>
> _______________________________________
>
msg268359 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-06-12 10:42
New changeset a825aee0721f by Berker Peksag in branch '3.5':
Issue #27188: Fix various sqlite3 documentation errors
https://hg.python.org/cpython/rev/a825aee0721f

New changeset 187b2bc0fe26 by Berker Peksag in branch 'default':
Issue #27188: Merge from 3.5
https://hg.python.org/cpython/rev/187b2bc0fe26
msg268360 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-12 10:44
Thanks for the patch Dave. I found a couple of more issues while reviewing the patch and fixed them.
History
Date User Action Args
2016-06-12 10:44:25berker.peksagsetstatus: open -> closed
resolution: fixed
messages: + msg268360

stage: patch review -> resolved
2016-06-12 10:42:03python-devsetnosy: + python-dev
messages: + msg268359
2016-06-07 00:39:58Dave Sawyersetmessages: + msg267574
2016-06-07 00:34:47Dave Sawyersetfiles: + issue27188_patch2.txt

messages: + msg267573
2016-06-05 17:26:45berker.peksagsetmessages: + msg267440
versions: + Python 3.5
2016-06-05 06:34:58SilentGhostsetassignee: docs@python
type: enhancement -> behavior
components: + Documentation

nosy: + SilentGhost, ghaering, berker.peksag, docs@python
messages: + msg267392
stage: patch review
2016-06-02 21:53:34Dave Sawyercreate