changelog.rst

=========
Changelog
=========

1.0
===

.. changelog::
    :version: 1.0.2

    .. change::
        :tags: bug
        :pullreq: bitbucket:18

      Update the Lingua translation extraction plugin to correctly
      handle templates mixing Python control statements (such as if,
      for and while) with template fragments. Pull request courtesy
      Laurent Daverio.

    .. change::
        :tags: feature
        :tickets: 236

      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.

      .. seealso::

        :ref:`syntax_exiting_early`

.. changelog::
    :version: 1.0.1
    :released: Thu Jan 22 2015

    .. change::
        :tags: feature
        :pullreq: bitbucket:9

      Added support for Lingua, a translation extraction system as an
      alternative to Babel.  Pull request courtesy Wichert Akkerman.

    .. change::
        :tags: bug, py3k
        :pullreq: bitbucket:11

      Modernized the examples/wsgi/run_wsgi.py file for Py3k.
      Pull requset courtesy Cody Taylor.

.. changelog::
    :version: 1.0.0
    :released: Sun Jun 8 2014

    .. change::
        :tags: bug, py2k
        :pullreq: bitbucket:8

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

    .. change::
        :tags: bug, py2k, filters
        :pullreq: bitbucket:7

      Added an html_escape filter that works in "non unicode" mode.
      Previously, when using ``disable_unicode=True``, the ``u`` filter
      would fail to handle non-ASCII bytes properly.  Pull request
      courtesy George Xie.

    .. change::
        :tags: 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.

    .. change::
        :tags: 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.

    .. change::
        :tags: bug, py3k

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

    .. change::
        :tags: bug, py3k
        :tickets: 227

      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.

    .. change::
        :tags: feature
        :pullreq: bitbucket:5

      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.

    .. change::
        :tags: feature
        :pullreq: bitbucket:4

      The mako-render script will now catch exceptions and run them
      into the text error handler, and exit with a non-zero exit code.
      Pull request courtesy Derek Harland.

    .. change::
        :tags: bug
        :pullreq: bitbucket:2

      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.

    .. change::
        :tags: feature, py3k
        :pullreq: github:7

      Support is added for Python 3 "keyword only" arguments, as used in
      defs.  Pull request courtesy Eevee.


0.9
===

.. changelog::
    :version: 0.9.1
    :released: Thu Dec 26 2013

    .. change::
        :tags: bug
        :tickets: 225

      Fixed bug in Babel plugin where translator comments
      would be lost if intervening text nodes were encountered.
      Fix courtesy Ned Batchelder.

    .. change::
        :tags: bug
        :tickets:

      Fixed TGPlugin.render method to support unicode template
      names in Py2K - courtesy Vladimir Magamedov.

    .. change::
        :tags: bug
        :tickets:

      Fixed an AST issue that was preventing correct operation
      under alpha versions of Python 3.4.  Pullreq courtesy Zer0-.

    .. change::
        :tags: bug
        :tickets:

      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.

    .. change::
        :tags: bug
        :tickets: 224

      Fixed issue where an old lexer rule prevented a template line
      which looked like "#*" from being correctly parsed.

.. changelog::
    :version: 0.9.0
    :released: Tue Aug 27 2013

    .. change::
        :tags: bug
        :tickets: 219

      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().

    .. change::
        :tags: bug
        :tickets:

      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.

    .. change::
        :tags: bug
        :tickets: 187

      The Babel plugin has been repaired to work on Python 3.

    .. change::
        :tags: bug
        :tickets: 207

      Using <%namespace import="*" module="somemodule"/> now
      skips over module elements that are not explcitly callable,
      avoiding TypeError when trying to produce partials.

    .. change::
        :tags: bug
        :tickets: 190

      Fixed Py3K bug where a "lambda" expression was not
      interpreted correctly within a template tag; also
      fixed in Py2.4.

0.8
===

