[test] [feature] The default test runner is now py.test. Running “python setup.py test”
will make use of py.test instead of nose. nose still works as a test
runner as well, however.¶

[lexer] [bug] Major improvements to lexing of intricate Python sections which may
contain complex backslash sequences, as well as support for the bitwise
operator (e.g. pipe symbol) inside of expression sections distinct
from the Mako “filter” operator, provided the operator is enclosed
within parentheses or brackets. Pull request courtesy Daniel Martin.¶

[installation] [bug] The “universal wheel” marker is removed from setup.cfg, because
our setup.py currently makes use of conditional dependencies.
In #249, the discussion is ongoing on how to correct our
setup.cfg / setup.py fully so that we can handle the per-version
dependency changes while still maintaining optimal wheel settings,
so this issue is not yet fully resolved.¶

[bug] [py3k] Repair some calls within the ast module that no longer work on Python3.5;
additionally replace the use of inspect.getargspec() under
Python 3 (seems to be called from the TG plugin) to avoid deprecation
warnings.¶

[feature] Added STOP_RENDERING keyword for returning/exiting from a
template early, which is a synonym for an empty string "".
Previously, the docs suggested a bare
return, but this could cause None to appear in the
rendered template result.

[py2k] [bug] Improved the error re-raise operation when a custom
Template.error_handler is used that does not handle
the exception; the original stack trace etc. is now preserved.
Pull request courtesy Manfred Haltner.¶

[general] Compatibility changes; in order to modernize the codebase, Mako
is now dropping support for Python 2.4 and Python 2.5 altogether.
The source base is now targeted at Python 2.6 and forwards.¶

[feature] Template modules now generate a JSON “metadata” structure at the bottom
of the source file which includes parseable information about the
templates’ source file, encoding etc. as well as a mapping of module
source lines to template lines, thus replacing the “# SOURCE LINE”
markers throughout the source code. The structure also indicates those
lines that are explicitly not part of the template’s source; the goal
here is to allow better integration with coverage and other tools.¶

[bug] [py3k] Fixed bug in decode.<encoding> filter where a non-string object
would not be correctly interpreted in Python 3.¶

[bug] [py3k] Fixed bug in Python parsing logic which would fail on Python 3
when a “try/except” targeted a tuple of exception types, rather
than a single exception.¶

[feature] mako-render is now implemented as a setuptools entrypoint script;
a standalone mako.cmd.cmdline() callable is now available, and the
system also uses argparse now instead of optparse. Pull request
courtesy Derek Harland.¶

[bug] A rework of the mako-render script allows the script to run
correctly when given a file pathname that is outside of the current
directory, e.g. mako-render../some_template.mako. In this case,
the “template root” defaults to the directory in which the template
is located, instead of “.”. The script also accepts a new argument
--template-dir which can be specified multiple times to establish
template lookup directories. Standard input for templates also works
now too. Pull request courtesy Derek Harland.¶

[bug] Changed the format of the “source encoding” header output
by the code generator to use the format #-*-coding:%s-*-
instead of #-*-encoding:%s-*-; the former is more common
and compatible with emacs. Courtesy Martin Geisler.¶

[bug] Fixed issue where an old lexer rule prevented a template line
which looked like “#*” from being correctly parsed.¶

[bug] The Context.locals_() method becomes a private underscored
method, as this method has a specific internal use. The purpose
of Context.kwargs has been clarified, in that it only delivers
top level keyword arguments originally passed to template.render().¶

[bug] Fixed the babel plugin to properly interpret ${} sections
inside of a “call” tag, i.e. <%self:some_tag attr=”${_(‘foo’)}”/>.
Code that’s subject to babel escapes in here needs to be
specified as a Python expression, not a literal. This change
is backwards incompatible vs. code that is relying upon a _(‘’)
translation to be working within a call tag.¶

[feature] Added new “loop” variable to templates,
is provided within a % for block to provide
info about the loop such as index, first/last,
odd/even, etc. A migration path is also provided
for legacy templates via the “enable_loop” argument
available on Template, TemplateLookup, and <%page>.
Thanks to Ben Trofatter for all
the work on this¶

