Skip to content

bpo-33014: Clarify str.isidentifier docstring #6088

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
willingc merged 3 commits into from
Oct 8, 2018
Merged

bpo-33014: Clarify str.isidentifier docstring #6088

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1cb2300
bpo-33014: Clarify str.isidentifier docstring
CuriousLearner Mar 12, 2018
7b039a0
Merge branch 'master' of github.com:CuriousLearner/cpython into fix-i…
CuriousLearner Jul 21, 2018
e6ae68c
bpo-33014: Add code example in isidentifier documentation
CuriousLearner Jul 21, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions Doc/library/stdtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1687,8 +1687,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`.

@willingc willingc Mar 12, 2018

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding an example would clarify the usage and differences:

Keywords, which are a small subset of identifiers used as reserved words, are not ordinary identifiers. To test if a string is a keyword, call :func:keyword.iskeyword to test whether a string s is a reserved identifier, such as :keyword: def and :keyword:class.

An example shows their usage:

>>> import keyword

>>> string_ordinary = 'hello'
>>> string_keyword = 'def'

>>> string_ordinary.isidentifier()
True
>>> keyword.iskeyword(string_ordinary)
False
>>> string_keyword.isidentifier()
True
>>> keyword.iskeyword(string_keyword)
True

@terryjreedy terryjreedy Mar 12, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This proposed change is in an entry about identifiers, not keywords. Expanding the keyword module doc would be a separate discussion. If we did something, I would it a bit shorter, such as

>>> from keyword import iskeyword

>>> 'hello'.isidentifier(), iskeyword('hello')
True, False
>>> 'def'.isidentifier(), iskeyword('def')
True, True

@willingc willingc Mar 12, 2018

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like @terryjreedy’s suggested example. More compact but captures the importance of contrasting both uses.


Example:
::

>>> from keyword import iskeyword

>>> 'hello'.isidentifier(), iskeyword('hello')
True, False
>>> 'def'.isidentifier(), iskeyword('def')
True, True


.. method:: str.islower()

Expand Down
6 changes: 3 additions & 3 deletions Objects/clinic/unicodeobject.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions Objects/unicodeobject.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12071,13 +12071,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));
}
Expand Down