even more tests, fixed severe bug with autoescaping.
--HG--
branch : trunk
diff --git a/docs/api.rst b/docs/api.rst
index 95064b5..cba97ea 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -56,8 +56,8 @@
High Level API
--------------
-.. autoclass:: jinja2.environment.Environment([options])
- :members: from_string, get_template, join_path, parse, lex, extend
+.. autoclass:: Environment([options])
+ :members: from_string, get_template, join_path, extend
.. attribute:: shared
@@ -96,8 +96,42 @@
.. automethod:: overlay([options])
+ .. method:: undefined([hint,] [obj,] name[, exc])
-.. autoclass:: jinja2.Template
+ Creates a new :class:`Undefined` object for `name`. This is useful
+ for filters or functions that may return undefined objects for
+ some operations. All parameters except of `hint` should be provided
+ as keyword parameters for better readability. The `hint` is used as
+ error message for the exception if provided, otherwise the error
+ message generated from `obj` and `name` automatically. The exception
+ provided as `exc` is raised if something with the generated undefined
+ object is done that the undefined object does not allow. The default
+ exception is :exc:`UndefinedError`. If a `hint` is provided the
+ `name` may be ommited.
+
+ The most common way to create an undefined object is by providing
+ a name only::
+
+ return environment.undefined(name='some_name')
+
+ This means that the name `some_name` is not defined. If the name
+ was from an attribute of an object it makes sense to tell the
+ undefined object the holder object to improve the error message::
+
+ if not hasattr(obj, 'attr'):
+ return environment.undefined(obj=obj, name='attr')
+
+ For a more complex example you can provide a hint. For example
+ the :func:`first` filter creates an undefined object that way::
+
+ return environment.undefined('no first item, sequence was empty')
+
+ If it the `name` or `obj` is known (for example because an attribute
+ was accessed) it shold be passed to the undefined object, even if
+ a custom `hint` is provided. This gives undefined objects the
+ possibility to enhance the error message.
+
+.. autoclass:: Template
:members: make_module, module, new_context
.. attribute:: globals
@@ -111,6 +145,11 @@
The loading name of the template. If the template was loaded from a
string this is `None`.
+ .. attribute:: filename
+
+ The filename of the template on the file system if it was loaded from
+ there. Otherwise this is `None`.
+
.. automethod:: render([context])
.. automethod:: generate([context])
@@ -125,7 +164,7 @@
.. _identifier-naming:
Notes on Identifiers
-~~~~~~~~~~~~~~~~~~~~
+--------------------
Jinja2 uses the regular Python 2.x naming rules. Valid identifiers have to
match ``[a-zA-Z_][a-zA-Z0-9_]*``. As a matter of fact non ASCII characters
@@ -153,11 +192,13 @@
The closest to regular Python behavior is the `StrictUndefined` which
disallows all operations beside testing if it's an undefined object.
-.. autoclass:: jinja2.runtime.Undefined
+.. autoclass:: jinja2.runtime.Undefined()
-.. autoclass:: jinja2.runtime.DebugUndefined
+.. autoclass:: jinja2.runtime.DebugUndefined()
-.. autoclass:: jinja2.runtime.StrictUndefined
+.. autoclass:: jinja2.runtime.StrictUndefined()
+
+Undefined objects are created by calling :attr:`undefined`.
The Context
@@ -170,8 +211,9 @@
A dict of read only, global variables the template looks up. These
can either come from another :class:`Context`, from the
- :attr:`Environment.globals` or :attr:`Template.globals`. It must not
- be altered.
+ :attr:`Environment.globals` or :attr:`Template.globals` or points
+ to a dict created by combining the globals with the variables
+ passed to the render function. It must not be altered.
.. attribute:: vars
@@ -399,3 +441,40 @@
that should be available all the time. Additionally :attr:`Template.globals`
exist that are variables available to a specific template that are available
to all :meth:`~Template.render` calls.
+
+
+Low Level API
+-------------
+
+The low level API exposes functionality that can be useful to understand some
+implementation details, debugging purposes or advanced :ref:`extension
+<jinja-extensions>` techniques.
+
+.. automethod:: Environment.lex
+
+.. automethod:: Environment.parse
+
+.. automethod:: Template.new_context
+
+.. method:: Template.root_render_func(context)
+
+ This is the low level render function. It's passed a :class:`Context`
+ that has to be created by :meth:`new_context` of the same template or
+ a compatible template. This render function is generated by the
+ compiler from the template code and returns a generator that yields
+ unicode strings.
+
+ If an exception in the template code happens the template engine will
+ not rewrite the exception but pass through the original one. As a
+ matter of fact this function should only be called from within a
+ :meth:`render` / :meth:`generate` / :meth:`stream` call.
+
+.. attribute:: Template.blocks
+
+ A dict of block render functions. Each of these functions works exactly
+ like the :meth:`root_render_func` with the same limitations.
+
+.. attribute:: Template.is_up_to_date
+
+ This attribute is `False` if there is a newer version of the template
+ available, otherwise `True`.