[feature] Added a real check for “reserved”
names, that is names which are never pulled
from the context and cannot be passed to
the template.render() method. Current names
are “context”, “loop”, “UNDEFINED”.¶

[feature] The html_error_template() will now
apply Pygments highlighting to the source
code displayed in the traceback, if Pygments
if available. Courtesy Ben Trofatter¶

[feature] Template caching has been converted into a plugin
system, whereby the usage of Beaker is just the
default plugin. Template and TemplateLookup
now accept a string “cache_impl” parameter which
refers to the name of a cache plugin, defaulting
to the name ‘beaker’. New plugins can be
registered as pkg_resources entrypoints under
the group “mako.cache”, or registered directly
using mako.cache.register_plugin(). The
core plugin is the mako.cache.CacheImpl
class.¶

[feature] Added support for Beaker cache regions
in templates. Usage of regions should be considered
as superseding the very obsolete idea of passing in
backend options, timeouts, etc. within templates.¶

[feature] The ‘put’ method on Cache is now
‘set’. ‘put’ is there for backwards compatibility.¶

[feature] The <%def>, <%block> and <%page> tags now accept
any argument named “cache_*”, and the key
minus the “cache_” prefix will be passed as keyword
arguments to the CacheImpl methods.¶

[feature] Template and TemplateLookup now accept an argument
cache_args, which refers to a dictionary containing
cache parameters. The cache_dir, cache_url, cache_type,
cache_timeout arguments are deprecated (will probably
never be removed, however) and can be passed
now as cache_args={‘url’:<some url>, ‘type’:’memcached’,
‘timeout’:50, ‘dir’:’/path/to/some/directory’}¶

[feature/bug] Can now refer to context variables
within extra arguments to <%block>, <%def>, i.e.
<%block name=”foo” cache_key=”${somekey}”>.
Filters can also be used in this way, i.e.
<%def name=”foo()” filter=”myfilter”>
then template.render(myfilter=some_callable)¶

[feature] Added module_writer argument to Template,
TemplateLookup, allows a callable to be passed which
takes over the writing of the template’s module source
file, so that special environment-specific steps
can be taken.¶

A Template is explicitly disallowed
from having a url that normalizes to relative outside
of the root. That is, if the Lookup is based
at /home/mytemplates, an include that would place
the ultimate template at
/home/mytemplates/../some_other_directory,
i.e. outside of /home/mytemplates,
is disallowed. This usage was never intended
despite the lack of an explicit check.
The main issue this causes
is that module files can be written outside
of the module root (or raise an error, if file perms aren’t
set up), and can also lead to the same template being
cached in the lookup under multiple, relative roots.
TemplateLookup instead has always supported multiple
file roots for this purpose.¶

New tag: <%block>. A variant on <%def> that
evaluates its contents in-place.
Can be named or anonymous,
the named version is intended for inheritance
layouts where any given section can be
surrounded by the <%block> tag in order for
it to become overrideable by inheriting
templates, without the need to specify a
top-level <%def> plus explicit call.
Modified scoping and argument rules as well as a
more strictly enforced usage scheme make it ideal
for this purpose without at all replacing most
other things that defs are still good for.
Lots of new docs.¶

The FastEncodingBuffer is now used
by default instead of cStringIO or StringIO,
regardless of whether output_encoding
is set to None or not. FEB is faster than
both. Only StringIO allows bytestrings
of unknown encoding to pass right
through, however - while it is of course
not recommended to send bytestrings of unknown
encoding to the output stream, this
mode of usage can be re-enabled by
setting the flag bytestring_passthrough
to True.¶

disable_unicode mode requires that
output_encoding be set to None - it also
forces the bytestring_passthrough flag
to True.¶

the <%namespace> tag raises an error
if the ‘template’ and ‘module’ attributes
are specified at the same time in
one tag. A different class is used
for each case which allows a reduction in
runtime conditional logic and function
call overhead.¶

