Code

Ticket #2333: revised-django.patch

File revised-django.patch, 129.4 KB (added by russellm, 8 years ago)

Combined version of previous patches to django directory, with some minor revisions and cleanup

  • django/test/simple.py

     
     1import unittest, doctest 
     2from django.conf import settings 
     3from django.core import management 
     4from django.test.utils import create_test_db, destroy_test_db 
     5from django.test.testcases import OutputChecker, DocTestRunner 
     6 
     7# The module name for tests outside models.py 
     8TEST_MODULE = 'tests' 
     9     
     10doctestOutputChecker = OutputChecker() 
     11 
     12def build_suite(app_module): 
     13    "Create a complete Django test suite for the provided application module" 
     14    suite = unittest.TestSuite() 
     15     
     16    # Load unit and doctests in the models.py file 
     17    suite.addTest(unittest.defaultTestLoader.loadTestsFromModule(app_module)) 
     18    try: 
     19        suite.addTest(doctest.DocTestSuite(app_module, 
     20                                           checker=doctestOutputChecker, 
     21                                           runner=DocTestRunner)) 
     22    except ValueError: 
     23        # No doc tests in models.py 
     24        pass 
     25     
     26    # Check to see if a separate 'tests' module exists parallel to the  
     27    # models module 
     28    try: 
     29        app_path = app_module.__name__.split('.')[:-1] 
     30        test_module = __import__('.'.join(app_path + [TEST_MODULE]), [], [], TEST_MODULE) 
     31         
     32        suite.addTest(unittest.defaultTestLoader.loadTestsFromModule(test_module)) 
     33        try:             
     34            suite.addTest(doctest.DocTestSuite(test_module,  
     35                                               checker=doctestOutputChecker, 
     36                                               runner=DocTestRunner)) 
     37        except ValueError: 
     38            # No doc tests in tests.py 
     39            pass 
     40    except ImportError: 
     41        # No tests.py file for application 
     42        pass             
     43 
     44    return suite 
     45 
     46def run_tests(module_list, verbosity=1, extra_tests=[]): 
     47    """ 
     48    Run the unit tests for all the modules in the provided list. 
     49    This testrunner will search each of the modules in the provided list, 
     50    looking for doctests and unittests in models.py or tests.py within 
     51    the module. A list of 'extra' tests may also be provided; these tests 
     52    will be added to the test suite. 
     53    """ 
     54     
     55    settings.DEBUG = False     
     56    suite = unittest.TestSuite() 
     57      
     58    for module in module_list: 
     59        suite.addTest(build_suite(module)) 
     60     
     61    for test in extra_tests: 
     62        suite.addTest(test) 
     63 
     64    old_name = create_test_db(verbosity) 
     65    management.syncdb(verbosity, interactive=False) 
     66    unittest.TextTestRunner(verbosity=verbosity).run(suite) 
     67    destroy_test_db(old_name, verbosity) 
  • django/test/client.py

     
     1from cStringIO import StringIO 
     2from django.contrib.admin.views.decorators import LOGIN_FORM_KEY, _encode_post_data 
     3from django.core.handlers.base import BaseHandler 
     4from django.core.handlers.wsgi import WSGIRequest 
     5from django.dispatch import dispatcher 
     6from django.http import urlencode, SimpleCookie 
     7from django.template import signals 
     8from django.utils.functional import curry 
     9 
     10class ClientHandler(BaseHandler): 
     11    """ 
     12    A HTTP Handler that can be used for testing purposes.  
     13    Uses the WSGI interface to compose requests, but returns 
     14    the raw HttpResponse object 
     15    """ 
     16    def __call__(self, environ): 
     17        from django.conf import settings 
     18        from django.core import signals 
     19 
     20        # Set up middleware if needed. We couldn't do this earlier, because 
     21        # settings weren't available. 
     22        if self._request_middleware is None: 
     23            self.load_middleware() 
     24 
     25        dispatcher.send(signal=signals.request_started) 
     26        try: 
     27            request = WSGIRequest(environ) 
     28            response = self.get_response(request.path, request) 
     29 
     30            # Apply response middleware 
     31            for middleware_method in self._response_middleware: 
     32                response = middleware_method(request, response) 
     33 
     34        finally: 
     35            dispatcher.send(signal=signals.request_finished) 
     36         
     37        return response 
     38 
     39def store_rendered_templates(store, signal, sender, template, context): 
     40    "A utility function for storing templates and contexts that are rendered" 
     41    store.setdefault('template',[]).append(template) 
     42    store.setdefault('context',[]).append(context) 
     43 
     44def encode_multipart(boundary, data): 
     45    """ 
     46    A simple method for encoding multipart POST data from a dictionary of 
     47    form values. 
     48     
     49    The key will be used as the form data name; the value will be transmitted 
     50    as content. If the value is a file, the contents of the file will be sent 
     51    as an application/octet-stream; otherwise, str(value) will be sent. 
     52    """ 
     53    lines = [] 
     54    for (key, value) in data.items(): 
     55        if isinstance(value, file): 
     56            lines.extend([ 
     57                '--' + boundary, 
     58                'Content-Disposition: form-data; name="%s"' % key, 
     59                '', 
     60                '--' + boundary, 
     61                'Content-Disposition: form-data; name="%s_file"; filename="%s"' % (key, value.name), 
     62                'Content-Type: application/octet-stream', 
     63                '', 
     64                value.read() 
     65            ]) 
     66        else: 
     67            lines.extend([ 
     68                '--' + boundary, 
     69                'Content-Disposition: form-data; name="%s"' % key, 
     70                '', 
     71                str(value) 
     72            ]) 
     73         
     74    lines.extend([ 
     75        '--' + boundary + '--', 
     76        '', 
     77    ]) 
     78    return '\r\n'.join(lines) 
     79 
     80class Client: 
     81    """ 
     82    A class that can act as a client for testing purposes.  
     83       
     84    It allows the user to compose GET and POST requests, and 
     85    obtain the response that the server gave to those requests. 
     86    The server Response objects are annotated with the details 
     87    of the contexts and templates that were rendered during the 
     88    process of serving the request. 
     89 
     90    Client objects are stateful - they will retain cookie (and 
     91    thus session) details for the lifetime of the Client instance. 
     92     
     93    This is not intended as a replacement for Twill/Selenium or 
     94    the like - it is here to allow testing against the 
     95    contexts and templates produced by a view, rather than the 
     96    HTML rendered to the end-user. 
     97    """ 
     98    def __init__(self, **defaults): 
     99        self.handler = TestHandler() 
     100        self.defaults = defaults 
     101        self.cookie = SimpleCookie() 
     102         
     103    def request(self, **request): 
     104        """ 
     105        The master request method. Composes the environment dictionary  
     106        and passes to the handler, returning the result of the handler. 
     107        Assumes defaults for the query environment, which can be overridden 
     108        using the arguments to the request. 
     109        """ 
     110 
     111        environ = { 
     112            'HTTP_COOKIE':      self.cookie, 
     113            'PATH_INFO':         '/', 
     114            'QUERY_STRING':      '', 
     115            'REQUEST_METHOD':    'GET', 
     116            'SCRIPT_NAME':       None,  
     117            'SERVER_NAME':       'testserver', 
     118            'SERVER_PORT':       80, 
     119            'SERVER_PROTOCOL':   'HTTP/1.1', 
     120        }         
     121        environ.update(self.defaults) 
     122        environ.update(request)         
     123 
     124        # Curry a data dictionary into an instance of 
     125        # the template renderer callback function 
     126        data = {} 
     127        on_template_render = curry(store_rendered_templates, data) 
     128        dispatcher.connect(on_template_render, signal=signals.template_rendered) 
     129 
     130        response = self.handler(environ) 
     131         
     132        # Add any rendered template detail to the response 
     133        # If there was only one template rendered (the most likely case),  
     134        # flatten the list to a single element 
     135        for detail in ('template', 'context'): 
     136            if data.get(detail): 
     137                if len(data[detail]) == 1: 
     138                    setattr(response, detail, data[detail][0]); 
     139                else: 
     140                    setattr(response, detail, data[detail]) 
     141            else: 
     142                setattr(response, detail, None) 
     143         
     144        if response.cookies: 
     145            self.cookie.update(response.cookies) 
     146 
     147        return response 
     148         
     149    def get(self, path, data={}, **extra): 
     150        "Request a response from the server using GET." 
     151        r = { 
     152            'CONTENT_LENGTH':  None, 
     153            'CONTENT_TYPE':    'text/html; charset=utf-8', 
     154            'PATH_INFO':       path, 
     155            'QUERY_STRING':    urlencode(data), 
     156            'REQUEST_METHOD': 'GET', 
     157        } 
     158        r.update(extra) 
     159         
     160        return self.request(**r) 
     161     
     162    def post(self, path, data={}, **extra): 
     163        "Request a response from the server using POST." 
     164         
     165        BOUNDARY = 'BoUnDaRyStRiNg' 
     166 
     167        encoded = encode_multipart(BOUNDARY, data) 
     168        stream = StringIO(encoded) 
     169        r = { 
     170            'CONTENT_LENGTH': len(encoded), 
     171            'CONTENT_TYPE':   'multipart/form-data; boundary=%s' % BOUNDARY, 
     172            'PATH_INFO':      path, 
     173            'REQUEST_METHOD': 'POST', 
     174            'wsgi.input':     stream, 
     175        } 
     176        r.update(extra) 
     177         
     178        return self.request(**r) 
     179 
     180    def login(self, path, username, password, **extra): 
     181        """ 
     182        A specialized sequence of GET and POST to log into a view that 
     183        is protected by @login_required or a similar access decorator. 
     184         
     185        path should be the URL of the login page, or of any page that 
     186        is login protected. 
     187         
     188        Returns True if login was successful; False if otherwise.         
     189        """ 
     190        # First, GET the login page.  
     191        # This is required to establish the session. 
     192        response = self.get(path) 
     193        if response.status_code != 200: 
     194            return False 
     195 
     196        # Set up the block of form data required by the login page. 
     197        form_data = { 
     198            'username': username, 
     199            'password': password, 
     200            'this_is_the_login_form':1, 
     201            'post_data':_encode_post_data({LOGIN_FORM_KEY: 1}) 
     202        } 
     203        response = self.post('/admin/', data=form_data, **extra) 
     204         
     205        # login page should response 200 (if you requested the login 
     206        # page specifically), or 302 (if you requested a login 
     207        # protected page, to which the login can redirect). 
     208        return response.status_code in (200,302) 
  • django/test/testcases.py

     
     1import re, doctest, unittest 
     2from django.db import transaction 
     3     
     4normalize_long_ints = lambda s: re.sub(r'(?<![\w])(\d+)L(?![\w])', '\\1', s) 
     5 
     6class OutputChecker(doctest.OutputChecker): 
     7    def check_output(self, want, got, optionflags): 
     8        ok = doctest.OutputChecker.check_output(self, want, got, optionflags) 
     9 
     10        # Doctest does an exact string comparison of output, which means long 
     11        # integers aren't equal to normal integers ("22L" vs. "22"). The 
     12        # following code normalizes long integers so that they equal normal 
     13        # integers. 
     14        if not ok: 
     15            return normalize_long_ints(want) == normalize_long_ints(got) 
     16        return ok 
     17                   
     18class DocTestRunner(doctest.DocTestRunner): 
     19    def __init__(self, *args, **kwargs): 
     20        doctest.DocTestRunner.__init__(self, *args, **kwargs) 
     21        self.optionflags = doctest.ELLIPSIS 
     22         
     23    def report_unexpected_exception(self, out, test, example, exc_info): 
     24        doctest.DocTestRunner.report_unexpected_exception(self,out,test,example,exc_info) 
     25         
     26        # Rollback, in case of database errors. Otherwise they'd have 
     27        # side effects on other tests. 
     28        from django.db import transaction 
     29        transaction.rollback_unless_managed() 
     30 
  • django/test/utils.py

     
     1import sys, time 
     2from django.conf import settings 
     3from django.db import connection, transaction 
     4 
     5# The prefix to put on the default database name when creating 
     6# the test database. 
     7TEST_DATABASE_PREFIX = 'test_' 
     8 
     9def _set_autocommit(connection): 
     10    "Make sure a connection is in autocommit mode." 
     11    if hasattr(connection.connection, "autocommit"): 
     12        connection.connection.autocommit(True) 
     13    elif hasattr(connection.connection, "set_isolation_level"): 
     14        connection.connection.set_isolation_level(0) 
     15 
     16def create_test_db(verbosity=1, autoclobber=False): 
     17    if verbosity >= 1: 
     18        print "Creating test database..." 
     19    # If we're using SQLite, it's more convenient to test against an 
     20    # in-memory database. 
     21    if settings.DATABASE_ENGINE == "sqlite3": 
     22        TEST_DATABASE_NAME = ":memory:" 
     23    else: 
     24        TEST_DATABASE_NAME = TEST_DATABASE_PREFIX + settings.DATABASE_NAME 
     25         
     26        # Create the test database and connect to it. We need to autocommit 
     27        # if the database supports it because PostgreSQL doesn't allow  
     28        # CREATE/DROP DATABASE statements within transactions. 
     29        cursor = connection.cursor() 
     30        _set_autocommit(connection) 
     31        try: 
     32            cursor.execute("CREATE DATABASE %s" % TEST_DATABASE_NAME) 
     33        except Exception, e:             
     34            sys.stderr.write("Got an error creating the test database: %s\n" % e) 
     35            if not autoclobber: 
     36                confirm = raw_input("It appears the test database, %s, already exists. Type 'yes' to delete it, or 'no' to cancel: " % TEST_DATABASE_NAME) 
     37            if autoclobber or confirm == 'yes': 
     38                try: 
     39                    if verbosity >= 1: 
     40                        print "Destroying old test database..."                 
     41                    cursor.execute("DROP DATABASE %s" % TEST_DATABASE_NAME) 
     42                    if verbosity >= 1: 
     43                        print "Creating test database..." 
     44                    cursor.execute("CREATE DATABASE %s" % TEST_DATABASE_NAME) 
     45                except Exception, e: 
     46                    sys.stderr.write("Got an error recreating the test database: %s\n" % e) 
     47                    sys.exit(2) 
     48            else: 
     49                print "Tests cancelled." 
     50                sys.exit(1) 
     51                
     52    connection.close() 
     53    old_database_name = settings.DATABASE_NAME 
     54    settings.DATABASE_NAME = TEST_DATABASE_NAME 
     55 
     56    # Get a cursor (even though we don't need one yet). This has 
     57    # the side effect of initializing the test database. 
     58    cursor = connection.cursor() 
     59             
     60    return old_database_name 
     61 
     62def destroy_test_db(old_database_name, verbosity=1): 
     63    # Unless we're using SQLite, remove the test database to clean up after 
     64    # ourselves. Connect to the previous database (not the test database) 
     65    # to do so, because it's not allowed to delete a database while being 
     66    # connected to it. 
     67    if verbosity >= 1: 
     68        print "Destroying test database..." 
     69    if settings.DATABASE_ENGINE != "sqlite3": 
     70        connection.close() 
     71        TEST_DATABASE_NAME = settings.DATABASE_NAME 
     72        settings.DATABASE_NAME = old_database_name 
     73        cursor = connection.cursor() 
     74        _set_autocommit(connection) 
     75        time.sleep(1) # To avoid "database is being accessed by other users" errors. 
     76        cursor.execute("DROP DATABASE %s" % TEST_DATABASE_NAME) 
     77        connection.close() 
     78 
  • django/test/doctest.py

     
     1# Module doctest. 
     2# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org). 
     3# Major enhancements and refactoring by: 
     4#     Jim Fulton 
     5#     Edward Loper 
     6 
     7# Provided as-is; use at your own risk; no warranty; no promises; enjoy! 
     8 
     9r"""Module doctest -- a framework for running examples in docstrings. 
     10 
     11In simplest use, end each module M to be tested with: 
     12 
     13def _test(): 
     14    import doctest 
     15    doctest.testmod() 
     16 
     17if __name__ == "__main__": 
     18    _test() 
     19 
     20Then running the module as a script will cause the examples in the 
     21docstrings to get executed and verified: 
     22 
     23python M.py 
     24 
     25This won't display anything unless an example fails, in which case the 
     26failing example(s) and the cause(s) of the failure(s) are printed to stdout 
     27(why not stderr? because stderr is a lame hack <0.2 wink>), and the final 
     28line of output is "Test failed.". 
     29 
     30Run it with the -v switch instead: 
     31 
     32python M.py -v 
     33 
     34and a detailed report of all examples tried is printed to stdout, along 
     35with assorted summaries at the end. 
     36 
     37You can force verbose mode by passing "verbose=True" to testmod, or prohibit 
     38it by passing "verbose=False".  In either of those cases, sys.argv is not 
     39examined by testmod. 
     40 
     41There are a variety of other ways to run doctests, including integration 
     42with the unittest framework, and support for running non-Python text 
     43files containing doctests.  There are also many ways to override parts 
     44of doctest's default behaviors.  See the Library Reference Manual for 
     45details. 
     46""" 
     47 
     48__docformat__ = 'reStructuredText en' 
     49 
     50__all__ = [ 
     51    # 0, Option Flags 
     52    'register_optionflag', 
     53    'DONT_ACCEPT_TRUE_FOR_1', 
     54    'DONT_ACCEPT_BLANKLINE', 
     55    'NORMALIZE_WHITESPACE', 
     56    'ELLIPSIS', 
     57    'IGNORE_EXCEPTION_DETAIL', 
     58    'COMPARISON_FLAGS', 
     59    'REPORT_UDIFF', 
     60    'REPORT_CDIFF', 
     61    'REPORT_NDIFF', 
     62    'REPORT_ONLY_FIRST_FAILURE', 
     63    'REPORTING_FLAGS', 
     64    # 1. Utility Functions 
     65    'is_private', 
     66    # 2. Example & DocTest 
     67    'Example', 
     68    'DocTest', 
     69    # 3. Doctest Parser 
     70    'DocTestParser', 
     71    # 4. Doctest Finder 
     72    'DocTestFinder', 
     73    # 5. Doctest Runner 
     74    'DocTestRunner', 
     75    'OutputChecker', 
     76    'DocTestFailure', 
     77    'UnexpectedException', 
     78    'DebugRunner', 
     79    # 6. Test Functions 
     80    'testmod', 
     81    'testfile', 
     82    'run_docstring_examples', 
     83    # 7. Tester 
     84    'Tester', 
     85    # 8. Unittest Support 
     86    'DocTestSuite', 
     87    'DocFileSuite', 
     88    'set_unittest_reportflags', 
     89    # 9. Debugging Support 
     90    'script_from_examples', 
     91    'testsource', 
     92    'debug_src', 
     93    'debug', 
     94] 
     95 
     96import __future__ 
     97 
     98import sys, traceback, inspect, linecache, os, re, types 
     99import unittest, difflib, pdb, tempfile 
     100import warnings 
     101from StringIO import StringIO 
     102 
     103# Don't whine about the deprecated is_private function in this 
     104# module's tests. 
     105warnings.filterwarnings("ignore", "is_private", DeprecationWarning, 
     106                        __name__, 0) 
     107 
     108# There are 4 basic classes: 
     109#  - Example: a <source, want> pair, plus an intra-docstring line number. 
     110#  - DocTest: a collection of examples, parsed from a docstring, plus 
     111#    info about where the docstring came from (name, filename, lineno). 
     112#  - DocTestFinder: extracts DocTests from a given object's docstring and 
     113#    its contained objects' docstrings. 
     114#  - DocTestRunner: runs DocTest cases, and accumulates statistics. 
     115# 
     116# So the basic picture is: 
     117# 
     118#                             list of: 
     119# +------+                   +---------+                   +-------+ 
     120# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results| 
     121# +------+                   +---------+                   +-------+ 
     122#                            | Example | 
     123#                            |   ...   | 
     124#                            | Example | 
     125#                            +---------+ 
     126 
     127# Option constants. 
     128 
     129OPTIONFLAGS_BY_NAME = {} 
     130def register_optionflag(name): 
     131    flag = 1 << len(OPTIONFLAGS_BY_NAME) 
     132    OPTIONFLAGS_BY_NAME[name] = flag 
     133    return flag 
     134 
     135DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1') 
     136DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE') 
     137NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE') 
     138ELLIPSIS = register_optionflag('ELLIPSIS') 
     139IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL') 
     140 
     141COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 | 
     142                    DONT_ACCEPT_BLANKLINE | 
     143                    NORMALIZE_WHITESPACE | 
     144                    ELLIPSIS | 
     145                    IGNORE_EXCEPTION_DETAIL) 
     146 
     147REPORT_UDIFF = register_optionflag('REPORT_UDIFF') 
     148REPORT_CDIFF = register_optionflag('REPORT_CDIFF') 
     149REPORT_NDIFF = register_optionflag('REPORT_NDIFF') 
     150REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE') 
     151 
     152REPORTING_FLAGS = (REPORT_UDIFF | 
     153                   REPORT_CDIFF | 
     154                   REPORT_NDIFF | 
     155                   REPORT_ONLY_FIRST_FAILURE) 
     156 
     157# Special string markers for use in `want` strings: 
     158BLANKLINE_MARKER = '<BLANKLINE>' 
     159ELLIPSIS_MARKER = '...' 
     160 
     161###################################################################### 
     162## Table of Contents 
     163###################################################################### 
     164#  1. Utility Functions 
     165#  2. Example & DocTest -- store test cases 
     166#  3. DocTest Parser -- extracts examples from strings 
     167#  4. DocTest Finder -- extracts test cases from objects 
     168#  5. DocTest Runner -- runs test cases 
     169#  6. Test Functions -- convenient wrappers for testing 
     170#  7. Tester Class -- for backwards compatibility 
     171#  8. Unittest Support 
     172#  9. Debugging Support 
     173# 10. Example Usage 
     174 
     175###################################################################### 
     176## 1. Utility Functions 
     177###################################################################### 
     178 
     179def is_private(prefix, base): 
     180    """prefix, base -> true iff name prefix + "." + base is "private". 
     181 
     182    Prefix may be an empty string, and base does not contain a period. 
     183    Prefix is ignored (although functions you write conforming to this 
     184    protocol may make use of it). 
     185    Return true iff base begins with an (at least one) underscore, but 
     186    does not both begin and end with (at least) two underscores. 
     187 
     188    >>> is_private("a.b", "my_func") 
     189    False 
     190    >>> is_private("____", "_my_func") 
     191    True 
     192    >>> is_private("someclass", "__init__") 
     193    False 
     194    >>> is_private("sometypo", "__init_") 
     195    True 
     196    >>> is_private("x.y.z", "_") 
     197    True 
     198    >>> is_private("_x.y.z", "__") 
     199    False 
     200    >>> is_private("", "")  # senseless but consistent 
     201    False 
     202    """ 
     203    warnings.warn("is_private is deprecated; it wasn't useful; " 
     204                  "examine DocTestFinder.find() lists instead", 
     205                  DeprecationWarning, stacklevel=2) 
     206    return base[:1] == "_" and not base[:2] == "__" == base[-2:] 
     207 
     208def _extract_future_flags(globs): 
     209    """ 
     210    Return the compiler-flags associated with the future features that 
     211    have been imported into the given namespace (globs). 
     212    """ 
     213    flags = 0 
     214    for fname in __future__.all_feature_names: 
     215        feature = globs.get(fname, None) 
     216        if feature is getattr(__future__, fname): 
     217            flags |= feature.compiler_flag 
     218    return flags 
     219 
     220def _normalize_module(module, depth=2): 
     221    """ 
     222    Return the module specified by `module`.  In particular: 
     223      - If `module` is a module, then return module. 
     224      - If `module` is a string, then import and return the 
     225        module with that name. 
     226      - If `module` is None, then return the calling module. 
     227        The calling module is assumed to be the module of 
     228        the stack frame at the given depth in the call stack. 
     229    """ 
     230    if inspect.ismodule(module): 
     231        return module 
     232    elif isinstance(module, (str, unicode)): 
     233        return __import__(module, globals(), locals(), ["*"]) 
     234    elif module is None: 
     235        return sys.modules[sys._getframe(depth).f_globals['__name__']] 
     236    else: 
     237        raise TypeError("Expected a module, string, or None") 
     238 
     239def _indent(s, indent=4): 
     240    """ 
     241    Add the given number of space characters to the beginning every 
     242    non-blank line in `s`, and return the result. 
     243    """ 
     244    # This regexp matches the start of non-blank lines: 
     245    return re.sub('(?m)^(?!$)', indent*' ', s) 
     246 
     247def _exception_traceback(exc_info): 
     248    """ 
     249    Return a string containing a traceback message for the given 
     250    exc_info tuple (as returned by sys.exc_info()). 
     251    """ 
     252    # Get a traceback message. 
     253    excout = StringIO() 
     254    exc_type, exc_val, exc_tb = exc_info 
     255    traceback.print_exception(exc_type, exc_val, exc_tb, file=excout) 
     256    return excout.getvalue() 
     257 
     258# Override some StringIO methods. 
     259class _SpoofOut(StringIO): 
     260    def getvalue(self): 
     261        result = StringIO.getvalue(self) 
     262        # If anything at all was written, make sure there's a trailing 
     263        # newline.  There's no way for the expected output to indicate 
     264        # that a trailing newline is missing. 
     265        if result and not result.endswith("\n"): 
     266            result += "\n" 
     267        # Prevent softspace from screwing up the next test case, in 
     268        # case they used print with a trailing comma in an example. 
     269        if hasattr(self, "softspace"): 
     270            del self.softspace 
     271        return result 
     272 
     273    def truncate(self,   size=None): 
     274        StringIO.truncate(self, size) 
     275        if hasattr(self, "softspace"): 
     276            del self.softspace 
     277 
     278# Worst-case linear-time ellipsis matching. 
     279def _ellipsis_match(want, got): 
     280    """ 
     281    Essentially the only subtle case: 
     282    >>> _ellipsis_match('aa...aa', 'aaa') 
     283    False 
     284    """ 
     285    if ELLIPSIS_MARKER not in want: 
     286        return want == got 
     287 
     288    # Find "the real" strings. 
     289    ws = want.split(ELLIPSIS_MARKER) 
     290    assert len(ws) >= 2 
     291 
     292    # Deal with exact matches possibly needed at one or both ends. 
     293    startpos, endpos = 0, len(got) 
     294    w = ws[0] 
     295    if w:   # starts with exact match 
     296        if got.startswith(w): 
     297            startpos = len(w) 
     298            del ws[0] 
     299        else: 
     300            return False 
     301    w = ws[-1] 
     302    if w:   # ends with exact match 
     303        if got.endswith(w): 
     304            endpos -= len(w) 
     305            del ws[-1] 
     306        else: 
     307            return False 
     308 
     309    if startpos > endpos: 
     310        # Exact end matches required more characters than we have, as in 
     311        # _ellipsis_match('aa...aa', 'aaa') 
     312        return False 
     313 
     314    # For the rest, we only need to find the leftmost non-overlapping 
     315    # match for each piece.  If there's no overall match that way alone, 
     316    # there's no overall match period. 
     317    for w in ws: 
     318        # w may be '' at times, if there are consecutive ellipses, or 
     319        # due to an ellipsis at the start or end of `want`.  That's OK. 
     320        # Search for an empty string succeeds, and doesn't change startpos. 
     321        startpos = got.find(w, startpos, endpos) 
     322        if startpos < 0: 
     323            return False 
     324        startpos += len(w) 
     325 
     326    return True 
     327 
     328def _comment_line(line): 
     329    "Return a commented form of the given line" 
     330    line = line.rstrip() 
     331    if line: 
     332        return '# '+line 
     333    else: 
     334        return '#' 
     335 
     336class _OutputRedirectingPdb(pdb.Pdb): 
     337    """ 
     338    A specialized version of the python debugger that redirects stdout 
     339    to a given stream when interacting with the user.  Stdout is *not* 
     340    redirected when traced code is executed. 
     341    """ 
     342    def __init__(self, out): 
     343        self.__out = out 
     344        pdb.Pdb.__init__(self) 
     345 
     346    def trace_dispatch(self, *args): 
     347        # Redirect stdout to the given stream. 
     348        save_stdout = sys.stdout 
     349        sys.stdout = self.__out 
     350        # Call Pdb's trace dispatch method. 
     351        try: 
     352            return pdb.Pdb.trace_dispatch(self, *args) 
     353        finally: 
     354            sys.stdout = save_stdout 
     355 
     356# [XX] Normalize with respect to os.path.pardir? 
     357def _module_relative_path(module, path): 
     358    if not inspect.ismodule(module): 
     359        raise TypeError, 'Expected a module: %r' % module 
     360    if path.startswith('/'): 
     361        raise ValueError, 'Module-relative files may not have absolute paths' 
     362 
     363    # Find the base directory for the path. 
     364    if hasattr(module, '__file__'): 
     365        # A normal module/package 
     366        basedir = os.path.split(module.__file__)[0] 
     367    elif module.__name__ == '__main__': 
     368        # An interactive session. 
     369        if len(sys.argv)>0 and sys.argv[0] != '': 
     370            basedir = os.path.split(sys.argv[0])[0] 
     371        else: 
     372            basedir = os.curdir 
     373    else: 
     374        # A module w/o __file__ (this includes builtins) 
     375        raise ValueError("Can't resolve paths relative to the module " + 
     376                         module + " (it has no __file__)") 
     377 
     378    # Combine the base directory and the path. 
     379    return os.path.join(basedir, *(path.split('/'))) 
     380 
     381###################################################################### 
     382## 2. Example & DocTest 
     383###################################################################### 
     384## - An "example" is a <source, want> pair, where "source" is a 
     385##   fragment of source code, and "want" is the expected output for 
     386##   "source."  The Example class also includes information about 
     387##   where the example was extracted from. 
     388## 
     389## - A "doctest" is a collection of examples, typically extracted from 
     390##   a string (such as an object's docstring).  The DocTest class also 
     391##   includes information about where the string was extracted from. 
     392 
     393class Example: 
     394    """ 
     395    A single doctest example, consisting of source code and expected 
     396    output.  `Example` defines the following attributes: 
     397 
     398      - source: A single Python statement, always ending with a newline. 
     399        The constructor adds a newline if needed. 
     400 
     401      - want: The expected output from running the source code (either 
     402        from stdout, or a traceback in case of exception).  `want` ends 
     403        with a newline unless it's empty, in which case it's an empty 
     404        string.  The constructor adds a newline if needed. 
     405 
     406      - exc_msg: The exception message generated by the example, if 
     407        the example is expected to generate an exception; or `None` if 
     408        it is not expected to generate an exception.  This exception 
     409        message is compared against the return value of 
     410        `traceback.format_exception_only()`.  `exc_msg` ends with a 
     411        newline unless it's `None`.  The constructor adds a newline 
     412        if needed. 
     413 
     414      - lineno: The line number within the DocTest string containing 
     415        this Example where the Example begins.  This line number is 
     416        zero-based, with respect to the beginning of the DocTest. 
     417 
     418      - indent: The example's indentation in the DocTest string. 
     419        I.e., the number of space characters that preceed the 
     420        example's first prompt. 
     421 
     422      - options: A dictionary mapping from option flags to True or 
     423        False, which is used to override default options for this 
     424        example.  Any option flags not contained in this dictionary 
     425        are left at their default value (as specified by the 
     426        DocTestRunner's optionflags).  By default, no options are set. 
     427    """ 
     428    def __init__(self, source, want, exc_msg=None, lineno=0, indent=0, 
     429                 options=None): 
     430        # Normalize inputs. 
     431        if not source.endswith('\n'): 
     432            source += '\n' 
     433        if want and not want.endswith('\n'): 
     434            want += '\n' 
     435        if exc_msg is not None and not exc_msg.endswith('\n'): 
     436            exc_msg += '\n' 
     437        # Store properties. 
     438        self.source = source 
     439        self.want = want 
     440        self.lineno = lineno 
     441        self.indent = indent 
     442        if options is None: options = {} 
     443        self.options = options 
     444        self.exc_msg = exc_msg 
     445 
     446class DocTest: 
     447    """ 
     448    A collection of doctest examples that should be run in a single 
     449    namespace.  Each `DocTest` defines the following attributes: 
     450 
     451      - examples: the list of examples. 
     452 
     453      - globs: The namespace (aka globals) that the examples should 
     454        be run in. 
     455 
     456      - name: A name identifying the DocTest (typically, the name of 
     457        the object whose docstring this DocTest was extracted from). 
     458 
     459      - filename: The name of the file that this DocTest was extracted 
     460        from, or `None` if the filename is unknown. 
     461 
     462      - lineno: The line number within filename where this DocTest 
     463        begins, or `None` if the line number is unavailable.  This 
     464        line number is zero-based, with respect to the beginning of 
     465        the file. 
     466 
     467      - docstring: The string that the examples were extracted from, 
     468        or `None` if the string is unavailable. 
     469    """ 
     470    def __init__(self, examples, globs, name, filename, lineno, docstring): 
     471        """ 
     472        Create a new DocTest containing the given examples.  The 
     473        DocTest's globals are initialized with a copy of `globs`. 
     474        """ 
     475        assert not isinstance(examples, basestring), \ 
     476               "DocTest no longer accepts str; use DocTestParser instead" 
     477        self.examples = examples 
     478        self.docstring = docstring 
     479        self.globs = globs.copy() 
     480        self.name = name 
     481        self.filename = filename 
     482        self.lineno = lineno 
     483 
     484    def __repr__(self): 
     485        if len(self.examples) == 0: 
     486            examples = 'no examples' 
     487        elif len(self.examples) == 1: 
     488            examples = '1 example' 
     489        else: 
     490            examples = '%d examples' % len(self.examples) 
     491        return ('<DocTest %s from %s:%s (%s)>' % 
     492                (self.name, self.filename, self.lineno, examples)) 
     493 
     494 
     495    # This lets us sort tests by name: 
     496    def __cmp__(self, other): 
     497        if not isinstance(other, DocTest): 
     498            return -1 
     499        return cmp((self.name, self.filename, self.lineno, id(self)), 
     500                   (other.name, other.filename, other.lineno, id(other))) 
     501 
     502###################################################################### 
     503## 3. DocTestParser 
     504###################################################################### 
     505 
     506class DocTestParser: 
     507    """ 
     508    A class used to parse strings containing doctest examples. 
     509    """ 
     510    # This regular expression is used to find doctest examples in a 
     511    # string.  It defines three groups: `source` is the source code 
     512    # (including leading indentation and prompts); `indent` is the 
     513    # indentation of the first (PS1) line of the source code; and 
     514    # `want` is the expected output (including leading indentation). 
     515    _EXAMPLE_RE = re.compile(r''' 
     516        # Source consists of a PS1 line followed by zero or more PS2 lines. 
     517        (?P<source> 
     518            (?:^(?P<indent> [ ]*) >>>    .*)    # PS1 line 
     519            (?:\n           [ ]*  \.\.\. .*)*)  # PS2 lines 
     520        \n? 
     521        # Want consists of any non-blank lines that do not start with PS1. 
     522        (?P<want> (?:(?![ ]*$)    # Not a blank line 
     523                     (?![ ]*>>>)  # Not a line starting with PS1 
     524                     .*$\n?       # But any other line 
     525                  )*) 
     526        ''', re.MULTILINE | re.VERBOSE) 
     527 
     528    # A regular expression for handling `want` strings that contain 
     529    # expected exceptions.  It divides `want` into three pieces: 
     530    #    - the traceback header line (`hdr`) 
     531    #    - the traceback stack (`stack`) 
     532    #    - the exception message (`msg`), as generated by 
     533    #      traceback.format_exception_only() 
     534    # `msg` may have multiple lines.  We assume/require that the 
     535    # exception message is the first non-indented line starting with a word 
     536    # character following the traceback header line. 
     537    _EXCEPTION_RE = re.compile(r""" 
     538        # Grab the traceback header.  Different versions of Python have 
     539        # said different things on the first traceback line. 
     540        ^(?P<hdr> Traceback\ \( 
     541            (?: most\ recent\ call\ last 
     542            |   innermost\ last 
     543            ) \) : 
     544        ) 
     545        \s* $                # toss trailing whitespace on the header. 
     546        (?P<stack> .*?)      # don't blink: absorb stuff until... 
     547        ^ (?P<msg> \w+ .*)   #     a line *starts* with alphanum. 
     548        """, re.VERBOSE | re.MULTILINE | re.DOTALL) 
     549 
     550    # A callable returning a true value iff its argument is a blank line 
     551    # or contains a single comment. 
     552    _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match 
     553 
     554    def parse(self, string, name='<string>'): 
     555        """ 
     556        Divide the given string into examples and intervening text, 
     557        and return them as a list of alternating Examples and strings. 
     558        Line numbers for the Examples are 0-based.  The optional 
     559        argument `name` is a name identifying this string, and is only 
     560        used for error messages. 
     561        """ 
     562        string = string.expandtabs() 
     563        # If all lines begin with the same indentation, then strip it. 
     564        min_indent = self._min_indent(string) 
     565        if min_indent > 0: 
     566            string = '\n'.join([l[min_indent:] for l in string.split('\n')]) 
     567 
     568        output = [] 
     569        charno, lineno = 0, 0 
     570        # Find all doctest examples in the string: 
     571        for m in self._EXAMPLE_RE.finditer(string): 
     572            # Add the pre-example text to `output`. 
     573            output.append(string[charno:m.start()]) 
     574            # Update lineno (lines before this example) 
     575            lineno += string.count('\n', charno, m.start()) 
     576            # Extract info from the regexp match. 
     577            (source, options, want, exc_msg) = \ 
     578                     self._parse_example(m, name, lineno) 
     579            # Create an Example, and add it to the list. 
     580            if not self._IS_BLANK_OR_COMMENT(source): 
     581                output.append( Example(source, want, exc_msg, 
     582                                    lineno=lineno, 
     583                                    indent=min_indent+len(m.group('indent')), 
     584                                    options=options) ) 
     585            # Update lineno (lines inside this example) 
     586            lineno += string.count('\n', m.start(), m.end()) 
     587            # Update charno. 
     588            charno = m.end() 
     589        # Add any remaining post-example text to `output`. 
     590        output.append(string[charno:]) 
     591        return output 
     592 
     593    def get_doctest(self, string, globs, name, filename, lineno): 
     594        """ 
     595        Extract all doctest examples from the given string, and 
     596        collect them into a `DocTest` object. 
     597 
     598        `globs`, `name`, `filename`, and `lineno` are attributes for 
     599        the new `DocTest` object.  See the documentation for `DocTest` 
     600        for more information. 
     601        """ 
     602        return DocTest(self.get_examples(string, name), globs, 
     603                       name, filename, lineno, string) 
     604 
     605    def get_examples(self, string, name='<string>'): 
     606        """ 
     607        Extract all doctest examples from the given string, and return 
     608        them as a list of `Example` objects.  Line numbers are 
     609        0-based, because it's most common in doctests that nothing 
     610        interesting appears on the same line as opening triple-quote, 
     611        and so the first interesting line is called \"line 1\" then. 
     612 
     613        The optional argument `name` is a name identifying this 
     614        string, and is only used for error messages. 
     615        """ 
     616        return [x for x in self.parse(string, name) 
     617                if isinstance(x, Example)] 
     618 
     619    def _parse_example(self, m, name, lineno): 
     620        """ 
     621        Given a regular expression match from `_EXAMPLE_RE` (`m`), 
     622        return a pair `(source, want)`, where `source` is the matched 
     623        example's source code (with prompts and indentation stripped); 
     624        and `want` is the example's expected output (with indentation 
     625        stripped). 
     626 
     627        `name` is the string's name, and `lineno` is the line number 
     628        where the example starts; both are used for error messages. 
     629        """ 
     630        # Get the example's indentation level. 
     631        indent = len(m.group('indent')) 
     632 
     633        # Divide source into lines; check that they're properly 
     634        # indented; and then strip their indentation & prompts. 
     635        source_lines = m.group('source').split('\n') 
     636        self._check_prompt_blank(source_lines, indent, name, lineno) 
     637        self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno) 
     638        source = '\n'.join([sl[indent+4:] for sl in source_lines]) 
     639 
     640        # Divide want into lines; check that it's properly indented; and 
     641        # then strip the indentation.  Spaces before the last newline should 
     642        # be preserved, so plain rstrip() isn't good enough. 
     643        want = m.group('want') 
     644        want_lines = want.split('\n') 
     645        if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]): 
     646            del want_lines[-1]  # forget final newline & spaces after it 
     647        self._check_prefix(want_lines, ' '*indent, name, 
     648                           lineno + len(source_lines)) 
     649        want = '\n'.join([wl[indent:] for wl in want_lines]) 
     650 
     651        # If `want` contains a traceback message, then extract it. 
     652        m = self._EXCEPTION_RE.match(want) 
     653        if m: 
     654            exc_msg = m.group('msg') 
     655        else: 
     656            exc_msg = None 
     657 
     658        # Extract options from the source. 
     659        options = self._find_options(source, name, lineno) 
     660 
     661        return source, options, want, exc_msg 
     662 
     663    # This regular expression looks for option directives in the 
     664    # source code of an example.  Option directives are comments 
     665    # starting with "doctest:".  Warning: this may give false 
     666    # positives for string-literals that contain the string 
     667    # "#doctest:".  Eliminating these false positives would require 
     668    # actually parsing the string; but we limit them by ignoring any 
     669    # line containing "#doctest:" that is *followed* by a quote mark. 
     670    _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$', 
     671                                      re.MULTILINE) 
     672 
     673    def _find_options(self, source, name, lineno): 
     674        """ 
     675        Return a dictionary containing option overrides extracted from 
     676        option directives in the given source string. 
     677 
     678        `name` is the string's name, and `lineno` is the line number 
     679        where the example starts; both are used for error messages. 
     680        """ 
     681        options = {} 
     682        # (note: with the current regexp, this will match at most once:) 
     683        for m in self._OPTION_DIRECTIVE_RE.finditer(source): 
     684            option_strings = m.group(1).replace(',', ' ').split() 
     685            for option in option_strings: 
     686                if (option[0] not in '+-' or 
     687                    option[1:] not in OPTIONFLAGS_BY_NAME): 
     688                    raise ValueError('line %r of the doctest for %s ' 
     689                                     'has an invalid option: %r' % 
     690                                     (lineno+1, name, option)) 
     691                flag = OPTIONFLAGS_BY_NAME[option[1:]] 
     692                options[flag] = (option[0] == '+') 
     693        if options and self._IS_BLANK_OR_COMMENT(source): 
     694            raise ValueError('line %r of the doctest for %s has an option ' 
     695                             'directive on a line with no example: %r' % 
     696                             (lineno, name, source)) 
     697        return options 
     698 
     699    # This regular expression finds the indentation of every non-blank 
     700    # line in a string. 
     701    _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE) 
     702 
     703    def _min_indent(self, s): 
     704        "Return the minimum indentation of any non-blank line in `s`" 
     705        indents = [len(indent) for indent in self._INDENT_RE.findall(s)] 
     706        if len(indents) > 0: 
     707            return min(indents) 
     708        else: 
     709            return 0 
     710 
     711    def _check_prompt_blank(self, lines, indent, name, lineno): 
     712        """ 
     713        Given the lines of a source string (including prompts and 
     714        leading indentation), check to make sure that every prompt is 
     715        followed by a space character.  If any line is not followed by 
     716        a space character, then raise ValueError. 
     717        """ 
     718        for i, line in enumerate(lines): 
     719            if len(line) >= indent+4 and line[indent+3] != ' ': 
     720                raise ValueError('line %r of the docstring for %s ' 
     721                                 'lacks blank after %s: %r' % 
     722                                 (lineno+i+1, name, 
     723                                  line[indent:indent+3], line)) 
     724 
     725    def _check_prefix(self, lines, prefix, name, lineno): 
     726        """ 
     727        Check that every line in the given list starts with the given 
     728        prefix; if any line does not, then raise a ValueError. 
     729        """ 
     730        for i, line in enumerate(lines): 
     731            if line and not line.startswith(prefix): 
     732                raise ValueError('line %r of the docstring for %s has ' 
     733                                 'inconsistent leading whitespace: %r' % 
     734                                 (lineno+i+1, name, line)) 
     735 
     736 
     737###################################################################### 
     738## 4. DocTest Finder 
     739###################################################################### 
     740 
     741class DocTestFinder: 
     742    """ 
     743    A class used to extract the DocTests that are relevant to a given 
     744    object, from its docstring and the docstrings of its contained 
     745    objects.  Doctests can currently be extracted from the following 
     746    object types: modules, functions, classes, methods, staticmethods, 
     747    classmethods, and properties. 
     748    """ 
     749 
     750    def __init__(self, verbose=False, parser=DocTestParser(), 
     751                 recurse=True, _namefilter=None, exclude_empty=True): 
     752        """ 
     753        Create a new doctest finder. 
     754 
     755        The optional argument `parser` specifies a class or 
     756        function that should be used to create new DocTest objects (or 
     757        objects that implement the same interface as DocTest).  The 
     758        signature for this factory function should match the signature 
     759        of the DocTest constructor. 
     760 
     761        If the optional argument `recurse` is false, then `find` will 
     762        only examine the given object, and not any contained objects. 
     763 
     764        If the optional argument `exclude_empty` is false, then `find` 
     765        will include tests for objects with empty docstrings. 
     766        """ 
     767        self._parser = parser 
     768        self._verbose = verbose 
     769        self._recurse = recurse 
     770        self._exclude_empty = exclude_empty 
     771        # _namefilter is undocumented, and exists only for temporary backward- 
     772        # compatibility support of testmod's deprecated isprivate mess. 
     773        self._namefilter = _namefilter 
     774 
     775    def find(self, obj, name=None, module=None, globs=None, 
     776             extraglobs=None): 
     777        """ 
     778        Return a list of the DocTests that are defined by the given 
     779        object's docstring, or by any of its contained objects' 
     780        docstrings. 
     781 
     782        The optional parameter `module` is the module that contains 
     783        the given object.  If the module is not specified or is None, then 
     784        the test finder will attempt to automatically determine the 
     785        correct module.  The object's module is used: 
     786 
     787            - As a default namespace, if `globs` is not specified. 
     788            - To prevent the DocTestFinder from extracting DocTests 
     789              from objects that are imported from other modules. 
     790            - To find the name of the file containing the object. 
     791            - To help find the line number of the object within its 
     792              file. 
     793 
     794        Contained objects whose module does not match `module` are ignored. 
     795 
     796        If `module` is False, no attempt to find the module will be made. 
     797        This is obscure, of use mostly in tests:  if `module` is False, or 
     798        is None but cannot be found automatically, then all objects are 
     799        considered to belong to the (non-existent) module, so all contained 
     800        objects will (recursively) be searched for doctests. 
     801 
     802        The globals for each DocTest is formed by combining `globs` 
     803        and `extraglobs` (bindings in `extraglobs` override bindings 
     804        in `globs`).  A new copy of the globals dictionary is created 
     805        for each DocTest.  If `globs` is not specified, then it 
     806        defaults to the module's `__dict__`, if specified, or {} 
     807        otherwise.  If `extraglobs` is not specified, then it defaults 
     808        to {}. 
     809 
     810        """ 
     811        # If name was not specified, then extract it from the object. 
     812        if name is None: 
     813            name = getattr(obj, '__name__', None) 
     814            if name is None: 
     815                raise ValueError("DocTestFinder.find: name must be given " 
     816                        "when obj.__name__ doesn't exist: %r" % 
     817                                 (type(obj),)) 
     818 
     819        # Find the module that contains the given object (if obj is 
     820        # a module, then module=obj.).  Note: this may fail, in which 
     821        # case module will be None. 
     822        if module is False: 
     823            module = None 
     824        elif module is None: 
     825            module = inspect.getmodule(obj) 
     826 
     827        # Read the module's source code.  This is used by 
     828        # DocTestFinder._find_lineno to find the line number for a 
     829        # given object's docstring. 
     830        try: 
     831            file = inspect.getsourcefile(obj) or inspect.getfile(obj) 
     832            source_lines = linecache.getlines(file) 
     833            if not source_lines: 
     834                source_lines = None 
     835        except TypeError: 
     836            source_lines = None 
     837 
     838        # Initialize globals, and merge in extraglobs. 
     839        if globs is None: 
     840            if module is None: 
     841                globs = {} 
     842            else: 
     843                globs = module.__dict__.copy() 
     844        else: 
     845            globs = globs.copy() 
     846        if extraglobs is not None: 
     847            globs.update(extraglobs) 
     848 
     849        # Recursively explore `obj`, extracting DocTests. 
     850        tests = [] 
     851        self._find(tests, obj, name, module, source_lines, globs, {}) 
     852        return tests 
     853 
     854    def _filter(self, obj, prefix, base): 
     855        """ 
     856        Return true if the given object should not be examined. 
     857        """ 
     858        return (self._namefilter is not None and 
     859                self._namefilter(prefix, base)) 
     860 
     861    def _from_module(self, module, object): 
     862        """ 
     863        Return true if the given object is defined in the given 
     864        module. 
     865        """ 
     866        if module is None: 
     867            return True 
     868        elif inspect.isfunction(object): 
     869            return module.__dict__ is object.func_globals 
     870        elif inspect.isclass(object): 
     871            return module.__name__ == object.__module__ 
     872        elif inspect.getmodule(object) is not None: 
     873            return module is inspect.getmodule(object) 
     874        elif hasattr(object, '__module__'): 
     875            return module.__name__ == object.__module__ 
     876        elif isinstance(object, property): 
     877            return True # [XX] no way not be sure. 
     878        else: 
     879            raise ValueError("object must be a class or function") 
     880 
     881    def _find(self, tests, obj, name, module, source_lines, globs, seen): 
     882        """ 
     883        Find tests for the given object and any contained objects, and 
     884        add them to `tests`. 
     885        """ 
     886        if self._verbose: 
     887            print 'Finding tests in %s' % name 
     888 
     889        # If we've already processed this object, then ignore it. 
     890        if id(obj) in seen: 
     891            return 
     892        seen[id(obj)] = 1 
     893 
     894        # Find a test for this object, and add it to the list of tests. 
     895        test = self._get_test(obj, name, module, globs, source_lines) 
     896        if test is not None: 
     897            tests.append(test) 
     898 
     899        # Look for tests in a module's contained objects. 
     900        if inspect.ismodule(obj) and self._recurse: 
     901            for valname, val in obj.__dict__.items(): 
     902                # Check if this contained object should be ignored. 
     903                if self._filter(val, name, valname): 
     904                    continue 
     905                valname = '%s.%s' % (name, valname) 
     906                # Recurse to functions & classes. 
     907                if ((inspect.isfunction(val) or inspect.isclass(val)) and 
     908                    self._from_module(module, val)): 
     909                    self._find(tests, val, valname, module, source_lines, 
     910                               globs, seen) 
     911 
     912        # Look for tests in a module's __test__ dictionary. 
     913        if inspect.ismodule(obj) and self._recurse: 
     914            for valname, val in getattr(obj, '__test__', {}).items(): 
     915                if not isinstance(valname, basestring): 
     916                    raise ValueError("DocTestFinder.find: __test__ keys " 
     917                                     "must be strings: %r" % 
     918                                     (type(valname),)) 
     919                if not (inspect.isfunction(val) or inspect.isclass(val) or 
     920                        inspect.ismethod(val) or inspect.ismodule(val) or 
     921                        isinstance(val, basestring)): 
     922                    raise ValueError("DocTestFinder.find: __test__ values " 
     923                                     "must be strings, functions, methods, " 
     924                                     "classes, or modules: %r" % 
     925                                     (type(val),)) 
     926                valname = '%s.__test__.%s' % (name, valname) 
     927                self._find(tests, val, valname, module, source_lines, 
     928                           globs, seen) 
     929 
     930        # Look for tests in a class's contained objects. 
     931        if inspect.isclass(obj) and self._recurse: 
     932            for valname, val in obj.__dict__.items(): 
     933                # Check if this contained object should be ignored. 
     934                if self._filter(val, name, valname): 
     935                    continue 
     936                # Special handling for staticmethod/classmethod. 
     937                if isinstance(val, staticmethod): 
     938                    val = getattr(obj, valname) 
     939                if isinstance(val, classmethod): 
     940                    val = getattr(obj, valname).im_func 
     941 
     942                # Recurse to methods, properties, and nested classes. 
     943                if ((inspect.isfunction(val) or inspect.isclass(val) or 
     944                      isinstance(val, property)) and 
     945                      self._from_module(module, val)): 
     946                    valname = '%s.%s' % (name, valname) 
     947                    self._find(tests, val, valname, module, source_lines, 
     948                               globs, seen) 
     949 
     950    def _get_test(self, obj, name, module, globs, source_lines): 
     951        """ 
     952        Return a DocTest for the given object, if it defines a docstring; 
     953        otherwise, return None. 
     954        """ 
     955        # Extract the object's docstring.  If it doesn't have one, 
     956        # then return None (no test for this object). 
     957        if isinstance(obj, basestring): 
     958            docstring = obj 
     959        else: 
     960            try: 
     961                if obj.__doc__ is None: 
     962                    docstring = '' 
     963                else: 
     964                    docstring = obj.__doc__ 
     965                    if not isinstance(docstring, basestring): 
     966                        docstring = str(docstring) 
     967            except (TypeError, AttributeError): 
     968                docstring = '' 
     969 
     970        # Find the docstring's location in the file. 
     971        lineno = self._find_lineno(obj, source_lines) 
     972 
     973        # Don't bother if the docstring is empty. 
     974        if self._exclude_empty and not docstring: 
     975            return None 
     976 
     977        # Return a DocTest for this object. 
     978        if module is None: 
     979            filename = None 
     980        else: 
     981            filename = getattr(module, '__file__', module.__name__) 
     982            if filename[-4:] in (".pyc", ".pyo"): 
     983                filename = filename[:-1] 
     984        return self._parser.get_doctest(docstring, globs, name, 
     985                                        filename, lineno) 
     986 
     987    def _find_lineno(self, obj, source_lines): 
     988        """ 
     989        Return a line number of the given object's docstring.  Note: 
     990        this method assumes that the object has a docstring. 
     991        """ 
     992        lineno = None 
     993 
     994        # Find the line number for modules. 
     995        if inspect.ismodule(obj): 
     996            lineno = 0 
     997 
     998        # Find the line number for classes. 
     999        # Note: this could be fooled if a class is defined multiple 
     1000        # times in a single file. 
     1001        if inspect.isclass(obj): 
     1002            if source_lines is None: 
     1003                return None 
     1004            pat = re.compile(r'^\s*class\s*%s\b' % 
     1005                             getattr(obj, '__name__', '-')) 
     1006            for i, line in enumerate(source_lines): 
     1007                if pat.match(line): 
     1008                    lineno = i 
     1009                    break 
     1010 
     1011        # Find the line number for functions & methods. 
     1012        if inspect.ismethod(obj): obj = obj.im_func 
     1013        if inspect.isfunction(obj): obj = obj.func_code 
     1014        if inspect.istraceback(obj): obj = obj.tb_frame 
     1015        if inspect.isframe(obj): obj = obj.f_code 
     1016        if inspect.iscode(obj): 
     1017            lineno = getattr(obj, 'co_firstlineno', None)-1 
     1018 
     1019        # Find the line number where the docstring starts.  Assume 
     1020        # that it's the first line that begins with a quote mark. 
     1021        # Note: this could be fooled by a multiline function 
     1022        # signature, where a continuation line begins with a quote 
     1023        # mark. 
     1024        if lineno is not None: 
     1025            if source_lines is None: 
     1026                return lineno+1 
     1027            pat = re.compile('(^|.*:)\s*\w*("|\')') 
     1028            for lineno in range(lineno, len(source_lines)): 
     1029                if pat.match(source_lines[lineno]): 
     1030                    return lineno 
     1031 
     1032        # We couldn't find the line number. 
     1033        return None 
     1034 
     1035###################################################################### 
     1036## 5. DocTest Runner 
     1037###################################################################### 
     1038 
     1039class DocTestRunner: 
     1040    """ 
     1041    A class used to run DocTest test cases, and accumulate statistics. 
     1042    The `run` method is used to process a single DocTest case.  It 
     1043    returns a tuple `(f, t)`, where `t` is the number of test cases 
     1044    tried, and `f` is the number of test cases that failed. 
     1045 
     1046        >>> tests = DocTestFinder().find(_TestClass) 
     1047        >>> runner = DocTestRunner(verbose=False) 
     1048        >>> for test in tests: 
     1049        ...     print runner.run(test) 
     1050        (0, 2) 
     1051        (0, 1) 
     1052        (0, 2) 
     1053        (0, 2) 
     1054 
     1055    The `summarize` method prints a summary of all the test cases that 
     1056    have been run by the runner, and returns an aggregated `(f, t)` 
     1057    tuple: 
     1058 
     1059        >>> runner.summarize(verbose=1) 
     1060        4 items passed all tests: 
     1061           2 tests in _TestClass 
     1062           2 tests in _TestClass.__init__ 
     1063           2 tests in _TestClass.get 
     1064           1 tests in _TestClass.square 
     1065        7 tests in 4 items. 
     1066        7 passed and 0 failed. 
     1067        Test passed. 
     1068        (0, 7) 
     1069 
     1070    The aggregated number of tried examples and failed examples is 
     1071    also available via the `tries` and `failures` attributes: 
     1072 
     1073        >>> runner.tries 
     1074        7 
     1075        >>> runner.failures 
     1076        0 
     1077 
     1078    The comparison between expected outputs and actual outputs is done 
     1079    by an `OutputChecker`.  This comparison may be customized with a 
     1080    number of option flags; see the documentation for `testmod` for 
     1081    more information.  If the option flags are insufficient, then the 
     1082    comparison may also be customized by passing a subclass of 
     1083    `OutputChecker` to the constructor. 
     1084 
     1085    The test runner's display output can be controlled in two ways. 
     1086    First, an output function (`out) can be passed to 
     1087    `TestRunner.run`; this function will be called with strings that 
     1088    should be displayed.  It defaults to `sys.stdout.write`.  If 
     1089    capturing the output is not sufficient, then the display output 
     1090    can be also customized by subclassing DocTestRunner, and 
     1091    overriding the methods `report_start`, `report_success`, 
     1092    `report_unexpected_exception`, and `report_failure`. 
     1093    """ 
     1094    # This divider string is used to separate failure messages, and to 
     1095    # separate sections of the summary. 
     1096    DIVIDER = "*" * 70 
     1097 
     1098    def __init__(self, checker=None, verbose=None, optionflags=0): 
     1099        """ 
     1100        Create a new test runner. 
     1101 
     1102        Optional keyword arg `checker` is the `OutputChecker` that 
     1103        should be used to compare the expected outputs and actual 
     1104        outputs of doctest examples. 
     1105 
     1106        Optional keyword arg 'verbose' prints lots of stuff if true, 
     1107        only failures if false; by default, it's true iff '-v' is in 
     1108        sys.argv. 
     1109 
     1110        Optional argument `optionflags` can be used to control how the 
     1111        test runner compares expected output to actual output, and how 
     1112        it displays failures.  See the documentation for `testmod` for 
     1113        more information. 
     1114        """ 
     1115        self._checker = checker or OutputChecker() 
     1116        if verbose is None: 
     1117            verbose = '-v' in sys.argv 
     1118        self._verbose = verbose 
     1119        self.optionflags = optionflags 
     1120        self.original_optionflags = optionflags 
     1121 
     1122        # Keep track of the examples we've run. 
     1123        self.tries = 0 
     1124        self.failures = 0 
     1125        self._name2ft = {} 
     1126 
     1127        # Create a fake output target for capturing doctest output. 
     1128        self._fakeout = _SpoofOut() 
     1129 
     1130    #///////////////////////////////////////////////////////////////// 
     1131    # Reporting methods 
     1132    #///////////////////////////////////////////////////////////////// 
     1133 
     1134    def report_start(self, out, test, example): 
     1135        """ 
     1136        Report that the test runner is about to process the given 
     1137        example.  (Only displays a message if verbose=True) 
     1138        """ 
     1139        if self._verbose: 
     1140            if example.want: 
     1141                out('Trying:\n' + _indent(example.source) + 
     1142                    'Expecting:\n' + _indent(example.want)) 
     1143            else: 
     1144                out('Trying:\n' + _indent(example.source) + 
     1145                    'Expecting nothing\n') 
     1146 
     1147    def report_success(self, out, test, example, got): 
     1148        """ 
     1149        Report that the given example ran successfully.  (Only 
     1150        displays a message if verbose=True) 
     1151        """ 
     1152        if self._verbose: 
     1153            out("ok\n") 
     1154 
     1155    def report_failure(self, out, test, example, got): 
     1156        """ 
     1157        Report that the given example failed. 
     1158        """ 
     1159        out(self._failure_header(test, example) + 
     1160            self._checker.output_difference(example, got, self.optionflags)) 
     1161 
     1162    def report_unexpected_exception(self, out, test, example, exc_info): 
     1163        """ 
     1164        Report that the given example raised an unexpected exception. 
     1165        """ 
     1166        out(self._failure_header(test, example) + 
     1167            'Exception raised:\n' + _indent(_exception_traceback(exc_info))) 
     1168 
     1169    def _failure_header(self, test, example): 
     1170        out = [self.DIVIDER] 
     1171        if test.filename: 
     1172            if test.lineno is not None and example.lineno is not None: 
     1173                lineno = test.lineno + example.lineno + 1 
     1174            else: 
     1175                lineno = '?' 
     1176            out.append('File "%s", line %s, in %s' % 
     1177                       (test.filename, lineno, test.name)) 
     1178        else: 
     1179            out.append('Line %s, in %s' % (example.lineno+1, test.name)) 
     1180        out.append('Failed example:') 
     1181        source = example.source 
     1182        out.append(_indent(source)) 
     1183        return '\n'.join(out) 
     1184 
     1185    #///////////////////////////////////////////////////////////////// 
     1186    # DocTest Running 
     1187    #///////////////////////////////////////////////////////////////// 
     1188 
     1189    def __run(self, test, compileflags, out): 
     1190        """ 
     1191        Run the examples in `test`.  Write the outcome of each example 
     1192        with one of the `DocTestRunner.report_*` methods, using the 
     1193        writer function `out`.  `compileflags` is the set of compiler 
     1194        flags that should be used to execute examples.  Return a tuple 
     1195        `(f, t)`, where `t` is the number of examples tried, and `f` 
     1196        is the number of examples that failed.  The examples are run 
     1197        in the namespace `test.globs`. 
     1198        """ 
     1199        # Keep track of the number of failures and tries. 
     1200        failures = tries = 0 
     1201 
     1202        # Save the option flags (since option directives can be used 
     1203        # to modify them). 
     1204        original_optionflags = self.optionflags 
     1205 
     1206        SUCCESS, FAILURE, BOOM = range(3) # `outcome` state 
     1207 
     1208        check = self._checker.check_output 
     1209 
     1210        # Process each example. 
     1211        for examplenum, example in enumerate(test.examples): 
     1212 
     1213            # If REPORT_ONLY_FIRST_FAILURE is set, then suppress 
     1214            # reporting after the first failure. 
     1215            quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and 
     1216                     failures > 0) 
     1217 
     1218            # Merge in the example's options. 
     1219            self.optionflags = original_optionflags 
     1220            if example.options: 
     1221                for (optionflag, val) in example.options.items(): 
     1222                    if val: 
     1223                        self.optionflags |= optionflag 
     1224                    else: 
     1225                        self.optionflags &= ~optionflag 
     1226 
     1227            # Record that we started this example. 
     1228            tries += 1 
     1229            if not quiet: 
     1230                self.report_start(out, test, example) 
     1231 
     1232            # Use a special filename for compile(), so we can retrieve 
     1233            # the source code during interactive debugging (see 
     1234            # __patched_linecache_getlines). 
     1235            filename = '<doctest %s[%d]>' % (test.name, examplenum) 
     1236 
     1237            # Run the example in the given context (globs), and record 
     1238            # any exception that gets raised.  (But don't intercept 
     1239            # keyboard interrupts.) 
     1240            try: 
     1241                # Don't blink!  This is where the user's code gets run. 
     1242                exec compile(example.source, filename, "single", 
     1243                             compileflags, 1) in test.globs 
     1244                self.debugger.set_continue() # ==== Example Finished ==== 
     1245                exception = None 
     1246            except KeyboardInterrupt: 
     1247                raise 
     1248            except: 
     1249                exception = sys.exc_info() 
     1250                self.debugger.set_continue() # ==== Example Finished ==== 
     1251 
     1252            got = self._fakeout.getvalue()  # the actual output 
     1253            self._fakeout.truncate(0) 
     1254            outcome = FAILURE   # guilty until proved innocent or insane 
     1255 
     1256            # If the example executed without raising any exceptions, 
     1257            # verify its output. 
     1258            if exception is None: 
     1259                if check(example.want, got, self.optionflags): 
     1260                    outcome = SUCCESS 
     1261 
     1262            # The example raised an exception:  check if it was expected. 
     1263            else: 
     1264                exc_info = sys.exc_info() 
     1265                exc_msg = traceback.format_exception_only(*exc_info[:2])[-1] 
     1266                if not quiet: 
     1267                    got += _exception_traceback(exc_info) 
     1268 
     1269                # If `example.exc_msg` is None, then we weren't expecting 
     1270                # an exception. 
     1271                if example.exc_msg is None: 
     1272                    outcome = BOOM 
     1273 
     1274                # We expected an exception:  see whether it matches. 
     1275                elif check(example.exc_msg, exc_msg, self.optionflags): 
     1276                    outcome = SUCCESS 
     1277 
     1278                # Another chance if they didn't care about the detail. 
     1279                elif self.optionflags & IGNORE_EXCEPTION_DETAIL: 
     1280                    m1 = re.match(r'[^:]*:', example.exc_msg) 
     1281                    m2 = re.match(r'[^:]*:', exc_msg) 
     1282                    if m1 and m2 and check(m1.group(0), m2.group(0), 
     1283                                           self.optionflags): 
     1284                        outcome = SUCCESS 
     1285 
     1286            # Report the outcome. 
     1287            if outcome is SUCCESS: 
     1288                if not quiet: 
     1289                    self.report_success(out, test, example, got) 
     1290            elif outcome is FAILURE: 
     1291                if not quiet: 
     1292                    self.report_failure(out, test, example, got) 
     1293                failures += 1 
     1294            elif outcome is BOOM: 
     1295                if not quiet: 
     1296                    self.report_unexpected_exception(out, test, example, 
     1297                                                     exc_info) 
     1298                failures += 1 
     1299            else: 
     1300                assert False, ("unknown outcome", outcome) 
     1301 
     1302        # Restore the option flags (in case they were modified) 
     1303        self.optionflags = original_optionflags 
     1304 
     1305        # Record and return the number of failures and tries. 
     1306        self.__record_outcome(test, failures, tries) 
     1307        return failures, tries 
     1308 
     1309    def __record_outcome(self, test, f, t): 
     1310        """ 
     1311        Record the fact that the given DocTest (`test`) generated `f` 
     1312        failures out of `t` tried examples. 
     1313        """ 
     1314        f2, t2 = self._name2ft.get(test.name, (0,0)) 
     1315        self._name2ft[test.name] = (f+f2, t+t2) 
     1316        self.failures += f 
     1317        self.tries += t 
     1318 
     1319    __LINECACHE_FILENAME_RE = re.compile(r'<doctest ' 
     1320                                         r'(?P<name>[\w\.]+)' 
     1321                                         r'\[(?P<examplenum>\d+)\]>$') 
     1322    def __patched_linecache_getlines(self, filename): 
     1323        m = self.__LINECACHE_FILENAME_RE.match(filename) 
     1324        if m and m.group('name') == self.test.name: 
     1325            example = self.test.examples[int(m.group('examplenum'))] 
     1326            return example.source.splitlines(True) 
     1327        else: 
     1328            return self.save_linecache_getlines(filename) 
     1329 
     1330    def run(self, test, compileflags=None, out=None, clear_globs=True): 
     1331        """ 
     1332        Run the examples in `test`, and display the results using the 
     1333        writer function `out`. 
     1334 
     1335        The examples are run in the namespace `test.globs`.  If 
     1336        `clear_globs` is true (the default), then this namespace will 
     1337        be cleared after the test runs, to help with garbage 
     1338        collection.  If you would like to examine the namespace after 
     1339        the test completes, then use `clear_globs=False`. 
     1340 
     1341        `compileflags` gives the set of flags that should be used by 
     1342        the Python compiler when running the examples.  If not 
     1343        specified, then it will default to the set of future-import 
     1344        flags that apply to `globs`. 
     1345 
     1346        The output of each example is checked using 
     1347        `DocTestRunner.check_output`, and the results are formatted by 
     1348        the `DocTestRunner.report_*` methods. 
     1349        """ 
     1350        self.test = test 
     1351 
     1352        if compileflags is None: 
     1353            compileflags = _extract_future_flags(test.globs) 
     1354 
     1355        save_stdout = sys.stdout 
     1356        if out is None: 
     1357            out = save_stdout.write 
     1358        sys.stdout = self._fakeout 
     1359 
     1360        # Patch pdb.set_trace to restore sys.stdout during interactive 
     1361        # debugging (so it's not still redirected to self._fakeout). 
     1362        # Note that the interactive output will go to *our* 
     1363        # save_stdout, even if that's not the real sys.stdout; this 
     1364        # allows us to write test cases for the set_trace behavior. 
     1365        save_set_trace = pdb.set_trace 
     1366        self.debugger = _OutputRedirectingPdb(save_stdout) 
     1367        self.debugger.reset() 
     1368        pdb.set_trace = self.debugger.set_trace 
     1369 
     1370        # Patch linecache.getlines, so we can see the example's source 
     1371        # when we're inside the debugger. 
     1372        self.save_linecache_getlines = linecache.getlines 
     1373        linecache.getlines = self.__patched_linecache_getlines 
     1374 
     1375        try: 
     1376            return self.__run(test, compileflags, out) 
     1377        finally: 
     1378            sys.stdout = save_stdout 
     1379            pdb.set_trace = save_set_trace 
     1380            linecache.getlines = self.save_linecache_getlines 
     1381            if clear_globs: 
     1382                test.globs.clear() 
     1383 
     1384    #///////////////////////////////////////////////////////////////// 
     1385    # Summarization 
     1386    #///////////////////////////////////////////////////////////////// 
     1387    def summarize(self, verbose=None): 
     1388        """ 
     1389        Print a summary of all the test cases that have been run by 
     1390        this DocTestRunner, and return a tuple `(f, t)`, where `f` is 
     1391        the total number of failed examples, and `t` is the total 
     1392        number of tried examples. 
     1393 
     1394        The optional `verbose` argument controls how detailed the 
     1395        summary is.  If the verbosity is not specified, then the 
     1396        DocTestRunner's verbosity is used. 
     1397        """ 
     1398        if verbose is None: 
     1399            verbose = self._verbose 
     1400        notests = [] 
     1401        passed = [] 
     1402        failed = [] 
     1403        totalt = totalf = 0 
     1404        for x in self._name2ft.items(): 
     1405            name, (f, t) = x 
     1406            assert f <= t 
     1407            totalt += t 
     1408            totalf += f 
     1409            if t == 0: 
     1410                notests.append(name) 
     1411            elif f == 0: 
     1412                passed.append( (name, t) ) 
     1413            else: 
     1414                failed.append(x) 
     1415        if verbose: 
     1416            if notests: 
     1417                print len(notests), "items had no tests:" 
     1418                notests.sort() 
     1419                for thing in notests: 
     1420                    print "   ", thing 
     1421            if passed: 
     1422                print len(passed), "items passed all tests:" 
     1423                passed.sort() 
     1424                for thing, count in passed: 
     1425                    print " %3d tests in %s" % (count, thing) 
     1426        if failed: 
     1427            print self.DIVIDER 
     1428            print len(failed), "items had failures:" 
     1429            failed.sort() 
     1430            for thing, (f, t) in failed: 
     1431                print " %3d of %3d in %s" % (f, t, thing) 
     1432        if verbose: 
     1433            print totalt, "tests in", len(self._name2ft), "items." 
     1434            print totalt - totalf, "passed and", totalf, "failed." 
     1435        if totalf: 
     1436            print "***Test Failed***", totalf, "failures." 
     1437        elif verbose: 
     1438            print "Test passed." 
     1439        return totalf, totalt 
     1440 
     1441    #///////////////////////////////////////////////////////////////// 
     1442    # Backward compatibility cruft to maintain doctest.master. 
     1443    #///////////////////////////////////////////////////////////////// 
     1444    def merge(self, other): 
     1445        d = self._name2ft 
     1446        for name, (f, t) in other._name2ft.items(): 
     1447            if name in d: 
     1448                print "*** DocTestRunner.merge: '" + name + "' in both" \ 
     1449                    " testers; summing outcomes." 
     1450                f2, t2 = d[name] 
     1451                f = f + f2 
     1452                t = t + t2 
     1453            d[name] = f, t 
     1454 
     1455class OutputChecker: 
     1456    """ 
     1457    A class used to check the whether the actual output from a doctest 
     1458    example matches the expected output.  `OutputChecker` defines two 
     1459    methods: `check_output`, which compares a given pair of outputs, 
     1460    and returns true if they match; and `output_difference`, which 
     1461    returns a string describing the differences between two outputs. 
     1462    """ 
     1463    def check_output(self, want, got, optionflags): 
     1464        """ 
     1465        Return True iff the actual output from an example (`got`) 
     1466        matches the expected output (`want`).  These strings are 
     1467        always considered to match if they are identical; but 
     1468        depending on what option flags the test runner is using, 
     1469        several non-exact match types are also possible.  See the 
     1470        documentation for `TestRunner` for more information about 
     1471        option flags. 
     1472        """ 
     1473        # Handle the common case first, for efficiency: 
     1474        # if they're string-identical, always return true. 
     1475        if got == want: 
     1476            return True 
     1477 
     1478        # The values True and False replaced 1 and 0 as the return 
     1479        # value for boolean comparisons in Python 2.3. 
     1480        if not (optionflags & DONT_ACCEPT_TRUE_FOR_1): 
     1481            if (got,want) == ("True\n", "1\n"): 
     1482                return True 
     1483            if (got,want) == ("False\n", "0\n"): 
     1484                return True 
     1485 
     1486        # <BLANKLINE> can be used as a special sequence to signify a 
     1487        # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used. 
     1488        if not (optionflags & DONT_ACCEPT_BLANKLINE): 
     1489            # Replace <BLANKLINE> in want with a blank line. 
     1490            want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER), 
     1491                          '', want) 
     1492            # If a line in got contains only spaces, then remove the 
     1493            # spaces. 
     1494            got = re.sub('(?m)^\s*?$', '', got) 
     1495            if got == want: 
     1496                return True 
     1497 
     1498        # This flag causes doctest to ignore any differences in the 
     1499        # contents of whitespace strings.  Note that this can be used 
     1500        # in conjunction with the ELLIPSIS flag. 
     1501        if optionflags & NORMALIZE_WHITESPACE: 
     1502            got = ' '.join(got.split()) 
     1503            want = ' '.join(want.split()) 
     1504            if got == want: 
     1505                return True 
     1506 
     1507        # The ELLIPSIS flag says to let the sequence "..." in `want` 
     1508        # match any substring in `got`. 
     1509        if optionflags & ELLIPSIS: 
     1510            if _ellipsis_match(want, got): 
     1511                return True 
     1512 
     1513        # We didn't find any match; return false. 
     1514        return False 
     1515 
     1516    # Should we do a fancy diff? 
     1517    def _do_a_fancy_diff(self, want, got, optionflags): 
     1518        # Not unless they asked for a fancy diff. 
     1519        if not optionflags & (REPORT_UDIFF | 
     1520                              REPORT_CDIFF | 
     1521                              REPORT_NDIFF): 
     1522            return False 
     1523 
     1524        # If expected output uses ellipsis, a meaningful fancy diff is 
     1525        # too hard ... or maybe not.  In two real-life failures Tim saw, 
     1526        # a diff was a major help anyway, so this is commented out. 
     1527        # [todo] _ellipsis_match() knows which pieces do and don't match, 
     1528        # and could be the basis for a kick-ass diff in this case. 
     1529        ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want: 
     1530        ##    return False 
     1531 
     1532        # ndiff does intraline difference marking, so can be useful even 
     1533        # for 1-line differences. 
     1534        if optionflags & REPORT_NDIFF: 
     1535            return True 
     1536 
     1537        # The other diff types need at least a few lines to be helpful. 
     1538        return want.count('\n') > 2 and got.count('\n') > 2 
     1539 
     1540    def output_difference(self, example, got, optionflags): 
     1541        """ 
     1542        Return a string describing the differences between the 
     1543        expected output for a given example (`example`) and the actual 
     1544        output (`got`).  `optionflags` is the set of option flags used 
     1545        to compare `want` and `got`. 
     1546        """ 
     1547        want = example.want 
     1548        # If <BLANKLINE>s are being used, then replace blank lines 
     1549        # with <BLANKLINE> in the actual output string. 
     1550        if not (optionflags & DONT_ACCEPT_BLANKLINE): 
     1551            got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got) 
     1552 
     1553        # Check if we should use diff. 
     1554        if self._do_a_fancy_diff(want, got, optionflags): 
     1555            # Split want & got into lines. 
     1556            want_lines = want.splitlines(True)  # True == keep line ends 
     1557            got_lines = got.splitlines(True) 
     1558            # Use difflib to find their differences. 
     1559            if optionflags & REPORT_UDIFF: 
     1560                diff = difflib.unified_diff(want_lines, got_lines, n=2) 
     1561                diff = list(diff)[2:] # strip the diff header 
     1562                kind = 'unified diff with -expected +actual' 
     1563            elif optionflags & REPORT_CDIFF: 
     1564                diff = difflib.context_diff(want_lines, got_lines, n=2) 
     1565                diff = list(diff)[2:] # strip the diff header 
     1566                kind = 'context diff with expected followed by actual' 
     1567            elif optionflags & REPORT_NDIFF: 
     1568                engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK) 
     1569                diff = list(engine.compare(want_lines, got_lines)) 
     1570                kind = 'ndiff with -expected +actual' 
     1571            else: 
     1572                assert 0, 'Bad diff option' 
     1573            # Remove trailing whitespace on diff output. 
     1574            diff = [line.rstrip() + '\n' for line in diff] 
     1575            return 'Differences (%s):\n' % kind + _indent(''.join(diff)) 
     1576 
     1577        # If we're not using diff, then simply list the expected 
     1578        # output followed by the actual output. 
     1579        if want and got: 
     1580            return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got)) 
     1581        elif want: 
     1582            return 'Expected:\n%sGot nothing\n' % _indent(want) 
     1583        elif got: 
     1584            return 'Expected nothing\nGot:\n%s' % _indent(got) 
     1585        else: 
     1586            return 'Expected nothing\nGot nothing\n' 
     1587 
     1588class DocTestFailure(Exception): 
     1589    """A DocTest example has failed in debugging mode. 
     1590 
     1591    The exception instance has variables: 
     1592 
     1593    - test: the DocTest object being run 
     1594 
     1595    - excample: the Example object that failed 
     1596 
     1597    - got: the actual output 
     1598    """ 
     1599    def __init__(self, test, example, got): 
     1600        self.test = test 
     1601        self.example = example 
     1602        self.got = got 
     1603 
     1604    def __str__(self): 
     1605        return str(self.test) 
     1606 
     1607class UnexpectedException(Exception): 
     1608    """A DocTest example has encountered an unexpected exception 
     1609 
     1610    The exception instance has variables: 
     1611 
     1612    - test: the DocTest object being run 
     1613 
     1614    - excample: the Example object that failed 
     1615 
     1616    - exc_info: the exception info 
     1617    """ 
     1618    def __init__(self, test, example, exc_info): 
     1619        self.test = test 
     1620        self.example = example 
     1621        self.exc_info = exc_info 
     1622 
     1623    def __str__(self): 
     1624        return str(self.test) 
     1625 
     1626class DebugRunner(DocTestRunner): 
     1627    r"""Run doc tests but raise an exception as soon as there is a failure. 
     1628 
     1629       If an unexpected exception occurs, an UnexpectedException is raised. 
     1630       It contains the test, the example, and the original exception: 
     1631 
     1632         >>> runner = DebugRunner(verbose=False) 
     1633         >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42', 
     1634         ...                                    {}, 'foo', 'foo.py', 0) 
     1635         >>> try: 
     1636         ...     runner.run(test) 
     1637         ... except UnexpectedException, failure: 
     1638         ...     pass 
     1639 
     1640         >>> failure.test is test 
     1641         True 
     1642 
     1643         >>> failure.example.want 
     1644         '42\n' 
     1645 
     1646         >>> exc_info = failure.exc_info 
     1647         >>> raise exc_info[0], exc_info[1], exc_info[2] 
     1648         Traceback (most recent call last): 
     1649         ... 
     1650         KeyError 
     1651 
     1652       We wrap the original exception to give the calling application 
     1653       access to the test and example information. 
     1654 
     1655       If the output doesn't match, then a DocTestFailure is raised: 
     1656 
     1657         >>> test = DocTestParser().get_doctest(''' 
     1658         ...      >>> x = 1 
     1659         ...      >>> x 
     1660         ...      2 
     1661         ...      ''', {}, 'foo', 'foo.py', 0) 
     1662 
     1663         >>> try: 
     1664         ...    runner.run(test) 
     1665         ... except DocTestFailure, failure: 
     1666         ...    pass 
     1667 
     1668       DocTestFailure objects provide access to the test: 
     1669 
     1670         >>> failure.test is test 
     1671         True 
     1672 
     1673       As well as to the example: 
     1674 
     1675         >>> failure.example.want 
     1676         '2\n' 
     1677 
     1678       and the actual output: 
     1679 
     1680         >>> failure.got 
     1681         '1\n' 
     1682 
     1683       If a failure or error occurs, the globals are left intact: 
     1684 
     1685         >>> del test.globs['__builtins__'] 
     1686         >>> test.globs 
     1687         {'x': 1} 
     1688 
     1689         >>> test = DocTestParser().get_doctest(''' 
     1690         ...      >>> x = 2 
     1691         ...      >>> raise KeyError 
     1692         ...      ''', {}, 'foo', 'foo.py', 0) 
     1693 
     1694         >>> runner.run(test) 
     1695         Traceback (most recent call last): 
     1696         ... 
     1697         UnexpectedException: <DocTest foo from foo.py:0 (2 examples)> 
     1698 
     1699         >>> del test.globs['__builtins__'] 
     1700         >>> test.globs 
     1701         {'x': 2} 
     1702 
     1703       But the globals are cleared if there is no error: 
     1704 
     1705         >>> test = DocTestParser().get_doctest(''' 
     1706         ...      >>> x = 2 
     1707         ...      ''', {}, 'foo', 'foo.py', 0) 
     1708 
     1709         >>> runner.run(test) 
     1710         (0, 1) 
     1711 
     1712         >>> test.globs 
     1713         {} 
     1714 
     1715       """ 
     1716 
     1717    def run(self, test, compileflags=None, out=None, clear_globs=True): 
     1718        r = DocTestRunner.run(self, test, compileflags, out, False) 
     1719        if clear_globs: 
     1720            test.globs.clear() 
     1721        return r 
     1722 
     1723    def report_unexpected_exception(self, out, test, example, exc_info): 
     1724        raise UnexpectedException(test, example, exc_info) 
     1725 
     1726    def report_failure(self, out, test, example, got): 
     1727        raise DocTestFailure(test, example, got) 
     1728 
     1729###################################################################### 
     1730## 6. Test Functions 
     1731###################################################################### 
     1732# These should be backwards compatible. 
     1733 
     1734# For backward compatibility, a global instance of a DocTestRunner 
     1735# class, updated by testmod. 
     1736master = None 
     1737 
     1738def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None, 
     1739            report=True, optionflags=0, extraglobs=None, 
     1740            raise_on_error=False, exclude_empty=False): 
     1741    """m=None, name=None, globs=None, verbose=None, isprivate=None, 
     1742       report=True, optionflags=0, extraglobs=None, raise_on_error=False, 
     1743       exclude_empty=False 
     1744 
     1745    Test examples in docstrings in functions and classes reachable 
     1746    from module m (or the current module if m is not supplied), starting 
     1747    with m.__doc__.  Unless isprivate is specified, private names 
     1748    are not skipped. 
     1749 
     1750    Also test examples reachable from dict m.__test__ if it exists and is 
     1751    not None.  m.__test__ maps names to functions, classes and strings; 
     1752    function and class docstrings are tested even if the name is private; 
     1753    strings are tested directly, as if they were docstrings. 
     1754 
     1755    Return (#failures, #tests). 
     1756 
     1757    See doctest.__doc__ for an overview. 
     1758 
     1759    Optional keyword arg "name" gives the name of the module; by default 
     1760    use m.__name__. 
     1761 
     1762    Optional keyword arg "globs" gives a dict to be used as the globals 
     1763    when executing examples; by default, use m.__dict__.  A copy of this 
     1764    dict is actually used for each docstring, so that each docstring's 
     1765    examples start with a clean slate. 
     1766 
     1767    Optional keyword arg "extraglobs" gives a dictionary that should be 
     1768    merged into the globals that are used to execute examples.  By 
     1769    default, no extra globals are used.  This is new in 2.4. 
     1770 
     1771    Optional keyword arg "verbose" prints lots of stuff if true, prints 
     1772    only failures if false; by default, it's true iff "-v" is in sys.argv. 
     1773 
     1774    Optional keyword arg "report" prints a summary at the end when true, 
     1775    else prints nothing at the end.  In verbose mode, the summary is 
     1776    detailed, else very brief (in fact, empty if all tests passed). 
     1777 
     1778    Optional keyword arg "optionflags" or's together module constants, 
     1779    and defaults to 0.  This is new in 2.3.  Possible values (see the 
     1780    docs for details): 
     1781 
     1782        DONT_ACCEPT_TRUE_FOR_1 
     1783        DONT_ACCEPT_BLANKLINE 
     1784        NORMALIZE_WHITESPACE 
     1785        ELLIPSIS 
     1786        IGNORE_EXCEPTION_DETAIL 
     1787        REPORT_UDIFF 
     1788        REPORT_CDIFF 
     1789        REPORT_NDIFF 
     1790        REPORT_ONLY_FIRST_FAILURE 
     1791 
     1792    Optional keyword arg "raise_on_error" raises an exception on the 
     1793    first unexpected exception or failure. This allows failures to be 
     1794    post-mortem debugged. 
     1795 
     1796    Deprecated in Python 2.4: 
     1797    Optional keyword arg "isprivate" specifies a function used to 
     1798    determine whether a name is private.  The default function is 
     1799    treat all functions as public.  Optionally, "isprivate" can be 
     1800    set to doctest.is_private to skip over functions marked as private 
     1801    using the underscore naming convention; see its docs for details. 
     1802 
     1803    Advanced tomfoolery:  testmod runs methods of a local instance of 
     1804    class doctest.Tester, then merges the results into (or creates) 
     1805    global Tester instance doctest.master.  Methods of doctest.master 
     1806    can be called directly too, if you want to do something unusual. 
     1807    Passing report=0 to testmod is especially useful then, to delay 
     1808    displaying a summary.  Invoke doctest.master.summarize(verbose) 
     1809    when you're done fiddling. 
     1810    """ 
     1811    global master 
     1812 
     1813    if isprivate is not None: 
     1814        warnings.warn("the isprivate argument is deprecated; " 
     1815                      "examine DocTestFinder.find() lists instead", 
     1816                      DeprecationWarning) 
     1817 
     1818    # If no module was given, then use __main__. 
     1819    if m is None: 
     1820        # DWA - m will still be None if this wasn't invoked from the command 
     1821        # line, in which case the following TypeError is about as good an error 
     1822        # as we should expect 
     1823        m = sys.modules.get('__main__') 
     1824 
     1825    # Check that we were actually given a module. 
     1826    if not inspect.ismodule(m): 
     1827        raise TypeError("testmod: module required; %r" % (m,)) 
     1828 
     1829    # If no name was given, then use the module's name. 
     1830    if name is None: 
     1831        name = m.__name__ 
     1832 
     1833    # Find, parse, and run all tests in the given module. 
     1834    finder = DocTestFinder(_namefilter=isprivate, exclude_empty=exclude_empty) 
     1835 
     1836    if raise_on_error: 
     1837        runner = DebugRunner(verbose=verbose, optionflags=optionflags) 
     1838    else: 
     1839        runner = DocTestRunner(verbose=verbose, optionflags=optionflags) 
     1840 
     1841    for test in finder.find(m, name, globs=globs, extraglobs=extraglobs): 
     1842        runner.run(test) 
     1843 
     1844    if report: 
     1845        runner.summarize() 
     1846 
     1847    if master is None: 
     1848        master = runner 
     1849    else: 
     1850        master.merge(runner) 
     1851 
     1852    return runner.failures, runner.tries 
     1853 
     1854def testfile(filename, module_relative=True, name=None, package=None, 
     1855             globs=None, verbose=None, report=True, optionflags=0, 
     1856             extraglobs=None, raise_on_error=False, parser=DocTestParser()): 
     1857    """ 
     1858    Test examples in the given file.  Return (#failures, #tests). 
     1859 
     1860    Optional keyword arg "module_relative" specifies how filenames 
     1861    should be interpreted: 
     1862 
     1863      - If "module_relative" is True (the default), then "filename" 
     1864         specifies a module-relative path.  By default, this path is 
     1865         relative to the calling module's directory; but if the 
     1866         "package" argument is specified, then it is relative to that 
     1867         package.  To ensure os-independence, "filename" should use 
     1868         "/" characters to separate path segments, and should not 
     1869         be an absolute path (i.e., it may not begin with "/"). 
     1870 
     1871      - If "module_relative" is False, then "filename" specifies an 
     1872        os-specific path.  The path may be absolute or relative (to 
     1873        the current working directory). 
     1874 
     1875    Optional keyword arg "name" gives the name of the test; by default 
     1876    use the file's basename. 
     1877 
     1878    Optional keyword argument "package" is a Python package or the 
     1879    name of a Python package whose directory should be used as the 
     1880    base directory for a module relative filename.  If no package is 
     1881    specified, then the calling module's directory is used as the base 
     1882    directory for module relative filenames.  It is an error to 
     1883    specify "package" if "module_relative" is False. 
     1884 
     1885    Optional keyword arg "globs" gives a dict to be used as the globals 
     1886    when executing examples; by default, use {}.  A copy of this dict 
     1887    is actually used for each docstring, so that each docstring's 
     1888    examples start with a clean slate. 
     1889 
     1890    Optional keyword arg "extraglobs" gives a dictionary that should be 
     1891    merged into the globals that are used to execute examples.  By 
     1892    default, no extra globals are used. 
     1893 
     1894    Optional keyword arg "verbose" prints lots of stuff if true, prints 
     1895    only failures if false; by default, it's true iff "-v" is in sys.argv. 
     1896 
     1897    Optional keyword arg "report" prints a summary at the end when true, 
     1898    else prints nothing at the end.  In verbose mode, the summary is 
     1899    detailed, else very brief (in fact, empty if all tests passed). 
     1900 
     1901    Optional keyword arg "optionflags" or's together module constants, 
     1902    and defaults to 0.  Possible values (see the docs for details): 
     1903 
     1904        DONT_ACCEPT_TRUE_FOR_1 
     1905        DONT_ACCEPT_BLANKLINE 
     1906        NORMALIZE_WHITESPACE 
     1907        ELLIPSIS 
     1908        IGNORE_EXCEPTION_DETAIL 
     1909        REPORT_UDIFF 
     1910        REPORT_CDIFF 
     1911        REPORT_NDIFF 
     1912        REPORT_ONLY_FIRST_FAILURE 
     1913 
     1914    Optional keyword arg "raise_on_error" raises an exception on the 
     1915    first unexpected exception or failure. This allows failures to be 
     1916    post-mortem debugged. 
     1917 
     1918    Optional keyword arg "parser" specifies a DocTestParser (or 
     1919    subclass) that should be used to extract tests from the files. 
     1920 
     1921    Advanced tomfoolery:  testmod runs methods of a local instance of 
     1922    class doctest.Tester, then merges the results into (or creates) 
     1923    global Tester instance doctest.master.  Methods of doctest.master 
     1924    can be called directly too, if you want to do something unusual. 
     1925    Passing report=0 to testmod is especially useful then, to delay 
     1926    displaying a summary.  Invoke doctest.master.summarize(verbose) 
     1927    when you're done fiddling. 
     1928    """ 
     1929    global master 
     1930 
     1931    if package and not module_relative: 
     1932        raise ValueError("Package may only be specified for module-" 
     1933                         "relative paths.") 
     1934 
     1935    # Relativize the path 
     1936    if module_relative: 
     1937        package = _normalize_module(package) 
     1938        filename = _module_relative_path(package, filename) 
     1939 
     1940    # If no name was given, then use the file's name. 
     1941    if name is None: 
     1942        name = os.path.basename(filename) 
     1943 
     1944    # Assemble the globals. 
     1945    if globs is None: 
     1946        globs = {} 
     1947    else: 
     1948        globs = globs.copy() 
     1949    if extraglobs is not None: 
     1950        globs.update(extraglobs) 
     1951 
     1952    if raise_on_error: 
     1953        runner = DebugRunner(verbose=verbose, optionflags=optionflags) 
     1954    else: 
     1955        runner = DocTestRunner(verbose=verbose, optionflags=optionflags) 
     1956 
     1957    # Read the file, convert it to a test, and run it. 
     1958    s = open(filename).read() 
     1959    test = parser.get_doctest(s, globs, name, filename, 0) 
     1960    runner.run(test) 
     1961 
     1962    if report: 
     1963        runner.summarize() 
     1964 
     1965    if master is None: 
     1966        master = runner 
     1967    else: 
     1968        master.merge(runner) 
     1969 
     1970    return runner.failures, runner.tries 
     1971 
     1972def run_docstring_examples(f, globs, verbose=False, name="NoName", 
     1973                           compileflags=None, optionflags=0): 
     1974    """ 
     1975    Test examples in the given object's docstring (`f`), using `globs` 
     1976    as globals.  Optional argument `name` is used in failure messages. 
     1977    If the optional argument `verbose` is true, then generate output 
     1978    even if there are no failures. 
     1979 
     1980    `compileflags` gives the set of flags that should be used by the 
     1981    Python compiler when running the examples.  If not specified, then 
     1982    it will default to the set of future-import flags that apply to 
     1983    `globs`. 
     1984 
     1985    Optional keyword arg `optionflags` specifies options for the 
     1986    testing and output.  See the documentation for `testmod` for more 
     1987    information. 
     1988    """ 
     1989    # Find, parse, and run all tests in the given module. 
     1990    finder = DocTestFinder(verbose=verbose, recurse=False) 
     1991    runner = DocTestRunner(verbose=verbose, optionflags=optionflags) 
     1992    for test in finder.find(f, name, globs=globs): 
     1993        runner.run(test, compileflags=compileflags) 
     1994 
     1995###################################################################### 
     1996## 7. Tester 
     1997###################################################################### 
     1998# This is provided only for backwards compatibility.  It's not 
     1999# actually used in any way. 
     2000 
     2001class Tester: 
     2002    def __init__(self, mod=None, globs=None, verbose=None, 
     2003                 isprivate=None, optionflags=0): 
     2004 
     2005        warnings.warn("class Tester is deprecated; " 
     2006                      "use class doctest.DocTestRunner instead", 
     2007                      DeprecationWarning, stacklevel=2) 
     2008        if mod is None and globs is None: 
     2009            raise TypeError("Tester.__init__: must specify mod or globs") 
     2010        if mod is not None and not inspect.ismodule(mod): 
     2011            raise TypeError("Tester.__init__: mod must be a module; %r" % 
     2012                            (mod,)) 
     2013        if globs is None: 
     2014            globs = mod.__dict__ 
     2015        self.globs = globs 
     2016 
     2017        self.verbose = verbose 
     2018        self.isprivate = isprivate 
     2019        self.optionflags = optionflags 
     2020        self.testfinder = DocTestFinder(_namefilter=isprivate) 
     2021        self.testrunner = DocTestRunner(verbose=verbose, 
     2022                                        optionflags=optionflags) 
     2023 
     2024    def runstring(self, s, name): 
     2025        test = DocTestParser().get_doctest(s, self.globs, name, None, None) 
     2026        if self.verbose: 
     2027            print "Running string", name 
     2028        (f,t) = self.testrunner.run(test) 
     2029        if self.verbose: 
     2030            print f, "of", t, "examples failed in string", name 
     2031        return (f,t) 
     2032 
     2033    def rundoc(self, object, name=None, module=None): 
     2034        f = t = 0 
     2035        tests = self.testfinder.find(object, name, module=module, 
     2036                                     globs=self.globs) 
     2037        for test in tests: 
     2038            (f2, t2) = self.testrunner.run(test) 
     2039            (f,t) = (f+f2, t+t2) 
     2040        return (f,t) 
     2041 
     2042    def rundict(self, d, name, module=None): 
     2043        import new 
     2044        m = new.module(name) 
     2045        m.__dict__.update(d) 
     2046        if module is None: 
     2047            module = False 
     2048        return self.rundoc(m, name, module) 
     2049 
     2050    def run__test__(self, d, name): 
     2051        import new 
     2052        m = new.module(name) 
     2053        m.__test__ = d 
     2054        return self.rundoc(m, name) 
     2055 
     2056    def summarize(self, verbose=None): 
     2057        return self.testrunner.summarize(verbose) 
     2058 
     2059    def merge(self, other): 
     2060        self.testrunner.merge(other.testrunner) 
     2061 
     2062###################################################################### 
     2063## 8. Unittest Support 
     2064###################################################################### 
     2065 
     2066_unittest_reportflags = 0 
     2067 
     2068def set_unittest_reportflags(flags): 
     2069    """Sets the unittest option flags. 
     2070 
     2071    The old flag is returned so that a runner could restore the old 
     2072    value if it wished to: 
     2073 
     2074      >>> old = _unittest_reportflags 
     2075      >>> set_unittest_reportflags(REPORT_NDIFF | 
     2076      ...                          REPORT_ONLY_FIRST_FAILURE) == old 
     2077      True 
     2078 
     2079      >>> import doctest 
     2080      >>> doctest._unittest_reportflags == (REPORT_NDIFF | 
     2081      ...                                   REPORT_ONLY_FIRST_FAILURE) 
     2082      True 
     2083 
     2084    Only reporting flags can be set: 
     2085 
     2086      >>> set_unittest_reportflags(ELLIPSIS) 
     2087      Traceback (most recent call last): 
     2088      ... 
     2089      ValueError: ('Only reporting flags allowed', 8) 
     2090 
     2091      >>> set_unittest_reportflags(old) == (REPORT_NDIFF | 
     2092      ...                                   REPORT_ONLY_FIRST_FAILURE) 
     2093      True 
     2094    """ 
     2095    global _unittest_reportflags 
     2096 
     2097    if (flags & REPORTING_FLAGS) != flags: 
     2098        raise ValueError("Only reporting flags allowed", flags) 
     2099    old = _unittest_reportflags 
     2100    _unittest_reportflags = flags 
     2101    return old 
     2102 
     2103 
     2104class DocTestCase(unittest.TestCase): 
     2105 
     2106    def __init__(self, test, optionflags=0, setUp=None, tearDown=None, 
     2107                 checker=None, runner=DocTestRunner): 
     2108 
     2109        unittest.TestCase.__init__(self) 
     2110        self._dt_optionflags = optionflags 
     2111        self._dt_checker = checker 
     2112        self._dt_test = test 
     2113        self._dt_setUp = setUp 
     2114        self._dt_tearDown = tearDown 
     2115        self._dt_runner = runner 
     2116 
     2117    def setUp(self): 
     2118        test = self._dt_test 
     2119 
     2120        if self._dt_setUp is not None: 
     2121            self._dt_setUp(test) 
     2122 
     2123    def tearDown(self): 
     2124        test = self._dt_test 
     2125 
     2126        if self._dt_tearDown is not None: 
     2127            self._dt_tearDown(test) 
     2128 
     2129        test.globs.clear() 
     2130 
     2131    def runTest(self): 
     2132        test = self._dt_test 
     2133        old = sys.stdout 
     2134        new = StringIO() 
     2135        optionflags = self._dt_optionflags 
     2136 
     2137        if not (optionflags & REPORTING_FLAGS): 
     2138            # The option flags don't include any reporting flags, 
     2139            # so add the default reporting flags 
     2140            optionflags |= _unittest_reportflags 
     2141 
     2142        runner = self._dt_runner(optionflags=optionflags, 
     2143                                 checker=self._dt_checker, verbose=False) 
     2144 
     2145        try: 
     2146            runner.DIVIDER = "-"*70 
     2147            failures, tries = runner.run( 
     2148                test, out=new.write, clear_globs=False) 
     2149        finally: 
     2150            sys.stdout = old 
     2151 
     2152        if failures: 
     2153            raise self.failureException(self.format_failure(new.getvalue())) 
     2154 
     2155    def format_failure(self, err): 
     2156        test = self._dt_test 
     2157        if test.lineno is None: 
     2158            lineno = 'unknown line number' 
     2159        else: 
     2160            lineno = '%s' % test.lineno 
     2161        lname = '.'.join(test.name.split('.')[-1:]) 
     2162        return ('Failed doctest test for %s\n' 
     2163                '  File "%s", line %s, in %s\n\n%s' 
     2164                % (test.name, test.filename, lineno, lname, err) 
     2165                ) 
     2166 
     2167    def debug(self): 
     2168        r"""Run the test case without results and without catching exceptions 
     2169 
     2170           The unit test framework includes a debug method on test cases 
     2171           and test suites to support post-mortem debugging.  The test code 
     2172           is run in such a way that errors are not caught.  This way a 
     2173           caller can catch the errors and initiate post-mortem debugging. 
     2174 
     2175           The DocTestCase provides a debug method that raises 
     2176           UnexpectedException errors if there is an unexepcted 
     2177           exception: 
     2178 
     2179             >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42', 
     2180             ...                {}, 'foo', 'foo.py', 0) 
     2181             >>> case = DocTestCase(test) 
     2182             >>> try: 
     2183             ...     case.debug() 
     2184             ... except UnexpectedException, failure: 
     2185             ...     pass 
     2186 
     2187           The UnexpectedException contains the test, the example, and 
     2188           the original exception: 
     2189 
     2190             >>> failure.test is test 
     2191             True 
     2192 
     2193             >>> failure.example.want 
     2194             '42\n' 
     2195 
     2196             >>> exc_info = failure.exc_info 
     2197             >>> raise exc_info[0], exc_info[1], exc_info[2] 
     2198             Traceback (most recent call last): 
     2199             ... 
     2200             KeyError 
     2201 
     2202           If the output doesn't match, then a DocTestFailure is raised: 
     2203 
     2204             >>> test = DocTestParser().get_doctest(''' 
     2205             ...      >>> x = 1 
     2206             ...      >>> x 
     2207             ...      2 
     2208             ...      ''', {}, 'foo', 'foo.py', 0) 
     2209             >>> case = DocTestCase(test) 
     2210 
     2211             >>> try: 
     2212             ...    case.debug() 
     2213             ... except DocTestFailure, failure: 
     2214             ...    pass 
     2215 
     2216           DocTestFailure objects provide access to the test: 
     2217 
     2218             >>> failure.test is test 
     2219             True 
     2220 
     2221           As well as to the example: 
     2222 
     2223             >>> failure.example.want 
     2224             '2\n' 
     2225 
     2226           and the actual output: 
     2227 
     2228             >>> failure.got 
     2229             '1\n' 
     2230 
     2231           """ 
     2232 
     2233        self.setUp() 
     2234        runner = DebugRunner(optionflags=self._dt_optionflags, 
     2235                             checker=self._dt_checker, verbose=False) 
     2236        runner.run(self._dt_test) 
     2237        self.tearDown() 
     2238 
     2239    def id(self): 
     2240        return self._dt_test.name 
     2241 
     2242    def __repr__(self): 
     2243        name = self._dt_test.name.split('.') 
     2244        return "%s (%s)" % (name[-1], '.'.join(name[:-1])) 
     2245 
     2246    __str__ = __repr__ 
     2247 
     2248    def shortDescription(self): 
     2249        return "Doctest: " + self._dt_test.name 
     2250 
     2251def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, 
     2252                 test_class=DocTestCase, **options): 
     2253    """ 
     2254    Convert doctest tests for a module to a unittest test suite. 
     2255 
     2256    This converts each documentation string in a module that 
     2257    contains doctest tests to a unittest test case.  If any of the 
     2258    tests in a doc string fail, then the test case fails.  An exception 
     2259    is raised showing the name of the file containing the test and a 
     2260    (sometimes approximate) line number. 
     2261 
     2262    The `module` argument provides the module to be tested.  The argument 
     2263    can be either a module or a module name. 
     2264 
     2265    If no argument is given, the calling module is used. 
     2266 
     2267    A number of options may be provided as keyword arguments: 
     2268 
     2269    setUp 
     2270      A set-up function.  This is called before running the 
     2271      tests in each file. The setUp function will be passed a DocTest 
     2272      object.  The setUp function can access the test globals as the 
     2273      globs attribute of the test passed. 
     2274 
     2275    tearDown 
     2276      A tear-down function.  This is called after running the 
     2277      tests in each file.  The tearDown function will be passed a DocTest 
     2278      object.  The tearDown function can access the test globals as the 
     2279      globs attribute of the test passed. 
     2280 
     2281    globs 
     2282      A dictionary containing initial global variables for the tests. 
     2283 
     2284    optionflags 
     2285       A set of doctest option flags expressed as an integer. 
     2286    """ 
     2287 
     2288    if test_finder is None: 
     2289        test_finder = DocTestFinder() 
     2290 
     2291    module = _normalize_module(module) 
     2292    tests = test_finder.find(module, globs=globs, extraglobs=extraglobs) 
     2293    if globs is None: 
     2294        globs = module.__dict__ 
     2295    if not tests: 
     2296        # Why do we want to do this? Because it reveals a bug that might 
     2297        # otherwise be hidden. 
     2298        raise ValueError(module, "has no tests") 
     2299 
     2300    tests.sort() 
     2301    suite = unittest.TestSuite() 
     2302    for test in tests: 
     2303        if len(test.examples) == 0: 
     2304            continue 
     2305        if not test.filename: 
     2306            filename = module.__file__ 
     2307            if filename[-4:] in (".pyc", ".pyo"): 
     2308                filename = filename[:-1] 
     2309            test.filename = filename 
     2310        suite.addTest(test_class(test, **options)) 
     2311 
     2312    return suite 
     2313 
     2314class DocFileCase(DocTestCase): 
     2315 
     2316    def id(self): 
     2317        return '_'.join(self._dt_test.name.split('.')) 
     2318 
     2319    def __repr__(self): 
     2320        return self._dt_test.filename 
     2321    __str__ = __repr__ 
     2322 
     2323    def format_failure(self, err): 
     2324        return ('Failed doctest test for %s\n  File "%s", line 0\n\n%s' 
     2325                % (self._dt_test.name, self._dt_test.filename, err) 
     2326                ) 
     2327 
     2328def DocFileTest(path, module_relative=True, package=None, 
     2329                globs=None, parser=DocTestParser(), **options): 
     2330    if globs is None: 
     2331        globs = {} 
     2332 
     2333    if package and not module_relative: 
     2334        raise ValueError("Package may only be specified for module-" 
     2335                         "relative paths.") 
     2336 
     2337    # Relativize the path. 
     2338    if module_relative: 
     2339        package = _normalize_module(package) 
     2340        path = _module_relative_path(package, path) 
     2341 
     2342    # Find the file and read it. 
     2343    name = os.path.basename(path) 
     2344    doc = open(path).read() 
     2345 
     2346    # Convert it to a test, and wrap it in a DocFileCase. 
     2347    test = parser.get_doctest(doc, globs, name, path, 0) 
     2348    return DocFileCase(test, **options) 
     2349 
     2350def DocFileSuite(*paths, **kw): 
     2351    """A unittest suite for one or more doctest files. 
     2352 
     2353    The path to each doctest file is given as a string; the 
     2354    interpretation of that string depends on the keyword argument 
     2355    "module_relative". 
     2356 
     2357    A number of options may be provided as keyword arguments: 
     2358 
     2359    module_relative 
     2360      If "module_relative" is True, then the given file paths are 
     2361      interpreted as os-independent module-relative paths.  By 
     2362      default, these paths are relative to the calling module's 
     2363      directory; but if the "package" argument is specified, then 
     2364      they are relative to that package.  To ensure os-independence, 
     2365      "filename" should use "/" characters to separate path 
     2366      segments, and may not be an absolute path (i.e., it may not 
     2367      begin with "/"). 
     2368 
     2369      If "module_relative" is False, then the given file paths are 
     2370      interpreted as os-specific paths.  These paths may be absolute 
     2371      or relative (to the current working directory). 
     2372 
     2373    package 
     2374      A Python package or the name of a Python package whose directory 
     2375      should be used as the base directory for module relative paths. 
     2376      If "package" is not specified, then the calling module's 
     2377      directory is used as the base directory for module relative 
     2378      filenames.  It is an error to specify "package" if 
     2379      "module_relative" is False. 
     2380 
     2381    setUp 
     2382      A set-up function.  This is called before running the 
     2383      tests in each file. The setUp function will be passed a DocTest 
     2384      object.  The setUp function can access the test globals as the 
     2385      globs attribute of the test passed. 
     2386 
     2387    tearDown 
     2388      A tear-down function.  This is called after running the 
     2389      tests in each file.  The tearDown function will be passed a DocTest 
     2390      object.  The tearDown function can access the test globals as the 
     2391      globs attribute of the test passed. 
     2392 
     2393    globs 
     2394      A dictionary containing initial global variables for the tests. 
     2395 
     2396    optionflags 
     2397      A set of doctest option flags expressed as an integer. 
     2398 
     2399    parser 
     2400      A DocTestParser (or subclass) that should be used to extract 
     2401      tests from the files. 
     2402    """ 
     2403    suite = unittest.TestSuite() 
     2404 
     2405    # We do this here so that _normalize_module is called at the right 
     2406    # level.  If it were called in DocFileTest, then this function 
     2407    # would be the caller and we might guess the package incorrectly. 
     2408    if kw.get('module_relative', True): 
     2409        kw['package'] = _normalize_module(kw.get('package')) 
     2410 
     2411    for path in paths: 
     2412        suite.addTest(DocFileTest(path, **kw)) 
     2413 
     2414    return suite 
     2415 
     2416###################################################################### 
     2417## 9. Debugging Support 
     2418###################################################################### 
     2419 
     2420def script_from_examples(s): 
     2421    r"""Extract script from text with examples. 
     2422 
     2423       Converts text with examples to a Python script.  Example input is 
     2424       converted to regular code.  Example output and all other words 
     2425       are converted to comments: 
     2426 
     2427       >>> text = ''' 
     2428       ...       Here are examples of simple math. 
     2429       ... 
     2430       ...           Python has super accurate integer addition 
     2431       ... 
     2432       ...           >>> 2 + 2 
     2433       ...           5 
     2434       ... 
     2435       ...           And very friendly error messages: 
     2436       ... 
     2437       ...           >>> 1/0 
     2438       ...           To Infinity 
     2439       ...           And 
     2440       ...           Beyond 
     2441       ... 
     2442       ...           You can use logic if you want: 
     2443       ... 
     2444       ...           >>> if 0: 
     2445       ...           ...    blah 
     2446       ...           ...    blah 
     2447       ...           ... 
     2448       ... 
     2449       ...           Ho hum 
     2450       ...           ''' 
     2451 
     2452       >>> print script_from_examples(text) 
     2453       # Here are examples of simple math. 
     2454       # 
     2455       #     Python has super accurate integer addition 
     2456       # 
     2457       2 + 2 
     2458       # Expected: 
     2459       ## 5 
     2460       # 
     2461       #     And very friendly error messages: 
     2462       # 
     2463       1/0 
     2464       # Expected: 
     2465       ## To Infinity 
     2466       ## And 
     2467       ## Beyond 
     2468       # 
     2469       #     You can use logic if you want: 
     2470       # 
     2471       if 0: 
     2472          blah 
     2473          blah 
     2474       # 
     2475       #     Ho hum 
     2476       """ 
     2477    output = [] 
     2478    for piece in DocTestParser().parse(s): 
     2479        if isinstance(piece, Example): 
     2480            # Add the example's source code (strip trailing NL) 
     2481            output.append(piece.source[:-1]) 
     2482            # Add the expected output: 
     2483            want = piece.want 
     2484            if want: 
     2485                output.append('# Expected:') 
     2486                output += ['## '+l for l in want.split('\n')[:-1]] 
     2487        else: 
     2488            # Add non-example text. 
     2489            output += [_comment_line(l) 
     2490                       for l in piece.split('\n')[:-1]] 
     2491 
     2492    # Trim junk on both ends. 
     2493    while output and output[-1] == '#': 
     2494        output.pop() 
     2495    while output and output[0] == '#': 
     2496        output.pop(0) 
     2497    # Combine the output, and return it. 
     2498    return '\n'.join(output) 
     2499 
     2500def testsource(module, name): 
     2501    """Extract the test sources from a doctest docstring as a script. 
     2502 
     2503    Provide the module (or dotted name of the module) containing the 
     2504    test to be debugged and the name (within the module) of the object 
     2505    with the doc string with tests to be debugged. 
     2506    """ 
     2507    module = _normalize_module(module) 
     2508    tests = DocTestFinder().find(module) 
     2509    test = [t for t in tests if t.name == name] 
     2510    if not test: 
     2511        raise ValueError(name, "not found in tests") 
     2512    test = test[0] 
     2513    testsrc = script_from_examples(test.docstring) 
     2514    return testsrc 
     2515 
     2516def debug_src(src, pm=False, globs=None): 
     2517    """Debug a single doctest docstring, in argument `src`'""" 
     2518    testsrc = script_from_examples(src) 
     2519    debug_script(testsrc, pm, globs) 
     2520 
     2521def debug_script(src, pm=False, globs=None): 
     2522    "Debug a test script.  `src` is the script, as a string." 
     2523    import pdb 
     2524 
     2525    # Note that tempfile.NameTemporaryFile() cannot be used.  As the 
     2526    # docs say, a file so created cannot be opened by name a second time 
     2527    # on modern Windows boxes, and execfile() needs to open it. 
     2528    srcfilename = tempfile.mktemp(".py", "doctestdebug") 
     2529    f = open(srcfilename, 'w') 
     2530    f.write(src) 
     2531    f.close() 
     2532 
     2533    try: 
     2534        if globs: 
     2535            globs = globs.copy() 
     2536        else: 
     2537            globs = {} 
     2538 
     2539        if pm: 
     2540            try: 
     2541                execfile(srcfilename, globs, globs) 
     2542            except: 
     2543                print sys.exc_info()[1] 
     2544                pdb.post_mortem(sys.exc_info()[2]) 
     2545        else: 
     2546            # Note that %r is vital here.  '%s' instead can, e.g., cause 
     2547            # backslashes to get treated as metacharacters on Windows. 
     2548            pdb.run("execfile(%r)" % srcfilename, globs, globs) 
     2549 
     2550    finally: 
     2551        os.remove(srcfilename) 
     2552 
     2553def debug(module, name, pm=False): 
     2554    """Debug a single doctest docstring. 
     2555 
     2556    Provide the module (or dotted name of the module) containing the 
     2557    test to be debugged and the name (within the module) of the object 
     2558    with the docstring with tests to be debugged. 
     2559    """ 
     2560    module = _normalize_module(module) 
     2561    testsrc = testsource(module, name) 
     2562    debug_script(testsrc, pm, module.__dict__) 
     2563 
     2564###################################################################### 
     2565## 10. Example Usage 
     2566###################################################################### 
     2567class _TestClass: 
     2568    """ 
     2569    A pointless class, for sanity-checking of docstring testing. 
     2570 
     2571    Methods: 
     2572        square() 
     2573        get() 
     2574 
     2575    >>> _TestClass(13).get() + _TestClass(-12).get() 
     2576    1 
     2577    >>> hex(_TestClass(13).square().get()) 
     2578    '0xa9' 
     2579    """ 
     2580 
     2581    def __init__(self, val): 
     2582        """val -> _TestClass object with associated value val. 
     2583 
     2584        >>> t = _TestClass(123) 
     2585        >>> print t.get() 
     2586        123 
     2587        """ 
     2588 
     2589        self.val = val 
     2590 
     2591    def square(self): 
     2592        """square() -> square TestClass's associated value 
     2593 
     2594        >>> _TestClass(13).square().get() 
     2595        169 
     2596        """ 
     2597 
     2598        self.val = self.val ** 2 
     2599        return self 
     2600 
     2601    def get(self): 
     2602        """get() -> return TestClass's associated value. 
     2603 
     2604        >>> x = _TestClass(-42) 
     2605        >>> print x.get() 
     2606        -42 
     2607        """ 
     2608 
     2609        return self.val 
     2610 
     2611__test__ = {"_TestClass": _TestClass, 
     2612            "string": r""" 
     2613                      Example of a string object, searched as-is. 
     2614                      >>> x = 1; y = 2 
     2615                      >>> x + y, x * y 
     2616                      (3, 2) 
     2617                      """, 
     2618 
     2619            "bool-int equivalence": r""" 
     2620                                    In 2.2, boolean expressions displayed 
     2621                                    0 or 1.  By default, we still accept 
     2622                                    them.  This can be disabled by passing 
     2623                                    DONT_ACCEPT_TRUE_FOR_1 to the new 
     2624                                    optionflags argument. 
     2625                                    >>> 4 == 4 
     2626                                    1 
     2627                                    >>> 4 == 4 
     2628                                    True 
     2629                                    >>> 4 > 4 
     2630                                    0 
     2631                                    >>> 4 > 4 
     2632                                    False 
     2633                                    """, 
     2634 
     2635            "blank lines": r""" 
     2636                Blank lines can be marked with <BLANKLINE>: 
     2637                    >>> print 'foo\n\nbar\n' 
     2638                    foo 
     2639                    <BLANKLINE> 
     2640                    bar 
     2641                    <BLANKLINE> 
     2642            """, 
     2643 
     2644            "ellipsis": r""" 
     2645                If the ellipsis flag is used, then '...' can be used to 
     2646                elide substrings in the desired output: 
     2647                    >>> print range(1000) #doctest: +ELLIPSIS 
     2648                    [0, 1, 2, ..., 999] 
     2649            """, 
     2650 
     2651            "whitespace normalization": r""" 
     2652                If the whitespace normalization flag is used, then 
     2653                differences in whitespace are ignored. 
     2654                    >>> print range(30) #doctest: +NORMALIZE_WHITESPACE 
     2655                    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 
     2656                     15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 
     2657                     27, 28, 29] 
     2658            """, 
     2659           } 
     2660 
     2661def _test(): 
     2662    r = unittest.TextTestRunner() 
     2663    r.run(DocTestSuite()) 
     2664 
     2665if __name__ == "__main__": 
     2666    _test() 
  • django/conf/global_settings.py

     
    295295################## 
    296296 
    297297AUTHENTICATION_BACKENDS = ('django.contrib.auth.backends.ModelBackend',) 
     298 
     299########### 
     300# TESTING # 
     301########### 
     302 
     303TEST_RUNNER='django.test.simple.run_tests' 
  • django/core/management.py

     
    423423get_sql_all.help_doc = "Prints the CREATE TABLE, initial-data and CREATE INDEX SQL statements for the given model module name(s)." 
    424424get_sql_all.args = APP_ARGS 
    425425 
    426 def syncdb(): 
     426def syncdb(verbosity=2, interactive=True): 
    427427    "Creates the database tables for all apps in INSTALLED_APPS whose tables haven't already been created." 
    428428    from django.db import connection, transaction, models, get_creation_module 
    429429    from django.db.models import signals 
     
    471471                except KeyError: 
    472472                    pending_references[refto] = refs 
    473473            sql.extend(_get_sql_for_pending_references(model, pending_references)) 
    474             print "Creating table %s" % model._meta.db_table 
     474            if verbosity >= 2: 
     475                print "Creating table %s" % model._meta.db_table 
    475476            for statement in sql: 
    476477                cursor.execute(statement) 
    477478            table_list.append(model._meta.db_table) 
     
    480481            if model in created_models: 
    481482                sql = _get_many_to_many_sql_for_model(model) 
    482483                if sql: 
    483                     print "Creating many-to-many tables for %s model" % model.__name__ 
     484                    if verbosity >= 2: 
     485                        print "Creating many-to-many tables for %s model" % model.__name__ 
    484486                    for statement in sql: 
    485487                        cursor.execute(statement) 
    486488 
     
    490492    # to do at this point. 
    491493    for app in models.get_apps(): 
    492494        dispatcher.send(signal=signals.post_syncdb, sender=app, 
    493             app=app, created_models=created_models) 
     495            app=app, created_models=created_models,  
     496            verbosity=verbosity, interactive=interactive) 
    494497 
    495498        # Install initial data for the app (but only if this is a model we've 
    496499        # just created) 
     
    11401143dbshell.args = "" 
    11411144 
    11421145def runfcgi(args): 
    1143     """Run this project as a FastCGI application. requires flup.""" 
     1146    """Run this project as a FastCGI application. Requires flup.""" 
    11441147    from django.core.servers.fastcgi import runfastcgi 
    11451148    runfastcgi(args) 
    11461149runfcgi.args = '[various KEY=val options, use `runfcgi help` for help]' 
    11471150 
     1151def test(verbosity, app_labels): 
     1152    "Runs the test suite for the specified applications" 
     1153    from django.conf import settings 
     1154    from django.db.models import get_app, get_apps 
     1155 
     1156    if len(app_labels) == 0: 
     1157        app_list = get_apps() 
     1158    else: 
     1159        app_list = [get_app(app_label) for app_label in app_labels] 
     1160     
     1161    test_path = settings.TEST_RUNNER.split('.') 
     1162    # Allow for Python 2.5 relative paths 
     1163    if len(test_path) > 1: 
     1164        test_module_name = '.'.join(test_path[:-1]) 
     1165    else: 
     1166        test_module_name = '.' 
     1167    test_module = __import__(test_module_name, [],[],test_path[-1]) 
     1168    test_runner = getattr(test_module, test_path[-1]) 
     1169     
     1170    test_runner(app_list, verbosity) 
     1171test.help_doc = 'Runs the test suite for the specified applications, or the entire site if no apps are specified' 
     1172test.args = '[--verbosity] ' + APP_ARGS 
     1173 
    11481174# Utilities for command-line script 
    11491175 
    11501176DEFAULT_ACTION_MAPPING = { 
     
    11691195    'startproject': startproject, 
    11701196    'syncdb': syncdb, 
    11711197    'validate': validate, 
     1198    'test':test, 
    11721199} 
    11731200 
    11741201NO_SQL_TRANSACTION = ( 
     
    12191246        help='Lets you manually add a directory the Python path, e.g. "/home/djangoprojects/myproject".') 
    12201247    parser.add_option('--plain', action='store_true', dest='plain', 
    12211248        help='Tells Django to use plain Python, not IPython, for "shell" command.') 
     1249    parser.add_option('--noinput', action='store_false', dest='interactive', default=True, 
     1250        help='Tells Django to NOT prompt the user for input of any kind.') 
    12221251    parser.add_option('--noreload', action='store_false', dest='use_reloader', default=True, 
    12231252        help='Tells Django to NOT use the auto-reloader when running the development server.') 
     1253    parser.add_option('--verbosity', action='store', dest='verbosity', default='2', 
     1254        type='choice', choices=['0', '1', '2'], 
     1255        help='Verbosity level; 0=minimal output, 1=normal output, 2=all output') 
     1256 
    12241257    options, args = parser.parse_args(argv[1:]) 
    12251258 
    12261259    # Take care of options. 
     
    12471280 
    12481281    if action == 'shell': 
    12491282        action_mapping[action](options.plain is True) 
    1250     elif action in ('syncdb', 'validate', 'diffsettings', 'dbshell'): 
     1283    elif action in ('validate', 'diffsettings', 'dbshell'): 
    12511284        action_mapping[action]() 
     1285    elif action == 'syncdb': 
     1286        action_mapping[action](int(options.verbosity), options.interactive) 
    12521287    elif action == 'inspectdb': 
    12531288        try: 
    12541289            for line in action_mapping[action](): 
     
    12611296            action_mapping[action](args[1]) 
    12621297        except IndexError: 
    12631298            parser.print_usage_and_exit() 
     1299    elif action == 'test': 
     1300        try: 
     1301            action_mapping[action](int(options.verbosity), args[1:]) 
     1302        except IndexError: 
     1303            parser.print_usage_and_exit() 
    12641304    elif action in ('startapp', 'startproject'): 
    12651305        try: 
    12661306            name = args[1] 
  • django/views/debug.py

     
    115115            'function': '?', 
    116116            'lineno': '?', 
    117117        }] 
    118     t = Template(TECHNICAL_500_TEMPLATE) 
     118    t = Template(TECHNICAL_500_TEMPLATE, name='Technical 500 Template') 
    119119    c = Context({ 
    120120        'exception_type': exc_type.__name__, 
    121121        'exception_value': exc_value, 
     
    141141            # tried exists but is an empty list. The URLconf must've been empty. 
    142142            return empty_urlconf(request) 
    143143 
    144     t = Template(TECHNICAL_404_TEMPLATE) 
     144    t = Template(TECHNICAL_404_TEMPLATE, name='Technical 404 Template') 
    145145    c = Context({ 
    146146        'root_urlconf': settings.ROOT_URLCONF, 
    147147        'urlpatterns': tried, 
     
    154154 
    155155def empty_urlconf(request): 
    156156    "Create an empty URLconf 404 error response." 
    157     t = Template(EMPTY_URLCONF_TEMPLATE) 
     157    t = Template(EMPTY_URLCONF_TEMPLATE, name='Empty URLConf Template') 
    158158    c = Context({ 
    159159        'project_name': settings.SETTINGS_MODULE.split('.')[0] 
    160160    }) 
  • django/views/static.py

     
    8181    try: 
    8282        t = loader.get_template('static/directory_index') 
    8383    except TemplateDoesNotExist: 
    84         t = Template(DEFAULT_DIRECTORY_INDEX_TEMPLATE) 
     84        t = Template(DEFAULT_DIRECTORY_INDEX_TEMPLATE, name='Default Directory Index Template') 
    8585    files = [] 
    8686    for f in os.listdir(fullpath): 
    8787        if not f.startswith('.'): 
  • django/contrib/contenttypes/management.py

     
    55from django.dispatch import dispatcher 
    66from django.db.models import get_models, signals 
    77 
    8 def create_contenttypes(app, created_models): 
     8def create_contenttypes(app, created_models, verbosity): 
    99    from django.contrib.contenttypes.models import ContentType 
    1010    app_models = get_models(app) 
    1111    if not app_models: 
     
    1919            ct = ContentType(name=str(opts.verbose_name), 
    2020                app_label=opts.app_label, model=opts.object_name.lower()) 
    2121            ct.save() 
    22             print "Adding content type '%s | %s'" % (ct.app_label, ct.model) 
     22            if verbosity >= 2: 
     23                print "Adding content type '%s | %s'" % (ct.app_label, ct.model) 
    2324 
    2425dispatcher.connect(create_contenttypes, signal=signals.post_syncdb) 
  • django/contrib/auth/management.py

     
    1616        perms.append((_get_permission_codename(action, opts), 'Can %s %s' % (action, opts.verbose_name))) 
    1717    return perms + list(opts.permissions) 
    1818 
    19 def create_permissions(app, created_models): 
     19def create_permissions(app, created_models, verbosity): 
    2020    from django.contrib.contenttypes.models import ContentType 
    2121    from django.contrib.auth.models import Permission 
    2222    app_models = get_models(app) 
     
    2727        for codename, name in _get_all_permissions(klass._meta): 
    2828            p, created = Permission.objects.get_or_create(codename=codename, content_type__pk=ctype.id, 
    2929                defaults={'name': name, 'content_type': ctype}) 
    30             if created: 
     30            if created and verbosity >= 2: 
    3131                print "Adding permission '%s'" % p 
    3232 
    33 def create_superuser(app, created_models): 
     33def create_superuser(app, created_models, verbosity, **kwargs): 
    3434    from django.contrib.auth.models import User 
    3535    from django.contrib.auth.create_superuser import createsuperuser as do_create 
    36     if User in created_models: 
     36    if User in created_models and kwargs.get('interactive', True): 
    3737        msg = "\nYou just installed Django's auth system, which means you don't have " \ 
    3838                "any superusers defined.\nWould you like to create one now? (yes/no): " 
    3939        confirm = raw_input(msg) 
  • django/contrib/sites/management.py

     
    77from django.contrib.sites.models import Site 
    88from django.contrib.sites import models as site_app 
    99 
    10 def create_default_site(app, created_models): 
     10def create_default_site(app, created_models, verbosity): 
    1111    if Site in created_models: 
    12         print "Creating example.com Site object" 
     12        if verbosity >= 2: 
     13            print "Creating example.com Site object" 
    1314        s = Site(domain="example.com", name="example.com") 
    1415        s.save() 
    1516 
  • django/template/__init__.py

     
    6060from django.template.context import Context, RequestContext, ContextPopException 
    6161from django.utils.functional import curry 
    6262from django.utils.text import smart_split 
     63from django.dispatch import dispatcher 
     64from django.template import signals 
    6365 
    6466__all__ = ('Template', 'Context', 'RequestContext', 'compile_string') 
    6567 
     
    137139        return self.source 
    138140 
    139141class Template(object): 
    140     def __init__(self, template_string, origin=None): 
     142    def __init__(self, template_string, origin=None, name='<Unknown Template>'): 
    141143        "Compilation stage" 
    142144        if settings.TEMPLATE_DEBUG and origin == None: 
    143145            origin = StringOrigin(template_string) 
    144146            # Could do some crazy stack-frame stuff to record where this string 
    145147            # came from... 
    146148        self.nodelist = compile_string(template_string, origin) 
     149        self.name = name 
    147150 
    148151    def __iter__(self): 
    149152        for node in self.nodelist: 
     
    152155 
    153156    def render(self, context): 
    154157        "Display stage -- can be called many times" 
     158        dispatcher.send(signal=signals.template_rendered, sender=self, template=self, context=context) 
    155159        return self.nodelist.render(context) 
    156160 
    157161def compile_string(template_string, origin): 
  • django/template/defaulttags.py

     
    251251            output = '' 
    252252        if self.parsed: 
    253253            try: 
    254                 t = Template(output) 
     254                t = Template(output, name=self.filepath) 
    255255                return t.render(context) 
    256256            except TemplateSyntaxError, e: 
    257257                if settings.DEBUG: 
  • django/template/loader_tags.py

     
    5757        except TemplateDoesNotExist: 
    5858            raise TemplateSyntaxError, "Template %r cannot be extended, because it doesn't exist" % parent 
    5959        else: 
    60             return get_template_from_string(source, origin) 
     60            return get_template_from_string(source, origin, parent) 
    6161 
    6262    def render(self, context): 
    6363        compiled_parent = self.get_parent(context) 
  • django/template/loader.py

     
    7676    Returns a compiled Template object for the given template name, 
    7777    handling template inheritance recursively. 
    7878    """ 
    79     return get_template_from_string(*find_template_source(template_name)) 
     79    source, origin = find_template_source(template_name) 
     80    template = get_template_from_string(source, origin, template_name) 
     81    return template 
    8082 
    81 def get_template_from_string(source, origin=None): 
     83def get_template_from_string(source, origin=None, name=None): 
    8284    """ 
    8385    Returns a compiled Template object for the given template code, 
    8486    handling template inheritance recursively. 
    8587    """ 
    86     return Template(source, origin) 
     88    return Template(source, origin, name) 
    8789 
    8890def render_to_string(template_name, dictionary=None, context_instance=None): 
    8991    """