25. Development Tools

The modules described in this chapter help you write software. For example, the pydoc module takes a module and generates documentation based on the module’s contents. The doctest and unittest modules contains frameworks for writing unit tests that automatically exercise code and verify that the expected output is produced. 2to3 can translate Python 2.x source code into valid Python 3.x code.

The list of modules described in this chapter is:

• 25.1. pydoc — Documentation generator and online help system
• 25.2. doctest — Test interactive Python examples
  • 25.2.1. Simple Usage: Checking Examples in Docstrings
  • 25.2.2. Simple Usage: Checking Examples in a Text File
  • 25.2.3. How It Works
    • 25.2.3.1. Which Docstrings Are Examined?
    • 25.2.3.2. How are Docstring Examples Recognized?
    • 25.2.3.3. What’s the Execution Context?
    • 25.2.3.4. What About Exceptions?
    • 25.2.3.5. Option Flags
      • DONT_ACCEPT_TRUE_FOR_1
      • DONT_ACCEPT_BLANKLINE
      • NORMALIZE_WHITESPACE
      • ELLIPSIS
      • IGNORE_EXCEPTION_DETAIL
      • SKIP
      • COMPARISON_FLAGS
      • REPORT_UDIFF
      • REPORT_CDIFF
      • REPORT_NDIFF
      • REPORT_ONLY_FIRST_FAILURE
      • REPORTING_FLAGS
      • register_optionflag()
    • 25.2.3.6. Directives
    • 25.2.3.7. Warnings
  • 25.2.4. Basic API
    • testfile()
    • testmod()
    • run_docstring_examples()
  • 25.2.5. Unittest API
    • DocFileSuite()
    • DocTestSuite()
    • set_unittest_reportflags()
  • 25.2.6. Advanced API
    • 25.2.6.1. DocTest Objects
      • DocTest
        • DocTest.examples
        • DocTest.globs
        • DocTest.name
        • DocTest.filename
        • DocTest.lineno
        • DocTest.docstring
    • 25.2.6.2. Example Objects
      • Example
        • Example.source
        • Example.want
        • Example.exc_msg
        • Example.lineno
        • Example.indent
        • Example.options
    • 25.2.6.3. DocTestFinder objects
      • DocTestFinder
        • DocTestFinder.find()
    • 25.2.6.4. DocTestParser objects
      • DocTestParser
        • DocTestParser.get_doctest()
        • DocTestParser.get_examples()
        • DocTestParser.parse()
    • 25.2.6.5. DocTestRunner objects
      • DocTestRunner
        • DocTestRunner.report_start()
        • DocTestRunner.report_success()
        • DocTestRunner.report_failure()
        • DocTestRunner.report_unexpected_exception()
        • DocTestRunner.run()
        • DocTestRunner.summarize()
    • 25.2.6.6. OutputChecker objects
      • OutputChecker
        • OutputChecker.check_output()
        • OutputChecker.output_difference()
  • 25.2.7. Debugging
    • script_from_examples()
    • testsource()
    • debug()
    • debug_src()
    • DebugRunner
    • DocTestFailure
    • DocTestFailure.test
    • DocTestFailure.example
    • DocTestFailure.got
    • UnexpectedException
    • UnexpectedException.test
    • UnexpectedException.example
    • UnexpectedException.exc_info
  • 25.2.8. Soapbox
