changelog.rst

    .. change::
        :tags:
        :tickets: 99

      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.

    .. change::
        :tags:
        :tickets: 122

      RichTraceback(), html_error_template().render(),
      text_error_template().render() now accept "error"
      and "traceback" as optional arguments, and
      these are now actually used.

    .. change::
        :tags:
        :tickets:

      The exception output generated when
      format_exceptions=True will now be as a Python
      unicode if it occurred during render_unicode(),
      or an encoded string if during render().

    .. change::
        :tags:
        :tickets: 112

      A percent sign can be emitted as the first
      non-whitespace character on a line by escaping
      it as in "%%".

    .. change::
        :tags:
        :tickets: 94

      Template accepts empty control structure, i.e.
      % if: %endif, etc.

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

      The <%page args> tag can now be used in a base
      inheriting template - the full set of render()
      arguments are passed down through the inherits
      chain.  Undeclared arguments go into **pageargs
      as usual.

    .. change::
        :tags:
        :tickets: 109

      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.

    .. change::
        :tags:
        :tickets: 128

      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.

    .. change::
        :tags:
        :tickets: 73

      TemplateLookup raises TopLevelLookupException for
      a given path that is a directory, not a filename,
      instead of passing through to the template to
      generate IOError.


.. changelog::
    :version: 0.2.6
    :released:

    .. change::
        :tags:
        :tickets:

      Fix mako function decorators to preserve the
      original function's name in all cases. Patch
      from Scott Torborg.

    .. change::
        :tags:
        :tickets: 118

      Support the <%namespacename:defname> syntax in
      the babel extractor.

    .. change::
        :tags:
        :tickets: 88

      Further fixes to unicode handling of .py files with the
      html_error_template.

.. changelog::
    :version: 0.2.5
    :released: Mon Sep  7 2009

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets: 101

      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.

    .. change::
        :tags:
        :tickets: 104

      Fixed namespace.__getattr__() to raise
      AttributeError on attribute not found
      instead of RuntimeError.

    .. change::
        :tags:
        :tickets: 97

      Added last_modified accessor to Template,
      returns the time.time() when the module
      was created.

    .. change::
        :tags:
        :tickets: 102

      Fixed lexing support for whitespace
      around '=' sign in defs.

    .. change::
        :tags:
        :tickets: 108

      Removed errant "lower()" in the lexer which
      was causing tags to compile with
      case-insensitive names, thus messing up
      custom <%call> names.

    .. change::
        :tags:
        :tickets: 110

      added "mako.__version__" attribute to
      the base module.

.. changelog::
    :version: 0.2.4
    :released: Tue Dec 23 2008

    .. change::
        :tags:
        :tickets:

      Fixed compatibility with Jython 2.5b1.

.. changelog::
    :version: 0.2.3
    :released: Sun Nov 23 2008

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets:

      added support for Jython 2.5.

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets:

      added "cache" accessor to Template, Namespace.
      e.g.  ${local.cache.get('somekey')} or
      template.cache.invalidate_body()

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets: 92

      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.

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets: 93

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

    .. change::
        :tags:
        :tickets: 88

      fixed the html_error_template not handling tracebacks from
      normal .py files with a magic encoding comment

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets: 90

      fixed Python 2.3 compat. in mako.pyparser

    .. change::
        :tags:
        :tickets:

      fix Babel 0.9.3 compatibility; stripping comment tags is now
      optional (and enabled by default).

.. changelog::
    :version: 0.2.2
    :released: Mon Jun 23 2008

    .. change::
        :tags:
        :tickets: 87

      cached blocks now use the current context when rendering
      an expired section, instead of the original context
      passed in

    .. change::
        :tags:
        :tickets:

      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.

.. changelog::
    :version: 0.2.1
    :released: Mon Jun 16 2008

    .. change::
        :tags:
        :tickets:

      fixed bug where 'output_encoding' parameter would prevent
      render_unicode() from returning a unicode object.

    .. change::
        :tags:
        :tickets:

      bumped magic number, which forces template recompile for
      this version (fixes incompatible compile symbols from 0.1
      series).

    .. change::
        :tags:
        :tickets:

      added a few docs for cache options, specifically those that
      help with memcached.

