classification
Title: sqlite3 signature discrepancies between documentation and implementation
Type: Stage: patch review
Components: Documentation Versions: Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, docs@python, erlendaasland, nchammas, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2021-02-01 20:10 by nchammas, last changed 2021-03-28 21:07 by erlendaasland.

Pull Requests
URL Status Linked Edit
PR 24489 closed erlendaasland, 2021-02-09 11:03
Messages (10)
msg386100 - (view) Author: Nicholas Chammas (nchammas) * Date: 2021-02-01 20:10
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)
```
msg386120 - (view) Author: Erlend Egeberg Aasland (erlendaasland) * Date: 2021-02-01 22:34
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.
msg386708 - (view) Author: Erlend Egeberg Aasland (erlendaasland) * Date: 2021-02-09 10:58
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 :-(
msg386741 - (view) Author: Erlend Egeberg Aasland (erlendaasland) * Date: 2021-02-09 19:55
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.
msg386806 - (view) Author: Erlend Egeberg Aasland (erlendaasland) * Date: 2021-02-10 21:07
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.
msg386813 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2021-02-10 22:27
The problem is that sqlite3 isn't the only module where there are discrepancies between documentation and implementation. If we are going to change public sqlite3 APIs in to be positional-only, I'd prefer writing a PEP and fix all modules once and for all.
msg386826 - (view) Author: Erlend Egeberg Aasland (erlendaasland) * Date: 2021-02-11 10:17
> If we are going to change public sqlite3 APIs in to be positional-only, I'd prefer writing a PEP and fix all modules once and for all.

Right. I assume you mean that such a PEP would contain a set of guidelines for how to handle these dilemmas? It would be almost impossible to create a set of strict rules that can handle all cases, AFAICS.
msg389544 - (view) Author: Erlend Egeberg Aasland (erlendaasland) * Date: 2021-03-26 10:28
> I'd prefer writing a PEP and fix all modules once and for all.

Berker, I started drafting a PEP. Would you be interested in helping?
msg389552 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2021-03-26 14:25
> Berker, I started drafting a PEP. Would you be interested in helping?

Of course! I may be not be able to respond to you quickly in the next few weeks, though.
msg389651 - (view) Author: Erlend Egeberg Aasland (erlendaasland) * Date: 2021-03-28 21:07
> Of course! I may be not be able to respond to you quickly in the next few weeks, though.

Thank you! I'll send you a preliminary version sometime this week.
History
Date User Action Args
2021-03-28 21:07:22erlendaaslandsetmessages: + msg389651
2021-03-26 14:25:25berker.peksagsetmessages: + msg389552
2021-03-26 10:28:07erlendaaslandsetmessages: + msg389544
2021-02-11 10:17:16erlendaaslandsetmessages: + msg386826
2021-02-10 22:27:29berker.peksagsetmessages: + msg386813
2021-02-10 21:07:23erlendaaslandsetmessages: + msg386806
title: Update sqlite3 docs and docstrings to reflect implementation -> sqlite3 signature discrepancies between documentation and implementation
2021-02-09 19:55:00erlendaaslandsetmessages: + msg386741
title: sqlite3.create_function takes parameter named narg, not num_params -> Update sqlite3 docs and docstrings to reflect implementation
2021-02-09 11:03:10erlendaaslandsetkeywords: + patch
stage: patch review
pull_requests: + pull_request23280
2021-02-09 10:58:02erlendaaslandsetmessages: + msg386708
2021-02-02 13:25:49erlendaaslandsetnosy: + serhiy.storchaka
2021-02-01 22:35:06erlendaaslandsetversions: + Python 3.10
2021-02-01 22:34:47erlendaaslandsetnosy: + berker.peksag, erlendaasland
messages: + msg386120
2021-02-01 20:10:10nchammascreate