Add displayTracebacks argument to Klein.run.

This enables per-Klein app control of traceback display.

Fixes #112

AUTHORS

@@ -13,3 +13,4 @@ Paul Hummer
 Russel Haering
 Tom Most
 Wilfredo Sánchez Vega
+Evilham

docs/examples/disablingtracebacks.rst

@@ -0,0 +1,68 @@
+====================================
+Example -- Disabling traceback pages
+====================================
+
+If processing a request fails, by default Klein (and Twisted) show an error
+page that prints the traceback and other useful debugging information.
+
+This is not desirable when you deploy code publicly, in such a case, you
+should disable this behaviour.
+
+There are multiple ways to do this, you can do this on a Klein-app scope or
+change the default for the python process.
+
+We will use following Klein app:
+
+.. code-block:: python
+
+    from klein import Klein
+
+    app = Klein()
+
+    @app.route('/OK')
+    def requestOK(self, request):
+        return 'OK'
+
+    @app.route('/KO')
+    def requestKO(self, request):
+        raise RuntimeError('Oops')
+
+
+Example - Disable traceback pages on a single Klein app
+=======================================================
+
+This works by passing the ``displayTracebacks`` argument as ``False``
+to ``app.run``.
+
+.. code-block:: python
+
+    if __name__ == '__main__':
+        import sys
+        displayTracebacks = '--production' not in sys.args
+
+        # The Klein app will not display tracebacks if the script is called
+        # with a --production argument, but it will otherwise.
+        app.run('localhost', 8080, displayTracebacks=displayTracebacks)
+
+
+Example - Disable traceback pages process wide
+==============================================
+
+This method also affects other Twisted Sites.
+
+Under the hood, Klein uses ``twisted.web.server.Site``, which has an
+instance variable ``displayTracebacks`` that defaults to ``True``.
+
+For the rationale behind that, check
+https://twistedmatrix.com/trac/ticket/135
+
+.. code-block:: python
+
+    # Disable tracebacks by default for any Site object.
+    from twisted.web.server import Site
+    Site.displayTracebacks = False
+
+
+    if __name__ == '__main__':
+        # The Klein app won't display tracebacks
+        app.run('localhost', 8080)

src/klein/_app.py

@@ -374,7 +374,7 @@ def urlFor(self, request, endpoint, values=None, method=None,
 
 
     def run(self, host=None, port=None, logFile=None,
-            endpoint_description=None):
+            endpoint_description=None, displayTracebacks=True):
         """
         Run a minimal twisted.web server on the specified C{port}, bound to the
         interface specified by C{host} and logging to C{logFile}.
@@ -399,6 +399,10 @@ def run(self, host=None, port=None, logFile=None,
             protocol, port and interface. May contain other optional arguments,
              e.g. to use SSL: "ssl:443:privateKey=key.pem:certKey=crt.pem"
         @type endpoint_description: str
+
+        @param displayTracebacks: Weather a processing error will result in
+            a page displaying the traceback with debugging information or not.
+        @type displayTracebacks: bool
         """
         if logFile is None:
             logFile = sys.stdout
@@ -410,7 +414,11 @@ def run(self, host=None, port=None, logFile=None,
                                                                        host)
 
         endpoint = endpoints.serverFromString(reactor, endpoint_description)
-        endpoint.listen(Site(self.resource()))
+
+        site = Site(self.resource())
+        site.displayTracebacks = displayTracebacks
+
+        endpoint.listen(site)
         reactor.run()