    #!/usr/bin/env python

    """DebugAppServer

    `DebugAppServer` executes all requests within the main thread, allowing
    servlets to be easily debugged using any Python debugger. The drawback is
    that only one request can be processed at a time using this approach.

    Also, exceptions are not caught and gracefully handled with an HTML error
    page. Instead, the exceptions rise uncaught which allows the debugger to
    trap them so you can inspect the program.

    To use, simply run "python Launch.py DebugAppServer" using whatever debugging
    environment you prefer.

    Caveats:

    This app server supports the AutoReload feature but not for Python's standard
    modules or WebKit or WebKit's dependencies (MiscUtils, WebUtils and TaskKit).
    Even with that limitation, auto-reload is still useful because if you modify
    any module in your site, the auto-reload will happen. Note that the app server
    *will* restart when the aformentioned modules are modified, but the modules
    won't actually be reloaded.

    Currently the session sweeper is still run within a separate thread, and
    a "close thread" is started up by the AppServer base class, but neither
    of these two extra threads should pose any problems debugging servlets.

    Tested on:
        - WingIDE on Windows, http://wingware.com/
        - PythonWin
        - JEdit with the JPyDbg plugin, on Windows

    """

    import sys

    import ThreadedAppServer, Profiler

    # We are going to replace ThreadedAppServer with our own class,
    # so we need to save a reference to the original class.
    OriginalThreadedAppServer = ThreadedAppServer.ThreadedAppServer

    # We want the Python debugger to trap the exceptions, not WebKit
    ThreadedAppServer.doesRunHandleExceptions = False

    class DebugAppServer(OriginalThreadedAppServer):
        """Single-threaded AppServer for debugging purposes.

        We are piggybacking on 99% of the code in ThreadedAppServer. Our
        trick is to replace the request queue with a dummy object that
        executes requests immediately instead of pushing them onto a queue
        to be handled by other threads.

        """

        ## Init ##

        _excludePrefixes = 'WebKit MiscUtils WebUtils TaskKit'.split()

        def __init__(self, path=None):
            """Initialize DebugAppServer."""
            # Initialize the base class
            OriginalThreadedAppServer.__init__(self, path)
            # Replace the request queue with a dummy object that merely
            # runs request handlers as soon as they are "pushed"
            self._requestQueue = DummyRequestQueue()
            print 'You are running the debugging app server.'

        def config(self):
            """Return default configuration."""
            # Force ThreadedAppServer to create an empty thread pool by hacking
            # the settings to zero. This is not strictly necessary to do.
            if self._config is None:
                OriginalThreadedAppServer.config(self)
                self.setSetting('StartServerThreads', 0)
                self.setSetting('MaxServerThreads', 0)
                self.setSetting('MinServerThreads', 0)
            return self._config

        ## Overridden methods ##

        def mainloop(self):
            """Main loop for Windows.

            This is needed for COM support on Windows, because special thread
            initialization is required on any thread that runs servlets, in
            this case the main thread itself.

            """
            self.initThread()
            try:
                OriginalThreadedAppServer.mainloop(self)
            finally:
                self.delThread()

        def createApplication(self):
            """Create and return an application object. Invoked by __init__."""
            return DebugApplication(server=self)

        def restart(self):
            # The normal restart technique is to exit the application
            # with a special exit code and let an exta-process script
            # start the app server up again. That works poorly for a
            # debugging environment which is attached to a particular process.
            Profiler.reset()
            self.initiateShutdown()
            self._closeThread.join()
            sys.stdout.flush()
            sys.stderr.flush()
            self._imp.delModules(includePythonModules=False,
                excludePrefixes=self._excludePrefixes)
            raise ThreadedAppServer.RestartAppServerError

    from Application import Application

    class DebugApplication(Application):
        """This is a modified Application class for debugging."""

        ## Overridden methods ##

        # Don't handle exceptions gracefully because we want
        # them to rise uncaught so the debugger will kick in.

        # @@ 2005-07-15 CE: This works well for exceptions within responding to
        # a request, but for problems during importing a servlet, the exception
        # gets printed to console and the debugger does not kick in.

        def handleException(self):
            """Handle exception.

            This should only be used in cases where there is no transaction object,
            for example if an exception occurs when attempting to save a session
            to disk.

            """
            raise

        def handleExceptionInTransaction(self, excInfo, transaction):
            """Handle exception with info.

            Raises exception `excInfo` (as returned by ``sys.exc_info()``)
            that was generated by `transaction`.

            """
            raise

    class DummyRequestQueue(object):
        """This is a dummy replacement for the request queue.

        It merely executes handlers as soon as they are "pushed".

        """

        ## Overridden methods ##

        @staticmethod
        def put(handler):
            handler.handleRequest()
            handler.close()

    ## Globals ##

    # Replace ThreadedAppServer class in the ThreadedAppServer module with our
    # DebugAppServer.  This seems like an awful hack, but it works and
    # requires less code duplication than other approaches I could think of, and
    # required a very minimal amount of modification to ThreadedAppServer.py.
    ThreadedAppServer.ThreadedAppServer = DebugAppServer

    # Grab the main function from ThreadedAppServer -- it has been "tricked"
    # into using DebugAppServer instead.
    main = ThreadedAppServer.main

    # Tweak ThreadedAppServer so that it never runs the main loop in a thread:
    def runMainLoopInThread():
        return 0
    ThreadedAppServer.runMainLoopInThread = runMainLoopInThread