the keys() in the Context, as well as
it’s internal _data dictionary, now
include just what was specified to
render() as well as Mako builtins
‘caller’, ‘capture’. The contents
of __builtin__ are no longer copied.
Thanks to Daniel Lopez for pointing
this out.¶

Beaker is now part of “extras” in
setup.py instead of “install_requires”.
This to produce a lighter weight install
for those who don’t use the caching
as well as to conform to Pyramid
deployment practices.¶

New flag on Template, TemplateLookup -
strict_undefined=True, will cause
variables not found in the context to
raise a NameError immediately, instead of
defaulting to the UNDEFINED value.¶

The range of Python identifiers that
are considered “undefined”, meaning they
are pulled from the context, has been
trimmed back to not include variables
declared inside of expressions (i.e. from
list comprehensions), as well as
in the argument list of lambdas. This
to better support the strict_undefined
feature. The change should be
fully backwards-compatible but involved
a little bit of tinkering in the AST code,
which hadn’t really been touched for
a couple of years, just FYI.¶

Now using MarkupSafe for HTML escaping,
i.e. in place of cgi.escape(). Faster
C-based implementation and also escapes
single quotes for additional security.
Supports the __html__ attribute for
the given expression as well.

When using “disable_unicode” mode,
a pure Python HTML escaper function
is used which also quotes single quotes.

When a .py is being created, the tempfile
where the source is stored temporarily is
now made in the same directory as that of
the .py file. This ensures that the two
files share the same filesystem, thus
avoiding cross-filesystem synchronization
issues. Thanks to Charles Cazabon.¶

Source code escaping has been simplified.
In particular, module source files are now
generated with the Python “magic encoding
comment”, and source code is passed through
mostly unescaped, except for that code which
is regenerated from parsed Python source.
This fixes usage of unicode in
<%namespace:defname> tags.¶

defs declared within a <%namespace> section, an
uncommon feature, have been improved. The defs
no longer get doubly-rendered in the body() scope,
and now allow local variable assignment without
breakage.¶

Windows paths are handled correctly if a Template
is passed only an absolute filename (i.e. with c:
drive etc.) and no URI - the URI is converted
to a forward-slash path and module_directory
is treated as a windows path.¶

Added a “decorator” kw argument to <%def>,
allows custom decoration functions to wrap
rendering callables. Mainly intended for
custom caching algorithms, not sure what
other uses there may be (but there may be).
Examples are in the “filtering” docs.¶

When Mako creates subdirectories in which
to store templates, it uses the more
permissive mode of 0775 instead of 0750,
helping out with certain multi-process
scenarios. Note that the mode is always
subject to the restrictions of the existing
umask.¶

the <%namespacename:defname> syntax described at
http://techspot.zzzeek.org/?p=28 has now
been added as a built in syntax, and is recommended
as a more modern syntax versus <%call expr=”expression”>.
The %call tag itself will always remain,
with <%namespacename:defname> presenting a more HTML-like
alternative to calling defs, both plain and
nested. Many examples of the new syntax are in the
“Calling a def with embedded content” section
of the docs.¶

cache module now uses Beaker’s CacheManager
object directly, so that all cache types are included.
memcached is available as both “ext:memcached” and
“memcached”, the latter for backwards compatibility.¶

added “cache_enabled=True” flag to Template,
TemplateLookup. Setting this to False causes cache
operations to “pass through” and execute every time;
this flag should be integrated in Pylons with its own
cache_enabled configuration setting.¶

the Cache object now supports invalidate_def(name),
invalidate_body(), invalidate_closure(name),
invalidate(key), which will remove the given key
from the cache, if it exists. The cache arguments
(i.e. storage type) are derived from whatever has
been already persisted for that template.¶

For cache changes to work fully, Beaker 1.1 is required.
1.0.1 and up will work as well with the exception of
cache expiry. Note that Beaker 1.1 is required
for applications which use dynamically generated keys,
since previous versions will permanently store state in memory
for each individual key, thus consuming all available
memory for an arbitrarily large number of distinct
keys.¶

