Skip to content

gh-89509: Fix "truthy"/"falsy" in documentation #158663

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

Open
pochmann wants to merge 4 commits into
base: main
Choose a base branch
from
+5 −5
Open

gh-89509: Fix "truthy"/"falsy" in documentation #158663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5b0578b
Fix "truthy" in smtplib.rst
pochmann Oct 3, 2026
20a9a73
Fix "Truthy"/"Falsy" in tkinter.rst
pochmann Oct 3, 2026
ded1b3e
Fix "truthy" in functions.rst
pochmann Oct 3, 2026
701ece5
Merge branch 'python:main' into patch-5
pochmann Oct 3, 2026
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
2 changes: 1 addition & 1 deletion Doc/builtins/functions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1945,7 +1945,7 @@ are always available. They are listed here in alphabetical order.
>>> MISSING
<MISSING>

Sentinel objects are truthy and compare equal only to themselves. They are
Sentinel objects are true and compare equal only to themselves. They are

@bitdancer bitdancer Oct 4, 2026

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.

In this particular context I would say:

Suggested change
Sentinel objects are true and compare equal only to themselves. They are
Sentinel objects are true in a boolean context and compare equal only to themselves. They are

@bitdancer bitdancer Oct 5, 2026

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.

How about "Sentinel objects evaluate as true"?

@pochmann pochmann Oct 5, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Still unnecessary and ugly, if not even wrong. "Are/is true" is how the documentation does it.

intended to be compared with the :keyword:`is` operator.

``sentinel`` does not support subclassing.
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/smtplib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
An :class:`SMTP` instance encapsulates an SMTP connection. It has methods
that support a full repertoire of SMTP and ESMTP operations.

If the host parameter is set to a truthy value, :meth:`SMTP.connect` is called with
If the host parameter is set to a true value, :meth:`SMTP.connect` is called with
host and port automatically when the object is created; otherwise, :meth:`!connect` must
be called manually.

Expand Down Expand Up @@ -88,7 +88,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
required from the beginning of the connection and using :meth:`SMTP.starttls` is
not appropriate.

If the host parameter is set to a truthy value, :meth:`SMTP.connect` is called with host
If the host parameter is set to a true value, :meth:`SMTP.connect` is called with host
and port automatically when the object is created; otherwise, :meth:`!SMTP.connect` must
be called manually.

Expand Down
4 changes: 2 additions & 2 deletions Doc/library/tkinter.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6747,13 +6747,13 @@ and :mod:`!tkinter.constants` namespaces.
YES
ON

Truthy values, all equal to the integer ``1``.
True values, all equal to the integer ``1``.

@bitdancer bitdancer Oct 4, 2026

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.

Even though True here is not marked up as being the boolean constant, I think this could still lead to confusion. Since the actual code uses 0 and 1 and not the booleans, I would rephrase this as:

All equal to ``1``, and so true in a boolean context.

@bitdancer bitdancer Oct 5, 2026

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.

Here we could just drop the mention of boolean altogether and just say "All equal to 1", which is in fact the case. Python programmers will know that 1 is true.

@pochmann pochmann Oct 5, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

That sentence describes tkinter's TRUE, YES and ON. Clearly being true is the point, and equality to 1 is a side note. I'd have to see how they're usually used, but saying only "equal to 1" might make people focus on the number value and write worse code.


.. data:: FALSE
NO
OFF

Falsy values, all equal to the integer ``0``.
False values, all equal to the integer ``0``.

@bitdancer bitdancer Oct 4, 2026

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.

Similarly here.


.. data:: N
S
Expand Down
Loading