On Tue, Jul 15, 2008 at 6:58 AM, Ben Finney <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]>
> :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
> ~~~~~~~~~~~~~~~~~
>
> ``default_test_loader``
> Replaces ``defaultTestLoader``
>
> ``TestResult`` attributes
> ~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ``add_error(…)``
> Replaces ``addError(…)``
>
> ``add_result(…)``
> Replaces ``addResult(…)``
>
> ``add_success(…)``
> Replaces ``addSuccess(…)``
>
> ``should_stop``
> Replaces ``shouldStop``
>
> ``start_test(…)``
> Replaces ``startTest(…)``
>
> ``stop_test(…)``
> Replaces ``stopTest(…)``
>
> ``tests_run``
> Replaces ``testsRun``
>
> ``was_successful(…)``
> Replaces ``wasSuccessful(…)``
>
> ``TestCase`` attributes
> ~~~~~~~~~~~~~~~~~~~~~~~
>
> ``__init__(self, method_name='run_test')``
> Replaces ``__init__(self, methodName='runTest')``
>
> ``_test_method_doc``
> Replaces ``_testMethodDoc``
>
> ``_test_method_name``
> Replaces ``_testMethodName``
>
> ``failure_exception``
> Replaces ``failureException``
>
> ``count_test_cases(…)``
> Replaces ``countTestCases(…)``
>
> ``default_test_result(…)``
> Replaces ``defaultTestResult(…)``
>
> ``fail_if(…)``
> Replaces ``failIf(…)``
>
> ``fail_if_almost_equal(…)``
> Replaces ``failIfAlmostEqual(…)``
>
> ``fail_if_equal(…)``
> Replaces ``failIfEqual(…)``
>
> ``fail_unless(…)``
> Replaces ``failUnless(…)``
>
> ``fail_unless_almost_equal(…)``
> Replaces ``failUnlessAlmostEqual(…)``
>
> ``fail_unless_equal(…)``
> Replaces ``failUnlessEqual(…)``
>
> ``fail_unless_raises(exc_class, callable_obj, *args, **kwargs)``
> Replaces ``failUnlessRaises(excClass, callableObj, *args, **kwargs)``
>
> ``run_test(…)``
> Replaces ``runTest(…)``
>
> ``set_up(…)``
> Replaces ``setUp(…)``
>
> ``short_description(…)``
> Replaces ``shortDescription(…)``
>
> ``tear_down(…)``
> Replaces ``tearDown(…)``
>
> ``FunctionTestCase`` attributes
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ``__init__(self, test_func, set_up, tear_down, description)``
> Replaces ``__init__(self, testFunc, setUp, tearDown, description)``
>
> ``run_test(…)``
> Replaces ``runTest(…)``
>
> ``set_up(…)``
> Replaces ``setUp(…)``
>
> ``short_description(…)``
> Replaces ``shortDescription(…)``
>
> ``tear_down(…)``
> Replaces ``tearDown(…)``
>
> ``TestSuite`` attributes
> ~~~~~~~~~~~~~~~~~~~~~~~~
>
> ``add_test(…)``
> Replaces ``addTest(…)``
>
> ``add_tests(…)``
> Replaces ``addTests(…)``
>
> ``count_test_cases(…)``
> Replaces ``countTestCases(…)``
>
> ``TestLoader`` attributes
> ~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ``sort_test_methods_using``
> Replaces ``sortTestMethodsUsing``
>
> ``suite_class``
> Replaces ``suiteClass``
>
> ``test_method_prefix``
> Replaces ``testMethodPrefix``
>
> ``get_test_case_names(self, test_case_class)``
> Replaces ``getTestCaseNames(self, testCaseClass)``
>
> ``load_tests_from_module(…)``
> Replaces ``loadTestsFromModule(…)``
>
> ``load_tests_from_name(…)``
> Replaces ``loadTestsFromName(…)``
>
> ``load_tests_from_names(…)``
> Replaces ``loadTestsFromNames(…)``
>
> ``load_tests_from_test_case(self, test_case_class)``
> Replaces ``loadTestsFromTestCase(self, testCaseClass)``
>
> ``_TextTestResult`` attributes
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ``show_all``
> Replaces ``showAll``
>
> ``add_error(…)``
> Replaces ``addError(…)``
>
> ``add_failure(…)``
> Replaces ``addFailure(…)``
>
> ``add_success(…)``
> Replaces ``addSuccess(…)``
>
> ``get_description(…)``
> Replaces ``getDescription(…)``
>
> ``print_error_list(…)``
> Replaces ``printErrorList(…)``
>
> ``print_errors(…)``
> Replaces ``printErrors(…)``
>
> ``start_test(…)``
> Replaces ``startTest(…)``
>
> ``TextTestRunner`` attributes
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ``_make_result(…)``
> Replaces ``_makeResult(…)``
>
> ``TestProgram`` attributes
> ~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ``__init__(self, module, default_test, argv, test_runner, test_loader)``
> Replaces ``__init__(self, module, defaultTest, argv, testRunner,
> testLoader)``
>
> ``create_tests(…)``
> Replaces ``createTests(…)``
>
> ``parse_args(…)``
> Replaces ``parseArgs(…)``
>
> ``run_tests(…)``
> Replaces ``runTests(…)``
>
> ``usage_exit(…)``
> 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 ``failure_exception``
> 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
> ``fail_if`` 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
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
