Text of bugs.python.org › issue47207 as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout.

Open the live page

Issue 47207: Switch datetime docstrings / documentation to using "Returns" rather than "Return"? - Python tracker

Python Home About News Documentation Downloads Community Foundation Developer's Guide Issue Tracker Issues Search Random Issue Summaries Issues with patch Easy issues Stats User Administration User List Committer List Help Tracker Documentation Tracker Development Report Tracker Problem Issue47207 ➜ This issue tracker has been migrated to GitHub , and is currently read-only . For more information, see the GitHub FAQs in the Python's Developer Guide.

Created on 2022-04-03 16:08 by p-ganssle , last changed 2022-04-11 14:59 by admin . Messages (2) msg416628 - (view) Author: Paul Ganssle (p-ganssle) * Date: 2022-04-03 16:08 In bpo-9305 , Fred Drake recommends preferring `Returns ...` over the imperative `Return ...`: https://bugs.python.org/issue9305#msg110912 Currently we're pretty consistent about `Return ...`, which is consistent with PEP 257 : https://peps.python.org/pep-0257/ That said, I actually think "Returns ..." sounds much better in the documentation, and I'd be happy to see it changed if others agree.

I have spun this off from bpo-9305 so that we can unblock https://github.com/python/cpython/pull/31697 . msg416760 - (view) Author: Stanley (slateny) * Date: 2022-04-05 07:58 Is there a bpo page or some sort that discusses why the imperative mood is used over the indicative mood other than convention of PEP 257 ? I found this ( https://mail.python.org/pipermail/tutor/2012-May/089584.html ) question and answer that seems to make sense, but it's not quite an official source.

If the reason for using imperative mood in docstrings doesn't apply to documentation, then I think there wouldn't be any problems in changing it. One thing raised in the mail thread was that 'Returns ...' isn't strictly grammatical, so perhaps that's something to consider. History Date User Action Args 2022-04-11 14:59:58 admin set github: 91363 2022-04-05 07:58:04 slateny set messages: + msg416760 2022-04-03 16:08:25 p-ganssle create Supported by The Python Software Foundation , Powered by Roundup Copyright © 1990-2022, Python Software Foundation Legal Statements