[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[Louis Sautier]

Change by Louis Sautier :


--
nosy: +sbraz
nosy_count: 7.0 -> 8.0
pull_requests: +28201
pull_request: https://github.com/python/cpython/pull/29976

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[Xiang Zhang]

Change by Xiang Zhang :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[miss-islington]

miss-islington  added the comment:


New changeset fa3fd4cb181120007aefc408366c0cef6fb62f9d by Miss Islington (bot) 
in branch '3.7':
bpo-34434: Update doc for bool(), float() and int() arguments (GH-8834)
https://github.com/python/cpython/commit/fa3fd4cb181120007aefc408366c0cef6fb62f9d


--
nosy: +miss-islington

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +8429

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[Xiang Zhang]

Xiang Zhang  added the comment:


New changeset 3fe89dac42809a7741d50ebf595be98833b79b97 by Xiang Zhang (Louis 
Sautier) in branch 'master':
bpo-34434: Update doc for bool(), float() and int() arguments (GH-8834)
https://github.com/python/cpython/commit/3fe89dac42809a7741d50ebf595be98833b79b97


--
nosy: +xiang.zhang

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[Raymond Hettinger]

Raymond Hettinger  added the comment:

> I'm not saying *no* documentation of the change is needed, 
> but I am saying, for list/tuple, the What's New note is 
> sufficient to cover it for those people who went mucking 
> through the CPython source code to find an undocumented 
> keyword they could use.

That seems like a reasonable position to take.

--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[Josh Rosenberg]

Josh Rosenberg  added the comment:

For tuple and list, no, they couldn't have looked at the help (because the help 
calls the argument "iterable", while the only keyword accepted was "sequence"). 
Nor was "sequence" documented in the online docs, nor anywhere else that I can 
find; it was solely in the C source code.

If it was discoverable in any other way, I wouldn't say documenting the change 
(outside of What's New) was completely unjustifiable (I acknowledge that int, 
bool and float warrant a mention, since they did document a functioning name 
for the argument; I was a little too down on them in my original messages).

But the only way someone would accidentally use keyword arguments for 
list/tuple is if they were fuzzing the constructor by submitting random keyword 
arguments until something worked. That seems an odd thing to worry about 
breaking. The error message wouldn't help either; the exception raised tells 
you what argument was unrecognized, but not the names of recognized arguments.

Even if you want to document it, it's hard to do so without being confusing, 
inaccurate, or both. The original PR's versionchanged message was:

*iterable* is now a positional-only parameter.

But "iterable" was never a legal keyword, so saying it's "now a positional-only 
parameter" implies that at some point, it wasn't, and you could pass it with 
the name "iterable", which is wrong/confusing. If you mention "sequence", 
you're mentioning a now defunct detail (confusing, but not wrong). I suppose 
you could have the versionchanged say "This function does not accept keyword 
arguments", but again, for all discoverable purposes, it never did.

I'm not saying *no* documentation of the change is needed, but I am saying, for 
list/tuple, the What's New note is sufficient to cover it for those people who 
went mucking through the CPython source code to find an undocumented keyword 
they could use.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[Brett Cannon]

Brett Cannon  added the comment:

Please don't use over-the-top language like "completely unjustifiable" because 
it is unnecessary and in this case wrong. We treat our documentation as a 
recording of the semantics of the stdlib as well as a recording of what 
semantic changes occurred between versions. Something did change semantically 
and so it should be documented. Whether the way the docs have previously been 
written would have suggested that someone accidentally used keyword arguments 
is not the critical point. Anyone could have looked at e.g. help() or simply 
stumbled upon the fact keyword arguments used to work and then suddenly 
discovered they didn't. At that point it's more helpful to the user to know 
when that changed occurred then to try and minimize the amount of text in the  
docs simply because they happened to have not been written to suggest keyword 
arguments worked when they, in fact, did.

IOW adding a "version changed" note is not bloat, it's about letting people 
know who happened to have used keyword arguments what version of Python is 
going to break their code.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[Josh Rosenberg]

Josh Rosenberg  added the comment:

Oh, I was checking old docs when I said the online docs didn't call int's 
argument "x"; the current docs do, so int, float and bool all justify a change 
(barely), it's just tuple and list for which it's completely unjustifiable.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[Josh Rosenberg]

Josh Rosenberg  added the comment:

Bloating the documentation is almost certainly unjustifiable for list and 
tuple, and only barely justifiable for int, bool and float, given that:

1. The documentation (at least for Python 3) has *never* claimed the arguments 
could be passed by keyword (all of them used brackets to indicate the argument 
was optional without implying a meaningful default, which is typically how 
"does not take arguments by keyword" was described before the current "/" 
convention)

and

2. Aside from bool and float (and to a lesser extent, int), the documented name 
of said parameter didn't match the name it was accepted under, e.g.:

   a. The docs for tuple and list claimed the name was "iterable"; the only 
accepted name was "sequence"
   b. The online docs for int gave a wholly invalid "name", calling it "number 
| string", when in fact it was accepted only as "x". That said, int's docstring 
does describe the name "correctly" as "x"

So for tuple/list it would have been impossible to write code that depended on 
being able to pass the first parameter by keyword unless you'd gone mucking 
about in the CPython source code to figure out the secret keyword name. I could 
justify a note for int/bool/float given that the docstrings for all of them 
named the argument, and bool/float named it in the online docs, but we don't 
need to document a change that no one could have taken a dependency on without 
going to extreme trouble.

--
nosy: +josh.r

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[Louis Sautier]

Change by Louis Sautier :


--
keywords: +patch
pull_requests: +8320
stage:  -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

[Brett Cannon]

Brett Cannon  added the comment:

Any interest in submitting a pull request to update the documentation?

--
assignee:  -> docs@python
components: +Documentation
nosy: +brett.cannon, docs@python
title: Removal of kwargs for int() etc not described as change -> Removal of 
kwargs for built-in types not covered with "changed in Python" note in 
documentation

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com