.. _runtime_toplevel:

============================
The Mako Runtime Environment
============================

This section describes a little bit about the objects and
built-in functions that are available in templates.

.. _context:

Context
=======

The :class:`.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.  Within the template
environment, it is available via the :ref:`reserved name <reserved_names>`
``context``.  The :class:`.Context` 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 :meth:`~.Template.render` function and
some built-in variables provided by Mako's runtime environment.

The Buffer
----------

The buffer is stored within the :class:`.Context`, and writing
to it is achieved by calling the :meth:`~.Context.write` method
-- in a template this looks like ``context.write('some string')``.
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
:ref:`filtering_toplevel`, or if you want to programmatically
send content to the output stream, such as within a ``<% %>``
block.

.. sourcecode:: mako

    <%
        context.write("some programmatic text")
    %>

The actual buffer may or may not be the original buffer sent to
the :class:`.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_vars:

Context 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
:class:`.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
:class:`.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 :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
  is to specify the option ``strict_undefined=True``
  to the :class:`.Template` or :class:`.TemplateLookup`.  This will cause
  any non-present variables to raise an immediate ``NameError``
  which includes the name of the variable in its message
  when :meth:`~.Template.render` is called -- ``UNDEFINED`` is not used.

  .. versionadded:: 0.3.6

* **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 :class:`.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, it's 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:

  .. sourcecode:: mako

        % if someval is UNDEFINED:
            someval is: no value
        % else:
            someval is: ${someval}
        % endif

Another facet of the :class:`.Context` is that its dictionary of
variables is **immutable**. Whatever is set when
:meth:`~.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 :class:`.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 :class:`.Context` will not necessarily make that value
available in other parts of the template's execution. Examples
of where Mako creates copies of the :class:`.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 :class:`.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 :class:`.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:

  .. sourcecode:: python

      output = template.render(attributes={})

  Within a template, just reference the dictionary:

  .. sourcecode:: mako

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

