classification
Title: Argument typo in dbm.ndbm.open
Type: enhancement Stage: resolved
Components: Versions:
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: Nosy List: brett.cannon, remi.lapeyre, rougeth, terry.reedy
Priority: normal Keywords: patch

Created on 2019-03-16 20:25 by rougeth, last changed 2019-04-02 21:25 by brett.cannon. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 12095 closed rougeth, 2019-03-22 23:38
Messages (5)
msg338097 - (view) Author: Marco Rougeth (rougeth) * Date: 2019-03-16 20:25
Reading the documentation for `dbm.gnu.open` I noticed that there were a typo in the `flags` argument, it was documented as `flag`, in plural form.

The same typo was present for `dbm.ndbm.open`, but in this case, `flag` makes more sense than `flags`, since the function accepts only one option as a flag.

I opened a PR [1] fixing both typos, but I’d like to discuss if makes sense to rename the argument on `dbm.ndbm.open` from `flags` to `flag`. As point out by  @remilapeyre, this change would be backwards compatible, since we cannot use the function with keyword arguments.

>>> dbm.ndbm.open(filename=‘foo’, flags=‘r’, mode=438)
Traceback (most recent call last):
  File “<stdin>”, line 1, in <module>
TypeError: open() takes no keyword arguments

What do you folks think about it?

1 - https://github.com/python/cpython/pull/12095
msg338629 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-03-23 00:02
I have trouble understanding this post.  The parameter name is 'flag', not 'flags' and there are no typos, including in ndbm.  The parameter name is singular because there is basically one flag with 4 possible values to indicate how to open.  The fact that gdbm has optional subflags does not require changing the name and I think it better to keep the documented API the same.

The only time 'flags' appears is in "Not all flags are valid for all versions of gdbm. The module constant open_flags is a string of supported flag characters."  Here, 'flags' refers to the multiple possible values for the 'flag' argument, not the argument itself.

I think that this issue and the PR should be closed.
msg338673 - (view) Author: Marco Rougeth (rougeth) * Date: 2019-03-23 12:12
Hi Terry, thanks for reviewing this and sorry for not being clear enough.

About dbm.gnu.open:

The docs indeed uses “flag”, in singular form, but it’s wrong because 1) the argument accepts, for some cases, 2 flags and, 2) the source code uses “flags” in plural form.

In [1]: import dbm.gnu
In [2]: help(dbm.gnu.open)                                                                                          
Help on built-in function open in module _gdbm:

open(filename, flags='r', mode=438, /)
[...]

If you continue to read the docstring, there's an explanation about the cases where you can use two flags.

About dbm.ndbm.open:

For this one, the docs is also different from source code:

In [3]: import dbm.ndbm
In [4]: help(dbm.ndbm.open)                                                                                         
Help on built-in function open in module _dbm:

open(filename, flags='r', mode=438, /)
[...]

The scope of the patch on Github ends here. It only makes the documentation consistent to the source code.

What I wanted to point out is that, in the case of ndbm.open, it accepts a flags option (in plural form) when it actually accepts only one. And since changing it would not make any difference from an user perspective, I believe we should go for it.
msg339367 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2019-04-02 21:21
Actually, it's even more subtle as the arguments are positional-only.
msg339368 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2019-04-02 21:25
So Terry is correct in so much as there is no parameter name. :) Both of the functions in question are positional-only, so the name actually doesn't matter beyond giving a way to reference the parameter in the documentation.

So thanks for the PR, Marco, but I'm going to reject this as there's nothing actually wrong with the gdbm or ndbm docs.
History
Date User Action Args
2019-04-02 21:25:40brett.cannonsetstatus: open -> closed
resolution: rejected
messages: + msg339368

stage: patch review -> resolved
2019-04-02 21:21:07brett.cannonsetnosy: + brett.cannon
messages: + msg339367
2019-03-23 12:12:22rougethsetmessages: + msg338673
2019-03-23 00:02:46terry.reedysetnosy: + terry.reedy
messages: + msg338629
2019-03-22 23:38:26rougethsetkeywords: + patch
stage: patch review
pull_requests: + pull_request12453
2019-03-16 22:31:41rougethsettitle: Argument typo in dam.ndbm.open -> Argument typo in dbm.ndbm.open
2019-03-16 20:27:24remi.lapeyresetnosy: + remi.lapeyre
2019-03-16 20:25:09rougethcreate