Title: Add docs for decorator
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4
Status: closed Resolution: duplicate
Dependencies: Superseder: More revisions to docs
View: 32843
Assigned To: docs@python Nosy List: cheryl.sabella, docs@python, ezio.melotti, ncoghlan, python-dev, r.david.murray, serhiy.storchaka, tim.peters
Priority: normal Keywords:

Created on 2013-10-26 17:41 by ncoghlan, last changed 2018-02-22 23:06 by cheryl.sabella. This issue is now closed.

Messages (14)
msg201379 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-26 17:41
It is *not* OK to have a "" flag that is true under -OO, nor a requires_docstrings decorator that still attempts to run the test under those conditions.

Issue 19330 updated them so their meaning matched their names and the surrounding comments, but they were apparently being used instead to refer to a specific kind of CPython build.

A more logical name for such a feature would be HAVE_C_DOCSTRINGS and requires_c_docstrings.
msg201380 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-26 17:51
Alternatively, if the affected tests should also be skipped under -OO, then I think changing the current definition of HAVE_DOCSTRINGS would also work:

MISSING_C_DOCSTRINGS = (check_impl_detail() and
                        sys.platform != 'win32' and
                        not sysconfig.get_config_var('WITH_DOC_STRINGS'))

HAVE_DOCSTRINGS = _check_docstrings.__doc__ is not None and not MISSING_C_DOCSTRINGS
msg201381 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2013-10-26 17:53
Think this is related to why the FreeBSD default buildbot is always failing now?


File "/usr/home/buildbot/buildarea/3.x.krah-freebsd/build/Lib/test/", line ?, in
Failed example:
    print(i.__next__.__doc__ if HAVE_DOCSTRINGS else 'x.__next__() <==> next(x)')
    x.__next__() <==> next(x)

I have no idea what HAVE_DOCSTRINGS is all about, alas :-(
msg201385 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2013-10-26 17:59
Yeah, HAVE_DOCSTRINGS was added when we were not sure whether to skip C
and Python docstrings separately.

I agree that the right thing is to have both requires_c_docstrings
and requires_py_docstrings.
msg201386 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2013-10-26 18:05
For reference see #17041 and msg180774. Separating the decorators
makes things clearer (after all we're dealing with extremely obscure
features here), merging them could mean less work.
msg201387 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-26 18:08
+1 for separate flags with appropriate names and skip messages.

It should only be the usage in test_contextlib which needs to be
migrated to the Python flags, although the C usage may be more
widespread. (The other Python cases are currently checking the
optimisation level instead)

However, it's 4 am here, so I'm going to go get some sleep :)
msg201406 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-27 02:46
I'll do an initial quick fix that also turns off HAVE_DOCSTRINGS when C level docstrings are missing, before working on a large patch to split it into two separate flags.
msg201412 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-10-27 04:19
New changeset 1927b7c01c78 by Nick Coghlan in branch 'default':
Mitigate #19412: restore test skips for --without-doc-strings
msg201415 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-27 05:39
On my Fedora system, test_gdb still fails when --without-doc-strings is configured, even after updating the decorator to cover both C and Python docstrings as an interim fix. That may be a real bug, though (see issue 19415 for details)

Regarding splitting the flags, I'm not sure I agree with RDM's reasoning in issue 17041. As soon as *any* docstrings are missing (whether it's C docstrings or Python docstrings), various parts of the introspection machinery are going to start behaving strangely.

By splitting the flags in the test suite, we're increasing the coupling between the tests and the implementation. For example, if something docstring dependent that was previously implemented in Python is moved to a C accelerator module, is it right for the test to have to know about that and switch to moving a different decorator?

In my view, "this is a C docstring" and "this is a Python docstring" is an implementation detail that the tests shouldn't have to care about. With the latest update, "test.supports.requires_docstrings" means "I require trustworthy docstrings, and if there's anything wrong with the docstring machinery, don't even try this test" without getting into the specifics of worrying about *why* the docstrings might be unreliable.
msg201421 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-10-27 06:26
I suppose that some tests (e.g. still fail with -O2.
msg201474 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-10-27 16:28
Nick: I agree with your reasoning.  I don't know why I said what I did on the other issue.
msg201509 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-28 02:07
OK, since David agrees the updated behaviour of the requires_docstring decorator makes sense (i.e. skipping __doc__ related tests whenever the docstrings are unreliable, regardless of the reason), I'm morphing this to be a docs issue.

At least requires_docstring should be documented, but it may be worth documenting HAVE_DOCSTRINGS and MISSING_C_DOCSTRINGS as well.
msg203110 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-11-17 00:12
I was bitten by this in #19535. See the third point about test_contextlib in msg203071.  I would expect support.requires_docstring to skip the test if -OO is used and the docstrings are missing.
msg312601 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-02-22 23:06
I added `HAVE_DOCSTRINGS`,`MISSING_C_DOCSTRINGS`, `requires_docstring` to the documentation under issue11015.  Additional changes to those three have been made under issue32843, so I am closing this issue in favor of issue32843.  Please comment on that PR if the wording still needs to be adjusted.  Thanks!
Date User Action Args
2018-02-22 23:06:31cheryl.sabellasetstatus: open -> closed

superseder: More revisions to docs

nosy: + cheryl.sabella
messages: + msg312601
resolution: duplicate
stage: needs patch -> resolved
2014-10-14 16:21:09skrahsetnosy: - skrah
2013-11-17 00:12:52ezio.melottisetmessages: + msg203110
2013-10-28 02:07:15ncoghlansettitle: Add a decorator for tests that require C level docstrings -> Add docs for decorator
nosy: + docs@python

messages: + msg201509

assignee: docs@python
components: + Documentation, - Tests
2013-10-27 16:28:48r.david.murraysetmessages: + msg201474
2013-10-27 06:26:28serhiy.storchakasetmessages: + msg201421
2013-10-27 05:39:41ncoghlansetassignee: ncoghlan -> (no value)

messages: + msg201415
nosy: + r.david.murray
2013-10-27 04:19:57python-devsetnosy: + python-dev
messages: + msg201412
2013-10-27 02:46:46ncoghlansetassignee: ncoghlan
messages: + msg201406
2013-10-26 18:19:33ezio.melottisetnosy: + ezio.melotti

type: enhancement
stage: needs patch
2013-10-26 18:08:34ncoghlansetmessages: + msg201387
2013-10-26 18:05:33skrahsetmessages: + msg201386
2013-10-26 17:59:49skrahsetmessages: + msg201385
2013-10-26 17:53:50tim.peterssetnosy: + tim.peters
messages: + msg201381
2013-10-26 17:51:34ncoghlansetmessages: + msg201380
2013-10-26 17:41:07ncoghlancreate