diff options
| -rw-r--r-- | CHANGES.txt | 21 | ||||
| -rw-r--r-- | TODO.txt | 6 | ||||
| -rw-r--r-- | docs/narr/MyProject/MyProject.ini | 1 | ||||
| -rw-r--r-- | docs/narr/project.rst | 15 | ||||
| -rw-r--r-- | docs/narr/templates.rst | 69 | ||||
| -rw-r--r-- | docs/whatsnew-1.3.rst | 10 | ||||
| -rw-r--r-- | repoze/bfg/chameleon_text.py | 5 | ||||
| -rw-r--r-- | repoze/bfg/chameleon_zpt.py | 5 | ||||
| -rw-r--r-- | repoze/bfg/paster_templates/alchemy/+project+.ini_tmpl | 1 | ||||
| -rw-r--r-- | repoze/bfg/paster_templates/routesalchemy/+project+.ini_tmpl | 1 | ||||
| -rw-r--r-- | repoze/bfg/paster_templates/starter/+project+.ini_tmpl | 1 | ||||
| -rw-r--r-- | repoze/bfg/paster_templates/zodb/+project+.ini_tmpl | 1 |
12 files changed, 125 insertions, 11 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 5d17d0134..e2199614f 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -62,10 +62,20 @@ Features narrative documentation chapter entitled ``Internationalization and Localization``. -- A new setting named ``default_locale_name`` was added. If this - string is present as a Paster ``.ini`` file option, it will be - considered the default locale name. The default locale name is used - during locale-related operations such as language translation. +- A new deployment setting named ``default_locale_name`` was added. + If this string is present as a Paster ``.ini`` file option, it will + be considered the default locale name. The default locale name is + used during locale-related operations such as language translation. + +- It is now possible to turn on Chameleon template "debugging mode" + for all Chameleon BFG templates by setting a BFG-related Paster + ``.ini`` file setting named ``debug_templates``. The exceptions + raised by Chameleon templates when a rendering fails are sometimes + less than helpful. ``debug_templates`` allows you to configure your + application development environment so that exceptions generated by + Chameleon during template compilation and execution will contain + more helpful debugging information. This mode is on by default in + all new projects. ZCML ---- @@ -141,6 +151,9 @@ Paster Templates - A ``default_locale_name = en`` setting was added to each existing paster template. +- A ``debug_templates = true`` setting was added to each existing + paster template. + Licensing --------- @@ -5,11 +5,6 @@ - Basic WSGI documentation (pipeline / app / server). -- Allow a debug argument to be supplied for template rendering - (requires Chameleon capable of accepting the ``debug`` argument to a - template constructor; behavior currently implemented on Chameleon - head but not in any release). - - Figure out a way to expose some of the functionality of ``Configurator._derive_view`` as an API. @@ -20,3 +15,4 @@ - Fix message catalog extraction / compilation documentation. +- Docs about creating a venusian decorator. diff --git a/docs/narr/MyProject/MyProject.ini b/docs/narr/MyProject/MyProject.ini index 38cbf879c..6741af913 100644 --- a/docs/narr/MyProject/MyProject.ini +++ b/docs/narr/MyProject/MyProject.ini @@ -6,6 +6,7 @@ use = egg:MyProject#app reload_templates = true debug_authorization = false debug_notfound = false +debug_templates = true default_locale_name = en [server:main] diff --git a/docs/narr/project.rst b/docs/narr/project.rst index dfac238b5..97df8a28c 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -233,6 +233,8 @@ section within the ``.ini`` file. For example, if your application reload_templates = true debug_authorization = false debug_notfound = false + debug_templates = true + default_locale_name = en If so, you can use the following command to invoke a debug shell using the name ``main`` as a section name: @@ -279,6 +281,8 @@ following ``.ini`` file content: reload_templates = true debug_authorization = false debug_notfound = false + debug_templates = true + default_locale_name = en [pipeline:main] pipeline = egg:repoze.tm2#tm @@ -534,6 +538,17 @@ detected. See :ref:`reload_templates_section` for more information. production applications, as template rendering is slowed when it is turned on. +The ``debug_templates`` setting in the ``[app:main]`` section is a +:mod:`repoze.bfg` -specific setting which is passed into the +framework. If it exists, and its value is ``true``, :term:`Chameleon` +template exceptions will contained more detailed and helpful +information about the error than when this value is ``false``. See +:ref:`debug_templates_section` for more information. + +.. warning:: The ``debug_templates`` option should be turned off for + production applications, as template rendering is slowed when it is + turned on. + Various other settings may exist in this section having to do with debugging or influencing runtime behavior of a :mod:`repoze.bfg` application. See :ref:`environment_chapter` for more information diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 23a1460a1..fc0f38b0f 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -501,6 +501,75 @@ application's configuration section, e.g.:: use = egg:MyProject#app reload_templates = true +.. _debug_templates_section: + +Nicer Exceptions in Templates +----------------------------- + +The exceptions raised by Chameleon templates when a rendering fails +are sometimes less than helpful. :mod:`repoze.bfg` allows you to +configure your application development environment so that exceptions +generated by Chameleon during template compilation and execution will +contain nicer debugging information. + +.. warning:: template-debugging behavior is not recommended for + production sites as it slows renderings; it's usually + only desirable during development. + +In order to turn on template exception debugging, you can use an +environment variable setting or a configuration file setting. + +To use an environment variable, start your application under a shell +using the ``BFG_DEBUG_TEMPLATES`` operating system environment +variable set to ``1``, For example:: + + $ BFG_DEBUG_TEMPLATES=1 bin/paster serve myproject.ini + +To use a setting in the application ``.ini`` file for the same +purpose, set the ``debug_templates`` key to ``true`` within the +application's configuration section, e.g.:: + + [app:main] + use = egg:MyProject#app + debug_templates = true + +With template debugging off, a :exc:`NameError` exception resulting +from rendering a template with an undefined variable +(e.g. ``${wrong}``) might end like this:: + + File "/home/fred/env/lib/python2.5/site-packages/Chameleon-1.2.3-py2.5.egg/chameleon/core/utils.py", line 332, in __getitem__ + raise NameError(key) + NameError: wrong + +Note that the exception has no information about which template was +being rendered when the error occured. But with template debugging +on, an exception resulting from the same problem might end like so:: + + RuntimeError: Caught exception rendering template. + - Expression: ``wrong`` + - Filename: /home/fred/env/bfgzodb/bfgzodb/templates/mytemplate.pt + - Arguments: renderer_name: bfgzodb:templates/mytemplate.pt + template: <PageTemplateFile - at 0x1d2ecf0> + xincludes: <XIncludes - at 0x1d3a130> + request: <Request - at 0x1d2ecd0> + project: bfgzodb + macros: <Macros - at 0x1d3aed0> + context: <MyModel None at 0x1d39130> + view: <function my_view at 0x1d23570> + + NameError: wrong + +The latter tells you which template the error occurred in, as well as +displaying the arguments passed to the template itself. + +.. note:: + + Turning on ``debug_templates`` has the same effect as using the + Chameleon environment variable ``CHAMELEON_DEBUG``. See `Chameleon + Environment Variables + <http://chameleon.repoze.org/docs/latest/config.html#environment-variables>`_ + for more information. + .. index:: single: template internationalization single: internationalization (of templates) diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index e8f2ddcdd..32964973d 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -105,6 +105,16 @@ Minor Feature Additions that user-defined decorators can be defined and found during :mod:`repoze.bfg` scanning. +- It is now possible to turn on Chameleon template "debugging mode" + for all Chameleon BFG templates by setting a BFG-related Paster + ``.ini`` file setting named ``debug_templates``. The exceptions + raised by Chameleon templates when a rendering fails are sometimes + less than helpful. ``debug_templates`` allows you to configure your + application development environment so that exceptions generated by + Chameleon during template compilation and execution will contain + more helpful debugging information. This mode is on by default in + newly generated projects. See also :ref:`debug_templates_section`. + Backwards Incompatibilites -------------------------- diff --git a/repoze/bfg/chameleon_text.py b/repoze/bfg/chameleon_text.py index deb1cc43d..73457a128 100644 --- a/repoze/bfg/chameleon_text.py +++ b/repoze/bfg/chameleon_text.py @@ -51,11 +51,14 @@ class TextTemplateRenderer(object): def template(self): settings = get_settings() auto_reload = settings and settings['reload_templates'] + debug = settings and settings['debug_templates'] reg = get_current_registry() translate = None if reg is not None: translate = reg.queryUtility(IChameleonTranslate) - return TextTemplateFile(self.path, auto_reload=auto_reload, + return TextTemplateFile(self.path, + auto_reload=auto_reload, + debug=debug, translate=translate) def implementation(self): diff --git a/repoze/bfg/chameleon_zpt.py b/repoze/bfg/chameleon_zpt.py index 687a11305..bacb102bb 100644 --- a/repoze/bfg/chameleon_zpt.py +++ b/repoze/bfg/chameleon_zpt.py @@ -34,11 +34,14 @@ class ZPTTemplateRenderer(object): def template(self): settings = get_settings() auto_reload = settings and settings['reload_templates'] + debug = settings and settings['debug_templates'] reg = get_current_registry() translate = None if reg is not None: translate = reg.queryUtility(IChameleonTranslate) - return PageTemplateFile(self.path, auto_reload=auto_reload, + return PageTemplateFile(self.path, + auto_reload=auto_reload, + debug=debug, translate=translate) def implementation(self): diff --git a/repoze/bfg/paster_templates/alchemy/+project+.ini_tmpl b/repoze/bfg/paster_templates/alchemy/+project+.ini_tmpl index 29fc7e806..1fa0609e0 100644 --- a/repoze/bfg/paster_templates/alchemy/+project+.ini_tmpl +++ b/repoze/bfg/paster_templates/alchemy/+project+.ini_tmpl @@ -6,6 +6,7 @@ use = egg:{{project}}#app reload_templates = true debug_authorization = false debug_notfound = false +debug_templates = true default_locale_name = en db_string = sqlite:///%(here)s/{{package}}.db db_echo = false diff --git a/repoze/bfg/paster_templates/routesalchemy/+project+.ini_tmpl b/repoze/bfg/paster_templates/routesalchemy/+project+.ini_tmpl index c249172d3..4f9fd0b00 100644 --- a/repoze/bfg/paster_templates/routesalchemy/+project+.ini_tmpl +++ b/repoze/bfg/paster_templates/routesalchemy/+project+.ini_tmpl @@ -6,6 +6,7 @@ use = egg:{{package}}#app reload_templates = true debug_authorization = false debug_notfound = false +debug_templates = true default_locale_name = en db_string = sqlite:///%(here)s/{{package}}.db diff --git a/repoze/bfg/paster_templates/starter/+project+.ini_tmpl b/repoze/bfg/paster_templates/starter/+project+.ini_tmpl index 15be80cf4..9bdeec1ae 100644 --- a/repoze/bfg/paster_templates/starter/+project+.ini_tmpl +++ b/repoze/bfg/paster_templates/starter/+project+.ini_tmpl @@ -6,6 +6,7 @@ use = egg:{{project}}#app reload_templates = true debug_authorization = false debug_notfound = false +debug_templates = true default_locale_name = en [server:main] diff --git a/repoze/bfg/paster_templates/zodb/+project+.ini_tmpl b/repoze/bfg/paster_templates/zodb/+project+.ini_tmpl index 51b4e1ab8..993cec596 100644 --- a/repoze/bfg/paster_templates/zodb/+project+.ini_tmpl +++ b/repoze/bfg/paster_templates/zodb/+project+.ini_tmpl @@ -6,6 +6,7 @@ use = egg:{{project}}#app reload_templates = true debug_authorization = false debug_notfound = false +debug_templates = true default_locale_name = en zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000 |