pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛 Release 0.4.dev0
Pylons Project Contributors
January 06, 2021
Contents
1 Overview 1
2 Installation 3
3 Setup 5
4 Using Chameleon templates 7
5 More information 17
6 Reporting bugs / development versions 19
Python Module Index 21
Index 23
i ii CHAPTER 1
Overview
pyramid_chameleon is a set of bindings that make templates written for the Chameleon templating system work under the Pyramid web framework.
1 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
2 Chapter 1. Overview CHAPTER 2
Installation
Install using setuptools, e.g. (within a virtualenv):
$ $myvenv/bin/easy_install pyramid_chameleon
3 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
4 Chapter 2. Installation CHAPTER 3
Setup
There are several ways to make sure that pyramid_chameleon is active. They are completely equivalent: 1) Add pyramid_chameleon to the pyramid.includes section of your applications main configuration section:
[app:main] ... pyramid.includes= pyramid_chameleon
2) Use the includeme function via config.include:
config.include('pyramid_chameleon')
Once activated, files with the .pt extension are considered to be Chameleon templates.
5 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
6 Chapter 3. Setup CHAPTER 4
Using Chameleon templates
Once pyramid_chameleon been activated .pt templates can be loaded either by looking up names that would be found on the Chameleon search path or by looking up an absolute asset specification (see Understanding Asset Specifications for more information). Quick example 1. Look up a template named foo.pt within the templates directory of a Python package named mypackage:
1 @view_config(renderer="mypackage:templates/foo.pt)
2 def sample_view(request):
3 return {'foo':1,'bar':2}
Quick example 2. Look up a template named foo.pt within the templates directory of the "current" Python package (the package in which this Python code is defined):
1 @view_config(renderer="templates/foo.pt)
2 def sample_view(request):
3 return {'foo':1,'bar':2}
Quick example 3: manufacturing a response object using the result of render() (a string) using a Chameleon template:
1 from pyramid.renderers import render
2 from pyramid.response import Response
3
4 def sample_view(request):
5 result= render('mypackage:templates/foo.pt',
6 {'foo':1,'bar':2},
7 request=request)
8 response= Response(result)
9 response.content_type='text/plain'
10 return response
Here’s an example view configuration which uses a Chameleon ZPT renderer registered imperatively:
7 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
1 # config is an instance of pyramid.config.Configurator
2
3 config.add_view('myproject.views.sample_view',
4 renderer='myproject:templates/foo.pt')
Here’s an example view configuration which uses a Chameleon text renderer registered imperatively:
1 config.add_view('myproject.views.sample_view',
2 renderer='myproject:templates/foo.txt')
4.1 Chameleon ZPT templates
Chameleon is an implementation of ZPT (Zope Page Templates) templating language. The Chameleon engine com- plies largely with the Zope Page Template template specification. However, it is significantly faster than the default implementation that is represented by zope.pagetemplates. The language definition documentation for Chameleon ZPT-style templates is available from the Chameleon website. Given a Chameleon ZPT template named foo.pt in a directory in your application named templates, you can render the template as a renderer like so:
1 from pyramid.view import view_config
2
3 @view_config(renderer='templates/foo.pt')
4 def my_view(request):
5 return {'foo':1,'bar':2}
Two built-in renderers exist for Chameleon templates. If the renderer parameter of a view configuration is an absolute path, a relative path or asset specification which has a final path element with a filename extension of .pt, the Chameleon ZPT renderer is used. If the extension is .txt, the Chameleon text renderer is used. The behavior of these renderers is the same, except for the engine used to render the template. When a Chameleon renderer is used in a view configuration, the view must return a Response object or a Python dictionary. If the view callable with an associated template returns a Python dictionary, the named template will be passed the dictionary as its keyword arguments, and the template renderer implementation will return the resulting rendered template in a response to the user. If the view callable returns anything but a Response object or a dictionary, an error will be raised. Before passing keywords to the template, the keyword arguments derived from the dictionary returned by the view are augmented. The callable object – whatever object was used to define the view – will be automatically inserted into the set of keyword arguments passed to the template as the view keyword. If the view callable was a class, the view key- word will be an instance of that class. Also inserted into the keywords passed to the template are renderer_name (the string used in the renderer attribute of the directive), renderer_info (an object containing renderer-related information), context (the context resource of the view used to render the template), and request (the request passed to the view used to render the template). request is also available as req in Pyramid 1.3+.
4.1.1 A sample ZPT template
Here’s what a simple Chameleon ZPT template used under Pyramid might look like:
1
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3
8 Chapter 4. Using Chameleon templates pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
(continued from previous page)
4 xmlns:tal="http://xml.zope.org/namespaces/tal">
5
6
7
8
9
10
Welcome to ${project}, an
11 application generated by the 12 href="http://docs.pylonsproject.org/projects/pyramid/current/" 13 >pyramid web 14 application framework. 15 16 Note the use of Mako and/or Genshi -style ${replacements} above. This is one of the ways that Chameleon ZPT differs from standard ZPT. The above template expects to find a project key in the set of keywords passed in to it via render() or render_to_response(). Typical ZPT attribute-based syntax (e.g. tal:content and tal:replace) also works in these templates. 4.1.2 Using ZPT macros in Pyramid When a renderer is used to render a template, Pyramid makes at least two top-level names available to the template by default: context and request. One of the common needs in ZPT-based templates is to use one template’s "macros" from within a different template. In Zope, this is typically handled by retrieving the template from the context. But the context in Pyramid is a resource object, and templates cannot usually be retrieved from resources. To use macros in Pyramid, you need to make the macro template itself available to the rendered template by passing the macro template, or even the macro itself, into the rendered template. To do this you can use the pyramid. renderers.get_renderer() API to retrieve the macro template, and pass it into the template being rendered via the dictionary returned by the view. For example, using a view configuration via a view_config decorator that uses a renderer: 1 from pyramid.renderers import get_renderer 2 from pyramid.view import view_config 3 4 @view_config(renderer='templates/mytemplate.pt') 5 def my_view(request): 6 main= get_renderer('templates/master.pt').implementation() 7 return {'main':main} Where templates/master.pt might look like so: 1 2 xmlns:tal="http://xml.zope.org/namespaces/tal" 3 xmlns:metal="http://xml.zope.org/namespaces/metal"> 4
5
6
7
8
9 Hello Fred!
10
11
12
13
4.1. Chameleon ZPT templates 9 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
And templates/mytemplate.pt might look like so:
1
2 xmlns:tal="http://xml.zope.org/namespaces/tal"
3 xmlns:metal="http://xml.zope.org/namespaces/metal">
4
5
6
7
8 Chris
9
10
11
4.1.3 Using a master page
You can also use macros and slots to create a master page that can be used by all your templates. This is very similar to using a macro from another template but uses the IBeforeRender event subscriber to make the macros available to any template.
1 from pyramid.renderers import get_renderer
2 from pyramid.interfaces import IBeforeRender
3 from pyramid.events import subscriber
4
5 @subscriber(IBeforeRender)
6 def globals_factory(event):
7 master= get_renderer('templates/master.pt').implementation()
8 event['master']= master
Where templates/master.pt provides a whole page with slots to be filled by views:
1
2
3
4
6
7
8
9
10
11
12
13
14
15
16
17
- Home
18
19
20
21
22
23
24
25
26
10 Chapter 4. Using Chameleon templates pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
And templates/index.pt fills the relevant slots:
1
2
3
4
5
6
7
Pyramid Chameleon
8
Chameleon is an XML-based templating language
9
10
4.2 Chameleon text templates
pyramid_chameleon also allows for the use of templates which are composed entirely of non-XML text via Chameleon. To do so, you can create templates that are entirely composed of text except for ${name} -style substi- tution points. Here’s an example usage of a Chameleon text template. Create a file on disk named mytemplate.txt in your project’s templates directory with the following contents:
Hello, ${name}!
Then in your project’s views.py module, you can create a view which renders this template:
1 from pyramid.view import view_config
2
3 @view_config(renderer='templates/mytemplate.txt')
4 def my_view(request):
5 return {'name':'world'}
When the template is rendered, it will show:
Hello, world!
If you’d rather use templates directly within a view callable (without the indirection of using renderer in view con- figuration), see the functions in pyramid.renderers for APIs which allow you to render templates imperatively.
4.3 Template variables provided by Pyramid
Pyramid by default will provide a set of variables that are available within your templates, please see System Values Used During Rendering for more information about those variables.
4.4 Using a Chameleon macro name within a renderer name
At times, you may want to render a macro inside of a Chameleon ZPT template instead of the full Chameleon ZPT template. To render the content of a define-macro field inside a Chameleon ZPT tem- plate, given a Chameleon template file named foo.pt and a macro named bar defined within it (e.g.
4.2. Chameleon text templates 11 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
1 from pyramid.view import view_config
2
3 @view_config(renderer='foo#bar.pt')
4 def my_view(request):
5 return {'project':'my project'}
The above will render only the bar macro defined within the foo.pt template instead of the entire template.
4.5 Side effects of rendering a Chameleon template
When a Chameleon template is rendered from a file, the templating engine writes a file in the same directory as the template file itself as a kind of cache, in order to do less work the next time the template needs to be read from disk. If you see "strange" .py files showing up in your templates directory (or otherwise directly "next" to your templates), it is due to this feature. If you’re using a version control system such as Subversion, you should configure it to ignore these files. Here’s the contents of the author’s svn propedit svn:ignore . in each of my templates directories.
*.pt.py *.txt.py
Note that I always name my Chameleon ZPT template files with a .pt extension and my Chameleon text template files with a .txt extension so that these svn:ignore patterns work.
4.6 Nicer exceptions in Chameleon templates
The exceptions raised by Chameleon templates when a rendering fails are sometimes less than helpful. Pyramid 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 PYRAMID_DEBUG_TEMPLATES oper- ating system environment variable set to 1, For example:
$ PYRAMID_DEBUG_TEMPLATES=1 bin/pserve myproject.ini
To use a setting in the application .ini file for the same purpose, set the pyramid.debug_templates key to true within the application’s configuration section, e.g.:
1 [app:main]
2 use= egg:MyProject
3 pyramid.debug_templates= true
With template debugging off, a NameError exception resulting from rendering a template with an undefined variable (e.g. ${wrong}) might end like this:
12 Chapter 4. Using Chameleon templates pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
File "...", 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/proj/proj/templates/mytemplate.pt - Arguments: renderer_name: proj:templates/mytemplate.pt template:
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 pyramid.debug_templates has the same effect as using the Chameleon environment vari- able CHAMELEON_DEBUG. See Chameleon Configuration for more information.
4.7 Automatically reloading templates
It’s often convenient to see changes you make to a template file appear immediately without needing to restart the application process. Pyramid allows you to configure your application development environment so that a change to a template will be automatically detected, and the template will be reloaded on the next rendering.
Warning: Auto-template-reload behavior is not recommended for production sites as it slows rendering slightly; it’s usually only desirable during development.
In order to turn on automatic reloading of templates, you can use an environment variable, or a configuration file setting. To use an environment variable, start your application under a shell using the PYRAMID_RELOAD_TEMPLATES operating system environment variable set to 1, For example:
$ PYRAMID_RELOAD_TEMPLATES=1 bin/pserve myproject.ini
To use a setting in the application .ini file for the same purpose, set the pyramid.reload_templates key to true within the application’s configuration section, e.g.:
1 [app:main]
2 use= egg:MyProject
3 pyramid.reload_templates= true
4.7. Automatically reloading templates 13 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
4.8 Settings
Chameleon derives additional settings to configure its template renderer. Many of these settings are optional and only need to be set if they should be different from the default. The below values can be present in the .ini file used to configure the Pyramid application (in the app section representing your Pyramid app) or they can be passed directly within the settings argument passed to a Pyramid Configurator. pyramid.reload_templates true or false representing whether Chameleon templates should be reloaded when they change on disk. Useful for development to be true. pyramid.debug_templates true or false representing whether Chameleon templates should be have extra debugging info turned on in tracebacks it generates.
4.9 Changing the Content-Type of a Chameleon-rendered response
Here’s an example of changing the content-type and status of the response object returned by a Chameleon-rendered Pyramid view:
1 @view_config(renderer='foo.pt')
2 def sample_view(request):
3 request.response.content_type='text/plain'
4 response.status_int= 204
5 return response
See Varying Attributes of Rendered Responses for more information.
4.10 Chameleon template internationalization
Chameleon supports internationalized units of text by reusing the translation facilities provided within Pyramid. See Internationalization and Localization for a general description of these facilities.
4.10.1 Translating template content
You need to add a few boilerplate lines to your application’s setup.py file in order to properly generate gettext files from your application’s templates.
Note: See Creating a Pyramid Project to learn about the composition of an application’s setup.py file.
In particular, add the Babel and lingua distributions to the install_requires list and insert a set of references to Babel message extractors within the call to setuptools.setup() inside your application’s setup.py file:
1 setup(name="mypackage",
2 # ...
3 install_requires=[
4 # ...
5 'Babel',
6 'lingua', (continues on next page)
14 Chapter 4. Using Chameleon templates pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
(continued from previous page)
7 ],
8 message_extractors={'.':[ 9 ('**.py','lingua_python', None ), 10 ('**.pt','lingua_xml', None ), 11 ]},
12 )
The message_extractors stanza placed into the setup.py file causes the Babel message catalog extraction machinery to also consider *.pt files when doing message id extraction. Once this is done you can generate .pot files derived from your Chameleon templates (and Python code). See Extracting Messages from Code and Templates in the Pyramid documentation for general information about this.
4.10.2 Chameleon template support for translation strings
When a Pyramid "translation string" (see Internationalization and Localization) is used as the subject of textual ren- dering by a pyramid_chameleon template renderer, it will automatically be translated to the requesting user’s language if a suitable translation exists. This is true of both the ZPT and text variants of the Chameleon template renderers. For example, in a Chameleon ZPT template, the translation string represented by "some_translation_string" in each example below will go through translation before being rendered:
${some_translation_string}
The features represented by attributes of the i18n namespace of Chameleon will also consult the Pyramid translations. See Translation (I18N).
Note: Unlike when Chameleon is used outside of Pyramid, when it is used within Pyramid, it does not support use of the zope.i18n translation framework. Applications which use Pyramid should use the features documented in this chapter rather than zope.i18n.
You can always disuse this automatic translation and perform a more manual translation as described in Performing a Translation.
4.11 Unit testing
When you are running unit tests, you will be required to use config.include('pyramid_chameleon') to add pyramid_chameleon so that its renderers are added to the config and can be used.:
from pyramid import testing from pyramid.response import Response from pyramid.renderers import render
(continues on next page)
4.11. Unit testing 15 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0
(continued from previous page) # The view we want to test def some_view(request): return Response(render('mypkg:templates/home.pt',{'var':'testing'})) class TestViews(unittest.TestCase): def setUp(self): self.config= testing.setUp() self.config.include('pyramid_chameleon')
def tearDown(self): testing.tearDown()
def test_some_view(self): from pyramid.testing import DummyRequest request= DummyRequest() response= some_view(request) # templates/home.pt starts with the standard tag for HTML5 self.assertTrue(' 4.12 Precompiling When first rendered, a Chameleon template is "compiled" to Python and then the resulting code is executed. The compiled Python code may then be stored to disk in a cache directory set in the CHAMELEON_CACHE environment variable. However compilation is relatively slow compared with execution, so the first time a view is rendered may be very slow. To work around this first request latency we offer a command line script to pre-compile templates to python. This is executed as follows: $ CHAMELEON_CACHE=/path/to/put/precompiled/templates \ pyramid-chameleon-precompile --dir /path/to/look/for/templates To further speed up the precompilation, use the --jobs $ time CHAMELEON_CACHE=~/tmp_chameleoncache pyramid-chameleon-precompile --dir ~/ ˓→template_files --jobs1 INFO:root:Compiled 318 out of 318 found templates CHAMELEON_CACHE=~/tmp_chameleoncache pyramid-chameleon-precompile --dir1 63.78s ˓→user1.04s system 92% cpu1:09.71 total $ rm -rf ~/tmp_chameleoncache/* $ time CHAMELEON_CACHE=~/tmp_chameleoncache pyramid-chameleon-precompile --dir ~/ ˓→template_files --jobs2 INFO:root:Compiled 318 out of 318 found templates CHAMELEON_CACHE=~/tmp_chameleoncache pyramid-chameleon-precompile --dir2 78.24s ˓→user1.07s system 172% cpu 45.959 total 16 Chapter 4. Using Chameleon templates CHAPTER 5 More information 5.1 Glossary Babel A collection of tools for internationalizing Python applications. Pyramid does not depend on Babel to operate, but if Babel is installed, additional locale functionality becomes available to your application. Chameleon Chameleon is an open-source template engine written in Python. Genshi An XML templating language by Christopher Lenz. Mako Mako is a template language which refines the familiar ideas of componentized layout and inheritance using Python with Python scoping and calling semantics. Response An object returned by a view callable that represents response data returned to the requesting user agent. It must implement the pyramid.interfaces.IResponse interface. A response object is typically an in- stance of the pyramid.response.Response class or a subclass such as pyramid.httpexceptions. HTTPFound. See Request and Response Objects for information about response objects. ZPT ZPT is the Zope Page Template templating language. 5.2 pyramid_chameleon API pyramid_chameleon.includeme(config) Adds renderers for .pt and .txt as well as registers Chameleon localization features. interface pyramid_chameleon.interfaces.IChameleonLookup interface pyramid_chameleon.interfaces.IChameleonTranslate Internal interface representing a chameleon translate function 17 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0 18 Chapter 5. More information CHAPTER 6 Reporting bugs / development versions Visit https://github.com/Pylons/pyramid_chameleon to download development or tagged versions. Visit https://github.com/Pylons/pyramid_chameleon/issues to report bugs. 6.1 Indices and tables • Glossary • genindex • modindex • search 19 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0 20 Chapter 6. Reporting bugs / development versions Python Module Index p pyramid_chameleon, 17 pyramid_chameleon.interfaces, 17 pyramid_chameleon.renderer, 17 21 pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛, 푅푒푙푒푎푠푒0.4.푑푒푣0 22 Python Module Index Index A template internationalization, 14 automatic reloading of templates, 13 template renderer side effects, 12 templates B debugging, 12 Babel, 17 U C Using a master page, 10 Chameleon, 17 Z Chameleon text templates, 11 Chameleon ZPT macros,9 ZPT, 17 ZPT macros,9 D ZPT template (sample),8 debugging templates, 12 G Genshi, 17 I IChameleonLookup (interface in pyra- mid_chameleon.interfaces), 17 IChameleonTranslate (interface in pyra- mid_chameleon.interfaces), 17 includeme() (in module pyramid_chameleon), 17 internationalization (of templates), 14 M Mako, 17 P pyramid_chameleon (module), 17 pyramid_chameleon.interfaces (module), 17 pyramid_chameleon.renderer (module), 17 R Response, 17 T template automatic reload, 13 23