177c566eca
backlash is a port of Werkzeug's debugger middleware to Webob. It has no additional dependencies beyond Webob and is being used by the TurboGears2 team as an alternative to the antiquated Paste/WebError. Leveraging this as an *optional* dependency to pecan would: * Remove a sizable chunk of code from pecan, some of which is embedded JavaScript that packagers have traditionally balked at. * Improve the interactive debugging experience for developers in a very meaningful way (the Werkzeug-based middleware provides features like an in-browser console debugger, the ability to load source code on a frame-by-frame basis). * Improve the unified debugging experience amongst several popular Python frameworks (some form of the debugging interface will be in use by Flask, Pecan, and TurboGears2). Change-Id: I85f50f677c6052bd2afd32811dedf33835135e12
61 lines
1.8 KiB
ReStructuredText
61 lines
1.8 KiB
ReStructuredText
.. _development:
|
||
|
||
Developing Pecan Applications Locally
|
||
=====================================
|
||
|
||
.. include:: reload.rst
|
||
:start-after: #reload
|
||
|
||
Debugging Pecan Applications
|
||
----------------------------
|
||
|
||
Pecan comes with simple debugging middleware for helping diagnose problems
|
||
in your applications. To enable the debugging middleware, simply set the
|
||
``debug`` flag to ``True`` in your configuration file::
|
||
|
||
app = {
|
||
...
|
||
'debug': True,
|
||
...
|
||
}
|
||
|
||
Once enabled, the middleware will automatically catch exceptions raised by your
|
||
application and display the Python stack trace and WSGI environment in your
|
||
browser when runtime exceptions are raised.
|
||
|
||
To improve debugging, including support for an interactive browser-based
|
||
console, Pecan makes use of the Python `backlash
|
||
<https://pypi.python.org/pypi/backlash>` library. You’ll need to install it
|
||
for development use before continuing::
|
||
|
||
$ pip install backlash
|
||
Downloading/unpacking backlash
|
||
...
|
||
Successfully installed backlash
|
||
|
||
|
||
Serving Static Files
|
||
--------------------
|
||
|
||
Pecan comes with simple file serving middleware for serving CSS, Javascript,
|
||
images, and other static files. You can configure it by ensuring that the
|
||
following options are specified in your configuration file:
|
||
|
||
::
|
||
|
||
app = {
|
||
...
|
||
'debug': True,
|
||
'static_root': '%(confdir)/public
|
||
}
|
||
|
||
where ``static_root`` is an absolute pathname to the directory in which your
|
||
static files live. For convenience, the path may include the ``%(confdir)``
|
||
variable, which Pecan will substitute with the absolute path of your
|
||
configuration file at runtime.
|
||
|
||
.. note::
|
||
|
||
In production, ``app.debug`` should *never* be set to ``True``, so you'll
|
||
need to serve your static files via your production web server.
|