.. changelog::
    :version: 0.8.1
    :released: Fri May 24 2013

    .. change::
        :tags: bug
        :tickets: 216

      Changed setup.py to skip installing markupsafe
      if Python version is < 2.6 or is between 3.0 and
      less than 3.3, as Markupsafe now only supports 2.6->2.X,
      3.3->3.X.

    .. change::
        :tags: bug
        :tickets: 214

      Fixed regression where "entity" filter wasn't
      converted for py3k properly (added tests.)

    .. change::
        :tags: bug
        :tickets: 212

      Fixed bug where mako-render script wasn't
      compatible with Py3k.

    .. change::
        :tags: bug
        :tickets: 213

      Cleaned up all the various deprecation/
      file warnings when running the tests under
      various Pythons with warnings turned on.

.. changelog::
    :version: 0.8.0
    :released: Wed Apr 10 2013

    .. change::
        :tags: feature
        :tickets:

      Performance improvement to the
      "legacy" HTML escape feature, used for XML
      escaping and when markupsafe isn't present,
      courtesy George Xie.

    .. change::
        :tags: bug
        :tickets: 209

      Fixed bug whereby an exception in Python 3
      against a module compiled to the filesystem would
      fail trying to produce a RichTraceback due to the
      content being in bytes.

    .. change::
        :tags: bug
        :tickets: 208

      Change default for compile()->reserved_names
      from tuple to frozenset, as this is expected to be
      a set by default.

    .. change::
        :tags: feature
        :tickets:

      Code has been reworked to support Python 2.4->
      Python 3.xx in place.  2to3 no longer needed.

    .. change::
        :tags: feature
        :tickets:

      Added lexer_cls argument to Template,
      TemplateLookup, allows alternate Lexer classes
      to be used.

    .. change::
        :tags: feature
        :tickets:

      Added future_imports parameter to Template
      and TemplateLookup, renders the __future__ header
      with desired capabilities at the top of the generated
      template module.  Courtesy Ben Trofatter.

0.7
===

.. changelog::
    :version: 0.7.3
    :released: Wed Nov 7 2012

    .. change::
        :tags: bug
        :tickets:

      legacy_html_escape function, used when
      Markupsafe isn't installed, was using an inline-compiled
      regexp which causes major slowdowns on Python 3.3;
      is now precompiled.

    .. change::
        :tags: bug
        :tickets: 201

      AST supporting now supports tuple-packed
      function arguments inside pure-python def
      or lambda expressions.

    .. change::
        :tags: bug
        :tickets:

      Fixed Py3K bug in the Babel extension.

    .. change::
        :tags: bug
        :tickets:

      Fixed the "filter" attribute of the
      <%text> tag so that it pulls locally specified
      identifiers from the context the same
      way as that of <%block> and <%filter>.

    .. change::
        :tags: bug
        :tickets:

      Fixed bug in plugin loader to correctly
      raise exception when non-existent plugin
      is specified.

.. changelog::
    :version: 0.7.2
    :released: Fri Jul 20 2012

    .. change::
        :tags: bug
        :tickets: 193

      Fixed regression in 0.7.1 where AST
      parsing for Py2.4 was broken.

.. changelog::
    :version: 0.7.1
    :released: Sun Jul 8 2012

    .. change::
        :tags: feature
        :tickets: 146

      Control lines with no bodies will
      now succeed, as "pass" is added for these
      when no statements are otherwise present.
      Courtesy Ben Trofatter

    .. change::
        :tags: bug
        :tickets: 192

      Fixed some long-broken scoping behavior
      involving variables declared in defs and such,
      which only became apparent when
      the strict_undefined flag was turned on.

    .. change::
        :tags: bug
        :tickets: 191

      Can now use strict_undefined at the
      same time args passed to def() are used
      by other elements of the <%def> tag.