Significant members of :class:`.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 isn't 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.:

  .. sourcecode:: mako

        ${next.body(**context.kwargs)}

* ``write(text)`` - write some text to the current output
  stream.
* ``lookup`` - returns the :class:`.TemplateLookup` instance that is
  used for all file-lookups within the current execution (even
  though individual :class:`.Template` instances can conceivably have
  different instances of a :class:`.TemplateLookup`, only the
  :class:`.TemplateLookup` of the originally-called :class:`.Template` gets
  used in a particular execution).

.. _loop_context:

The Loop Context
================

Within ``% for`` blocks, the :ref:`reserved name<reserved_names>` ``loop``
is available.  ``loop`` tracks the progress of
the ``for`` loop and makes it easy to use the iteration state to control
template behavior:

.. sourcecode:: mako

    <ul>
    % for a in ("one", "two", "three"):
        <li>Item ${loop.index}: ${a}</li>
    % endfor
    </ul>

.. versionadded:: 0.7

Iterations
----------

Regardless of the type of iterable you're looping over, ``loop`` always tracks
the 0-indexed iteration count (available at ``loop.index``), its parity
(through the ``loop.even`` and ``loop.odd`` bools), and ``loop.first``, a bool
indicating whether the loop is on its first iteration.  If your iterable
provides a ``__len__`` method, ``loop`` also provides access to
a count of iterations remaining at ``loop.reverse_index`` and ``loop.last``,
a bool indicating whether the loop is on its last iteration; accessing these
without ``__len__`` will raise a ``TypeError``.

Cycling
-------

Cycling is available regardless of whether the iterable you're using provides
a ``__len__`` method.  Prior to Mako 0.7, you might have generated a simple
zebra striped list using ``enumerate``:

.. sourcecode:: mako

    <ul>
    % for i, item in enumerate(('spam', 'ham', 'eggs')):
      <li class="${'odd' if i % 2 else 'even'}">${item}</li>
    % endfor
    </ul>

With ``loop.cycle``, you get the same results with cleaner code and less prep work:

.. sourcecode:: mako

    <ul>
    % for item in ('spam', 'ham', 'eggs'):
      <li class="${loop.cycle('even', 'odd')}">${item}</li>
    % endfor
    </ul>

Both approaches produce output like the following:

.. sourcecode:: html

    <ul>
      <li class="even">spam</li>
      <li class="odd">ham</li>
      <li class="even">eggs</li>
    </ul>

Parent Loops
------------

Loop contexts can also be transparently nested, and the Mako runtime will do
the right thing and manage the scope for you.  You can access the parent loop
context through ``loop.parent``.

This allows you to reach all the way back up through the loop stack by
chaining ``parent`` attribute accesses, i.e. ``loop.parent.parent....`` as
long as the stack depth isn't exceeded.  For example, you can use the parent
loop to make a checkered table:

.. sourcecode:: mako

    <table>
    % for consonant in 'pbj':
      <tr>
      % for vowel in 'iou':
        <td class="${'black' if (loop.parent.even == loop.even) else 'red'}">
          ${consonant + vowel}t
        </td>
      % endfor
      </tr>
    % endfor
    </table>

.. sourcecode:: html

    <table>
      <tr>
        <td class="black">
          pit
        </td>
        <td class="red">
          pot
        </td>
        <td class="black">
          put
        </td>
      </tr>
      <tr>
        <td class="red">
          bit
        </td>
        <td class="black">
          bot
        </td>
        <td class="red">
          but
        </td>
      </tr>
      <tr>
        <td class="black">
          jit
        </td>
        <td class="red">
          jot
        </td>
        <td class="black">
          jut
        </td>
      </tr>
    </table>

.. _migrating_loop:

Migrating Legacy Templates that Use the Word "loop"
---------------------------------------------------

.. versionchanged:: 0.7
   The ``loop`` name is now :ref:`reserved <reserved_names>` in Mako,
   which means a template that refers to a variable named ``loop``
   won't function correctly when used in Mako 0.7.

To ease the transition for such systems, the feature can be disabled across the board for
all templates, then re-enabled on a per-template basis for those templates which wish
to make use of the new system.

First, the ``enable_loop=False`` flag is passed to either the :class:`.TemplateLookup`
or :class:`.Template` object in use:

.. sourcecode:: python

    lookup = TemplateLookup(directories=['/docs'], enable_loop=False)

or:

.. sourcecode:: python

    template = Template("some template", enable_loop=False)

An individual template can make usage of the feature when ``enable_loop`` is set to
``False`` by switching it back on within the ``<%page>`` tag:

.. sourcecode:: mako

    <%page enable_loop="True"/>

    % for i in collection:
        ${i} ${loop.index}
    % endfor

Using the above scheme, it's safe to pass the name ``loop`` to the :meth:`.Template.render`
method as well as to freely make usage of a variable named ``loop`` within a template, provided
the ``<%page>`` tag doesn't override it.  New templates that want to use the ``loop`` context
can then set up ``<%page enable_loop="True"/>`` to use the new feature without affecting
old templates.

All the Built-in Names
======================

A one-stop shop for all the names Mako defines. Most of these
names are instances of :class:`.Namespace`, which are described
in the next section, :ref:`namespaces_toplevel`. Also, most of
these names other than ``context``, ``UNDEFINED``, and ``loop`` are
also present *within* the :class:`.Context` itself.   The names
``context``, ``loop`` and ``UNDEFINED`` themselves can't be passed
to the context and can't be substituted -- see the section :ref:`reserved_names`.

* ``context`` - this is the :class:`.Context` object, introduced
  at :ref:`context`.
* ``local`` - the namespace of the current template, described
  in :ref:`namespaces_builtin`.
* ``self`` - the namespace of the topmost template in an
  inheritance chain (if any, otherwise the same as ``local``),
  mostly described in :ref:`inheritance_toplevel`.
* ``parent`` - the namespace of the parent template in an
  inheritance chain (otherwise undefined); see
  :ref:`inheritance_toplevel`.
* ``next`` - the namespace of the next template in an
  inheritance chain (otherwise undefined); see
  :ref:`inheritance_toplevel`.
* ``caller`` - a "mini" namespace created when using the
  ``<%call>`` tag to define a "def call with content"; described
  in :ref:`defs_with_content`.
* ``loop`` - this provides access to :class:`.LoopContext` objects when
  they are requested within ``% for`` loops, introduced at :ref:`loop_context`.
* ``capture`` - a function that calls a given def and captures
  its resulting content into a string, which is returned. Usage
  is described in :ref:`filtering_toplevel`.
* ``UNDEFINED`` - a global singleton that is applied to all
  otherwise uninitialized template variables that were not
  located within the :class:`.Context` when rendering began,
  unless the :class:`.Template` flag ``strict_undefined``
  is set to ``True``. ``UNDEFINED`` is
  an instance of :class:`.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
  :ref:`namespaces_body`.

.. _reserved_names:

Reserved Names
--------------

Mako has a few names that are considered to be "reserved" and can't be used
as variable names.

.. versionchanged:: 0.7
   Mako raises an error if these words are found passed to the template
   as context arguments, whereas in previous versions they'd be silently
   ignored or lead to other error messages.

* ``context`` - see :ref:`context`.
* ``UNDEFINED`` - see :ref:`context_vars`.
* ``loop`` - see :ref:`loop_context`.  Note this can be disabled for legacy templates
  via the ``enable_loop=False`` argument; see :ref:`migrating_loop`.

API Reference
=============

.. autoclass:: mako.runtime.Context
    :show-inheritance:
    :members:

.. autoclass:: mako.runtime.LoopContext
    :show-inheritance:
    :members:

.. autoclass:: mako.runtime.Undefined
    :show-inheritance: