Title: Document unittest.SkipTest
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: brett.cannon, docs@python, ezio.melotti, michael.foord, python-dev, zach.ware
Priority: normal Keywords: patch

Created on 2013-03-01 15:04 by brett.cannon, last changed 2013-03-27 18:17 by ezio.melotti. This issue is now closed.

File name Uploaded Description Edit
issue17329.diff zach.ware, 2013-03-05 22:32 3.x patch review
issue17329-2.7.diff zach.ware, 2013-03-05 22:32 2.7 patch review
issue17329.v2.diff zach.ware, 2013-03-06 15:29 3.x version 2 review
Messages (9)
msg183262 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2013-03-01 15:04
msg183559 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-03-05 22:32
Here's a pair of patches for 3.x and 2.7.  The 3.x patch is actually targeted at default; it has a couple extra instances of ``SkipTest`` that are converted to :exc:`SkipTest` in the patch.
msg183560 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-03-05 22:37
In the patches, the description of SkipTest is copied directly from the docstring in Lib/unittest/ with a bit of markup added.  It mentions TestResult.skip(), which doesn't exist.  I wonder if that was meant to be TestCase.skipTest()?
msg183571 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-03-06 01:50
> I wonder if that was meant to be TestCase.skipTest()?

Most likely.

I would document this exception at the end of the "Skipping tests and expected failures".  You could documented it simply as "the exception raised by the skip decorators", and suggest to use TestCase.skipTest() to skip a test rather than just raising this exception directly.

I'm also not sure if the note should be kept -- it seems quite obvious to me that the test will be marked as skipped even if previous assertions succeeded.  Moreover, if the exception is generally not supposed to be used directly there's no need to explain how to use it.
msg183597 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-03-06 15:29
Fair points.  I had originally put it in the section you suggested, but then decided that it better fit in a new section of its own under "Classes and functions" as that section "describes in depth the API of unittest."  But then, it also makes sense to move the decorators into the new section, and just link to them in the old section.

So, how about this patch?  I'm fine with moving everything back to the old section if I've gone in the wrong direction :).  And I'll create the 2.7 patch after the 3.x version is approved one way or the other.
msg184764 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-03-20 13:55
Now I get what you were trying to do.
What I don't like is that now the patch splits the section about skipping in two separate parts, while it would be better to keep it together IMHO.
You argument about having the "theory" first and the actual API later makes sense, and it's somewhat mirrored by e.g. the "basic example" section and the detailed API about TestCase and the assert methods later.
If we keep the two parts together we are left with two options:
1) add SkipTest to the existing section as I suggested initially;
2) move the whole section down below where the API is described;

1) it's simpler and it's enough IMHO, but if 2) is better I think it would be better to move it after the "deprecated aliases" section.

Michael, do you have any preference?
msg185333 - (view) Author: Michael Foord (michael.foord) * (Python committer) Date: 2013-03-27 13:59
For features like test skipping I would prefer to keep all the documentation together.
msg185360 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-03-27 18:16
New changeset cd5c23583fa5 by Ezio Melotti in branch '3.2':
#17329: document unittest.SkipTest.  Initial patch by Zachary Ware.

New changeset 4bf2a53b53b6 by Ezio Melotti in branch '3.3':
#17329: merge with 3.2.

New changeset 53cc3dbb1918 by Ezio Melotti in branch 'default':
#17329: merge with 3.3.

New changeset 13eb2fd70893 by Ezio Melotti in branch '2.7':
#17329: document unittest.SkipTest.  Initial patch by Zachary Ware.
msg185361 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-03-27 18:17
Fixed, thanks for the patch!
Date User Action Args
2013-03-27 18:17:40ezio.melottisetstatus: open -> closed
resolution: fixed
messages: + msg185361

stage: needs patch -> resolved
2013-03-27 18:16:47python-devsetnosy: + python-dev
messages: + msg185360
2013-03-27 13:59:08michael.foordsetmessages: + msg185333
2013-03-20 13:55:13ezio.melottisetmessages: + msg184764
2013-03-10 01:36:21ezio.melottisetassignee: docs@python -> ezio.melotti
2013-03-06 15:29:13zach.waresetfiles: + issue17329.v2.diff

messages: + msg183597
2013-03-06 01:50:41ezio.melottisetmessages: + msg183571
2013-03-05 22:37:55zach.waresettype: enhancement
messages: + msg183560
versions: + Python 2.7, Python 3.2
2013-03-05 22:32:39zach.waresetfiles: + issue17329-2.7.diff
2013-03-05 22:32:11zach.waresetfiles: + issue17329.diff
keywords: + patch
messages: + msg183559

versions: + Python 3.3
2013-03-01 15:04:33brett.cannoncreate