[docs] [issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring
Terry J. Reedy
report at bugs.python.org
Mon Mar 12 19:30:13 EDT 2018
Terry J. Reedy <tjreedy at udel.edu> 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).
"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__)
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 <report at bugs.python.org>
More information about the docs