some more documentation updates and minor code cleanups. Additionally True and true in the template are the same now, same for false/False and none/None.
--HG--
branch : trunk
diff --git a/docs/_static/implementation.png b/docs/_static/implementation.png
new file mode 100644
index 0000000..21deae6
--- /dev/null
+++ b/docs/_static/implementation.png
Binary files differ
diff --git a/docs/_static/note.png b/docs/_static/note.png
new file mode 100644
index 0000000..c484da6
--- /dev/null
+++ b/docs/_static/note.png
Binary files differ
diff --git a/docs/_static/style.css b/docs/_static/style.css
index 8bfa23e..c5894f6 100644
--- a/docs/_static/style.css
+++ b/docs/_static/style.css
@@ -209,20 +209,25 @@
div.admonition {
margin: 10px 0 10px 0;
- padding: 10px;
+ padding: 10px 10px 10px 60px;
border: 1px solid #ccc;
- background-color: #f8f8f8;
}
div.admonition p.admonition-title {
- margin: -3px 0 5px 0;
+ background-color: #b41717;
+ color: white;
+ margin: -10px -10px 10px -60px;
+ padding: 4px 10px 4px 10px;
font-weight: bold;
- color: #b41717;
- font-size: 16px;
+ font-size: 15px;
}
-div.admonition p {
- margin: 0 0 0 40px;
+div.admonition-note {
+ background: url(note.png) no-repeat 10px 40px;
+}
+
+div.admonition-implementation {
+ background: url(implementation.png) no-repeat 10px 40px;
}
#toc {
@@ -296,7 +301,8 @@
dl.function dt,
dl.class dt,
dl.exception dt,
-dl.method dt {
+dl.method dt,
+dl.attribute dt {
font-weight: normal;
}
diff --git a/docs/api.rst b/docs/api.rst
index cc9e9d8..0dce618 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -95,6 +95,11 @@
High Level API
--------------
+The high-level API is the API you will use in the application to load and
+render Jinja2 templates. The :ref:`low-level-api` on the other side is only
+useful if you want to dig deeper into Jinja2 or :ref:`develop extensions
+<jinja-extensions>`.
+
.. autoclass:: Environment([options])
:members: from_string, get_template, join_path, extend
@@ -171,7 +176,7 @@
possibility to enhance the error message.
.. autoclass:: Template
- :members: make_module, module, new_context
+ :members: module, make_module
.. attribute:: globals
@@ -233,12 +238,62 @@
.. autoclass:: jinja2.runtime.Undefined()
+ .. attribute:: _undefined_hint
+
+ Either `None` or an unicode string with the error message for
+ the undefined object.
+
+ .. attribute:: _undefined_obj
+
+ Either `None` or the owner object that caused the undefined object
+ to be created (for example because an attribute does not exist).
+
+ .. attribute:: _undefined_name
+
+ The name for the undefined variable / attribute or just `None`
+ if no such information exists.
+
+ .. attribute:: _undefined_exception
+
+ The exception that the undefined object wants to raise. This
+ is usually one of :exc:`UndefinedError` or :exc:`SecurityError`.
+
+ .. method:: _fail_with_undefined_error(\*args, \**kwargs)
+
+ When called with any arguments this method raises
+ :attr:`_undefined_exception` with an error message generated
+ from the undefined hints stored on the undefined object.
+
.. autoclass:: jinja2.runtime.DebugUndefined()
.. autoclass:: jinja2.runtime.StrictUndefined()
Undefined objects are created by calling :attr:`undefined`.
+.. admonition:: Implementation
+
+ :class:`Undefined` objects are implemented by overriding the special
+ `__underscore__` methods. For example the default :class:`Undefined`
+ class implements `__unicode__` in a way that it returns an empty
+ string, however `__int__` and others still fail with an exception. To
+ allow conversion to int by returning ``0`` you can implement your own::
+
+ class NullUndefined(Undefined):
+ def __int__(self):
+ return 0
+ def __float__(self):
+ return 0.0
+
+ To disallow a method, just override it and raise
+ :attr:`_undefined_exception`. Because this is a very common idom in
+ undefined objects there is the helper method
+ :meth:`_fail_with_undefined_error`. That does that automatically. Here
+ a class that works like the regular :class:`UndefinedError` but chokes
+ on iteration::
+
+ class NonIterableUndefined(Undefined):
+ __iter__ = Undefined._fail_with_undefined_error
+
The Context
-----------
@@ -283,6 +338,20 @@
blocks registered. The last item in each list is the current active
block (latest in the inheritance chain).
+ .. automethod:: jinja2.runtime.Context.call(callable, \*args, \**kwargs)
+
+
+.. admonition:: Implementation
+
+ Context is immutable for the same reason Python's frame locals are
+ immutable inside functions. Both Jinja2 and Python are not using the
+ context / frame locals as data storage for variables but only as primary
+ data source.
+
+ When a template accesses a variable the template does not define, Jinja2
+ looks up the variable in the context, after that the variable is treated
+ as if it was defined in the template.
+
.. _loaders:
@@ -330,13 +399,17 @@
.. function:: escape(s)
- Convert the characters &, <, >, and " in string s to HTML-safe sequences.
- Use this if you need to display text that might contain such characters
- in HTML. This function will not escaped objects that do have an HTML
- representation such as already escaped data.
+ Convert the characters ``&``, ``<``, ``>``, ``'``, and ``"`` in string `s`
+ to HTML-safe sequences. Use this if you need to display text that might
+ contain such characters in HTML. This function will not escaped objects
+ that do have an HTML representation such as already escaped data.
+
+ The return value is a :class:`Markup` string.
.. autofunction:: jinja2.utils.clear_caches
+.. autofunction:: jinja2.utils.is_undefined
+
.. autoclass:: jinja2.utils.Markup
@@ -482,6 +555,8 @@
to all :meth:`~Template.render` calls.
+.. _low-level-api:
+
Low Level API
-------------
@@ -518,3 +593,10 @@
This attribute is `False` if there is a newer version of the template
available, otherwise `True`.
+
+.. admonition:: Note
+
+ The low-level API is fragile. Future Jinja2 versions will not change it
+ in a backwards incompatible way but modifications in the Jinja core may
+ shine through. For example if Jinja2 introduces a new AST node in later
+ versions that may be returned by :meth:`~Environment.parse`.
diff --git a/docs/sandbox.rst b/docs/sandbox.rst
index f6ec78c..bb0ca9f 100644
--- a/docs/sandbox.rst
+++ b/docs/sandbox.rst
@@ -29,3 +29,18 @@
.. autofunction:: is_internal_attribute
.. autofunction:: modifies_known_mutable
+
+.. admonition:: Note
+
+ The Jinja2 sandbox alone is no solution for perfect security. Especially
+ for web applications you have to keep in mind that users may create
+ templates with arbitrary HTML in so it's crucial to ensure that (if you
+ are running multiple users on the same server) they can't harm each other
+ via JavaScript insertions and much more.
+
+ Also the sandbox is only as good as the configuration. We stronly
+ recommend only passing non-shared resources to the template and use
+ some sort of whitelisting for attributes.
+
+ Also keep in mind that templates may raise runtime or compile time errors,
+ so make sure to catch them.
diff --git a/docs/switching.rst b/docs/switching.rst
index f521f08..0c49631 100644
--- a/docs/switching.rst
+++ b/docs/switching.rst
@@ -174,6 +174,13 @@
hmm. {{ user.username|e }} looks pretty normal
{% endif %}
+Loops
+~~~~~
+
+For loops work very similar to Django, the only incompatibility is that in
+Jinja2 the special variable for the loop context is called `loop` and not
+`forloop` like in Django.
+
Mako
----
diff --git a/docs/templates.rst b/docs/templates.rst
index ca30721..182ef94 100644
--- a/docs/templates.rst
+++ b/docs/templates.rst
@@ -147,19 +147,21 @@
This will yield all elements without whitespace between them. If `seq` was
a list of numbers from ``1`` to ``9`` the output would be ``123456789``.
-Note that you must not use a whitespace between the tag and the minus sign:
+If :ref:`line-statements` are enabled they strip leading whitespace
+automatically up to the beginning of the line.
- valid::
+.. admonition:: Note
+
+ You must not use a whitespace between the tag and the minus sign.
+
+ **valid**::
{%- if foo -%}...{% endif %}
- invalid::
+ **invalid**::
{% - if foo - %}...{% endif %}
-If :ref:`line-statements` are enabled they strip leading whitespace
-automatically up to the beginning of the line.
-
Escaping
--------
@@ -797,8 +799,16 @@
filter.
true / false:
- true is always true and false is always false. Keep in mind that those
- literals are lowercase!
+ true is always true and false is always false.
+
+.. admonition:: Note
+
+ The special constants `true`, `false` and `none` are indeed lowercase.
+ Because that caused confusion in the past, when writing `True` expands
+ to an undefined variable that is considered false, all three of them can
+ be written in title case too (`True`, `False`, and `None`). However for
+ consistency (all Jinja identifiers are lowercase) you should use the
+ lowercase versions.
Math
~~~~
@@ -854,12 +864,12 @@
(expr)
group an expression.
-Note that there is no support for any bit operations or something similar.
+.. admonition:: Note
-- special note regarding ``not``: The ``is`` and ``in`` operators support
- negation using an infix notation too: ``foo is not bar`` and
- ``foo not in bar`` instead of ``not foo is bar`` and ``not foo in bar``.
- All other expressions require a prefix notation: ``not (foo and bar).``
+ The ``is`` and ``in`` operators support negation using an infix notation
+ too: ``foo is not bar`` and ``foo not in bar`` instead of ``not foo is bar``
+ and ``not foo in bar``. All other expressions require a prefix notation:
+ ``not (foo and bar).``
Other Operators
