[Doc] sqlite3 Cursor.execute() return value is unspecified

[kephas]

BPO	46767
Nosy	@erlend-aasland, @kephas

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2022-02-16.11:16:39.049>
labels = ['3.7', '3.8', '3.9', '3.10', '3.11', 'type-feature', 'library']
title = '[Doc] sqlite3 Cursor.execute() return value is unspecified'
updated_at = <Date 2022-02-16.14:38:06.489>
user = 'https://github.com/kephas'

bugs.python.org fields:

activity = <Date 2022-02-16.14:38:06.489>
actor = 'erlendaasland'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2022-02-16.11:16:39.049>
creator = 'kephas'
dependencies = []
files = []
hgrepos = []
issue_num = 46767
keywords = []
message_count = 2.0
messages = ['413327', '413332']
nosy_count = 2.0
nosy_names = ['erlendaasland', 'kephas']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue46767'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9', 'Python 3.10', 'Python 3.11']

[kephas]

In the documentation of the sqlite3 module, the return value for Connection.execute() is told to be the Cursor that was implicitly created, but nothing is said about the return value/type when using Cursor.execute().

[erlend-aasland]

Quoting the docs:

This is a nonstandard shortcut that creates a cursor object by calling the
cursor() method, calls the cursor’s execute() method with the parameters
given, and returns the cursor.

There is already a backlink (or back reference) to the Connection.cursor() method, which again has a backlink to the Cursor class. What would you suggest to make things clearer?

How about the following rewording:

"[...] and returns the newly created cursor object".

(IMO this is too verbose; I'm fine with the current docs.)

[erlend-aasland]

After re-reading the current docs, I think a rewording might be helpful. I'll see if I can make things a little bit clearer.