.. changelog::
    :version: 0.7.0
    :released: Fri Mar 30 2012

    .. change::
        :tags: feature
        :tickets: 125

      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

    .. change::
        :tags: feature
        :tickets:

      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".

    .. change::
        :tags: feature
        :tickets: 95

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

    .. change::
        :tags: feature
        :tickets: 147

      Added support for context managers,
      i.e. "% with x as e:/ % endwith" support.
      Courtesy Ben Trofatter

    .. change::
        :tags: feature
        :tickets: 185

      Added class-level flag to CacheImpl
      "pass_context"; when True, the keyword argument
      'context' will be passed to get_or_create()
      containing the Mako Context object.

    .. change::
        :tags: bug
        :tickets: 182

      Fixed some Py3K resource warnings due
      to filehandles being implicitly closed.

    .. change::
        :tags: bug
        :tickets: 186

      Fixed endless recursion bug when
      nesting multiple def-calls with content.
      Thanks to Jeff Dairiki.

    .. change::
        :tags: feature
        :tickets:

      Added Jinja2 to the example
      benchmark suite, courtesy Vincent Férotin

Older Versions
==============

.. changelog::
    :version: 0.6.2
    :released: Thu Feb 2 2012

    .. change::
        :tags: bug
        :tickets: 86, 20

      The ${{"foo":"bar"}} parsing issue is fixed!!
      The legendary Eevee has slain the dragon!.  Also fixes quoting issue
      at.

.. changelog::
    :version: 0.6.1
    :released: Sat Jan 28 2012

    .. change::
        :tags: bug
        :tickets:

      Added special compatibility for the 0.5.0
      Cache() constructor, which was preventing file
      version checks and not allowing Mako 0.6 to
      recompile the module files.

.. changelog::
    :version: 0.6.0
    :released: Sat Jan 21 2012

    .. change::
        :tags: feature
        :tickets:

      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.

    .. change::
        :tags: feature
        :tickets:

      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.

    .. change::
        :tags: feature
        :tickets:

      The 'put' method on Cache is now
      'set'.  'put' is there for backwards compatibility.

    .. change::
        :tags: feature
        :tickets:

      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.

    .. change::
        :tags: feature
        :tickets:

      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'}

    .. change::
        :tags: feature/bug
        :tickets: 180

      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)

    .. change::
        :tags: feature
        :tickets: 178

      Added "--var name=value" option to the mako-render
      script, allows passing of kw to the template from
      the command line.

    .. change::
        :tags: feature
        :tickets: 181

      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.

    .. change::
        :tags: bug
        :tickets: 142

      The exception message in the html_error_template
      is now escaped with the HTML filter.

    .. change::
        :tags: bug
        :tickets: 173

      Added "white-space:pre" style to html_error_template()
      for code blocks so that indentation is preserved

    .. change::
        :tags: bug
        :tickets: 175

      The "benchmark" example is now Python 3 compatible
      (even though several of those old template libs aren't
      available on Py3K, so YMMV)


.. changelog::
    :version: 0.5.0
    :released: Wed Sep 28 2011

    .. change::
        :tags:
        :tickets: 174

      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.


.. changelog::
    :version: 0.4.2
    :released: Fri Aug 5 2011

    .. change::
        :tags:
        :tickets: 170

      Fixed bug regarding <%call>/def calls w/ content
      whereby the identity of the "caller" callable
      inside the <%def> would be corrupted by the
      presence of another <%call> in the same block.

    .. change::
        :tags:
        :tickets: 169

      Fixed the babel plugin to accommodate <%block>

.. changelog::
    :version: 0.4.1
    :released: Wed Apr 6 2011

    .. change::
        :tags:
        :tickets: 164

      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.

    .. change::
        :tags:
        :tickets: 165

      a slight adjustment to the "highlight" logic
      for generating template bound stacktraces.
      Will stick to known template source lines
      without any extra guessing.

