Descriptions in unittest and avoiding confusion
For the edification of all involved, this post summarizes a somewhat surprising behavior in unittest around docstrings. In bpo-46126<https://bugs.python.org/issue46126>, I reported an issue where I’d observed that CPython developers were avoiding the use of docstrings in unittests due to what was perceived as a masking of crucial information. On further investigation, it turns out that with the “descriptions” setting of the TextTestRunner is set to True (the default), unittest will emit the first line of a test’s docstring (if present) in addition to the location of the test. As a result, for tests that have docstrings, the output varies depending on this setting. Verbose output with docstrings and descriptions enabled: test_entry_points_unique_packages (test.test_importlib.test_metadata_api.APITests) Entry points should only be exposed for the first package ... ERROR Without docstrings or with descriptions disabled: test_entry_points_unique_packages (test.test_importlib.test_metadata_api.APITests) ... ERROR The output with the docstrings is more descriptive, providing more context and detail about the intention of the failed test. Because of the additional detail, however, unittest has elected to use a newline between the test location and the description, meaning the test result no longer appears on the same line as the test location, and thus if one were to grep for the test name, the result would be omitted, and if one were to grep for ERROR, the test name would be omitted. As part of the investigation, I published In Python, use docstrings or comments?<https://blog.jaraco.com/why-docstrings-are-preferable-to-comments/> exploring the motivations for and value added by allowing docstrings in test functions. It’s still an open consideration<https://bugs.python.org/issue47133> whether the unittest UX should format descriptions in the output differently to provide more consistent output while still allowing docstrings. Based on this information, CPython will most likely (pending GH-32128<https://github.com/python/cpython/pull/32128>) continue to use the default behavior (descriptions enabled) but will also allow for docstrings in its own tests.
I would like to point out another use case of triple quotes outside of docstrings. We do a lot of SQL here and so doing a parameterized query like: """SELECT foo FROM bar WHERE baz = %s""" is a whole lot cleaner and more natural than ("SELECT foo" + "FROM bar" + "WHERE baz = %s") For this toy example, one could just put it all on one line, but for rather more complicated SQL, it becomes a readability (and thus maintainability) factor to preserve SQL's one keyword per line formatting. So, yes, all of our SQL statements wind up in the parse tree and that's not optimal, but the suboptimality there is less for us than the suboptimality of the second form above. I would welcome a multiline comment format that didn't involve docstrings. Best, coyot
On Mon, 4 Apr 2022 at 17:22, Coyot Linden (Glenn Glazer) <coyot@lindenlab.com> wrote:
I would welcome a multiline comment format that didn't involve docstrings.
Err, sorry, I meant multiline string format.
I'm confused, what's wrong with """..."""? Triple quoted strings are not exclusively for docstrings... Paul
On 4/4/22 09:25, Paul Moore wrote:
On Mon, 4 Apr 2022 at 17:22, Coyot Linden (Glenn Glazer) <coyot@lindenlab.com> wrote:
I would welcome a multiline comment format that didn't involve docstrings. Err, sorry, I meant multiline string format. I'm confused, what's wrong with """..."""? Triple quoted strings are not exclusively for docstrings... Paul
That isn't my reading of PEP 257, I would be happy to be wrong about this. Best, coyot
On Mon, Apr 04, 2022 at 09:27:46AM -0700, Coyot Linden (Glenn Glazer) wrote:
On 4/4/22 09:25, Paul Moore wrote:
On Mon, 4 Apr 2022 at 17:22, Coyot Linden (Glenn Glazer) <coyot@lindenlab.com> wrote:
I would welcome a multiline comment format that didn't involve docstrings. Err, sorry, I meant multiline string format. I'm confused, what's wrong with """..."""? Triple quoted strings are not exclusively for docstrings... Paul
That isn't my reading of PEP 257, I would be happy to be wrong about this.
PEP 257 says that all docstrings should use triple quotes. It doesn't say that *only* docstrings should use triple quotes. -- Steve
"Well, that escalated quickly." :-) How did we get from a specific issue with docstrings and the unittest package's test reporting to multi-line comments? If this was Discourse that entire subdiscussion would have been flagged as off-topic and moved to its own thread. On Mon, Apr 4, 2022 at 10:12 AM Steven D'Aprano <steve@pearwood.info> wrote:
On 4/4/22 09:25, Paul Moore wrote:
On Mon, 4 Apr 2022 at 17:22, Coyot Linden (Glenn Glazer) <coyot@lindenlab.com> wrote:
I would welcome a multiline comment format that didn't involve docstrings. Err, sorry, I meant multiline string format. I'm confused, what's wrong with """..."""? Triple quoted strings are not exclusively for docstrings... Paul
That isn't my reading of PEP 257, I would be happy to be wrong about
On Mon, Apr 04, 2022 at 09:27:46AM -0700, Coyot Linden (Glenn Glazer) wrote: this.
PEP 257 says that all docstrings should use triple quotes. It doesn't say that *only* docstrings should use triple quotes.
-- Steve _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/3ULX4QF5... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido) *Pronouns: he/him **(why is my pronoun here?)* <http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-c...>
On 4/4/22 10:52, Coyot Linden (Glenn Glazer) wrote:
On 4/4/22 Guido wondered:
How did we get from a specific issue with docstrings and the unittest package's test reporting to multi-line comments?
Apologies, as I said earlier, I meant to write multiline /string/, not multiline /comment/ and it wasn't my intention to derail the thread but rather provide a different use case for multiline strings which seems, TIL, to be the accepted usage.
Guido's point is that your concern is completely unrelated to the unittest docstring display issue, and should have been a new thread. But, hey, we all make mistakes sometimes. :-) -- ~Ethan~
On 5/04/22 4:27 am, Coyot Linden (Glenn Glazer) wrote:
On 4/4/22 09:25, Paul Moore wrote:
I'm confused, what's wrong with """..."""? Triple quoted strings are not exclusively for docstrings... Paul
That isn't my reading of PEP 257, I would be happy to be wrong about this.
PEP 257 recommends that all docstrings be triple quoted, not that all triple quoted strings be docstrings. There is a difference! -- Greg
On 4/4/2022 11:07 AM, Coyot Linden (Glenn Glazer) wrote:
I would like to point out another use case of triple quotes outside of docstrings.
A docstring is *any* string literal, regardless of quotes, that is a statement in itself and is the *first* statement in the body of a module, class, or function. Triple quotes are routinely used for multiline strings elsewhere.
We do a lot of SQL here and so doing a parameterized query like:
"""SELECT foo FROM bar WHERE baz = %s"""
Others do the same. To be useful, you have to either bind the query string to something for use later query = """query string""" or immediately use it in an expression cursor = """SELECT %s"" % 'abc' In neither case will it be interpreted as a docstring.
I would welcome a multiline comment format that didn't involve docstrings.
Some people already use multiline strings for that, in positions where they do not become the docstring. At least in CPython, comment strings, at least in functions, appear to be omitted from the code object. def f(): 'docstring' 'other string' fc = f.__code__ fc.co_consts # ('docstring', None) # 'other string' absent. import dis dis.dis(f) # 'other string not loaded from anywhere else. # 1 0 RESUME 0 # # 3 2 LOAD_CONST 1 (None) # 4 RETURN_VALUE -- Terry Jan Reedy
On Mon, Apr 4, 2022 at 4:13 PM Coyot Linden (Glenn Glazer) < coyot@lindenlab.com> wrote:
I would like to point out another use case of triple quotes outside of docstrings. We do a lot of SQL here and so doing a parameterized query like:
"""SELECT foo FROM bar WHERE baz = %s"""
is a whole lot cleaner and more natural than
("SELECT foo" + "FROM bar" + "WHERE baz = %s")
[...] In the interests of fairness I should point out that the concatenation operators are redundant in the second example, and without them (thanks to the parentheses) the literals will be concatenated at compile time. I often use (code of some sort)'''\ SELECT foo FROM bar WHERE baz = %s""" to ensure the multiline string literal is correctly aligned, making indentation issues easier to diagnose. regards Steve
participants (9)
-
Coyot Linden (Glenn Glazer) -
Ethan Furman -
Greg Ewing -
Guido van Rossum -
Jason R. Coombs -
Paul Moore -
Steve Holden -
Steven D'Aprano -
Terry Reedy