[Python-checkins] bpo-33014: Clarify str.isidentifier docstring (GH-6088)

[Carol Willing]

https://github.com/python/cpython/commit/ffc5a14d00db984c8e72c7b67da8a493e17e2c14
commit: ffc5a14d00db984c8e72c7b67da8a493e17e2c14
branch: master
author: Sanyam Khurana <8039608+CuriousLearner at users.noreply.github.com>
committer: Carol Willing <carolcode at willingconsulting.com>
date: 2018-10-08T12:23:32+05:30
summary:

bpo-33014: Clarify str.isidentifier docstring (GH-6088)

* bpo-33014: Clarify str.isidentifier docstring

* bpo-33014: Add code example in isidentifier documentation

files:
M Doc/library/stdtypes.rst
M Objects/clinic/unicodeobject.c.h
M Objects/unicodeobject.c

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 5a133e32fced..d0d5c6157290 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1700,8 +1700,19 @@ expression support in the :mod:`re` module).
    Return true if the string is a valid identifier according to the language
    definition, section :ref:`identifiers`.
 
-   Use :func:`keyword.iskeyword` to test for reserved identifiers such as
-   :keyword:`def` and :keyword:`class`.
+   Call :func:`keyword.iskeyword` to test whether string ``s`` is a reserved
+   identifier, such as :keyword:`def` and :keyword:`class`.
+
+   Example:
+   ::
+
+      >>> from keyword import iskeyword
+
+      >>> 'hello'.isidentifier(), iskeyword('hello')
+      True, False
+      >>> 'def'.isidentifier(), iskeyword('def')
+      True, True
+
 
 .. method:: str.islower()
 
diff --git a/Objects/clinic/unicodeobject.c.h b/Objects/clinic/unicodeobject.c.h
index 8072516a8a36..cf5f13c6939e 100644
--- a/Objects/clinic/unicodeobject.c.h
+++ b/Objects/clinic/unicodeobject.c.h
@@ -381,8 +381,8 @@ PyDoc_STRVAR(unicode_isidentifier__doc__,
 "\n"
 "Return True if the string is a valid Python identifier, False otherwise.\n"
 "\n"
-"Use keyword.iskeyword() to test for reserved identifiers such as \"def\" and\n"
-"\"class\".");
+"Call keyword.iskeyword(s) to test whether string s is a reserved identifier,\n"
+"such as \"def\" or \"class");
 
 #define UNICODE_ISIDENTIFIER_METHODDEF    \
     {"isidentifier", (PyCFunction)unicode_isidentifier, METH_NOARGS, unicode_isidentifier__doc__},
@@ -951,4 +951,4 @@ unicode_sizeof(PyObject *self, PyObject *Py_UNUSED(ignored))
 {
     return unicode_sizeof_impl(self);
 }
-/*[clinic end generated code: output=561c88c912b8fe3b input=a9049054013a1b77]*/
+/*[clinic end generated code: output=c9476bf19f13c286 input=a9049054013a1b77]*/
diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
index a797f838eb41..16dd3d19e805 100644
--- a/Objects/unicodeobject.c
+++ b/Objects/unicodeobject.c
@@ -12100,13 +12100,13 @@ str.isidentifier as unicode_isidentifier
 
 Return True if the string is a valid Python identifier, False otherwise.
 
-Use keyword.iskeyword() to test for reserved identifiers such as "def" and
-"class".
+Call keyword.iskeyword(s) to test whether string s is a reserved identifier,
+such as "def" or "class
 [clinic start generated code]*/
 
 static PyObject *
 unicode_isidentifier_impl(PyObject *self)
-/*[clinic end generated code: output=fe585a9666572905 input=916b0a3c9f57e919]*/
+/*[clinic end generated code: output=fe585a9666572905 input=2fb643aafbcf0e1c]*/
 {
     return PyBool_FromLong(PyUnicode_IsIdentifier(self));
 }