sqlite3 signature discrepancies between documentation and implementation

[nchammas]

BPO	43094
Nosy	@berkerpeksag, @serhiy-storchaka, @nchammas, @erlend-aasland
PRs	bpo-43094: Update sqlite3 docs to match implementation #24489

^{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 2021-02-01.20:10:10.173>
labels = ['3.9', '3.10', 'docs']
title = 'sqlite3 signature discrepancies between documentation and implementation'
updated_at = <Date 2021-03-28.21:07:22.364>
user = 'https://github.com/nchammas'

bugs.python.org fields:

activity = <Date 2021-03-28.21:07:22.364>
actor = 'erlendaasland'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-02-01.20:10:10.173>
creator = 'nchammas'
dependencies = []
files = []
hgrepos = []
issue_num = 43094
keywords = ['patch']
message_count = 10.0
messages = ['386100', '386120', '386708', '386741', '386806', '386813', '386826', '389544', '389552', '389651']
nosy_count = 5.0
nosy_names = ['docs@python', 'berker.peksag', 'serhiy.storchaka', 'nchammas', 'erlendaasland']
pr_nums = ['24489']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue43094'
versions = ['Python 3.9', 'Python 3.10']

[nchammas]

The doc for sqlite3.create_function shows the signature as follows:

https://docs.python.org/3.9/library/sqlite3.html#sqlite3.Connection.create_function

create_function(name, num_params, func, *, deterministic=False)

But it appears that the parameter name is narg, not num_params. Trying num_params yields:

TypeError: function missing required argument 'narg' (pos 2)

[erlend-aasland]

There's also a discrepancy between the docs and the signature for create_aggregate():

https://docs.python.org/3.9/library/sqlite3.html#sqlite3.Connection.create_aggregate

create_aggregate(name, num_params, aggregate_class)

The second parameter is named n_arg, here with an underscore.

I'm not sure what's the best fix; fixing the docs or the signatures. If we fix the signatures, we'll at least get a kind of consistency.

[erlend-aasland]

Quoting from Victor Stinner's reply on python-dev (https://mail.python.org/archives/list/python-dev@python.org/message/X6SZIVOZ233TLLJV43UQEHMV3ELGP34S/):

If there are applications relying on the parameter name, it's better
to trust the Python implementation, rather than the documentation.

It would be better to make these parameters positional only in the
first place, but now it's too late for such backward incompatible
change :-(

[erlend-aasland]

Module level function discrepancies:

register_converter(), register_adapter(), and enable_callback_tracebacks() docstrings were unintentionally altered in recent AC updates. Docstrings should be restored. Docs are ok.

adapt() is not documented, but docstrings were unintentionally altered in recent AC updates. Docstrings should be restored.

connect() and enable_shared_cache() (latter is undocumented) are ok.

complete_statement() docs should be updated to reflect implementation.

[erlend-aasland]

sqlite3.Connection.set_progress_handler()

docs: set_progress_handler(handler, n)
impl: set_progress_handler(progress_handler, n)

Apart from that, the rest of sqlite3.Connection seems to be ok.

There's an ongoing discussion at python-dev about how to resolve this issue. I'm in favour of normalising the create_*() methods to be positional only (like create_collation() is now).

sqlite3.Cursor and sqlite3.Row methods seems to be ok as well.