diff options
| author | Mike Bayer <mike_mp@zzzcomputing.com> | 2010-11-12 18:13:07 -0500 |
|---|---|---|
| committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2010-11-12 18:13:07 -0500 |
| commit | 24945d54a03466d679207df763157b8512911220 (patch) | |
| tree | 97186478277604e581ec48b652d0bcdbd44f195a | |
| parent | e870d34764e6613eccfb98c83ea28c621bfe0e51 (diff) | |
| download | mako-24945d54a03466d679207df763157b8512911220.tar.gz | |
-remove old content
| -rw-r--r-- | doc/build/content/caching.txt | 64 | ||||
| -rw-r--r-- | doc/build/content/defs.txt | 301 | ||||
| -rw-r--r-- | doc/build/content/documentation.html | 23 | ||||
| -rw-r--r-- | doc/build/content/filtering.txt | 199 | ||||
| -rw-r--r-- | doc/build/content/index.html | 6 | ||||
| -rw-r--r-- | doc/build/content/inheritance.txt | 214 | ||||
| -rw-r--r-- | doc/build/content/namespaces.txt | 195 | ||||
| -rw-r--r-- | doc/build/content/runtime.txt | 113 | ||||
| -rw-r--r-- | doc/build/content/syntax.txt | 231 | ||||
| -rw-r--r-- | doc/build/content/unicode.txt | 152 | ||||
| -rw-r--r-- | doc/build/content/usage.txt | 255 |
11 files changed, 0 insertions, 1753 deletions
diff --git a/doc/build/content/caching.txt b/doc/build/content/caching.txt deleted file mode 100644 index 7e0c0b3..0000000 --- a/doc/build/content/caching.txt +++ /dev/null @@ -1,64 +0,0 @@ -Caching -============== - -Any template or component can be cached using the `cache` argument to the `<%page>` or `<%def>` directives: - - <%page cached="True"/> - - template text - -The above template, after being executed the first time, will store its content within a cache that by default is scoped within memory. Subsequent calls to the template's `render()` method will return content directly from the cache. When the `Template` object itself falls out of scope, its corresponding cache is garbage collected along with the template. - -Caching requires that the `beaker` package be installed on the system. - -The caching flag and all its options can be used with the `<%def>` tag. - - <%def name="mycomp" cached="True" cache_timeout="30" cache_type="memory"> - other text - </%def> - - -### Cache arguments {@name=arguments} - -The various cache arguments are cascaded from their default values, to the arguments specified programmatically to the `Template` or its originating `TemplateLookup`, then to those defined in the `<%page>` tag of an individual template, and finally to an individual `<%def>` tag within the template. This means you can define, for example, a cache type of `dbm` on your `TemplateLookup`, a cache timeout of 60 seconds in a particular template's `<%page>` tag, and within one of that template's `<%def>` tags `cache=True`, and that one particular def will then cache its data using a `dbm` cache and a data timeout of 60 seconds. - -The options available are: - -* cached="False|True" - turn caching on -* cache_timeout - number of seconds in which to invalidate the cached data. after this timeout, the content is re-generated on the next call. -* cache_type - type of caching. `memory`, `file`, `dbm`, or `memcached`. -* cache_url - (only used for `memcached` but required) a single IP address or a semi-colon separated list of IP address of memcache servers to use. -* cache_dir - In the case of the `file` and `dbm` cache types, this is the filesystem directory with which to store data files. If this option is not present, the value of `module_directory` is used (i.e. the directory where compiled template modules are stored). If neither option is available an exception is thrown. -In the case of the `memcached` type, this attribute is required and it's used to store the lock files. -* cache_key - the "key" used to uniquely identify this content in the cache. the total namespace of keys within the cache is local to the current template, and the default value of "key" is the name of the def which is storing its data. It is an evaluable tag, so you can put a Python expression to calculate the value of the key on the fly. For example, heres a page that caches any page which inherits from it, based on the filename of the calling template: - - <%page cached="True" cache_key="${self.filename}"/> - - ${next.body()} - - ## rest of template - -### Accessing the Cache {@name=accessing} - -The `Template`, as well as any template-derived namespace, has an accessor called `cache` which returns the `Cache` object for that template. This object is a facade on top of the Beaker internal cache object, and provides some very rudimental capabilities, such as the ability to get and put arbitrary values: - - <% - local.cache.put("somekey", type="memory", "somevalue") - %> - -Above, the cache associated with the `local` namespace is accessed and a key is placed within a memory cache. - -More commonly the `cache` object is used to invalidate cached sections programmatically: - - {python} - template = lookup.get_template('/sometemplate.html') - - # invalidate the "body" of the template - template.cache.invalidate_body() - - # invalidate an individual def - template.cache.invalidate_def('somedef') - - # invalidate an arbitrary key - template.cache.invalidate('somekey') -
\ No newline at end of file diff --git a/doc/build/content/defs.txt b/doc/build/content/defs.txt deleted file mode 100644 index 932597b..0000000 --- a/doc/build/content/defs.txt +++ /dev/null @@ -1,301 +0,0 @@ -Defs -============= - -The def is the single tag used to demarcate any block of text and/or code. It exists within generated Python as a callable function. - - <%def name="hello()"> - hello world - </%def> - -They are normally called as expressions. - - the def: ${hello()} - -If the `<%def>` is not nested inside of another `<%def>`, its known as a **top level def** and can be accessed anywhere in the template, including above where it was defined. - -All defs, top level or not, have access to the current contextual namespace in exactly the same way their containing template does. Suppose the template below is executed with the variables `username` and `accountdata` inside the context: - - Hello there ${username}, how are ya. Lets see what your account says: - - ${account()} - - <%def name="account()"> - Account for ${username}:<br/> - - % for row in accountdata: - Value: ${row}<br/> - % endfor - </%def> - -The `username` and `accountdata` variables are present within the main template body as well as the body of the `account()` def. - -Since defs are just Python functions, you can define and pass arguments to them as well: - - ${account(accountname='john')} - - <%def name="account(accountname, type='regular')"> - account name: ${accountname}, type ${type} - </%def> - -When you declare an argument signature for your def, they are required to follow normal Python conventions (i.e., all arguments are required except keyword arguments with a default value). This is in contrast to using context-level variables, which evaluate to `UNDEFINED` if you reference a name that does not exist. - -### Calling defs from Other Files {@name=remotedefs} - -Top level `<%defs>` are **exported** by your template's module, and can be called from the outside; including from other templates, as well as normal Python code. Calling a `<%def>` from another template is something like using an `<%include>` - except you are calling a specific function within the template, not the whole template. - -The remote `<%def>` call is also a little bit like calling functions from other modules in Python. There is an "import" step to pull the names from another template into your own template; then the function or functions are available. - -To import another template, use the `<%namespace>` tag: - - <%namespace name="mystuff" file="mystuff.html"/> - -The above tag adds a local variable "mystuff" to the current scope. - -Then, just call the defs off of `mystuff`: - - ${mystuff.somedef(x=5,y=7)} - -The `<%namespace>` tag also supports some of the other semantics of Python's `import` statement, including pulling names into the local variable space, or using `*` to represent all names, using the `import` attribute: - - <%namespace file="mystuff.html" import="foo, bar"/> - -This is just a quick intro to the concept of a **namespace**, which is a central Mako concept that has its own chapter in these docs. For more detail and examples, see [namespaces](rel:namespaces). - -### Calling defs programmatically {@name=programmatic} - -You can call def's programmatically from any `Template` object using the `get_def()` method, which returns a `DefTemplate` object. This is a `Template` subclass which the parent `Template` creates, and is usable like any other template: - - {python} - from mako.template import Template - - template = Template(""" - <%def name="hi(name)"> - hi ${name}! - </%def> - - <%def name="bye(name)"> - bye ${name}! - </%def> - """) - - print template.get_def("hi").render(name="ed") - print template.get_def("bye").render(name="ed") - - -### Defs within Defs {@name=nesteddefs} - -The def model follows regular Python rules for closures. Declaring `<%def>` inside another `<%def>` declares it within the parent's **enclosing scope**: - - <%def name="mydef()"> - <%def name="subdef()"> - a sub def - </%def> - - im the def, and the subcomopnent is ${subdef()} - </%def> - -Just like Python, names that exist outside the inner `<%def>` exist inside it as well: - - <% - x = 12 - %> - <%def name="outer()"> - <% - y = 15 - %> - <%def name="inner()"> - inner, x is ${x}, y is ${y} - </%def> - - outer, x is ${x}, y is ${y} - </%def> - -Assigning to a name inside of a def declares that name as local to the scope of that def (again, like Python itself). This means the following code will raise an error: - - <% - x = 10 - %> - <%def name="somedef()"> - ## error ! - somedef, x is ${x} - <% - x = 27 - %> - </%def> - -...because the assignment to `x` declares x as local to the scope of `somedef`, rendering the "outer" version unreachable in the expression that tries to render it. - -### Calling a def with embedded content and/or other defs {@name=defswithcontent} - -A flip-side to def within def is a def call with content. This is where you call a def, and at the same time declare a block of content (or multiple blocks) that can be used by the def being called. The main point of such a call is to create custom, nestable tags, just like any other template language's custom-tag creation system - where the external tag controls the execution of the nested tags and can communicate state to them. Only with Mako, you don't have to use any external Python modules, you can define arbitrarily nestable tags right in your templates. - -To achieve this, the target def is invoked using the form `<%namepacename:defname>` instead of the normal `${}` syntax. This syntax, introduced in Mako 0.2.3, is functionally equivalent another tag known as `call`, which takes the form `<%call expr='namespacename.defname(args)'>`. While `%call` is available in all versions of Mako, the newer style is probably more familiar looking. The `namespace` portion of the call is the name of the **namespace** in which the def is defined - in the most simple cases, this can be `local` or `self` to reference the current template's namespace (the difference between `local` and `self` is one of inheritance - see [namespaces_builtin](rel:namespaces_builtin) for details). - -When the target def is invoked, a variable `caller` is placed in its context which contains another namespace containing the body and other defs defined by the caller. The body itself is referenced by the method `body()`. Below, we build a `%def` that operates upon `caller.body()` to invoke the body of the custom tag: - - <%def name="buildtable()"> - <table> - <tr><td> - ${caller.body()} - </td></tr> - </table> - </%def> - - <%self:buildtable> - I am the table body. - </%self:buildtable> - -This produces the output (whitespace formatted): - - {html} - <table> - <tr><td> - I am the table body. - </td></tr> - </table> - -Using the older `%call` syntax looks like: - - <%def name="buildtable()"> - <table> - <tr><td> - ${caller.body()} - </td></tr> - </table> - </%def> - - <%call expr="buildtable()"> - I am the table body. - </%call> - -The `body()` can be executed multiple times or not at all. This means you can use def-call-with-content to build iterators, conditionals, etc: - - <%def name="lister(count)"> - % for x in range(count): - ${caller.body()} - % endfor - </%def> - - <%self:lister count="${3}"> - hi - </%self:lister> - -Produces: - - {html} - hi - hi - hi - -Notice above we pass `3` as a Python expression, so that it remains as an integer. - -A custom "conditional" tag: - - <%def name="conditional(expression)"> - % if expression: - ${caller.body()} - % endif - </%def> - - <%self:conditional expression="${4==4}"> - im the result - </%self:conditional> - -Produces: - - {html} - im the result - -But that's not all. The `body()` function also can handle arguments, which will augment the local namespace of the body callable. The caller must define the arguments which it expects to receive from its target def using the `args` attribute, which is a comma-separated list of argument names. Below, our `<%def>` calls the `body()` of its caller, passing in an element of data from its argument: - - <%def name="layoutdata(somedata)"> - <table> - % for item in somedata: - <tr> - % for col in item: - <td>${caller.body(col=col)}</td> - % endfor - </tr> - % endfor - </table> - </%def> - - <%self:layoutdata somedata="${[[1,2,3],[4,5,6],[7,8,9]]}" args="col">\ - Body data: ${col}\ - </%self:layoutdata> - -Produces: - - {html} - <table> - <tr> - <td>Body data: 1</td> - <td>Body data: 2</td> - <td>Body data: 3</td> - </tr> - <tr> - <td>Body data: 4</td> - <td>Body data: 5</td> - <td>Body data: 6</td> - </tr> - <tr> - <td>Body data: 7</td> - <td>Body data: 8</td> - <td>Body data: 9</td> - </tr> - </table> - -You don't have to stick to calling just the `body()` function. The caller can define any number of callables, allowing the `<%call>` tag to produce whole layouts: - - <%def name="layout()"> - ## a layout def - <div class="mainlayout"> - <div class="header"> - ${caller.header()} - </div> - <div class="sidebar"> - ${caller.sidebar()} - </div> - <div class="content"> - ${caller.body()} - </div> - </div> - </%def> - - ## calls the layout def - <%self:layout> - <%def name="header()"> - I am the header - </%def> - <%def name="sidebar()"> - <ul> - <li>sidebar 1</li> - <li>sidebar 2</li> - </ul> - </%def> - - this is the body - </%self:layout> - -The above layout would produce: - - <div class="mainlayout"> - <div class="header"> - I am the header - </div> - - <div class="sidebar"> - <ul> - <li>sidebar 1</li> - <li>sidebar 2</li> - </ul> - </div> - - <div class="content"> - this is the body - </div> - </div> - -The number of things you can do with `<%call>` and/or the `<%namespacename:defname>` calling syntax is enormous. You can create form widget libraries, such as an enclosing `<FORM>` tag and nested HTML input elements, or portable wrapping schemes using `<div>` or other elements. You can create tags that interpret rows of data, such as from a database, providing the individual columns of each row to a `body()` callable which lays out the row any way it wants. Basically anything you'd do with a "custom tag" or tag library in some other system, Mako provides via `<%def>`s and plain Python callables which are invoked via `<%namespacename:defname>` or `<%call>`. - - diff --git a/doc/build/content/documentation.html b/doc/build/content/documentation.html deleted file mode 100644 index 26403dc..0000000 --- a/doc/build/content/documentation.html +++ /dev/null @@ -1,23 +0,0 @@ -<%inherit file="base.html"/> -<%namespace name="tocns" file="toc.html"/> -<%namespace name="nav" file="nav.html"/> -<%page args="toc, extension"/> - -${tocns.toc(toc, extension=extension, paged=False)} - -<%def name="title()"> - Mako Documentation -</%def> - -% for file in toc.filenames: - <% - item = toc.get_by_file(file) - %> - - <A name="${item.path}"></a> - - ${nav.pagenav(item=item, paged=False, extension=extension)} - - ${self.get_namespace(file + '.html').body(toc=toc, extension=extension, paged=False)} -% endfor - diff --git a/doc/build/content/filtering.txt b/doc/build/content/filtering.txt deleted file mode 100644 index 829be0e..0000000 --- a/doc/build/content/filtering.txt +++ /dev/null @@ -1,199 +0,0 @@ -Filtering and Buffering {@name=filtering} -================================= - -### Expression Filtering - -As described in the Syntax chapter, the "`|`" operator can be applied to a "`${}`" expression to apply escape filters to the output: - - ${"this is some text" | u} - -The above expression applies URL escaping to the expression, and produces `this+is+some+text`. - -The built-in escape flags are: - -* `u` : URL escaping, provided by `urllib.quote_plus(string.encode('utf-8'))` -* `h` : HTML escaping, provided by `markupsafe.escape(string)` (new as of 0.3.4 - prior versions use `cgi.escape(string, True)`) -* `x` : XML escaping -* `trim` : whitespace trimming, provided by `string.strip()` -* `entity` : produces HTML entity references for applicable strings, derived from `htmlentitydefs` -* `unicode` (`str` on Python 3): produces a Python unicode string (this function is applied by default). -* `decode.<some encoding>` : decode input into a Python unicode with the specified encoding -* `n` : disable all default filtering; only filters specified in the local expression tag will be applied. - -To apply more than one filter, separate them by a comma: - - ${" <tag>some value</tag> " | h,trim} - -The above produces `<tag>some value</tag>`, with no leading or trailing whitespace. The HTML escaping function is applied first, the "trim" function second. - -Naturally, you can make your own filters too. A filter is just a Python function that accepts a single string argument, and returns the filtered result. The expressions after the `|` operator draw upon the local namespace of the template in which they appear, meaning you can define escaping functions locally: - - <%! - def myescape(text): - return "<TAG>" + text + "</TAG>" - %> - - Heres some tagged text: ${"text" | myescape} - -Or from any Python module: - - <%! - import myfilters - %> - - Heres some tagged text: ${"text" | myfilters.tagfilter} - -A page can apply a default set of filters to all expression tags using the `expression_filter` argument to the `%page` tag: - - <%page expression_filter="h"/> - - Escaped text: ${"<html>some html</html>"} - -Result: - - Escaped text: <html>some html</html> - -#### The default_filters Argument {@name=defaultfilters} - -In addition to the `expression_filter` argument, the `default_filters` argument to both `Template` and `TemplateLookup` can specify filtering for all expression tags at the programmatic level. This array-based argument, when given its default argument of `None`, will be internally set to `["unicode"]` (or `["str"]` on Python 3), except when `disable_unicode=True` is set in which case it defaults to `["str"]`: - - {python} - t = TemplateLookup(directories=['/tmp'], default_filters=['unicode']) - -To replace the usual `unicode`/`str` function with a specific encoding, the `decode` filter can be substituted: - - {python} - t = TemplateLookup(directories=['/tmp'], default_filters=['decode.utf8']) - -To disable `default_filters` entirely, set it to an empty list: - - {python} - t = TemplateLookup(directories=['/tmp'], default_filters=[]) - -Any string name can be added to `default_filters` where it will be added to all expressions as a filter. The filters are applied from left to right, meaning the leftmost filter is applied first. - - {python} - t = Template(templatetext, default_filters=['unicode', 'myfilter']) - -To ease the usage of `default_filters` with custom filters, you can also add imports (or other code) to all templates using the `imports` argument: - - {python} - t = TemplateLookup(directories=['/tmp'], - default_filters=['unicode', 'myfilter'], - imports=['from mypackage import myfilter']) - -The above will generate templates something like this: - - {python} - # .... - from mypackage import myfilter - - def render_body(context): - context.write(myfilter(unicode("some text"))) - -#### Turning off Filtering with the "n" filter - -In all cases the special `n` filter, used locally within an expression, will **disable** all filters declared in the `<%page>` tag as well `default_filters`. Such as: - - ${'myexpression' | n} - -Will render `myexpression` with no filtering of any kind, and - - ${'myexpression' | n, trim} - -will render `myexpression` using the `trim` filter only. - -### Filtering Defs - -The `%def` tag has a filter argument which will apply the given list of filter functions to the output of the `%def`: - - <%def name="foo()" filter="h, trim"> - <b>this is bold</b> - </%def> - -When the filter attribute is applied to a def as above, the def is automatically **buffered** as well. This is described next. - -### Buffering - -One of Mako's central design goals is speed. To this end, all of the textual content within a template and its various callables is by default piped directly to the single buffer that is stored within the `Context` object. While this normally is easy to miss, it has certain side effects. The main one is that when you call a def using the normal expression syntax, i.e. `${somedef()}`, it may appear that the return value of the function is the content it produced, which is then delivered to your template just like any other expression substitution, except that normally, this is not the case; the return value of `${somedef()}` is simply the empty string `''`. By the time you receive this empty string, the output of `somedef()` has been sent to the underlying buffer. - -You may not want this effect, if for example you are doing something like this: - - ${" results " + somedef() + " more results "} - -If the `somedef()` function produced the content "`somedef's results`", the above template would produce this output: - - somedef's results results more results - -This is because `somedef()` fully executes before the expression returns the results of its concatenation; the concatenation in turn receives just the empty string as its middle expression. - -Mako provides two ways to work around this. One is by applying buffering to the `%def` itself: - - <%def name="somedef()" buffered="True"> - somedef's results - </%def> - -The above definition will generate code similar to this: - - def somedef(): - context.push_buffer() - try: - context.write("somedef's results") - finally: - buf = context.pop_buffer() - return buf.getvalue() - -So that the content of `somedef()` is sent to a second buffer, which is then popped off the stack and its value returned. The speed hit inherent in buffering the output of a def is also apparent. - -Note that the `filter` argument on %def also causes the def to be buffered. This is so that the final content of the %def can be delivered to the escaping function in one batch, which reduces method calls and also produces more deterministic behavior for the filtering function itself, which can possibly be useful for a filtering function that wishes to apply a transformation to the text as a whole. - -The other way to buffer the output of a def or any Mako callable is by using the built-in `capture` function. This function performs an operation similar to the above buffering operation except it is specified by the caller. - - ${" results " + capture(somedef) + " more results "} - -Note that the first argument to the `capture` function is **the function itself**, not the result of calling it. This is because the `capture` function takes over the job of actually calling the target function, after setting up a buffered environment. To send arguments to the function, just send them to `capture` instead: - - ${capture(somedef, 17, 'hi', use_paging=True)} - -The above call is equivalent to the unbuffered call: - - ${somedef(17, 'hi', use_paging=True)} - -### Decorating - -This is a feature that's new as of version 0.2.5. Somewhat like a filter for a %def but more flexible, the `decorator` argument to `%def` allows the creation of a function that will work in a similar manner to a Python decorator. The function can control whether or not the function executes. The original intent of this function is to allow the creation of custom cache logic, but there may be other uses as well. - -`decorator` is intended to be used with a regular Python function, such as one defined in a library module. Here we'll illustrate the python function defined in the template for simplicities' sake: - - <%! - def bar(fn): - def decorate(context, *args, **kw): - context.write("BAR") - fn(*args, **kw) - context.write("BAR") - return '' - return decorate - %> - - <%def name="foo()" decorator="bar"> - this is foo - </%def> - - ${foo()} - -The above template will return, with more whitespace than this, `"BAR this is foo BAR"`. The function is the render callable itself (or possibly a wrapper around it), and by default will write to the context. To capture its output, use the `capture` callable in the `mako.runtime` module (available in templates as just `runtime`): - - <%! - def bar(fn): - def decorate(context, *args, **kw): - return "BAR" + runtime.capture(context, fn, *args, **kw) + "BAR" - return decorate - %> - - <%def name="foo()" decorator="bar"> - this is foo - </%def> - - ${foo()} - -The decorator can be used with top-level defs as well as nested defs. Note that when calling a top-level def from the `Template` api, i.e. `template.get_def('somedef').render()`, the decorator has to write the output to the `context`, i.e. as in the first example. The return value gets discarded.
\ No newline at end of file diff --git a/doc/build/content/index.html b/doc/build/content/index.html deleted file mode 100644 index e4f3518..0000000 --- a/doc/build/content/index.html +++ /dev/null @@ -1,6 +0,0 @@ -<%inherit file="base.html"/> -<%page args="toc, extension"/> - -<%namespace name="tocns" file="toc.html"/> - -${tocns.toc(toc, paged=True, extension=extension)} diff --git a/doc/build/content/inheritance.txt b/doc/build/content/inheritance.txt deleted file mode 100644 index ce73484..0000000 --- a/doc/build/content/inheritance.txt +++ /dev/null @@ -1,214 +0,0 @@ -Inheritance -=================== - -Using template inheritance, two or more templates can organize themselves into an **inheritance chain**, where content and functions from all involved templates can be intermixed. The general paradigm of template inheritance is this: if a template `A` inherits from template `B`, then template `A` agrees to send the executional control to template `B` at runtime (`A` is called the **inheriting** template). Template `B`, the **inherited** template, then makes decisions as to what resources from `A` shall be executed. - -In practice, it looks like this. Heres a hypothetical inheriting template, `index.html`: - - ## index.html - <%inherit file="base.html"/> - - <%def name="header()"> - this is some header content - </%def> - - this is the body content. - -And `base.html`, the inherited template: - - ## base.html - <html> - <body> - <div class="header"> - ${self.header()} - </div> - - ${self.body()} - - <div class="footer"> - ${self.footer()} - </div> - </body> - </html> - - <%def name="footer()"> - this is the footer - </%def> - -Here is a breakdown of the execution: - -* When `index.html` is rendered, control immediately passes to `base.html`. -* `base.html` then renders the top part of an HTML document, then calls the method `header()` off of a built in namespace called `self` (this namespace was first introduced in the Namespaces chapter in [namespaces_builtin_self](rel:namespaces_builtin_self)). Since `index.html` is the topmost template and also defines a def called `header()`, its this `header()` def that gets executed. -* Control comes back to `base.html`. Some more HTML is rendered. -* `base.html` executes `self.body()`. The `body()` function on all template-based namespaces refers to the main body of the template, therefore the main body of `index.html` is rendered. -* Control comes back to `base.html`. More HTML is rendered, then the `self.footer()` expression is invoked. -* The `footer` def is only defined in `base.html`, so being the topmost definition of `footer`, its the one that executes. If `index.html` also specified `footer`, then its version would **override** that of the base. -* `base.html` finishes up rendering its HTML and the template is complete, producing: - - <html> - <body> - <div class="header"> - this is some header content - </div> - - this is the body content. - - <div class="footer"> - this is the footer - </div> - </body> - </html> - -...and that is template inheritance in a nutshell. The main idea is that the methods that you call upon `self` always correspond to the topmost definition of that method. Very much the way `self` works in a Python class, even though Mako is not actually using Python class inheritance to implement this functionality. (Mako doesn't take the "inheritance" metaphor too seriously; while useful to setup some commonly recognized semantics, a textual template is not very much like an object-oriented class construct in practice). - -### Using the "next" namespace to produce content wrapping {@name=next} - -Sometimes you have an inheritance chain that spans more than two templates. Or maybe you don't, but youd like to build your system such that extra inherited templates can be inserted in the middle of a chain where they would be smoothly integrated. If each template wants to define its layout just within its main body, you can't just call `self.body()` to get at the inheriting template's body, since that is only the topmost body. To get at the body of the *next* template, you call upon the namespace `next`, which is the namespace of the template **immediately following** the current template. - -Lets change the line in `base.html` which calls upon `self.body()` to instead call upon `next.body()`: - - ## base.html - <html> - <body> - <div class="header"> - ${self.header()} - </div> - - ${next.body()} - - <div class="footer"> - ${self.footer()} - </div> - </body> - </html> - - <%def name="footer()"> - this is the footer - </%def> - -Lets also add an intermediate template called `layout.html`, which inherits from `base.html`: - - ## layout.html - <%inherit file="base.html"/> - <ul> - ${self.toolbar()} - </ul> - <div class="mainlayout"> - ${next.body()} - </div> - - <%def name="toolbar()"> - <li>selection 1</li> - <li>selection 2</li> - <li>selection 3</li> - </%def> - -And finally change `index.html` to inherit from `layout.html` instead: - - ## index.html - <%inherit file="layout.html"/> - - ## .. rest of template - -In this setup, each call to `next.body()` will render the body of the next template in the inheritance chain (which can be written as `base.html -> layout.html -> index.html`). Control is still first passed to the bottommost template `base.html`, and `self` still references the topmost definition of any particular def. - -The output we get would be: - - <html> - <body> - <div class="header"> - this is some header content - </div> - - <ul> - <li>selection 1</li> - <li>selection 2</li> - <li>selection 3</li> - </ul> - - <div class="mainlayout"> - this is the body content. - </div> - - <div class="footer"> - this is the footer - </div> - </body> - </html> - -So above, we have the `<html>`, `<body>` and `header`/`footer` layout of `base.html`, we have the `<ul>` and `mainlayout` section of `layout.html`, and the main body of `index.html` as well as its overridden `header` def. The `layout.html` template is inserted into the middle of the chain without `base.html` having to change anything. Without the `next` namespace, only the main body of `index.html` could be used; there would be no way to call `layout.html`'s body content. - -### Using the "parent" namespace to augment defs {@name=parent} - -Lets now look at the other inheritance-specific namespace, the opposite of `next` called `parent`. `parent` is the namespace of the template **immediately preceding** the current template. What is most useful about this namespace is the methods within it which can be accessed within overridden versions of those methods. This is not as hard as it sounds and is very much like using the `super` keyword in Python. Lets modify `index.html` to augment the list of selections provided by the `toolbar` function in `layout.html`: - - ## index.html - <%inherit file="layout.html"/> - - <%def name="header()"> - this is some header content - </%def> - - <%def name="toolbar()"> - ## call the parent's toolbar first - ${parent.toolbar()} - <li>selection 4</li> - <li>selection 5</li> - </%def> - - this is the body content. - -Above, we implemented a `toolbar()` function, which is meant to override the definition of `toolbar` within the inherited template `layout.html`. However, since we want the content from that of `layout.html` as well, we call it via the `parent` namespace whenever we want it's content, in this case before we add our own selections. So the output for the whole thing is now: - - <html> - <body> - <div class="header"> - this is some header content - </div> - - <ul> - <li>selection 1</li> - <li>selection 2</li> - <li>selection 3</li> - <li>selection 4</li> - <li>selection 5</li> - </ul> - - <div class="mainlayout"> - this is the body content. - </div> - - <div class="footer"> - this is the footer - </div> - </body> - </html> - -and you're now a template inheritance ninja ! - -### Inheritable Attributes - -The `attr` accessor of the `Namespace` object allows access to module level variables declared in a template. By accessing `self.attr`, you can access regular attributes from the inheritance chain as declared in `<%! %>` sections. Such as: - - <%! - class_ = "grey" - %> - - <div class="${self.attr.class_}"> - ${self.body()} - </div> - -If a an inheriting template overrides `class_` to be `white`, as in: - - <%! - class_ = "white" - %> - <%inherit file="parent.html"/> - - This is the body - -You'll get output like: - - <div class="white"> - This is the body - </div>
\ No newline at end of file diff --git a/doc/build/content/namespaces.txt b/doc/build/content/namespaces.txt deleted file mode 100644 index f691e31..0000000 --- a/doc/build/content/namespaces.txt +++ /dev/null @@ -1,195 +0,0 @@ -Namespaces -============= - -Namespaces are used to organize groups of components into categories, and also to "import" components from other files. - -If the file `components.html` defines these two components: - - ## components.html - <%def name="comp1()"> - this is comp1 - </%def> - - <%def name="comp2(x)"> - this is comp2, x is ${x} - </%def> - -You can make another file, for example `index.html`, that pulls those two components into a namespace called `comp`: - - ## index.html - <%namespace name="comp" file="components.html"/> - - Heres comp1: ${comp.comp1()} - Heres comp2: ${comp.comp2(x=5)} - -The `comp` variable above is an instance of `mako.runtime.Namespace`, a **proxy object** which delivers method calls to the underlying template callable using the current context. - -`<%namespace>` also provides an `import` attribute which can be used to pull the names into the local namespace, removing the need to call it via the ".". When `import` is used, the `name` attribute is optional. - - <%namespace file="components.html" import="comp1, comp2"/> - - Heres comp1: ${comp1()} - Heres comp2: ${comp2(x=5)} - -`import` also supports the "*" operator: - - <%namespace file="components.html" import="*"/> - - Heres comp1: ${comp1()} - Heres comp2: ${comp2(x=5)} - -The names imported by the `import` attribute take precedence over any names that exist within the current context. - -**Note** - in current versions of Mako, usage of "import='*'" is known to decrease performance of the template. This will be fixed in a future release. - -The `file` argument allows expressions - if looking for context variables, the `context` must be named explicitly: - - <%namespace name="dyn" file="${context['namespace_name']}"/> - -### Ways to Call Namespaces {@name=howtocall} - -There are essentially four ways to call a function from a namespace. - -The "expression" format, as described previously. Namespaces are just Python objects with functions on them, and can -be used in expressions like any other function: - - ${mynamespace.somefunction('some arg1', 'some arg2', arg3='some arg3', arg4='some arg4')} - -Synonymous with the "expression" format is the "custom tag" format, when a "closed" tag is used. This format, introduced in Mako 0.2.3, allows the usage of a "custom" Mako tag, with the function arguments passed in using named attributes: - - <%mynamespace:somefunction arg1="some arg1" arg2="some arg2" arg3="some arg3" arg4="some arg4"/> - -When using tags, the values of the arguments are taken as literal strings by default. To embed Python expressions as arguments, use the embedded expression format: - - <%mynamespace:somefunction arg1="${someobject.format()}" arg2="${somedef(5, 12)}"/> - -The "custom tag" format is intended mainly for namespace functions which recognize body content, which in Mako is known as a "def with embedded content": - - <%mynamespace:somefunction arg1="some argument" args="x, y"> - Some record: ${x}, ${y} - </%mynamespace:somefunction> - -The "classic" way to call defs with embedded content is the `<%call>` tag: - - <%call expr="mynamespace.somefunction(arg1='some argument')" args="x, y"> - Some record: ${x}, ${y} - </%call> - -For information on how to construct defs that embed content from the caller, see [defs_defswithcontent](rel:defs_defswithcontent). - -### Namespaces from Regular Python Modules {@name=frommodules} - -Namespaces can also import regular Python functions from modules. These callables need to take at least one argument, `context`: - -A module file `some/module.py` might contain the callable: - - {python} - def my_tag(context): - context.write("hello world") - return '' - -A template can use this module via: - - <%namespace name="hw" module="some.module"/> - - ${hw.my_tag()} - -Note that the `context` argument is not needed in the call; the `namespace` tag creates a locally-scoped callable which takes care of it. The `return ''` is so that the def does not dump a `None` into the output stream - the return value of any def is rendered after the def completes, in addition to whatever was passed to `context.write()` within its body. - -If your def is to be called in an "embedded content" context, that is as described in [defs_defswithcontent](rel:defs_defswithcontent), you should use the `@supports_caller` decorator, which will ensure that Mako will ensure the correct "caller" variable is available when your def is called, supporting embedded content: - - {python} - from mako.runtime import supports_caller - - @supports_caller - def my_tag(context): - context.write("<div>") - context['caller'].body() - context.write("</div>") - return '' - -Capturing of output is available as well, using the outside-of-templates version of the `capture()` function, which accepts the "context" as its first argument: - - {python} - from mako.runtime import supports_caller, capture - - @supports_caller - def my_tag(context): - return "<div>%s</div>" % \ - capture(context, context['caller'].body, x="foo", y="bar") - -### Declaring defs in namespaces. - -The `<%namespace>` tag supports the definition of `<%defs>` directly inside the tag. These defs become part of the namespace like any other function, and will override the definitions pulled in from a remote template or module: - - ## define a namespace - <%namespace name="stuff"> - <%def name="comp1()"> - comp1 - </%def> - </%namespace> - - ## then call it - ${stuff.comp1()} - -### The "body()" method {@name=body} - -Every namespace that is generated from a template contains a method called `body()`. This method corresponds to the main body of the template, and plays its most important roles when using inheritance relationships as well as def-calls-with-content. - -Since the `body()` method is available from a namespace just like all the other defs defined in a template, what happens if you send arguments to it ? By default, the `body()` method accepts no positional arguments, and for usefulness in inheritance scenarios will by default dump all keyword arguments into a dictionary called `pageargs`. But if you actually want to get at the keyword arguments, Mako recommends you define your own argument signature explicitly. You do this via using the `<%page>` tag: - - <%page args="x, y, someval=8, scope='foo', **kwargs"/> - -A template which defines the above signature requires that the variables `x` and `y` are defined, defines default values for `someval` and `scope`, and sets up `**kwargs` to receive all other keyword arguments. If `**kwargs` or similar is not present, the argument `**pageargs` gets tacked on by Mako. When the template is called as a top-level template (i.e. via `template.render()`) or via the `<%include>` tag, the values for these arguments will be pulled from the `Context`. In all other cases, i.e. via calling the `body()` method, the arguments are taken as ordinary arguments from the method call. So above, the body might be called as: - - ${self.body(5, y=10, someval=15, delta=7)} - -The `Context` object also supplies a `kwargs` accessor, for cases when youd like to pass along whatever is in the context to a `body()` callable: - - ${next.body(**context.kwargs)} - -The usefulness of calls like the above become more apparent when one works with inheriting templates. For more information on this, as well as the meanings of the names `self` and `next`, see [inheritance](rel:inheritance). - -### Namespace methods and properties {@name=properties} - -The `Namespace` class includes helpful accessors and methods: - -* `attr` - allows access module level attributes by name. This accessor allows templates to supply "scalar" attributes which are particularly handy in inheritance relationships. See the example in [inheritance](rel:inheritance). -* `module` - the Python module referenced by this Namespace. If the namespace references a `Template`, then this module is the equivalent of `template.module`, i.e. the generated module for the template. -* `filename` - the path of the filesystem file used for this Namespace's module or template. If this is a pure module-based Namespace, this evaluates to `module.__file__`. If a template-based namespace, it evaluates to the original template file location. -* `template` - the `Template` object referenced by this Namespace, if any. -* `uri` - the uri for this Namespace's template (i.e. whatever was sent to `lookup.get_template()`). This is the equivalent of `template.uri`. -* `context` - the `Context` object for this namespace. Namespaces are often created with copies of contexts that contain slightly different data, particularly in inheritance scenarios. Using the `Context` off of a `Namespace` one can traverse an entire chain of templates that inherit from one-another. -* `get_namespace(uri)` - this method returns a `Namespace` at the given `uri`. If the given uri is a relative uri (i.e. it does not contain ia leading slash `/`), the uri is adjusted to be relative to the uri **of the namespace itself**. This method is therefore mostly useful off of the built-in `local` namespace, described in the next section. In most cases, a template wouldn't need this function, and should instead use the `<%namespace>` tag to load namespaces. However, since all `<%namespace>` tags are evaulated before the body of the template ever runs, this method can be used to locate namespaces using expressions that were generated within the body code of the template, or to conditionally use a particular namespace. - -### Built-in Namespaces {@name=builtin} - -The namespace is so great that Mako gives your template one (or two) for free. The names of these namespaces are `local` and `self`. Other built-in namespaces include `parent` and `next`, which are optional and are described in [inheritance](rel:inheritance). - -#### local - -The `local` namespace is basically the namespace for the currently executing template. This means that all of the top level defs defined in your template, as well as your template's `body()` function, are also available off of the `local` namespace. - -The `local` namespace is also where properties like `uri`, `filename`, and `module` and the `get_namespace` method can be particularly useful. - -#### self - -The `self` namespace, in the case of a template that does not use inheritance, is synonomous with `local`. If inheritance is used, then `self` references the topmost template in the inheritance chain, where it is most useful for providing the ultimate form of various "method" calls which may have been overridden at various points in an inheritance chain. See [inheritance](rel:inheritance). - -### Inheritable Namespaces - -The `<%namespace>` tag includes an optional attribute `inheritable="True"`, which will cause the namespace to be attached to the `self` namespace. Since `self` is globally available throughout an inheritance chain (described in the next section), all the templates in an inheritance chain can get at the namespace imported in a super-template via `self`. - - ## base.html - <%namespace name="foo" file="foo.html" inheritable="True"/> - - ${next.body()} - - ## somefile.html - <%inherit file="base.html"/> - - ${self.foo.bar()} - -This allows a super-template to load a whole bunch of namespaces that its inheriting templates can get to, without them having to explicitly load those namespaces themselves. - -The `import="*"` part of the `<%namespace>` tag doesn't yet interact with the `inheritable` flag, so currently you have to use the explicit namespace name off of `self`, followed by the desired function name. But more on this in a future release. diff --git a/doc/build/content/runtime.txt b/doc/build/content/runtime.txt deleted file mode 100644 index 829b057..0000000 --- a/doc/build/content/runtime.txt +++ /dev/null @@ -1,113 +0,0 @@ -The Mako Runtime Environment {@name=runtime} -============================== - -This section describes a little bit about the objects and built-in functions that are available in templates. - -### Context {@name=context} - -The `Context` is the central object that is created when a template is first executed, and is responsible for handling all communication with the outside world. This includes two major components, one of which is the output buffer, which is a file-like object such as Python's `StringIO` or similar, and the other a dictionary of variables that can be freely referenced within a template; this dictionary is a combination of the arguments sent to the `template.render()` function and some built-in variables provided by Mako's runtime environment. - -#### The Buffer {@name=buffer} - -The buffer is stored within the `Context`, and writing to it is achieved by calling `context.write()`. You usually don't need to care about this as all text within a template, as well as all expressions provided by `${}`, automatically send everything to this method. The cases you might want to be aware of its existence are if you are dealing with various filtering/buffering scenarios, which are described in [filtering](rel:filtering), or if you want to programmatically send content to the output stream, such as within a `<% %>` block. - - <% - context.write("some programmatic text") - %> - -The actual buffer may or may not be the original buffer sent to the `Context` object, as various filtering/caching scenarios may "push" a new buffer onto the context's underlying buffer stack. For this reason, just stick with `context.write()` and content will always go to the topmost buffer. - -#### Context Variables {@name=variables} - -When your template is compiled into a Python module, the body -content is enclosed within a Python function called -`render_body`. Other top-level defs defined in the template are -defined within their own function bodies which are named after -the def's name with the prefix `render_` (i.e. `render_mydef`). -One of the first things that happens within these functions is -that all variable names that are referenced within the function -which are not defined in some other way (i.e. such as via -assignment, module level imports, etc.) are pulled from the -`Context` object's dictionary of variables. This is how you're -able to freely reference variable names in a template which -automatically correspond to what was passed into the current -`Context`. - -* **What happens if I reference a variable name that is not in - the current context?** - the value you get back is a special - value called `UNDEFINED`, or if the `strict_undefined=True` flag - is used a `NameError` is raised. `UNDEFINED` is just a simple global - variable with the class `mako.runtime.Undefined`. The - `UNDEFINED` object throws an error when you call `str()` on - it, which is what happens if you try to use it in an - expression. -* **UNDEFINED makes it hard for me to find what name is missing** - An alternative - introduced in version 0.3.6 is to specify the option - `strict_undefined=True` - to the `Template` or `TemplateLookup`. This will cause - any non-present variables to raise an immediate `NameError` - which includes the name of the variable in its message - when `render()` is called - `UNDEFINED` is not used. -* **Why not just return None?** Using `UNDEFINED`, or - raising a `NameError` is more - explicit and allows differentiation between a value of `None` - that was explicitly passed to the `Context` and a value that - wasn't present at all. -* **Why raise an exception when you call str() on it ? Why not - just return a blank string?** - Mako tries to stick to the - Python philosophy of "explicit is better than implicit". In - this case, its decided that the template author should be made - to specifically handle a missing value rather than - experiencing what may be a silent failure. Since `UNDEFINED` - is a singleton object just like Python's `True` or `False`, - you can use the `is` operator to check for it: - - % if someval is UNDEFINED: - someval is: no value - % else: - someval is: ${someval} - % endif - -Another facet of the `Context` is that its dictionary of variables is **immutable**. Whatever is set when `template.render()` is called is what stays. Of course, since its Python, you can hack around this and change values in the context's internal dictionary, but this will probably will not work as well as you'd think. The reason for this is that Mako in many cases creates copies of the `Context` object, which get sent to various elements of the template and inheriting templates used in an execution. So changing the value in your local `Context` will not necessarily make that value available in other parts of the template's execution. Examples of where Mako creates copies of the `Context` include within top-level def calls from the main body of the template (the context is used to propagate locally assigned variables into the scope of defs; since in the template's body they appear as inlined functions, Mako tries to make them act that way), and within an inheritance chain (each template in an inheritance chain has a different notion of `parent` and `next`, which are all stored in unique `Context` instances). - -* **So what if I want to set values that are global to everyone within a template request?** - All you have to do is provide a dictionary to your `Context` when the template first runs, and everyone can just get/set variables from that. Lets say its called `attributes`. - -Running the template looks like: - - {python} - output = template.render(attributes={}) - -Within a template, just reference the dictionary: - - <% - attributes['foo'] = 'bar' - %> - 'foo' attribute is: ${attributes['foo']} - -* **Why can't "attributes" be a built-in feature of the Context?** - This is an area where Mako is trying to make as few decisions about your application as it possibly can. Perhaps you don't want your templates to use this technique of assigning and sharing data, or perhaps you have a different notion of the names and kinds of data structures that should be passed around. Once again Mako would rather ask the user to be explicit. - -#### Context Methods and Accessors {@name=accessors} - -Significant members off of `Context` include: - -* `context[key]` / `context.get(key, default=None)` - dictionary-like accessors for the context. Normally, any variable you use in your template is automatically pulled from the context if it isnt defined somewhere already. Use the dictionary accessor and/or `get` method when you want a variable that *is* already defined somewhere else, such as in the local arguments sent to a %def call. If a key is not present, like a dictionary it raises `KeyError`. -* `keys()` - all the names defined within this context. -* `kwargs` - this returns a **copy** of the context's dictionary of variables. This is useful when you want to propagate the variables in the current context to a function as keyword arguments, i.e.: - - ${next.body(**context.kwargs)} - -* `write(text)` - write some text to the current output stream. -* `lookup` - returns the `TemplateLookup` instance that is used for all file-lookups within the current execution (even though individual `Template` instances can conceivably have different instances of a `TemplateLookup`, only the `TemplateLookup` of the originally-called `Template` gets used in a particular execution). - -### All the built-in names {@name=builtins} - -A one-stop shop for all the names Mako defines. Most of these names are instances of `Namespace`, which are described in the next section, [namespaces](rel:namespaces). Also, most of these names other than `context` and `UNDEFINED` are also present *within* the `Context` itself. - -* `local` - the namespace of the current template, described in [namespaces_builtin](rel:namespaces_builtin) -* `self` - the namespace of the topmost template in an inheritance chain (if any, otherwise the same as `local`), mostly described in [inheritance](rel:inheritance) -* `parent` - the namespace of the parent template in an inheritance chain (otherwise undefined); see [inheritance](rel:inheritance) -* `next` - the namespace of the next template in an inheritance chain (otherwise undefined); see [inheritance](rel:inheritance) -* `caller` - a "mini" namespace created when using the `<%call>` tag to define a "def call with content"; described in [defs_defswithcontent](rel:defs_defswithcontent) -* `capture` - a function that calls a given def and captures its resulting content into a string, which is returned. Usage is described in [filtering_buffering](rel:filtering_buffering) -* `UNDEFINED` - a global singleton that is applied to all otherwise uninitialized template variables that were not located within the `Context` when rendering began. Is an instance of `mako.runtime.Undefined`, and raises an exception when its `__str__()` method is called. -* `pageargs` - this is a dictionary which is present in a template which does not define any **kwargs section in its `<%page>` tag. All keyword arguments sent to the `body()` function of a template (when used via namespaces) go here by default unless otherwise defined as a page argument. If this makes no sense, it shouldn't; read the section [namespaces_body](rel:namespaces_body). diff --git a/doc/build/content/syntax.txt b/doc/build/content/syntax.txt deleted file mode 100644 index 565687d..0000000 --- a/doc/build/content/syntax.txt +++ /dev/null @@ -1,231 +0,0 @@ -Syntax {@name=syntax} -============================== - -A Mako template is parsed from a text stream containing any kind of content, XML, HTML, email text, etc. The template can further contain Mako-specific directives which represent variable and/or expression substitutions, control structures (i.e. conditionals and loops), server-side comments, full blocks of Python code, as well as various tags that offer additional functionality. All of these constructs compile into real Python code. This means that you can leverage the full power of Python in almost every aspect of a Mako template. - -### Expression Substitution - -The simplest expression is just a variable substitution. The syntax for this is the `${}` construct, which is inspired by Perl, Genshi, JSP EL, and others: - - this is x: ${x} - -Above, the string representation of `x` is applied to the template's output stream. If you're wondering where `x` comes from, its usually from the `Context` supplied to the template's rendering function. If `x` was not supplied to the template and was not otherwise assigned locally, it evaluates to a special value `UNDEFINED`. More on that later. - -The contents within the `${}` tag are evaluated by Python directly, so full expressions are OK: - - pythagorean theorem: ${pow(x,2) + pow(y,2)} - -The results of the expression are evaluated into a string result in all cases before being rendered to the output stream, such as the above example where the expression produces a numeric result. - -#### Expression Escaping - -Mako includes a number of built-in escaping mechanisms, including HTML, URI and XML escaping, as well as a "trim" function. These escapes can be added to an expression substituion using the `|` operator: - - ${"this is some text" | u} - -The above expression applies URL escaping to the expression, and produces `this+is+some+text`. The `u` name indicates URL escaping, whereas `h` represents HTML escaping, `x` represents XML escaping, and `trim` applies a trim function. - -Read more about built in filtering functions, including how to make your own filter functions, in [filtering](rel:filtering). - -### Control Structures - -A control structure refers to all those things that control the flow of a program - conditionals (i.e. if/else), loops (like while and for), as well as things like `try/except`. In Mako, control structures are written using the `%` marker followed by a regular Python control expression, and are "closed" by using another `%` marker with the tag "`end<name>`", where "`<name>`" is the keyword of the expression: - - % if x==5: - this is some output - % endif - -The `%` can appear anywhere on the line as long as no text precedes it; indentation is not signficant. The full range of Python "colon" expressions are allowed here, including `if/elif/else`, `while`, `for`, and even `def`, although Mako has a built-in tag for defs which is more full-featured. - - % for a in ['one', 'two', 'three', 'four', 'five']: - % if a[0] == 't': - its two or three - % elif a[0] == 'f': - four/five - % else: - one - %endif - % endfor - -The `%` sign can also be "escaped", if you actually want to emit a percent sign as the first non whitespace character on a line, by escaping it as in `%%`: - - %% some text - - %% some more text - - -### Comments - -Comments come in two varieties. The single line comment uses `##` as the first non-space characters on a line: - - ## this is a comment. - ...text ... - -A multiline version exists using `<%doc> ...text... </%doc>`: - - <%doc> - these are comments - more comments - </%doc> - -### Newline Filters - -The backslash ("`\`") character, placed at the end of any line, will consume the newline character before continuing to the next line: - - here is a line that goes onto \ - another line. - -The above text evaluates to: - - here is a line that goes onto another line. - -### Python Blocks - -Any arbitrary block of python can be dropped in using the `<% %>` tags: - - this is a template - <% - x = db.get_resource('foo') - y = [z.element for z in x if x.frobnizzle==5] - %> - % for elem in y: - element: ${elem} - % endfor - -Within `<% %>`, you're writing a regular block of Python code. While the code can appear with an arbitrary level of preceding whitespace, it has to be consistently formatted with itself. Mako's compiler will adjust the block of Python to be consistent with the surrounding generated Python code. - -#### Module-level Blocks - -A variant on `<% %>` is the module-level code block, denoted by `<%! %>`. Code within these tags is executed at the module level of the template, and not within the rendering function of the template. Therefore, this code does not have access to the template's context and is only executed when the template is loaded into memory (which can be only once per application, or more, depending on the runtime environment). Use the `<%! %>` tags to declare your template's imports, as well as any pure-Python functions you might want to declare: - - <%! - import mylib - import re - - def filter(text): - return re.sub(r'^@', '', text) - %> - -Any number of `<%! %>` blocks can be declared anywhere in a template; they will be rendered in the resulting module in the order that they appear. - -### Tags - -The rest of what Mako offers takes place in the form of tags. All tags use the same syntax, which is similar to an XML tag except that the first character of the tag name is a `%` character. The tag is closed either by a contained slash character, or an explicit closing tag: - - <%include file="foo.txt"/> - - <%def name="foo" buffered="True"> - this is a def - </%def> - -All tags have a set of attributes which are defined for each tag. Some of these attributes are required. Also, many attributes support **evaluation**, meaning you can embed an expression (using `${}`) inside the attribute text: - - <%include file="/foo/bar/${myfile}.txt"/> - -Whether or not an attribute accepts runtime evaluation depends on the type of tag and how that tag is compiled into the template. The best way to find out if you can stick an expression in is to try it ! The lexer will tell you if its not valid. - -Heres a quick summary of all the tags: - -#### <%page> - -This tag defines general characteristics of the template, including caching arguments, and optional lists of arguments which the template expects when invoked. - - <%page args="x, y, z='default'"/> - -Or a page tag that defines caching characteristics: - - <%page cached="True" cache_type="memory"/> - -Currently, only one `<%page>` tag gets used per template, the rest get ignored. While this will be improved in a future release, for now make sure you have only one `<%page>` tag defined in your template, else you may not get the results you want. The details of what `<%page>` is used for are described further in [namespaces_body](rel:namespaces_body) as well as [caching](rel:caching). - -#### <%include> - -A tag that is familiar from other template languages, %include is a regular joe that just accepts a file argument and calls in the rendered result of that file: - - <%include file="header.html"/> - - hello world - - <%include file="footer.html"/> - -Include also accepts arguments which are available as `<%page>` arguments in the receiving template: - - <%include file="toolbar.html" args="current_section='members', username='ed'"/> - -#### <%def> - -The `%def` tag defines a Python function which contains a set of content, that can be called at some other point in the template. The basic idea is simple: - - <%def name="myfunc(x)"> - this is myfunc, x is ${x} - </%def> - - ${myfunc(7)} - -The %def tag is a lot more powerful than a plain Python def, as the Mako compiler provides many extra services with %def that you wouldn't normally have, such as the ability to export defs as template "methods", automatic propagation of the current `Context`, buffering/filtering/caching flags, and def calls with content, which enable packages of defs to be sent as arguments to other def calls (not as hard as it sounds). Get the full deal on what %def can do in [defs](rel:defs). - -#### <%namespace> - -%namespace is Mako's equivalent of Python's `import` statement. It allows access to all the rendering functions and metadata of other template files, plain Python modules, as well as locally defined "packages" of functions. - - <%namespace file="functions.html" import="*"/> - -The underlying object generated by %namespace, an instance of `mako.runtime.Namespace`, is a central construct used in templates to reference template-specific information such as the current URI, inheritance structures, and other things that are not as hard as they sound right here. Namespaces are described in [namespaces](rel:namespaces). - -#### <%inherit> - -Inherit allows templates to arrange themselves in **inheritance chains**. This is a concept familiar in many other template languages. - - <%inherit file="base.html"/> - -When using the %inherit tag, control is passed to the topmost inherited template first, which then decides how to handle calling areas of content from its inheriting templates. Mako offers a lot of flexbility in this area, including dynamic inheritance, content wrapping, and polymorphic method calls. Check it out in [inheritance](rel:inheritance). - -#### <%namespacename:defname> - -As of Mako 0.2.3, any user-defined "tag" can be created against a namespace by using a tag with a name of the form *namespacename*:*defname*. The closed and open formats of such a tag are equivalent to an inline expression and the `<%call>` tag, respectively. - - <%mynamespace:somedef param="some value"> - this is the body - </%mynamespace:somedef> - -To create custom tags which accept a body, see [defs_defswithcontent](rel:defs_defswithcontent). - -#### <%call> - -The call tag is the "classic" form of a user-defined tag, and is roughly equiavlent to the `<%namespacename:defname>` syntax described above. This tag is also described in [defs_defswithcontent](rel:defs_defswithcontent). - -#### <%doc> - -The doc tag handles multiline comments: - - <%doc> - these are comments - more comments - </%doc> - -Also the `##` symbol as the first non-space characters on a line can be used for single line comments. - -#### <%text> - -This tag suspends the Mako lexer's normal parsing of Mako template directives, and returns its entire body contents as plain text. It is used pretty much to write documentation about Mako: - - <%text filter="h"> - heres some fake mako ${syntax} - <%def name="x()">${x}</%def> - %CLOSETEXT - -### Returning early from a template - -Sometimes you want to stop processing a template or `<%def>` method in the middle and just use the text you've accumulated so far. You can use a ``return`` statement inside a Python block to do that. - - % if not len(records): - No records found. - <% return %> - % endif - -Or perhaps: - - <% - if not len(records): - return - %> diff --git a/doc/build/content/unicode.txt b/doc/build/content/unicode.txt deleted file mode 100644 index 046f040..0000000 --- a/doc/build/content/unicode.txt +++ /dev/null @@ -1,152 +0,0 @@ -The Unicode Chapter {@name=unicode} -====================== - -The Python language supports two ways of representing what we know as "strings", i.e. series of characters. In Python 2, the two types are `string` and `unicode`, and in Python 3 they are `bytes` and `string`. A key aspect of the Python 2 `string` and Python 3 `bytes` types are that they contain no information regarding what **encoding** the data is stored in. For this reason they were commonly referred to as **byte strings** on Python 2, and Python 3 makes this name more explicit. The origins of this come from Python's background of being developed before the Unicode standard was even available, back when strings were C-style strings and were just that, a series of bytes. Strings that had only values below 128 just happened to be **ascii** strings and were printable on the console, whereas strings with values above 128 would produce all kinds of graphical characters and bells. - -Contrast the "bytestring" types with the "unicode/string" type. Objects of this type are created whenever you say something like `u"hello world"` (or in Python 3, just `"hello world"`). In this case, Python represents each character in the string internally using multiple bytes per character (something similar to UTF-16). Whats important is that when using the `unicode`/`string` type to store strings, Python knows the data's encoding; its in its own internal format. Whereas when using the `string`/`bytes` type, it does not. - -When Python 2 attempts to treat a byte-string as a string, which means its attempting to compare/parse its characters, to coerce it into another encoding, or to decode it to a unicode object, it has to guess what the encoding is. In this case, it will pretty much always guess the encoding as `ascii`...and if the bytestring contains bytes above value 128, you'll get an error. Python 3 eliminates much of this confusion by just raising an error unconditionally if a bytestring is used in a character-aware context. - -There is one operation that Python *can* do with a non-ascii bytestring, and its a great source of confusion: it can dump the bytestring straight out to a stream or a file, with nary a care what the encoding is. To Python, this is pretty much like dumping any other kind of binary data (like an image) to a stream somewhere. In Python 2, it is common to see programs that embed all kinds of international characters and encodings into plain byte-strings (i.e. using `"hello world"` style literals) can fly right through their run, sending reams of strings out to whereever they are going, and the programmer, seeing the same output as was expressed in the input, is now under the illusion that his or her program is Unicode-compliant. In fact, their program has no unicode awareness whatsoever, and similarly has no ability to interact with libraries that *are* unicode aware. Python 3 makes this much less likely by defaulting to unicode as the storage format for strings. - -The "pass through encoded data" scheme is what template languages like Cheetah and earlier versions of Myghty do by default. Mako as of version 0.2 also supports this mode of operation when using Python 2, using the "disable_unicode=True" flag. However, when using Mako in its default mode of unicode-aware, it requires explicitness when dealing with non-ascii encodings. Additionally, if you ever need to handle unicode strings and other kinds of encoding conversions more intelligently, the usage of raw bytestrings quickly becomes a nightmare, since you are sending the Python interpreter collections of bytes for which it can make no intelligent decisions with regards to encoding. In Python 3 Mako only allows usage of native, unicode strings. - -In normal Mako operation, all parsed template constructs and output streams are handled internally as Python `unicode` objects. Its only at the point of `render()` that this unicode stream may be rendered into whatever the desired output encoding is. The implication here is that the template developer must ensure that the encoding of all non-ascii templates is explicit (still required in Python 3), that all non-ascii-encoded expressions are in one way or another converted to unicode (not much of a burden in Python 3), and that the output stream of the template is handled as a unicode stream being encoded to some encoding (still required in Python 3). - -### Specifying the Encoding of a Template File - -This is the most basic encoding-related setting, and it is equivalent to Python's "magic encoding comment", as described in [pep-0263](http://www.python.org/dev/peps/pep-0263/). Any template that contains non-ascii characters requires that this comment be present so that Mako can decode to unicode (and also make usage of Python's AST parsing services). Mako's lexer will use this encoding in order to convert the template source into a `unicode` object before continuing its parsing: - - ## -*- coding: utf-8 -*- - - Alors vous imaginez ma surprise, au lever du jour, quand une drôle de petite voix m’a réveillé. Elle disait: « S’il vous plaît… dessine-moi un mouton! » - -For the picky, the regular expression used is derived from that of the abovementioned pep: - - {python} - #.*coding[:=]\s*([-\w.]+).*\n - -The lexer will convert to unicode in all cases, so that if any characters exist in the template that are outside of the specified encoding (or the default of `ascii`), the error will be immediate. - -As an alternative, the template encoding can be specified programmatically to either `Template` or `TemplateLookup` via the `input_encoding` parameter: - - {python} - t = TemplateLookup(directories=['./'], input_encoding='utf-8') - -The above will assume all located templates specify `utf-8` encoding, unless the template itself contains its own magic encoding comment, which takes precedence. - -### Handling Expressions - -The next area that encoding comes into play is in expression constructs. By default, Mako's treatment of an expression like this: - - ${"hello world"} - -looks something like this: - - {python} - context.write(unicode("hello world")) - -In Python 3, its just: - - {python} - context.write(str("hello world")) - -That is, **the output of all expressions is run through the `unicode` builtin**. This is the default setting, and can be modified to expect various encodings. The `unicode` step serves both the purpose of rendering non-string expressions into strings (such as integers or objects which contain `__str()__` methods), and to ensure that the final output stream is constructed as a unicode object. The main implication of this is that **any raw bytestrings that contain an encoding other than ascii must first be decoded to a Python unicode object**. It means you can't say this in Python 2: - - ${"voix m’a réveillé."} ## error in Python 2! - -You must instead say this: - - ${u"voix m’a réveillé."} ## OK ! - -Similarly, if you are reading data from a file that is streaming bytes, or returning data from some object that is returning a Python bytestring containing a non-ascii encoding, you have to explcitly decode to unicode first, such as: - - ${call_my_object().decode('utf-8')} - -Note that filehandles acquired by `open()` in Python 3 default to returning "text", that is the decoding is done for you. See Python 3's documentation for the `open()` builtin for details on this. - -If you want a certain encoding applied to *all* expressions, override the `unicode` builtin with the `decode` builtin at the `Template` or `TemplateLookup` level: - - {python} - t = Template(templatetext, default_filters=['decode.utf8']) - -Note that the built-in `decode` object is slower than the `unicode` function, since unlike `unicode` its not a Python builtin, and it also checks the type of the incoming data to determine if string conversion is needed first. - -The `default_filters` argument can be used to entirely customize the filtering process of expressions. This argument is described in [filtering_expression_defaultfilters](rel:filtering_expression_defaultfilters). - -### Defining Output Encoding - -Now that we have a template which produces a pure unicode output stream, all the hard work is done. We can take the output and do anything with it. - -As stated in the "Usage" chapter, both `Template` and `TemplateLookup` accept `output_encoding` and `encoding_errors` parameters which can be used to encode the output in any Python supported codec: - - {python} - from mako.template import Template - from mako.lookup import TemplateLookup - - mylookup = TemplateLookup(directories=['/docs'], output_encoding='utf-8', encoding_errors='replace') - - mytemplate = mylookup.get_template("foo.txt") - print mytemplate.render() - -`render()` will return a `bytes` object in Python 3 if an output encoding is specified. By default it performs no encoding and returns a native string. - -`render_unicode()` will return the template output as a Python `unicode` object (or `string` in Python 3): - - {python} - print mytemplate.render_unicode() - -The above method disgards the output encoding keyword argument; you can encode yourself by saying: - - {python} - print mytemplate.render_unicode().encode('utf-8', 'replace') - -#### Buffer Selection - -Mako does play some games with the style of buffering used internally, to maximize performance. Since the buffer is by far the most heavily used object in a render operation, its important! - -When calling `render()` on a template that does not specify any output encoding (i.e. its `ascii`), Python's `cStringIO` module, which cannot handle encoding of non-ascii `unicode` objects (even though it can send raw bytestrings through), is used for buffering. Otherwise, a custom Mako class called `FastEncodingBuffer` is used, which essentially is a super dumbed-down version of `StringIO` that gathers all strings into a list and uses `u''.join(elements)` to produce the final output - its markedly faster than `StringIO`. - -### Saying to Heck with it: Disabling the usage of Unicode entirely - -Some segements of Mako's userbase choose to make no usage of Unicode whatsoever, and instead would prefer the "passthru" approach; all string expressions in their templates return encoded bytestrings, and they would like these strings to pass right through. The only advantage to this approach is that templates need not use `u""` for literal strings; there's an arguable speed improvement as well since raw bytestrings generally perform slightly faster than unicode objects in Python. For these users, assuming they're sticking with Python 2, they can hit the `disable_unicode=True` flag as so: - - {python} - # -*- encoding:utf-8 -*- - from mako.template import Template - - t = Template("drôle de petite voix m’a réveillé.", disable_unicode=True, input_encoding='utf-8') - print t.code - -The `disable_unicode` mode is strictly a Python 2 thing. It is not supported at all in Python 3. - -The generated module source code will contain elements like these: - - {python} - # -*- encoding:utf-8 -*- - # ...more generated code ... - - - def render_body(context,**pageargs): - context.caller_stack.push_frame() - try: - __M_locals = dict(pageargs=pageargs) - # SOURCE LINE 1 - context.write('dr\xc3\xb4le de petite voix m\xe2\x80\x99a r\xc3\xa9veill\xc3\xa9.') - return '' - finally: - context.caller_stack.pop_frame() - -Where above that the string literal used within `context.write` is a regular bytestring. - -When `disable_unicode=True` is turned on, the `default_filters` argument which normally defaults to `["unicode"]` now defaults to `["str"]` instead. Setting default_filters to the empty list `[]` can remove the overhead of the `str` call. Also, in this mode you **cannot** safely call `render_unicode()` - you'll get unicode/decode errors. - -The `h` filter (html escape) uses a less performant pure Python escape function in non-unicode mode (note that in versions prior to 0.3.4, it used cgi.escape(), which has been replaced with a function that also escapes single quotes). This because MarkupSafe only supports Python unicode objects for non-ascii strings. - -**Rules for using disable_unicode=True** - - * don't use this mode unless you really, really want to and you absolutely understand what you're doing - * don't use this option just because you don't want to learn to use Unicode properly; we aren't supporting user issues in this mode of operation. We will however offer generous help for the vast majority of users who stick to the Unicode program. - * Python 3 is unicode by default, and the flag is not available when running on Python 3. - - diff --git a/doc/build/content/usage.txt b/doc/build/content/usage.txt deleted file mode 100644 index 1163117..0000000 --- a/doc/build/content/usage.txt +++ /dev/null @@ -1,255 +0,0 @@ -Basic Usage {@name=usage} -========================== - -This section describes the Python API for Mako templates. If you are using Mako within a web framework such as Pylons, the work of integrating Mako's API is already done for you, in which case you can skip to the next section, [syntax](rel:syntax). - -The most basic way to create a template and render it is through the `Template` class: - - {python} - from mako.template import Template - - mytemplate = Template("hello world!") - print mytemplate.render() - -Above, the text argument to `Template` is **compiled** into a Python module representation. This module contains a function called `render_body()`, which produces the output of the template. When `mytemplate.render()` is called, Mako sets up a runtime environment for the template and calls the `render_body()` function, capturing the output into a buffer and returning its string contents. - - -The code inside the `render_body()` function has access to a namespace of variables. You can specify these variables by sending them as additional keyword arguments to the `render()` method: - - {python} - from mako.template import Template - - mytemplate = Template("hello, ${name}!") - print mytemplate.render(name="jack") - -The `template.render()` method calls upon Mako to create a `Context` object, which stores all the variable names accessible to the template and also stores a buffer used to capture output. You can create this `Context` yourself and have the template render with it, using the `render_context` method: - - {python} - from mako.template import Template - from mako.runtime import Context - from StringIO import StringIO - - mytemplate = Template("hello, ${name}!") - buf = StringIO() - ctx = Context(buf, name="jack") - mytemplate.render_context(ctx) - print buf.getvalue() - -### Using File-Based Templates {@name=file} - -A `Template` can also load its template source code from a file, using the `filename` keyword argument: - - {python} - from mako.template import Template - - mytemplate = Template(filename='/docs/mytmpl.txt') - print mytemplate.render() - -For improved performance, a `Template` which is loaded from a file can also cache the source code to its generated module on the filesystem as a regular Python module file (i.e. a .py file). To do this, just add the `module_directory` argument to the template: - - {python} - from mako.template import Template - - mytemplate = Template(filename='/docs/mytmpl.txt', module_directory='/tmp/mako_modules') - print mytemplate.render() - -When the above code is rendered, a file `/tmp/mako_modules/docs/mytmpl.txt.py` is created containing the source code for the module. The next time a `Template` with the same arguments is created, this module file will be automatically re-used. - -### Using TemplateLookup {@name=lookup} - -All of the examples thus far have dealt with the usage of a single `Template` object. If the code within those templates tries to locate another template resource, it will need some way to find them, using simple URI strings. For this need, the resolution of other templates from within a template is accomplished by the `TemplateLookup` class. This class is constructed given a list of directories in which to search for templates, as well as keyword arguments that will be passed to the `Template` objects it creates. - - {python} - from mako.template import Template - from mako.lookup import TemplateLookup - - mylookup = TemplateLookup(directories=['/docs']) - mytemplate = Template("""<%include file="header.txt"/> hello world!""", lookup=mylookup) - -Above, we created a textual template which includes the file `header.txt`. In order for it to have somewhere to look for `header.txt`, we passed a `TemplateLookup` object to it, which will search in the directory `/docs` for the file `header.txt`. - -Usually, an application will store most or all of its templates as text files on the filesystem. So far, all of our examples have been a little bit contrived in order to illustrate the basic concepts. But a real application would get most or all of its templates directly from the `TemplateLookup`, using the aptly named `get_template` method, which accepts the URI of the desired template: - - {python} - from mako.template import Template - from mako.lookup import TemplateLookup - - mylookup = TemplateLookup(directories=['/docs'], module_directory='/tmp/mako_modules') - - def serve_template(templatename, **kwargs): - mytemplate = mylookup.get_template(templatename) - print mytemplate.render(**kwargs) - -In the example above, we create a `TemplateLookup` which will look for templates in the `/docs` directory, and will store generated module files in the `/tmp/mako_modules` directory. The lookup locates templates by appending the given URI to each of its search directories; so if you gave it a URI of `/etc/beans/info.txt`, it would search for the file `/docs/etc/beans/info.txt`, else raise a `TopLevelNotFound` exception, which is a custom Mako exception. - -When the lookup locates templates, it will also assign a `uri` property to the `Template` which is the uri passed to the `get_template()` call. `Template` uses this uri to calculate the name of its module file. So in the above example, a `templatename` argument of `/etc/beans/info.txt` will create a module file `/tmp/mako_modules/etc/beans/info.txt.py`. - -#### Setting the Collection Size {@name=size} - -The `TemplateLookup` also serves the important need of caching a fixed set of templates in memory at a given time, so that successive uri lookups do not result in full template compilations and/or module reloads on each request. By default, the `TemplateLookup` size is unbounded. You can specify a fixed size using the `collection_size` argument: - - {python} - mylookup = TemplateLookup(directories=['/docs'], - module_directory='/tmp/mako_modules', collection_size=500) - -The above lookup will continue to load templates into memory until it reaches a count of around 500. At that point, it will clean out a certain percentage of templates using a **least recently used** scheme. - -#### Setting Filesystem Checks {@name=checks} - -Another important flag on `TemplateLookup` is `filesystem_checks`. This defaults to `True`, and says that each time a template is returned by the `get_template()` method, the revision time of the original template file is checked against the last time the template was loaded, and if the file is newer will reload its contents and recompile the template. On a production system, setting `filesystem_checks` to `False` can afford a small to moderate performance increase (depending on the type of filesystem used). - -### Using Unicode and Encoding - -Both `Template` and `TemplateLookup` accept `output_encoding` and `encoding_errors` parameters which can be used to encode the output in any Python supported codec: - - {python} - from mako.template import Template - from mako.lookup import TemplateLookup - - mylookup = TemplateLookup(directories=['/docs'], output_encoding='utf-8', encoding_errors='replace') - - mytemplate = mylookup.get_template("foo.txt") - print mytemplate.render() - -When using Python 3, the `render()` method will return a `bytes` object, **if** `output_encoding` is set. Otherwise it returns a `string`. - -Additionally, the `render_unicode()` method exists which will return the template output as a Python `unicode` object, or in Python 3 a `string`: - - {python} - print mytemplate.render_unicode() - -The above method disregards the output encoding keyword argument; you can encode yourself by saying: - - {python} - print mytemplate.render_unicode().encode('utf-8', 'replace') - -Note that Mako's ability to return data in any encoding and/or `unicode` implies that the underlying output stream of the template is a Python unicode object. This behavior is described fully in [unicode](rel:unicode). - -### Handling Exceptions - -Template exceptions can occur in two distinct places. One is when you **lookup, parse and compile** the template, the other is when you **run** the template. Within the running of a template, exceptions are thrown normally from whatever Python code originated the issue. Mako has its own set of exception classes which mostly apply to the lookup and lexer/compiler stages of template construction. Mako provides some library routines that can be used to help provide Mako-specific information about any exception's stack trace, as well as formatting the exception within textual or HTML format. In all cases, the main value of these handlers is that of converting Python filenames, line numbers, and code samples into Mako template filenames, line numbers, and code samples. All lines within a stack trace which correspond to a Mako template module will be converted to be against the originating template file. - -To format exception traces, the `text_error_template` and `html_error_template` functions are provided. They make usage of `sys.exc_info()` to get at the most recently thrown exception. Usage of these handlers usually looks like: - - {python} - from mako import exceptions - - try: - template = lookup.get_template(uri) - print template.render() - except: - print exceptions.text_error_template().render() - -Or for the HTML render function: - - {python} - from mako import exceptions - - try: - template = lookup.get_template(uri) - print template.render() - except: - print exceptions.html_error_template().render() - -The `html_error_template` template accepts two options: specifying `full=False` causes only a section of an HTML document to be rendered. Specifying `css=False` will disable the default stylesheet from being rendered. - -E.g.: - - print exceptions.html_error_template().render(full=False) - -The HTML render function is also available built-in to `Template` using the `format_exceptions` flag. In this case, any exceptions raised within the **render** stage of the template will result in the output being substituted with the output of `html_error_template`. - - {python} - template = Template(filename="/foo/bar", format_exceptions=True) - print template.render() - -Note that the compile stage of the above template occurs when you construct the `Template` itself, and no output stream is defined. Therefore exceptions which occur within the lookup/parse/compile stage will not be handled and will propagate normally. While the pre-render traceback usually will not include any Mako-specific lines anyway, it will mean that exceptions which occur previous to rendering and those which occur within rendering will be handled differently...so the `try/except` patterns described previously are probably of more general use. - -The underlying object used by the error template functions is the `RichTraceback` object. This object can also be used directly to provide custom error views. Here's an example usage which describes its general API: - - {python} - from mako.exceptions import RichTraceback - - try: - template = lookup.get_template(uri) - print template.render() - except: - traceback = RichTraceback() - for (filename, lineno, function, line) in traceback.traceback: - print "File %s, line %s, in %s" % (filename, lineno, function) - print line, "\n" - print "%s: %s" % (str(traceback.error.__class__.__name__), traceback.error) - -Further information about `RichTraceback` is available within the module-level documentation for `mako.exceptions`. - - -### Common Framework Integrations - -The Mako distribution includes a little bit of helper code for the purpose of using Mako in some popular web framework scenarios. This is a brief description of whats included. - -#### Turbogears/Pylons Plugin - -The standard plugin methodology used by [Turbogears](http://www.turbogears.org) as well as [Pylons](http://www.pylonshq.com) is included in the module `mako.ext.turbogears`, using the `TGPlugin` class. This is also a setuptools entrypoint under the heading `python.templating.engines` with the name `mako`. - -#### WSGI - -A sample WSGI application is included in the distrubution in the file `examples/wsgi/run_wsgi.py`. This runner is set up to pull files from a `templates` as well as an `htdocs` directory and includes a rudimental two-file layout. The WSGI runner acts as a fully functional standalone web server, using `wsgiutils` to run itself, and propagates GET and POST arguments from the request into the `Context`, can serve images, css files and other kinds of files, and also displays errors using Mako's included exception-handling utilities. - -#### Pygments - -A [Pygments](http://pygments.pocoo.org)-compatible syntax highlighting module is included under `mako.ext.pygmentplugin`. This module is used in the generation of Mako documentation and also contains various setuptools entry points under the heading `pygments.lexers`, including `mako`, `html+mako`, `xml+mako` (see the `setup.py` file for all the entry points). - -#### Babel (Internationalization) - -Mako provides support for extracting gettext messages from templates via a [Babel](http://babel.edgewall.org/) extractor entry point under `mako.ext.babelplugin`. - -Gettext messages are extracted from all Python code sections, even the more obscure ones such as [control structures](rel:syntax_control), [def tag function declarations](rel:defs), [call tag exprs](rel:defs_defswithcontent) and even [page tag args](rel:syntax_tags_page). - -[Translator comments](http://babel.edgewall.org/wiki/Documentation/messages.html#comments-tags-and-translator-comments-explanation) may also be extracted from Mako templates when a comment tag is specified to [Babel](http://babel.edgewall.org/) (such as with the -c option). - -For example, a project '`myproj`' contains the following Mako template at myproj/myproj/templates/name.html: - - <div id="name"> - Name: - ## TRANSLATORS: This is a proper name. See the gettext - ## manual, section Names. - ${_('Francois Pinard')} - </div> - -To extract gettext messages from this template the project needs a Mako section in its [Babel Extraction Method Mapping file](http://babel.edgewall.org/wiki/Documentation/messages.html#extraction-method-mapping-and-configuration) (typically located at myproj/babel.cfg): - - {ini} - # Extraction from Python source files - - [python: myproj/**.py] - - # Extraction from Mako templates - - [mako: myproj/templates/**.html] - input_encoding = utf-8 - -The Mako extractor supports an optional `input_encoding` parameter specifying the encoding of the templates (identical to `Template`/`TemplateLookup`'s `input_encoding` parameter). - -Invoking [Babel](http://babel.edgewall.org/)'s extractor at the command line in the project's root directory: - - myproj$ pybabel extract -F babel.cfg -c "TRANSLATORS:" . - -Will output a gettext catalog to stdout including the following: - - #. TRANSLATORS: This is a proper name. See the gettext - #. manual, section Names. - #: myproj/templates/name.html:5 - msgid "Francois Pinard" - msgstr "" - -This is only a basic example: [Babel](http://babel.edgewall.org/) can be invoked from setup.py and its command line options specified in the accompanying setup.cfg via [Babel Distutils/Setuptools Integration](http://babel.edgewall.org/wiki/Documentation/setup.html). - -Comments must immediately precede a gettext message to be extracted. In the following case the TRANSLATORS: comment would not have been extracted: - - <div id="name"> - ## TRANSLATORS: This is a proper name. See the gettext - ## manual, section Names. - Name: ${_('Francois Pinard')} - </div> - -See the [Babel User Guide](http://babel.edgewall.org/wiki/Documentation/index.html) for more information. |