[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Sanyam Khurana]

Sanyam Khurana  added the comment:

Marking this fixed via 
https://github.com/python/cpython/commit/ffc5a14d00db984c8e72c7b67da8a493e17e2c14
 and 
https://github.com/python/cpython/commit/fc8205cb4b87edd1c19e1bcc26deaa1570f87988

Thanks, everyone!

--
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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Lele Gaifax]

Change by Lele Gaifax :


--
keywords: +patch
pull_requests: +9141
stage: needs patch -> patch review

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Carol Willing]

Carol Willing  added the comment:


New changeset ffc5a14d00db984c8e72c7b67da8a493e17e2c14 by Carol Willing (Sanyam 
Khurana) in branch 'master':
bpo-33014: Clarify str.isidentifier docstring (GH-6088)
https://github.com/python/cpython/commit/ffc5a14d00db984c8e72c7b67da8a493e17e2c14


--

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[R. David Murray]

R. David Murray  added the comment:

I think my wording would be an improvement to the docs as well.  You could link 
just the keyword function if you are worried about too many links, since that 
would keep the link count the same.

--

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

I concur with David about the docstring. But I think that no changes are needed 
in the module documentation. David's wording would contain two links (for 
iskeyword() and for keyword), and many links distract the attention.

We already spent for this issue more time than it deserves.

--

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[R. David Murray]

R. David Murray  added the comment:

For the original report that this issue was opened for:

   Use keyword.iskeyword() to test for reserved identifiers such as "def" and 
"class".

The obvious replacement is:

   Use the iskeyword() function from the keyword module to test for reserved 
identifiers such as "def" and "class".

--
nosy: +r.david.murray

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Separate PRs for doc and code changes will be needed anyway if the code change 
is restricted to 3.8.

To me, changing keyword.iskeyword.__doc__ from the irrelevant Python tautology 
'x.__contains__(y) <==> y in x.' to something that says what the function does, 
as docstrings should,  is a bug fix, not an enhancement.  Hence a slight 
slowdown is not a concern to me.  I see 4 possible types of fixes.

1. Write a python function with docstring.  3.8 only as it changes 
type(iskeyword).

def iskeyword(s):
"Return true if s is a Python keyword."
return s in kwlist

2. Change the aberrant set/frozenset.__contains__.__doc__ so it makes some 
sense as a docstring for a bound method (as with list and dict).  
  list/tuple.__contains__.__doc__ is 'Return key in self.'
  dict.__contains__.__doc__ is 'True if the dictionary has the specified key, 
else False.'

I would copy the dict __contains__ docstring, with 'Return' prefixed, to set 
and frozenset, with the obvious substitution.  I don't know about backporting 
this.

3. Make bound_method docstrings writable, like with Python function docstrings 
(3.8 only).  Then we could use Cheryl's suggestion.  Or add a function 
bounddoc(bound_method, docstring) that can change a bound_method's docsting.

CPython uses 2 types for built-in methods bound to an instance.  The choice is 
not consistent within a class or across classes for a particular method.
  builtin_function_or_method ([].append, frozenset().__contains__)
  method-wrapper ([].__contains__)
Python classes result in 'bound method'.  All 3 copy the docstring of the 
instance method.  (For Python classes, one can temporarily change the method 
docstring before creating a new bound method.)

4. Add makebound(method, instance, docstring) that creates a bound method (of 
the appropriate type) but with the passed docstring (3.8 only)

3 or 4 would allow any public bound method to have a custom docstring.

--

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Cheryl Sabella]

Cheryl Sabella  added the comment:

Too bad we couldn't do:

iskeyword = frozenset(kwlist).__contains__
iskeyword.__doc__ = 'Test whether a string is a reserved identifier.'

But I'm sure there are reasons for this:
AttributeError: attribute '__doc__' of 'builtin_function_or_method' objects is 
not writable

--
nosy: +csabella

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Carol Willing]

Carol Willing  added the comment:

I've made an additional suggestion on the open PR to add an example to the 
`.rst` doc that better clarifies the differences and usage of `iskeyword` and 
`isidentifier`.

Perhaps making that addition and skipping the updates to the C source code 
would be a reasonable step forward. While perhaps not ideal, it seems a 
reasonable compromise to provide more helpful documentation without any 
potential performance impact or regression.

--

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

For changing a docstring we have to change the implementation of iskeyword(). 
It seems to me that the current implementation is the fastest, and any other 
implementation will be a tiny bit slower.

I just wanted to say that this enhancement has a non-zero cost.

--

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Terry J. Reedy]

Terry J. Reedy  added the comment:

As I posted above, keywork.iskeyword already has a bizarrely incorrect 
docstring, so how can there be a performance impact? And why single out such a 
rarely used function?

--

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

The change that will add a docstring to keyword.iskeyword() inevitable will 
have a negative performance effect. Is it worth it?

--
nosy: +rhettinger, serhiy.storchaka

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Sanyam Khurana]

Sanyam Khurana  added the comment:

Carol, Yes, I've raised a PR.

Currently, I've updated the docs for `str.isidentifier` clarifying the usage of 
`keyword.iskeyword`

For updating the docstring of `keyword.iskeyword`, I saw that `Lib/Keyword.py` 
defines this on line 55: `iskeyword = frozenset(kwlist).__contains__`

The docstring of the file says that it is automatically generated from 
`graminit.c`. I observed that file and have no clue on how to proceed to have 
the doc string updated. Can someone provide me a pointer on this please?

--
keywords:  -patch
stage: patch review -> needs patch

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Sanyam Khurana]

Change by Sanyam Khurana :


--
keywords: +patch
pull_requests: +5850
stage: needs patch -> patch review

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Terry J. Reedy]

Change by Terry J. Reedy :


--
versions: +Python 2.7, Python 3.6, Python 3.8

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Terry J. Reedy]

Change by Terry J. Reedy :


--
nosy: +willingc -serhiy.storchaka
title: Clarify str.isidentifier docstring, fix keyword.iskeyword docstring -> 
Clarify str.isidentifier docstring; fix keyword.iskeyword docstring
versions:  -Python 2.7, Python 3.6, Python 3.8

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring, fix keyword.iskeyword docstring

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Debating historical design decisions that effectively cannot be changed is off 
topic for the tracker (but fair game on python-list).  However, I will explain 
this much.  The s.isxyz questions are answered by examining the characters and 
codepoints in s.  Answering iskeyword(s) requires reference to the collection 
of keywords, kwlist, which must be exposed to users, and which may change in 
any new version.  We usually attach constant data attributes to modules (other 
than builtins), and never (that I can think of) to built-in classes.  "def 
iskeyword(s): return s in kwlist:" belongs in the module with kwlist.

--
nosy:  -willingc
title: Clarify doc string for str.isidentifier() -> Clarify str.isidentifier 
docstring, fix keyword.iskeyword docstring

___
Python tracker 

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

[issue33014] Clarify str.isidentifier docstring, fix keyword.iskeyword docstring

[Terry J. Reedy]

Change by Terry J. Reedy :


--
title: Clarify doc string for str.isidentifier() -> Clarify str.isidentifier 
docstring, fix keyword.iskeyword docstring

___
Python tracker 

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