• 25.3. unittest — Unit testing framework
  • 25.3.1. Basic example
  • 25.3.2. Command-Line Interface
    • 25.3.2.1. Command-line options
  • 25.3.3. Test Discovery
  • 25.3.4. Organizing test code
  • 25.3.5. Re-using old test code
  • 25.3.6. Skipping tests and expected failures
    • skip()
    • skipIf()
    • skipUnless()
    • expectedFailure()
    • SkipTest
  • 25.3.7. Classes and functions
    • 25.3.7.1. Test cases
      • TestCase
        • TestCase.setUp()
        • TestCase.tearDown()
        • TestCase.setUpClass()
        • TestCase.tearDownClass()
        • TestCase.run()
        • TestCase.skipTest()
        • TestCase.debug()
        • TestCase.assertEqual()
        • TestCase.assertNotEqual()
        • TestCase.assertTrue()
        • TestCase.assertFalse()
        • TestCase.assertIs()
        • TestCase.assertIsNot()
        • TestCase.assertIsNone()
        • TestCase.assertIsNotNone()
        • TestCase.assertIn()
        • TestCase.assertNotIn()
        • TestCase.assertIsInstance()
        • TestCase.assertNotIsInstance()
        • TestCase.assertRaises()
        • TestCase.assertRaisesRegexp()
        • TestCase.assertAlmostEqual()
        • TestCase.assertNotAlmostEqual()
        • TestCase.assertGreater()
        • TestCase.assertGreaterEqual()
        • TestCase.assertLess()
        • TestCase.assertLessEqual()
        • TestCase.assertRegexpMatches()
        • TestCase.assertNotRegexpMatches()
        • TestCase.assertItemsEqual()
        • TestCase.assertDictContainsSubset()
        • TestCase.addTypeEqualityFunc()
        • TestCase.assertMultiLineEqual()
        • TestCase.assertSequenceEqual()
        • TestCase.assertListEqual()
        • TestCase.assertTupleEqual()
        • TestCase.assertSetEqual()
        • TestCase.assertDictEqual()
        • TestCase.fail()
        • TestCase.failureException
        • TestCase.longMessage
        • TestCase.maxDiff
        • TestCase.countTestCases()
        • TestCase.defaultTestResult()
        • TestCase.id()
        • TestCase.shortDescription()
        • TestCase.addCleanup()
        • TestCase.doCleanups()
      • FunctionTestCase
      • 25.3.7.1.1. Deprecated aliases
    • 25.3.7.2. Grouping tests
      • TestSuite
        • TestSuite.addTest()
        • TestSuite.addTests()
        • TestSuite.run()
        • TestSuite.debug()
        • TestSuite.countTestCases()
        • TestSuite.__iter__()
    • 25.3.7.3. Loading and running tests
      • TestLoader
        • TestLoader.loadTestsFromTestCase()
        • TestLoader.loadTestsFromModule()
        • TestLoader.loadTestsFromName()
        • TestLoader.loadTestsFromNames()
        • TestLoader.getTestCaseNames()
        • TestLoader.discover()
        • TestLoader.testMethodPrefix
        • TestLoader.sortTestMethodsUsing
        • TestLoader.suiteClass
      • TestResult
        • TestResult.errors
        • TestResult.failures
        • TestResult.skipped
        • TestResult.expectedFailures
        • TestResult.unexpectedSuccesses
        • TestResult.shouldStop
        • TestResult.testsRun
        • TestResult.buffer
        • TestResult.failfast
        • TestResult.wasSuccessful()
        • TestResult.stop()
        • TestResult.startTest()
        • TestResult.stopTest()
        • TestResult.startTestRun()
        • TestResult.stopTestRun()
        • TestResult.addError()
        • TestResult.addFailure()
        • TestResult.addSuccess()
        • TestResult.addSkip()
        • TestResult.addExpectedFailure()
        • TestResult.addUnexpectedSuccess()
      • TextTestResult
      • defaultTestLoader
      • TextTestRunner
        • TextTestRunner._makeResult()
      • main()
      • 25.3.7.3.1. load_tests Protocol
  • 25.3.8. Class and Module Fixtures
    • 25.3.8.1. setUpClass and tearDownClass
    • 25.3.8.2. setUpModule and tearDownModule
  • 25.3.9. Signal Handling
    • installHandler()
    • registerResult()
    • removeResult()
    • removeHandler()
• 25.4. 2to3 - Automated Python 2 to 3 code translation
  • 25.4.1. Using 2to3
  • 25.4.2. Fixers
  • 25.4.3. lib2to3 - 2to3’s library
• 25.5. test — Regression tests package for Python
  • 25.5.1. Writing Unit Tests for the test package
  • 25.5.2. Running tests using the command-line interface
• 25.6. test.support — Utility functions for tests
  • TestFailed
  • ResourceDenied
  • verbose
  • have_unicode
  • is_jython
  • TESTFN
  • TEST_HTTP_URL
  • forget()
  • is_resource_enabled()
  • requires()
  • findfile()
  • run_unittest()
  • check_warnings()
  • check_py3k_warnings()
  • captured_stdout()
  • import_module()
  • import_fresh_module()
  • TransientResource
  • EnvironmentVarGuard
  • EnvironmentVarGuard.set()
  • EnvironmentVarGuard.unset()
  • WarningsRecorder