.. changelog::
    :version: 0.4.0
    :released: Sun Mar 6 2011

    .. change::
        :tags:
        :tickets:

      A 20% speedup for a basic two-page
      inheritance setup rendering
      a table of escaped data
      (see http://techspot.zzzeek.org/2010/11/19/quick-mako-vs.-jinja-speed-test/).
      A few configurational changes which
      affect those in the I-don't-do-unicode
      camp should be noted below.

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets:

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

    .. change::
        :tags:
        :tickets: 156

      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.

    .. change::
        :tags:
        :tickets: 159

      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.


.. changelog::
    :version: 0.3.6
    :released: Sat Nov 13 2010

    .. change::
        :tags:
        :tickets: 126

      Documentation is on Sphinx.

    .. change::
        :tags:
        :tickets: 154

      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.

    .. change::
        :tags:
        :tickets: 153

      The Beaker import (or attempt thereof)
      is delayed until actually needed;
      this to remove the performance penalty
      from startup, particularly for
      "single execution" environments
      such as shell scripts.

    .. change::
        :tags:
        :tickets: 155

      Patch to lexer to not generate an empty
      '' write in the case of backslash-ended
      lines.

    .. change::
        :tags:
        :tickets: 148

      Fixed missing **extra collection in
      setup.py which prevented setup.py
      from running 2to3 on install.

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets:

      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.

.. changelog::
    :version: 0.3.5
    :released: Sun Oct 24 2010

    .. change::
        :tags:
        :tickets: 141

      The <%namespace> tag allows expressions
      for the `file` argument, i.e. with ${}.
      The `context` variable, if needed,
      must be referenced explicitly.

    .. change::
        :tags:
        :tickets:

      ${} expressions embedded in tags,
      such as <%foo:bar x="${...}">, now
      allow multiline Python expressions.

    .. change::
        :tags:
        :tickets:

      Fixed previously non-covered regular
      expression, such that using a ${} expression
      inside of a tag element that doesn't allow
      them raises a CompileException instead of
      silently failing.

    .. change::
        :tags:
        :tickets: 151

      Added a try/except around "import markupsafe".
      This to support GAE which can't run markupsafe. No idea whatsoever if the
      install_requires in setup.py also breaks GAE,
      couldn't get an answer on this.

.. changelog::
    :version: 0.3.4
    :released: Tue Jun 22 2010

    .. change::
        :tags:
        :tickets:

      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.

      Note that Pylons by default doesn't
      use Mako's filter - check your
      environment.py file.

    .. change::
        :tags:
        :tickets: 137

      Fixed call to "unicode.strip" in
      exceptions.text_error_template which
      is not Py3k compatible.

.. changelog::
    :version: 0.3.3
    :released: Mon May 31 2010

    .. change::
        :tags:
        :tickets: 135

      Added conditional to RichTraceback
      such that if no traceback is passed
      and sys.exc_info() has been reset,
      the formatter just returns blank
      for the "traceback" portion.

    .. change::
        :tags:
        :tickets: 131

      Fixed sometimes incorrect usage of
      exc.__class__.__name__
      in html/text error templates when using
      Python 2.4

    .. change::
        :tags:
        :tickets:

      Fixed broken @property decorator on
      template.last_modified

    .. change::
        :tags:
        :tickets: 132

      Fixed error formatting when a stacktrace
      line contains no line number, as in when
      inside an eval/exec-generated function.

    .. change::
        :tags:
        :tickets:

      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.

.. changelog::
    :version: 0.3.2
    :released: Thu Mar 11 2010

    .. change::
        :tags:
        :tickets: 116

      Calling a def from the top, via
      template.get_def(...).render() now checks the
      argument signature the same way as it did in
      0.2.5, so that TypeError is not raised.
      reopen of

.. changelog::
    :version: 0.3.1
    :released: Sun Mar 7 2010

    .. change::
        :tags:
        :tickets: 129

      Fixed incorrect dir name in setup.py

.. changelog::
    :version: 0.3.0
    :released: Fri Mar 5 2010

    .. change::
        :tags:
        :tickets: 123