.. changelog::
    :version: 0.2.0
    :released: Tue Jun  3 2008

    .. change::
        :tags:
        :tickets:

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

    .. change::
        :tags:
        :tickets: 77

      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)

    .. change::
        :tags:
        :tickets: 76

      inlined the "write" function of Context into a local
      template variable. This affords a 12-30% speedup in
      template render time. (idea courtesy same anonymous
      guest)

    .. change::
        :tags:
        :tickets:

      New Features, API changes:

    .. change::
        :tags:
        :tickets: 62

      added "attr" accessor to namespaces. Returns
      attributes configured as module level attributes, i.e.
      within <%! %> sections.  i.e.:

      # somefile.html
      <%!
          foo = 27
      %>

      # some other template
      <%namespace name="myns" file="somefile.html"/>
      ${myns.attr.foo}

      The slight backwards incompatibility here is, you
      can't have namespace defs named "attr" since the
      "attr" descriptor will occlude it.

    .. change::
        :tags:
        :tickets: 78

      cache_key argument can now render arguments passed
      directly to the %page or %def, i.e. <%def
      name="foo(x)" cached="True" cache_key="${x}"/>

    .. change::
        :tags:
        :tickets:

      some functions on Context are now private:
      _push_buffer(), _pop_buffer(),
      caller_stack._push_frame(), caller_stack._pop_frame().

    .. change::
        :tags:
        :tickets: 56, 81

      added a runner script "mako-render" which renders
      standard input as a template to stdout

    .. change::
        :tags: bugfixes
        :tickets: 83, 84

      can now use most names from __builtins__ as variable
      names without explicit declaration (i.e. 'id',
      'exception', 'range', etc.)

    .. change::
        :tags: bugfixes
        :tickets: 84

      can also use builtin names as local variable names
      (i.e. dict, locals) (came from fix for)

    .. change::
        :tags: bugfixes
        :tickets: 68

      fixed bug in python generation when variable names are
      used with identifiers like "else", "finally", etc.
      inside them

    .. change::
        :tags: bugfixes
        :tickets: 69

      fixed codegen bug which occured 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

    .. change::
        :tags: bugfixes
        :tickets: 71

      fixed issue with inline format_exceptions that was
      producing blank exception pages when an inheriting
      template is present

    .. change::
        :tags: bugfixes
        :tickets:

      format_exceptions will apply the encoding options of
      html_error_template() to the buffered output

    .. change::
        :tags: bugfixes
        :tickets: 75

      rewrote the "whitespace adjuster" function to work
      with more elaborate combinations of quotes and
      comments


.. changelog::
    :version: 0.1.10
    :released:

    .. change::
        :tags:
        :tickets:

      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)

    .. change::
        :tags:
        :tickets:

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

    .. change::
        :tags:
        :tickets:

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

.. changelog::
    :version: 0.1.9
    :released:

    .. change::
        :tags:
        :tickets: 47

      filters.Decode filter can also accept a non-basestring
      object and will call str() + unicode() on it

    .. change::
        :tags:
        :tickets: 53

      comments can be placed at the end of control lines,
      i.e. if foo: # a comment,, thanks to
      Paul Colomiets

    .. change::
        :tags:
        :tickets: 16

      fixed expressions and page tag arguments and with embedded
      newlines in CRLF templates, follow up to, thanks
      Eric Woroshow

    .. change::
        :tags:
        :tickets: 51

      added an IOError catch for source file not found in RichTraceback
      exception reporter

