fireflask 0.2.0
Simple, beautiful logging from Flask web apps to FireBug console
License: Apache License 2.0
Keywords: webapp Flask debug log logging FireBug FireLogger FirePython

fireflask
=========

I've long wanted to use `FirePython
<http://firelogger.binaryage.com/#python>`_ for debugging `Flask
<http://flask.pocoo.org>`_ web apps, but could never seem to get it working
right.

After a long time away, I circled back to it, and `with help from the Flask
folks <https://github.com/mitsuhiko/flask/issues/752>`_, got it working
smoothly.

Indeed, it was so simple to do, knowing the right invocation and
configuration, that I can only blame myself for not getting it earlier. My
only consolation is that there is no real documentation (the usage link on
FireLogger's home page is a dead link).

So, having figured it out, I'm sharing in the hopes that others
can now simply use this beautiful tool.

.. image:: http://content.screencast.com/users/jonathaneunice/folders/Jing/media/ca71bb7a-e383-4607-a66a-12a27f18208e/00000330.png
    :align: center


Basic Idea
==========

The code is sufficiently simple I can put the core of it here::

    from flask import Flask
    from logging import DEBUG
    from firepython.middleware import FirePythonWSGI, logging

    app = Flask('appname')
    app.wsgi_app = FirePythonWSGI(app.wsgi_app)
    logging.getLogger().setLevel(DEBUG)

That's it. Now you're off to the races. When the app server is run,
any logging messages you direct to the ``logging`` object end up
in your FireBug / FireLogger console. More complete versions of this
demo code can be found in ``trivial.py`` and ``demo_primitive.py``
in the repository.

FireFlask
=========

To make things even simpler, the ``fireflask`` module requires just
two lines of code (one to import ``fireflask``, and one to put it
into operation). ::

    from flask import Flask
    from fireflask import *

    app = Flask('appname')
    FireFlask(app)

    @app.route('/')
    def hello_world():

        logging.info('serving hello_world content')
        return 'Hello World!'

    app.run()

Here we've completed the program with a function that provides
content, and the startup code for the Flask web server.
``fireflask`` isn't a huge lines-of-code
savings, but it will save you a few steps
and make the program cleaner.

Notes
=====

 * This has been tested under Python 2.7. No promises are made
   for other versions of Python.

 * The author, `Jonathan Eunice <mailto:jonathan.eunice@gmail.com>`_ or
   `@jeunice on Twitter <http://twitter.com/jeunice>`_
   welcomes your comments and suggestions.

Installation
============

To install or upgrade to the latest version of ``fireflask``::

    pip install -U fireflask

This will install the ``firepython`` module automatically.
Or, if you want to use just the primitive approach::

    pip install -U firepython

(You may need to prefix these with ``sudo`` to authorize installation.)

Use the standard Firefox tools to install FireBug and the
FireLogger extension.

Use
===

To run the demonstration programs, run
``trivial.py``, ``demo_primitive.py`` or ``demo.py``.

Browse to ``127.0.0.1:5000`` in Firefox, with the FireBug extension
turned on, and the Logger pane visible. This is the FireBug icon:

.. image:: http://content.screencast.com/users/jonathaneunice/folders/Jing/media/795cbb0a-aa03-4d01-993f-4a1e4e2ce427/00000329.png
    :align: center

When FireBug is operational, it's displayed in color, not grayed
out.  If you browse to the page before FireBug is turned on, you'll
need to reload the page to see the logged messages.