[Python-Dev] PEP: Consolidating names in the unittest module (original) (raw)

Collin Winter collinw at gmail.com
Wed Jul 16 02:20:30 CEST 2008

On Tue, Jul 15, 2008 at 6:58 AM, Ben Finney <ben+python at benfinney.id.au> wrote:

Significant updates include removing all reference to the (already-resolved) new-style class issue, adding footnotes and references, and a Rationale summary of discussion on both sides of the divide for 'assert*' versus 'fail*' names.

:PEP: XXX :Title: Consolidating names in the unittest module :Version: 0.2 :Last-Modified: 2008-07-15 :Author: Ben Finney <ben+python at benfinney.id.au> :Status: Draft :Type: Standards Track :Content-Type: test/x-rst :Created: 2008-07-14 :Python-Version: 2.7, 3.1 :Post-History: .. contents:: Abstract ======== This PEP proposes to consolidate the names that constitute the API of the standard library unittest module, with the goal of removing redundant names, and conforming with PEP 8. Motivation ========== The normal use case for the unittest module is to subclass its classes, overriding and re-using its functios and methods. This draws constant attention to the fact that the existing implementation fails several current Python standards: * It does not conform to PEP 8 [#PEP-8], requiring users to write their own non-PEP-8 conformant names when overriding methods, and encouraging extensions to further depart from PEP 8. * It has many synonyms in its API, which goes against the Zen of Python [#PEP-20] (specifically, that "there should be one, and preferably only one, obvious way to do it"). Specification ============= Remove obsolete names --------------------- The following module attributes are not documented as part of the API and are marked as obsolete in the implementation. They will be removed. * makeLoader * getTestCaseNames * makeSuite * findTestCases Remove redundant names ---------------------- The following attribute names exist only as synonyms for other names. They are to be removed, leaving only one name for each attribute in the API. TestCase attributes ~~~~~~~~~~~~~~~~~~~~~~~ * assertEqual * assertEquals * assertNotEqual * assertNotEquals * assertAlmostEqual * assertAlmostEquals * assertNotAlmostEqual * assertNotAlmostEquals * assertRaises * assert * assertTrue * assertFalse Conform API with PEP 8 ---------------------- The following names are to be introduced, each replacing an existing name, to make all names in the module conform with PEP 8 [#PEP-8]. Each name is shown with the existing name that it replaces. Where function parameters are to be renamed also, they are shown. Where function parameters are not to be renamed, they are elided with the ellipse ("…") symbol. Module attributes ~~~~~~~~~~~~~~~~~ defaulttestloader Replaces defaultTestLoader TestResult attributes ~~~~~~~~~~~~~~~~~~~~~~~~~ adderror(…) Replaces addError(…) addresult(…) Replaces addResult(…) addsuccess(…) Replaces addSuccess(…) shouldstop Replaces shouldStop starttest(…) Replaces startTest(…) stoptest(…) Replaces stopTest(…) testsrun Replaces testsRun wassuccessful(…) Replaces wasSuccessful(…) TestCase attributes ~~~~~~~~~~~~~~~~~~~~~~~ _init_(self, methodname='runtest') Replaces _init_(self, methodName='runTest') testmethoddoc Replaces testMethodDoc testmethodname Replaces testMethodName failureexception Replaces failureException counttestcases(…) Replaces countTestCases(…) defaulttestresult(…) Replaces defaultTestResult(…) failif(…) Replaces failIf(…) failifalmostequal(…) Replaces failIfAlmostEqual(…) failifequal(…) Replaces failIfEqual(…) failunless(…) Replaces failUnless(…) failunlessalmostequal(…) Replaces failUnlessAlmostEqual(…) failunlessequal(…) Replaces failUnlessEqual(…) failunlessraises(excclass, callableobj, *args, **kwargs) Replaces failUnlessRaises(excClass, callableObj, *args, **kwargs) runtest(…) Replaces runTest(…) setup(…) Replaces setUp(…) shortdescription(…) Replaces shortDescription(…) teardown(…) Replaces tearDown(…) FunctionTestCase attributes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ _init_(self, testfunc, setup, teardown, description) Replaces _init_(self, testFunc, setUp, tearDown, description) runtest(…) Replaces runTest(…) setup(…) Replaces setUp(…) shortdescription(…) Replaces shortDescription(…) teardown(…) Replaces tearDown(…) TestSuite attributes ~~~~~~~~~~~~~~~~~~~~~~~~ addtest(…) Replaces addTest(…) addtests(…) Replaces addTests(…) counttestcases(…) Replaces countTestCases(…) TestLoader attributes ~~~~~~~~~~~~~~~~~~~~~~~~~ sorttestmethodsusing Replaces sortTestMethodsUsing suiteclass Replaces suiteClass testmethodprefix Replaces testMethodPrefix gettestcasenames(self, testcaseclass) Replaces getTestCaseNames(self, testCaseClass) loadtestsfrommodule(…) Replaces loadTestsFromModule(…) loadtestsfromname(…) Replaces loadTestsFromName(…) loadtestsfromnames(…) Replaces loadTestsFromNames(…) loadtestsfromtestcase(self, testcaseclass) Replaces loadTestsFromTestCase(self, testCaseClass) TextTestResult attributes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ showall Replaces showAll adderror(…) Replaces addError(…) addfailure(…) Replaces addFailure(…) addsuccess(…) Replaces addSuccess(…) getdescription(…) Replaces getDescription(…) printerrorlist(…) Replaces printErrorList(…) printerrors(…) Replaces printErrors(…) starttest(…) Replaces startTest(…) TextTestRunner attributes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ makeresult(…) Replaces makeResult(…) TestProgram attributes ~~~~~~~~~~~~~~~~~~~~~~~~~~ _init_(self, module, defaulttest, argv, testrunner, testloader) Replaces _init_(self, module, defaultTest, argv, testRunner, testLoader) createtests(…) Replaces createTests(…) parseargs(…) Replaces parseArgs(…) runtests(…) Replaces runTests(…) usageexit(…) Replaces usageExit(…) Rationale ========= Redundant names --------------- The current API, with two or in some cases three different names referencing exactly the same function, leads to an overbroad and redundant API that violates PEP 20 [#PEP-20] ("there should be one, and preferably only one, obvious way to do it"). Removal of assert* names ---------------------------- While there is consensus support to remove redundant names for the TestCase test methods, the issue of which set of names should be retained is controversial. Arguments in favour of retaining only the assert* names: * BDFL preference: The BDFL has stated [#vanrossum-1] a preference for the assert* names. * Precedent: The Python standard library currently uses the assert* names by a roughly 8:1 majority over the fail* names. (Counting unit tests in the py3k tree at 2008-07-15 [#pitrou-1].) An ad-hoc sampling of other projects that use unittest also demonstrates strong preference for use of the assert* names [#bennetts-1]. * Positive admonition: The assert* names state the intent of how the code under test should behave, while the fail* names are phrased in terms of how the code should not behave. Arguments in favour of retaining only the fail* names: * Explicit is better than implicit: The fail* names state *what the function will do* explicitly: fail the test. With the assert* names, the action to be taken is only implicit. * Avoid false implication: The test methods do not have any necessary connection with the built-in assert statement. Even the exception raised, while it defaults to AssertionException, is explicitly customisable via the documented failureexception attribute. Choosing the fail* names avoids the false association with either of these. This is exacerbated by the plain-boolean test using a name of assert (with a trailing underscore) to avoid a name collision with the built-in assert statement. The corresponding failif name has no such issue. PEP 8 names ----------- Although unittest (and its predecessor PyUnit) are intended to be familiar to users of other xUnit interfaces, there is no attempt at direct API compatibility since the only code that Python's unittest interfaces with is other Python code. The module is in the standard library and its names should all conform with PEP 8 [#PEP-8]. Backwards Compatibility ======================= The names to be obsoleted should be deprecated and removed according to the schedule for modules in PEP 4 [#PEP-4]. While deprecated, use of the deprecated attributes should raise a DeprecationWarning, with a message stating which replacement name should be used.

Is any provision being made for a 2to3 fixer/otherwise-automated transition for the changes you propose here?

Collin Winter

More information about the Python-Dev mailing list