.. changelog::
    :version: 0.1.8
    :released: Tue Jun 26 2007

    .. change::
        :tags:
        :tickets:

      variable names declared in render methods by internal
      codegen prefixed by "__M_" to prevent name collisions
      with user code

    .. change::
        :tags:
        :tickets: 45

      added a Babel (http://babel.edgewall.org/) extractor entry
      point, allowing extraction of gettext messages directly from
      mako templates via Babel

    .. change::
        :tags:
        :tickets:

      fix to turbogears plugin to work with dot-separated names
      (i.e. load_template('foo.bar')).  also takes file extension
      as a keyword argument (default is 'mak').

    .. change::
        :tags:
        :tickets: 35

      more tg fix:  fixed, allowing string-based
      templates with tgplugin even if non-compatible args were sent

.. changelog::
    :version: 0.1.7
    :released: Wed Jun 13 2007

    .. change::
        :tags:
        :tickets:

      one small fix to the unit tests to support python 2.3

    .. change::
        :tags:
        :tickets:

      a slight hack to how cache.py detects Beaker's memcached,
      works around unexplained import behavior observed on some
      python 2.3 installations

.. changelog::
    :version: 0.1.6
    :released: Fri May 18 2007

    .. change::
        :tags:
        :tickets:

      caching is now supplied directly by Beaker, which has
      all of MyghtyUtils merged into it now.  The latest Beaker
      (0.7.1) also fixes a bug related to how Mako was using the
      cache API.

    .. change::
        :tags:
        :tickets: 34

      fix to module_directory path generation when the path is "./"

    .. change::
        :tags:
        :tickets: 35

      TGPlugin passes options to string-based templates

    .. change::
        :tags:
        :tickets: 28

      added an explicit stack frame step to template runtime, which
      allows much simpler and hopefully bug-free tracking of 'caller',
      fixes

    .. change::
        :tags:
        :tickets:

      if plain Python defs are used with <%call>, a decorator
      @runtime.supports_callable exists to ensure that the "caller"
      stack is properly handled for the def.

    .. change::
        :tags:
        :tickets: 37

      fix to RichTraceback and exception reporting to get template
      source code as a unicode object

    .. change::
        :tags:
        :tickets: 39

      html_error_template includes options "full=True", "css=True"
      which control generation of HTML tags, CSS

    .. change::
        :tags:
        :tickets: 40

      added the 'encoding_errors' parameter to Template/TemplateLookup
      for specifying the error handler associated with encoding to
      'output_encoding'

    .. change::
        :tags:
        :tickets: 37

      the Template returned by html_error_template now defaults to
      output_encoding=sys.getdefaultencoding(),
      encoding_errors='htmlentityreplace'

    .. change::
        :tags:
        :tickets:

      control lines, i.e. % lines, support backslashes to continue long
      lines (#32)

    .. change::
        :tags:
        :tickets:

      fixed codegen bug when defining <%def> within <%call> within <%call>

    .. change::
        :tags:
        :tickets:

      leading utf-8 BOM in template files is honored according to pep-0263

.. changelog::
    :version: 0.1.5
    :released: Sat Mar 31 2007

    .. change::
        :tags:
        :tickets: 26

      AST expression generation - added in just about everything
      expression-wise from the AST module

    .. change::
        :tags:
        :tickets: 27

      AST parsing, properly detects imports of the form "import foo.bar"

    .. change::
        :tags:
        :tickets:

      fix to lexing of <%docs> tag nested in other tags

    .. change::
        :tags:
        :tickets: 29

      fix to context-arguments inside of <%include> tag which broke
      during 0.1.4

    .. change::
        :tags:
        :tickets:

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

    .. change::
        :tags:
        :tickets:

      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.

.. changelog::
    :version: 0.1.4
    :released: Sat Mar 10 2007

    .. change::
        :tags:
        :tickets:

      got defs-within-defs to be cacheable

    .. change::
        :tags:
        :tickets: 23

      fixes to code parsing/whitespace adjusting where plain python comments
      may contain quote characters

    .. change::
        :tags:
        :tickets:

      fix to variable scoping for identifiers only referenced within
      functions

    .. change::
        :tags:
        :tickets:

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

    .. change::
        :tags:
        :tickets:

      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

    .. change::
        :tags:
        :tickets:

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

    .. change::
        :tags:
        :tickets:

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

    .. change::
        :tags:
        :tickets: 24

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

.. changelog::
    :version: 0.1.3
    :released: Wed Feb 21 2007

    .. change::
        :tags:
        :tickets:

      ***Small Syntax Change*** - the single line comment character is now
      *two* hash signs, i.e. "## this is a comment".  This avoids a common
      collection with CSS selectors.

    .. change::
        :tags:
        :tickets:

      the magic "coding" comment (i.e. # coding:utf-8) will still work with
      either one "#" sign or two for now; two is preferred going forward, i.e.
      ## coding:<someencoding>.

    .. change::
        :tags:
        :tickets:

      new multiline comment form: "<%doc> a comment </%doc>"

    .. change::
        :tags:
        :tickets:

      UNDEFINED evaluates to False

    .. change::
        :tags:
        :tickets:

      improvement to scoping of "caller" variable when using <%call> tag

    .. change::
        :tags:
        :tickets:

      added lexer error for unclosed control-line (%) line

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets:

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

.. changelog::
    :version: 0.1.2
    :released: Thu Feb  1 2007

    .. change::
        :tags:
        :tickets: 11

      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

    .. change::
        :tags:
        :tickets:

      all template lexing converts the template to unicode first, to
      immediately catch any encoding issues and ensure internal unicode
      representation.

    .. change::
        :tags:
        :tickets:

      added module_filename argument to Template to allow specification of a
      specific module file

    .. change::
        :tags:
        :tickets: 14

      added modulename_callable to TemplateLookup to allow a function to
      determine module filenames (takes filename, uri arguments). used for

    .. change::
        :tags:
        :tickets:

      added optional input_encoding flag to Template, to allow sending a
      unicode() object with no magic encoding comment

    .. change::
        :tags:
        :tickets:

      "expression_filter" argument in <%page> applies only to expressions

    .. change::
        :tags: "unicode"
        :tickets:

      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.

    .. change::
        :tags:
        :tickets:

      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.

    .. change::
        :tags:
        :tickets: 16

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

    .. change::
        :tags:
        :tickets:

      small fix to local variable propigation for locals that are conditionally
      declared

    .. change::
        :tags:
        :tickets:

      got "top level" def calls to work, i.e. template.get_def("somedef").render()

.. changelog::
    :version: 0.1.1
    :released: Sun Jan 14 2007

    .. change::
        :tags:
        :tickets: 8

      buffet plugin supports string-based templates, allows ToscaWidgets to work

    .. change::
        :tags:
        :tickets:

      AST parsing fixes: fixed TryExcept identifier parsing

    .. change::
        :tags:
        :tickets:

      removed textmate tmbundle from contrib and into separate SVN location;
      windows users cant handle those files, setuptools not very good at
      "pruning" certain directories

    .. change::
        :tags:
        :tickets:

      fix so that "cache_timeout" parameter is propigated

    .. change::
        :tags:
        :tickets: