Pylons

Pylons Globals
==============

So far we have seen a number of objects including ``request``, ``response`` and
``abort``.  These are referred to as the Pylons Globals because Pylons takes
great care behind the scenes to make sure they are available throughout your
application in both you project's controllers and its templates. 

There are other Pylons Globals too which we'll discuss throughout the book.
Here is a complete list of the Pylons Globals and a brief summary of what each
is used for:

.. XXX MO Update this list.  Add 'response'. I think the i18n globals have
.. XXX MO changed or are no longer imported by default.
.. XXX MO Have any more decorators been added?

.. XXX MO I would separate global objects available in both the controller
.. XXX MO and template, vs functions that apply only to the controller.
.. XXX MO Also, the list should be alphabetical.

.. XXX MO Also, new controllers import a few globals explicitly, rather than
   "import \*"ing myapp.lib.base.  I don't know what the definitive "complete"
   list of globals is.  I'm inclined to list the StackedObjectProxies
   separately, render_\* in pylons.templating, and mention that there are
   other useful functions in pylons.controllers.util and pylons.decorators.

``request``
    The request object

``response``
    The global response object used to specify details about the response
    returned to the browser.
    
``abort``
    Function to abort the request immediately by raising an HTTPException 
    according to the specified status code

``render``
    Function to render a template and return a string

``session``
    Acts as a dict to store session data.

``redirect_to``
    Function to redirect the browser to a different location via the HTTP 302 
    status code (by raising an HTTPException)

``etag_cache``, ``cache``
    Used in caching, described in Chapter XXX.
    
``h``
    h is the point at which all the Pylons helper functions are utilized from. By
    default Pylons will load only the Rails helper functions from the `Web
    Helpers </WebHelpers/module-index.html>`_ package but you can add your own as
    needed.

``c``
    The Pylons context object, recreated on each request and used for passing data
    around throughout your Pylons application

``g``
    The Pylons global object, created when the server starts and destroyed
    when the server exits the ``g`` object persists across multiple requests.

``WSGIController``, ``BaseController``
    The main controller objects your Pylons controllers will be derived from.

``jsonify``, ``validate``
    Decorators used respectively to return valid JSON data from a Python object 
    and to validate a form submission.
    
``model``
    Your project's ``helloworld.model`` module which will contain data model 
    information.
    
``_``, ``ungettext``, ``N_``
    Functions to help with internationalisation described in Chapter XXX.

.. note :: 

    One thing that sometimes concerns newcomers to Pylons is that it is
    generally considered bad practice to name variables with just one letter in
    case someone else decides to create a variable with the same name. Whilst this
    is true you will find during Pylons development that you use the ``h``, ``c``
    and ``g`` objects very frequently so the Pylons developers decided the short
    names were preferable. The ``_`` variable used in internationalisation is a
    Python convention.

.. XXX MO Pylons has officially renamed 'c' to tmpl_context and 'g' to 
   app_globals.  New controllers now import::

       from pylons import request, response, session
       from pylons import tmpl_context as c
       from pylons.controllers.util import abort, redirect_to

       from tmpapp.lib.base import BaseController, render
       #import tmpapp.model as model

   This is subject to change of course.  Note that 'g' and 'h' are not
   imported at all; it's up to the user to know about them and import them
   if he wants.

   You could mention that the one-letter globals were a legacy from Myghty,
   which borrowed them from Perl's HTML::Mason.