fixed bug whereby an <%included> template with
<%page> args named the same as a __builtin__ would not
honor the default value specified in <%page>¶

RichTraceback() now accepts an optional traceback object
to be used in place of sys.exc_info()[2]. html_error_template()
and text_error_template() accept an optional
render()-time argument “traceback” which is passed to the
RichTraceback object.¶

added ModuleTemplate class, which allows the construction
of a Template given a Python module generated by a previous
Template. This allows Python modules alone to be used
as templates with no compilation step. Source code
and template source are optional but allow error reporting
to work correctly.¶

fixed a critical issue regarding caching, whereby
a cached block would raise an error when called within a
cache-refresh operation that was initiated after the
initiating template had completed rendering.¶

Speed improvements (as though we needed them, but people
contributed and there you go):¶

added “bytestring passthru” mode, via
disable_unicode=True argument passed to Template or
TemplateLookup. All unicode-awareness and filtering is
turned off, and template modules are generated with
the appropriate magic encoding comment. In this mode,
template expressions can only receive raw bytestrings
or Unicode objects which represent straight ASCII, and
render_unicode() may not be used if multibyte
characters are present. When enabled, speed
improvement around 10-20%. (courtesy
anonymous guest)¶

[bugfixes] fixed codegen bug which occurred when using <%page>
level caching, combined with an expression-based
cache_key, combined with the usage of <%namespace
import=”*”/> - fixed lexer exceptions not cleaning up
temporary files, which could lead to a maximum number
of file descriptors used in the process¶

fixed propagation of ‘caller’ such that nested %def calls
within a <%call> tag’s argument list propigates ‘caller’
to the %call function itself (propigates to the inner
calls too, this is a slight side effect which previously
existed anyway)¶

fixed bug where local.get_namespace() could put an
incorrect “self” in the current context¶

fixed another namespace bug where the namespace functions
did not have access to the correct context containing
their ‘self’ and ‘parent’¶

added “n” filter, disables all filters normally applied to an expression
via <%page> or default_filters (but not those within the filter)¶

added buffer_filters argument, defines filters applied to the return value
of buffered/cached/filtered %defs, after all filters defined with the %def
itself have been applied. allows the creation of default expression filters
that let the output of return-valued %defs “opt out” of that filtering
via passing special attributes or objects.¶

fix to variable scoping for identifiers only referenced within
functions¶

added a path normalization step to lookup so URIs like
“/foo/bar/../etc/../foo” pre-process the “..” tokens before checking
the filesystem¶

fixed/improved “caller” semantics so that undefined caller is
“UNDEFINED”, propigates __nonzero__ method so it evaulates to False if
not present, True otherwise. this way you can say % if caller:n
${caller.body()}n% endif¶

<%include> has an “args” attribute that can pass arguments to the
called template (keyword arguments only, must be declared in that
page’s <%page> tag.)¶

<%include> plus arguments is also programmatically available via
self.include_file(<filename>, **kwargs)¶

further escaping added for multibyte expressions in %def, %call
attributes¶

added “preprocessor” argument to Template, TemplateLookup - is a single
callable or list of callables which will be applied to the template text
before lexing. given the text as an argument, returns the new text.¶

added mako.ext.preprocessors package, contains one preprocessor so far:
‘convert_comments’, which will convert single # comments to the new ##
format¶

fix to parsing of code/expression blocks to insure that non-ascii
characters, combined with a template that indicates a non-standard
encoding, are expanded into backslash-escaped glyphs before being AST
parsed¶

[“unicode”] added “default_filters” argument to Template, TemplateLookup. applies only
to expressions, gets prepended to “expression_filter” arg from <%page>.
defaults to, so that all expressions get stringified into u’’
by default (this is what Mako already does). By setting to [], expressions
are passed through raw.¶

added “imports” argument to Template, TemplateLookup. so you can predefine
a list of import statements at the top of the template. can be used in
conjunction with default_filters.¶

support for CRLF templates…whoops ! welcome to all the windows users.¶