diff options
| -rw-r--r-- | CHANGES.rst | 18 | ||||
| -rw-r--r-- | docs/api.rst | 58 | ||||
| -rw-r--r-- | docs/extensions.rst | 16 | ||||
| -rw-r--r-- | docs/faq.rst | 24 | ||||
| -rw-r--r-- | docs/integration.rst | 12 | ||||
| -rw-r--r-- | docs/intro.rst | 26 | ||||
| -rw-r--r-- | docs/sandbox.rst | 10 | ||||
| -rw-r--r-- | docs/switching.rst | 62 | ||||
| -rw-r--r-- | docs/templates.rst | 18 | ||||
| -rw-r--r-- | docs/tricks.rst | 4 | ||||
| -rw-r--r-- | examples/bench.py | 4 | ||||
| -rw-r--r-- | examples/rwbench/django/layout.html | 2 | ||||
| -rw-r--r-- | examples/rwbench/genshi/layout.html | 2 | ||||
| -rw-r--r-- | examples/rwbench/jinja/layout.html | 2 | ||||
| -rw-r--r-- | examples/rwbench/mako/layout.html | 2 | ||||
| -rw-r--r-- | examples/rwbench/rwbench.py | 4 | ||||
| -rw-r--r-- | ext/Vim/jinja.vim | 2 | ||||
| -rw-r--r-- | ext/django2jinja/django2jinja.py | 2 | ||||
| -rw-r--r-- | ext/djangojinja2.py | 10 | ||||
| -rw-r--r-- | ext/inlinegettext.py | 2 | ||||
| -rw-r--r-- | jinja2/__init__.py | 4 | ||||
| -rw-r--r-- | jinja2/bccache.py | 4 | ||||
| -rw-r--r-- | jinja2/environment.py | 2 | ||||
| -rw-r--r-- | jinja2/ext.py | 6 | ||||
| -rw-r--r-- | jinja2/filters.py | 2 | ||||
| -rw-r--r-- | jinja2/nodes.py | 2 | ||||
| -rw-r--r-- | jinja2/parser.py | 4 | ||||
| -rw-r--r-- | jinja2/tests.py | 4 | ||||
| -rw-r--r-- | jinja2/utils.py | 4 | ||||
| -rwxr-xr-x | scripts/jinja2-debug.py | 6 |
30 files changed, 158 insertions, 160 deletions
diff --git a/CHANGES.rst b/CHANGES.rst index 738e9fe..d53a4db 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -258,7 +258,7 @@ Released 2017-01-07, codename Derivation - Change the logic for macro autoescaping to be based on the runtime autoescaping information at call time instead of macro define time. - Ported a modified version of the ``tojson`` filter from Flask to - Jinja2 and hooked it up with the new policy framework. + Jinja and hooked it up with the new policy framework. - Block sets are now marked ``safe`` by default. - On Python 2 the asciification of ASCII strings can now be disabled with the ``compiler.ascii_str`` policy. @@ -304,7 +304,7 @@ Released 2015-07-26, codename Replacement - Changed cache keys to use absolute file names if available instead of load names. - Fixed loop length calculation for some iterators. -- Changed how Jinja2 enforces strings to be native strings in Python 2 +- Changed how Jinja enforces strings to be native strings in Python 2 to work when people break their default encoding. - Added :func:`make_logging_undefined` which returns an undefined object that logs failures into a logger. @@ -425,12 +425,12 @@ Released 2011-07-24, codename Convolution Previously an import suddenly "disappeared" in a scoped block. - Automatically detect newer Python interpreter versions before loading code from bytecode caches to prevent segfaults on invalid - opcodes. The segfault in earlier Jinja2 versions here was not a - Jinja2 bug but a limitation in the underlying Python interpreter. If - you notice Jinja2 segfaulting in earlier versions after an upgrade + opcodes. The segfault in earlier Jinja versions here was not a + Jinja bug but a limitation in the underlying Python interpreter. If + you notice Jinja segfaulting in earlier versions after an upgrade of the Python interpreter you don't have to upgrade, it's enough to flush the bytecode cache. This just no longer makes this necessary, - Jinja2 will automatically detect these cases now. + Jinja will automatically detect these cases now. - The sum filter can now sum up values by attribute. This is a backwards incompatible change. The argument to the filter previously was the optional starting index which defaults to zero. This now @@ -498,7 +498,7 @@ Released 2010-08-17 than the pluralize count will no longer raise a :exc:`KeyError`. - Removed builtin markup class and switched to markupsafe. For backwards compatibility the pure Python implementation still exists - but is pulled from markupsafe by the Jinja2 developers. The debug + but is pulled from markupsafe by the Jinja developers. The debug support went into a separate feature called "debugsupport" and is disabled by default because it is only relevant for Python 2.4 - Fixed an issue with unary operators having the wrong precedence. @@ -581,7 +581,7 @@ Version 2.2.1 Released 2009-09-14 -- Fixes some smaller problems for Jinja2 on Jython. +- Fixes some smaller problems for Jinja on Jython. Version 2.2 @@ -687,4 +687,4 @@ Version 2.0rc1 Released 2008-06-09 -- First release of Jinja2 +- First release of Jinja 2. diff --git a/docs/api.rst b/docs/api.rst index 99270ec..871b326 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,16 +3,16 @@ API .. module:: jinja2 :noindex: - :synopsis: public Jinja2 API + :synopsis: public Jinja API -This document describes the API to Jinja2 and not the template language. It +This document describes the API to Jinja and not the template language. It will be most useful as reference to those implementing the template interface -to the application and not those who are creating Jinja2 templates. +to the application and not those who are creating Jinja templates. Basics ------ -Jinja2 uses a central object called the template :class:`Environment`. +Jinja uses a central object called the template :class:`Environment`. Instances of this class are used to store the configuration and global objects, and are used to load templates from the file system or other locations. Even if you are creating templates from strings by using the constructor of @@ -24,7 +24,7 @@ initialization and use that to load templates. In some cases however, it's useful to have multiple environments side by side, if different configurations are in use. -The simplest way to configure Jinja2 to load templates for your application +The simplest way to configure Jinja to load templates for your application looks roughly like this:: from jinja2 import Environment, PackageLoader, select_autoescape @@ -55,7 +55,7 @@ a lot easier to use it also enables template inheritance. .. admonition:: Notes on Autoescaping - In future versions of Jinja2 we might enable autoescaping by default + In future versions of Jinja we might enable autoescaping by default for security reasons. As such you are encouraged to explicitly configure autoescaping now instead of relying on the default. @@ -63,7 +63,7 @@ a lot easier to use it also enables template inheritance. Unicode ------- -Jinja2 is using Unicode internally which means that you have to pass Unicode +Jinja is using Unicode internally which means that you have to pass Unicode objects to the render function or bytestrings that only consist of ASCII characters. Additionally newlines are normalized to one end of line sequence which is per default UNIX style (``\n``). @@ -88,24 +88,24 @@ second line of the Python module using the Unicode literal:: We recommend utf-8 as Encoding for Python modules and templates as it's possible to represent every Unicode character in utf-8 and because it's -backwards compatible to ASCII. For Jinja2 the default encoding of templates +backwards compatible to ASCII. For Jinja the default encoding of templates is assumed to be utf-8. -It is not possible to use Jinja2 to process non-Unicode data. The reason -for this is that Jinja2 uses Unicode already on the language level. For -example Jinja2 treats the non-breaking space as valid whitespace inside +It is not possible to use Jinja to process non-Unicode data. The reason +for this is that Jinja uses Unicode already on the language level. For +example Jinja treats the non-breaking space as valid whitespace inside expressions which requires knowledge of the encoding or operating on an Unicode string. For more details about Unicode in Python have a look at the excellent `Unicode documentation`_. -Another important thing is how Jinja2 is handling string literals in +Another important thing is how Jinja is handling string literals in templates. A naive implementation would be using Unicode strings for all string literals but it turned out in the past that this is problematic as some libraries are typechecking against `str` explicitly. For example `datetime.strftime` does not accept Unicode arguments. To not break it -completely Jinja2 is returning `str` for strings that fit into ASCII and +completely Jinja is returning `str` for strings that fit into ASCII and for everything else `unicode`: >>> m = Template(u"{% set a, b = 'foo', 'föö' %}").module @@ -121,8 +121,8 @@ 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 +render Jinja templates. The :ref:`low-level-api` on the other side is only +useful if you want to dig deeper into Jinja or :ref:`develop extensions <jinja-extensions>`. .. autoclass:: Environment([options]) @@ -260,7 +260,7 @@ Autoescaping .. versionchanged:: 2.4 -Jinja2 now comes with autoescaping support. As of Jinja 2.9 the +Jinja now comes with autoescaping support. As of Jinja 2.9 the autoescape extension is removed and built-in. However autoescaping is not yet enabled by default though this will most likely change in the future. It's recommended to configure a sensible default for @@ -300,10 +300,8 @@ the `autoescape` block (see :ref:`autoescape-overrides`). 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 -are currently not allowed. This limitation will probably go away as soon as -unicode identifiers are fully specified for Python 3. +Jinja uses Python naming rules. Valid identifiers can be any combination +of Unicode characters accepted by Python. Filters and tests are looked up in separate namespaces and have slightly modified identifier syntax. Filters and tests may contain dots to group @@ -445,11 +443,11 @@ The Context .. 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 + immutable inside functions. Both Jinja 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 + When a template accesses a variable the template does not define, Jinja looks up the variable in the context, after that the variable is treated as if it was defined in the template. @@ -469,7 +467,7 @@ own loader, subclass :class:`BaseLoader` and override `get_source`. .. autoclass:: jinja2.BaseLoader :members: get_source, load -Here a list of the builtin loaders Jinja2 provides: +Here a list of the builtin loaders Jinja provides: .. autoclass:: jinja2.FileSystemLoader @@ -531,7 +529,7 @@ Builtin bytecode caches: Async Support ------------- -Starting with version 2.9, Jinja2 also supports the Python `async` and +Starting with version 2.9, Jinja also supports the Python `async` and `await` constructs. As far as template designers go this feature is entirely opaque to them however as a developer you should be aware of how it's implemented as it influences what type of APIs you can safely expose @@ -578,7 +576,7 @@ Example:: env.policies['urlize.rel'] = 'nofollow noopener' ``compiler.ascii_str``: - This boolean controls on Python 2 if Jinja2 should store ASCII only + This boolean controls on Python 2 if Jinja should store ASCII only literals as bytestring instead of unicode strings. This used to be always enabled for Jinja versions below 2.9 and now can be changed. Traditionally it was done this way since some APIs in Python 2 failed @@ -626,7 +624,7 @@ Utilities --------- These helper functions and classes are useful if you add custom filters or -functions to a Jinja2 environment. +functions to a Jinja environment. .. autofunction:: jinja2.environmentfilter @@ -658,7 +656,7 @@ functions to a Jinja2 environment. .. admonition:: Note - The Jinja2 :class:`Markup` class is compatible with at least Pylons and + The Jinja :class:`Markup` class is compatible with at least Pylons and Genshi. It's expected that more template engines and framework will pick up the `__html__` concept soon. @@ -915,9 +913,9 @@ don't recommend using any of those. .. admonition:: Note - The low-level API is fragile. Future Jinja2 versions will try not to - change it in a backwards incompatible way but modifications in the Jinja2 - core may shine through. For example if Jinja2 introduces a new AST node + The low-level API is fragile. Future Jinja versions will try not to + change it in a backwards incompatible way but modifications in the Jinja + core may shine through. For example if Jinja introduces a new AST node in later versions that may be returned by :meth:`~Environment.parse`. The Meta API diff --git a/docs/extensions.rst b/docs/extensions.rst index 1573284..8cb0ff7 100644 --- a/docs/extensions.rst +++ b/docs/extensions.rst @@ -3,7 +3,7 @@ Extensions ========== -Jinja2 supports extensions that can add extra filters, tests, globals or even +Jinja supports extensions that can add extra filters, tests, globals or even extend the parser. The main motivation of extensions is to move often used code into a reusable class like adding support for internationalization. @@ -11,11 +11,11 @@ code into a reusable class like adding support for internationalization. Adding Extensions ----------------- -Extensions are added to the Jinja2 environment at creation time. Once the +Extensions are added to the Jinja environment at creation time. Once the environment is created additional extensions cannot be added. To add an extension pass a list of extension classes or import paths to the ``extensions`` parameter of the :class:`~jinja2.Environment` constructor. The following -example creates a Jinja2 environment with the i18n extension loaded:: +example creates a Jinja environment with the i18n extension loaded:: jinja_env = Environment(extensions=['jinja2.ext.i18n']) @@ -196,7 +196,7 @@ Loop Controls **Import name:** ``jinja2.ext.loopcontrols`` This extension adds support for ``break`` and ``continue`` in loops. After -enabling, Jinja2 provides those two keywords which work exactly like in +enabling, Jinja provides those two keywords which work exactly like in Python. .. _with-extension: @@ -242,13 +242,13 @@ Writing Extensions .. module:: jinja2.ext -By writing extensions you can add custom tags to Jinja2. This is a non-trivial +By writing extensions you can add custom tags to Jinja. This is a non-trivial task and usually not needed as the default tags and expressions cover all common use cases. The i18n extension is a good example of why extensions are useful. Another one would be fragment caching. When writing extensions you have to keep in mind that you are working with the -Jinja2 template compiler which does not validate the node tree you are passing +Jinja template compiler which does not validate the node tree you are passing to it. If the AST is malformed you will get all kinds of compiler or runtime errors that are horrible to debug. Always make sure you are using the nodes you create correctly. The API documentation below shows which nodes exist and @@ -257,7 +257,7 @@ how to use them. Example Extension ~~~~~~~~~~~~~~~~~ -The following example implements a ``cache`` tag for Jinja2 by using the +The following example implements a ``cache`` tag for Jinja by using the `cachelib`_ library: .. literalinclude:: cache_extension.py @@ -365,7 +365,7 @@ code objects. Extensions that provide custom statements can return nodes to execute custom Python code. The list below describes all nodes that are currently available. The AST may -change between Jinja2 versions but will stay backwards compatible. +change between Jinja versions but will stay backwards compatible. For more information have a look at the repr of :meth:`jinja2.Environment.parse`. diff --git a/docs/faq.rst b/docs/faq.rst index 97bc39e..294fef1 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -18,7 +18,7 @@ How fast is it? We really hate benchmarks especially since they don't reflect much. The performance of a template depends on many factors and you would have to benchmark different engines in different situations. The benchmarks from the -testsuite show that Jinja2 has a similar performance to `Mako`_ and is between +testsuite show that Jinja has a similar performance to `Mako`_ and is between 10 and 20 times faster than Django's template engine or Genshi. These numbers should be taken with tons of salt as the benchmarks that took these numbers only test a few performance related situations such as looping. Generally @@ -28,12 +28,12 @@ code. .. _Mako: https://www.makotemplates.org/ -How Compatible is Jinja2 with Django? -------------------------------------- +How Compatible is Jinja with Django? +------------------------------------ -The default syntax of Jinja2 matches Django syntax in many ways. However +The default syntax of Jinja matches Django syntax in many ways. However this similarity doesn't mean that you can use a Django template unmodified -in Jinja2. For example filter arguments use a function call syntax rather +in Jinja. For example filter arguments use a function call syntax rather than a colon to separate filter name and arguments. Additionally the extension interface in Jinja is fundamentally different from the Django one which means that your custom tags won't work any longer. @@ -80,7 +80,7 @@ So some amount of logic is required in templates to keep everyone happy. And Jinja leaves it pretty much to you how much logic you want to put into templates. There are some restrictions in what you can do and what not. -Jinja2 neither allows you to put arbitrary Python code into templates nor +Jinja neither allows you to put arbitrary Python code into templates nor does it allow all Python expressions. The operators are limited to the most common ones and more advanced expressions such as list comprehensions and generator expressions are not supported. This keeps the template engine @@ -106,7 +106,7 @@ integers and floats for a table of statistics the template designer can omit the escaping because he knows that integers or floats don't contain any unsafe parameters. -Additionally Jinja2 is a general purpose template engine and not only used +Additionally Jinja is a general purpose template engine and not only used for HTML/XML generation. For example you may generate LaTeX, emails, CSS, JavaScript, or configuration files. @@ -130,7 +130,7 @@ My tracebacks look weird. What's happening? If the debugsupport module is not compiled and you are using a Python installation without ctypes (Python 2.4 without ctypes, Jython or Google's -AppEngine) Jinja2 is unable to provide correct debugging information and +AppEngine) Jinja is unable to provide correct debugging information and the traceback may be incomplete. There is currently no good workaround for Jython or the AppEngine as ctypes is unavailable there and it's not possible to use the debugsupport extension. @@ -150,7 +150,7 @@ Credit for this snippet goes to `Thomas Johansson Why is there no Python 2.3/2.4/2.5/2.6/3.1/3.2/3.3 support? ----------------------------------------------------------- -Python 2.3 is missing a lot of features that are used heavily in Jinja2. This +Python 2.3 is missing a lot of features that are used heavily in Jinja. This decision was made as with the upcoming Python 2.6 and 3.0 versions it becomes harder to maintain the code for older Python versions. If you really need Python 2.3 support you either have to use Jinja 1 or other templating @@ -160,11 +160,11 @@ Python 2.4/2.5/3.1/3.2 support was removed when we switched to supporting Python 2 and 3 by the same sourcecode (without using 2to3). It was required to drop support because only Python 2.6/2.7 and >=3.3 support byte and unicode literals in a way compatible to each other version. If you really need support -for older Python 2 (or 3) versions, you can just use Jinja2 2.6. +for older Python 2 (or 3) versions, you can just use Jinja 2.6. Python 2.6/3.3 support was dropped because it got dropped in various upstream projects (such as wheel or pytest), which would make it difficult to continue -supporting it. Jinja2 2.10 was the last version supporting Python 2.6/3.3. +supporting it. Jinja 2.10 was the last version supporting Python 2.6/3.3. My Macros are overridden by something ------------------------------------- @@ -186,7 +186,7 @@ child.tmpl: {% macro foo() %}CHILD{% endmacro %} {% block body %}{{ foo() }}{% endblock %} -This will print ``LAYOUT`` in Jinja2. This is a side effect of having +This will print ``LAYOUT`` in Jinja. This is a side effect of having the parent template evaluated after the child one. This allows child templates passing information to the parent template. To avoid this issue rename the macro or variable in the parent template to have an diff --git a/docs/integration.rst b/docs/integration.rst index ff8fbaf..2cfad55 100644 --- a/docs/integration.rst +++ b/docs/integration.rst @@ -1,7 +1,7 @@ Integration =========== -Jinja2 provides some code for integration into other tools such as frameworks, +Jinja provides some code for integration into other tools such as frameworks, the `Babel`_ library or your favourite editor for fancy code highlighting. This is a brief description of whats included. @@ -19,7 +19,7 @@ support is implemented as part of the :ref:`i18n-extension` extension. Gettext messages extracted from both `trans` tags and code expressions. -To extract gettext messages from templates, the project needs a Jinja2 section +To extract gettext messages from templates, the project needs a Jinja section in its Babel extraction method `mapping file`_: .. sourcecode:: ini @@ -59,7 +59,7 @@ With `Pylons`_ 0.9.7 onwards it's incredible easy to integrate Jinja into a Pylons powered application. The template engine is configured in `config/environment.py`. The configuration -for Jinja2 looks something like that:: +for Jinja looks something like that:: from jinja2 import Environment, PackageLoader config['pylons.app_globals'].jinja_env = Environment( @@ -81,8 +81,8 @@ snippet and add it into your `config/environment.py`:: TextMate -------- -There is a `bundle for TextMate`_ that supports syntax highlighting for Jinja1 -and Jinja2 for text based templates as well as HTML. It also contains a few +There is a `bundle for TextMate`_ that supports syntax highlighting for Jinja 1 +and Jinja 2 for text based templates as well as HTML. It also contains a few often used snippets. .. _bundle for TextMate: https://github.com/mitsuhiko/jinja2-tmbundle @@ -92,7 +92,7 @@ Vim A syntax plugin for `Vim`_ is available `from the jinja repository <https://github.com/pallets/jinja/blob/master/ext/Vim/jinja.vim>`_. The script -supports Jinja1 and Jinja2. Once installed, two file types are available +supports Jinja 1 and Jinja 2. Once installed, two file types are available (``jinja`` and ``htmljinja``). The first one is for text-based templates and the second is for HTML templates. For HTML documents, the plugin attempts to automatically detect Jinja syntax inside of existing HTML documents. diff --git a/docs/intro.rst b/docs/intro.rst index e01450a..c20c5e9 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,21 +1,21 @@ Introduction ============ -This is the documentation for the Jinja2 general purpose templating language. -Jinja2 is a library for Python that is designed to be flexible, fast and secure. +This is the documentation for the Jinja general purpose templating language. +Jinja is a library for Python that is designed to be flexible, fast and secure. If you have any exposure to other text-based template languages, such as Smarty or -Django, you should feel right at home with Jinja2. It's both designer and +Django, you should feel right at home with Jinja. It's both designer and developer friendly by sticking to Python's principles and adding functionality useful for templating environments. Prerequisites ------------- -Jinja2 works with Python 2.7.x and >= 3.4. If you are using Python -3.2 you can use an older release of Jinja2 (2.6) as support for Python 3.2 -was dropped in Jinja2 version 2.7. The last release which supported Python 2.6 -and 3.3 was Jinja2 2.10. +Jinja works with Python 2.7.x and >= 3.5. If you are using Python +3.2 you can use an older release of Jinja (2.6) as support for Python 3.2 +was dropped in Jinja version 2.7. The last release which supported Python 2.6 +and 3.3 was Jinja 2.10. If you wish to use the :class:`~jinja2.PackageLoader` class, you will also need `setuptools`_ or `distribute`_ installed at runtime. @@ -23,11 +23,11 @@ need `setuptools`_ or `distribute`_ installed at runtime. Installation ------------ -You can install the most recent Jinja2 version using `pip`_:: +You can install the most recent Jinja version using `pip`_:: pip install Jinja2 -This will install Jinja2 in your Python installation's site-packages directory. +This will install Jinja in your Python installation's site-packages directory. Installing the development version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -50,15 +50,15 @@ has the advantage that the C extensions are compiled. MarkupSafe Dependency ~~~~~~~~~~~~~~~~~~~~~ -As of version 2.7 Jinja2 depends on the `MarkupSafe`_ module. If you install -Jinja2 via ``pip`` it will be installed automatically for you. +As of version 2.7 Jinja depends on the `MarkupSafe`_ module. If you install +Jinja via ``pip`` it will be installed automatically for you. .. _MarkupSafe: https://markupsafe.palletsprojects.com/ Basic API Usage --------------- -This section gives you a brief introduction to the Python API for Jinja2 +This section gives you a brief introduction to the Python API for Jinja templates. The most basic way to create a template and render it is through @@ -77,6 +77,6 @@ called with a dict or keyword arguments expands the template. The dict or keywords arguments passed to the template are the so-called "context" of the template. -What you can see here is that Jinja2 is using unicode internally and the +What you can see here is that Jinja is using unicode internally and the return value is an unicode string. So make sure that your application is indeed using unicode internally. diff --git a/docs/sandbox.rst b/docs/sandbox.rst index 71ccc0d..0dac5a0 100644 --- a/docs/sandbox.rst +++ b/docs/sandbox.rst @@ -1,7 +1,7 @@ Sandbox ======= -The Jinja2 sandbox can be used to evaluate untrusted code. Access to unsafe +The Jinja sandbox can be used to evaluate untrusted code. Access to unsafe attributes and methods is prohibited. Assuming `env` is a :class:`SandboxedEnvironment` in the default configuration @@ -36,7 +36,7 @@ API .. admonition:: Note - The Jinja2 sandbox alone is no solution for perfect security. Especially + The Jinja 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 @@ -54,7 +54,7 @@ Operator Intercepting .. versionadded:: 2.6 -For maximum performance Jinja2 will let operators call directly the type +For maximum performance Jinja will let operators call directly the type specific callback methods. This means that it's not possible to have this intercepted by overriding :meth:`Environment.call`. Furthermore a conversion from operator to special method is not always directly possible @@ -65,7 +65,7 @@ With Jinja 2.6 there is now support for explicit operator intercepting. This can be used to customize specific operators as necessary. In order to intercept an operator one has to override the :attr:`SandboxedEnvironment.intercepted_binops` attribute. Once the -operator that needs to be intercepted is added to that set Jinja2 will +operator that needs to be intercepted is added to that set Jinja will generate bytecode that calls the :meth:`SandboxedEnvironment.call_binop` function. For unary operators the `unary` attributes and methods have to be used instead. @@ -90,5 +90,5 @@ Jinja2:: operator, left, right) Make sure to always call into the super method, even if you are not -intercepting the call. Jinja2 might internally call the method to +intercepting the call. Jinja might internally call the method to evaluate expressions. diff --git a/docs/switching.rst b/docs/switching.rst index 01a7d0d..1e2701d 100644 --- a/docs/switching.rst +++ b/docs/switching.rst @@ -4,21 +4,21 @@ Switching from other Template Engines .. highlight:: html+jinja If you have used a different template engine in the past and want to switch -to Jinja2 here is a small guide that shows the basic syntactic and semantic +to Jinja here is a small guide that shows the basic syntactic and semantic changes between some common, similar text template engines for Python. -Jinja1 ------- +Jinja 1 +------- -Jinja2 is mostly compatible with Jinja1 in terms of API usage and template -syntax. The differences between Jinja1 and 2 are explained in the following +Jinja 2 is mostly compatible with Jinja 1 in terms of API usage and template +syntax. The differences between Jinja 1 and 2 are explained in the following list. API ~~~ Loaders - Jinja2 uses a different loader API. Because the internal representation + Jinja 2 uses a different loader API. Because the internal representation of templates changed there is no longer support for external caching systems such as memcached. The memory consumed by templates is comparable with regular Python modules now and external caching doesn't give any @@ -27,38 +27,38 @@ Loaders Loading templates from strings In the past it was possible to generate templates from a string with the - default environment configuration by using `jinja.from_string`. Jinja2 + default environment configuration by using `jinja.from_string`. Jinja 2 provides a :class:`Template` class that can be used to do the same, but with optional additional configuration. Automatic unicode conversion - Jinja1 performed automatic conversion of bytestrings in a given encoding + Jinja 1 performed automatic conversion of bytestrings in a given encoding into unicode objects. This conversion is no longer implemented as it was inconsistent as most libraries are using the regular Python ASCII - bytestring to Unicode conversion. An application powered by Jinja2 - *has to* use unicode internally everywhere or make sure that Jinja2 only + bytestring to Unicode conversion. An application powered by Jinja 2 + *has to* use unicode internally everywhere or make sure that Jinja 2 only gets unicode strings passed. i18n - Jinja1 used custom translators for internationalization. i18n is now - available as Jinja2 extension and uses a simpler, more gettext friendly + Jinja 1 used custom translators for internationalization. i18n is now + available as Jinja 2 extension and uses a simpler, more gettext friendly interface and has support for babel. For more details see :ref:`i18n-extension`. Internal methods - Jinja1 exposed a few internal methods on the environment object such + Jinja 1 exposed a few internal methods on the environment object such as `call_function`, `get_attribute` and others. While they were marked - as being an internal method it was possible to override them. Jinja2 + as being an internal method it was possible to override them. Jinja 2 doesn't have equivalent methods. Sandbox - Jinja1 was running sandbox mode by default. Few applications actually - used that feature so it became optional in Jinja2. For more details + Jinja 1 was running sandbox mode by default. Few applications actually + used that feature so it became optional in Jinja 2. For more details about the sandboxed execution see :class:`SandboxedEnvironment`. Context - Jinja1 had a stacked context as storage for variables passed to the - environment. In Jinja2 a similar object exists but it doesn't allow + Jinja 1 had a stacked context as storage for variables passed to the + environment. In Jinja 2 a similar object exists but it doesn't allow modifications nor is it a singleton. As inheritance is dynamic now multiple context objects may exist during template evaluation. @@ -70,10 +70,10 @@ Filters and Tests Templates ~~~~~~~~~ -Jinja2 has mostly the same syntax as Jinja1. What's different is that +Jinja 2 has mostly the same syntax as Jinja 1. What's different is that macros require parentheses around the argument list now. -Additionally Jinja2 allows dynamic inheritance now and dynamic includes. +Additionally Jinja 2 allows dynamic inheritance now and dynamic includes. The old helper function `rendertemplate` is gone now, `include` can be used instead. Includes no longer import macros and variable assignments, for that the new `import` tag is used. This concept is explained in the @@ -88,10 +88,10 @@ Django ------ If you have previously worked with Django templates, you should find -Jinja2 very familiar. In fact, most of the syntax elements look and +Jinja very familiar. In fact, most of the syntax elements look and work the same. -However, Jinja2 provides some more syntax elements covered in the +However, Jinja provides some more syntax elements covered in the documentation and some work a bit different. This section covers the template changes. As the API is fundamentally @@ -119,7 +119,7 @@ Django. This syntax is also used for macros. Filter Arguments ~~~~~~~~~~~~~~~~ -Jinja2 provides more than one argument for filters. Also the syntax for +Jinja provides more than one argument for filters. Also the syntax for argument passing is different. A template that looks like this in Django:: {{ items|join:", " }} @@ -146,10 +146,10 @@ operator. Here are some examples:: Loops ~~~~~ -For loops work very similarly to Django, but notably the Jinja2 special +For loops work very similarly to Django, but notably the Jinja special variable for the loop context is called `loop`, not `forloop` as in Django. -In addition, the Django `empty` argument is called `else` in Jinja2. For +In addition, the Django `empty` argument is called `else` in Jinja. For example, the Django template:: {% for item in items %} @@ -192,17 +192,17 @@ Mako .. highlight:: html+mako -If you have used Mako so far and want to switch to Jinja2 you can configure -Jinja2 to look more like Mako: +If you have used Mako so far and want to switch to Jinja you can configure +Jinja to look more like Mako: .. sourcecode:: python env = Environment('<%', '%>', '${', '}', '<%doc>', '</%doc>', '%', '##') -With an environment configured like that, Jinja2 should be able to interpret -a small subset of Mako templates. Jinja2 does not support embedded Python +With an environment configured like that, Jinja should be able to interpret +a small subset of Mako templates. Jinja does not support embedded Python code, so you would have to move that out of the template. The syntax for defs -(which are called macros in Jinja2) and template inheritance is different too. +(which are called macros in Jinja) and template inheritance is different too. The following Mako template:: <%inherit file="layout.html" /> @@ -213,7 +213,7 @@ The following Mako template:: % endfor </ul> -Looks like this in Jinja2 with the above configuration:: +Looks like this in Jinja with the above configuration:: <% extends "layout.html" %> <% block title %>Page Title<% endblock %> diff --git a/docs/templates.rst b/docs/templates.rst index 5c1d92a..39bdb36 100644 --- a/docs/templates.rst +++ b/docs/templates.rst @@ -105,7 +105,7 @@ printed or iterated over, and to fail for every other operation. .. admonition:: Implementation - For the sake of convenience, ``foo.bar`` in Jinja2 does the following + For the sake of convenience, ``foo.bar`` in Jinja does the following things on the Python layer: - check for an attribute called `bar` on `foo` @@ -245,7 +245,7 @@ a list of numbers from ``1`` to ``9``, the output would be ``123456789``. If :ref:`line-statements` are enabled, they strip leading whitespace automatically up to the beginning of the line. -By default, Jinja2 also removes trailing newlines. To keep single +By default, Jinja also removes trailing newlines. To keep single trailing newlines, configure Jinja to `keep_trailing_newline`. .. admonition:: Note @@ -493,7 +493,7 @@ Rendering ``grandchild2.tmpl`` will give Named Block End-Tags ~~~~~~~~~~~~~~~~~~~~ -Jinja2 allows you to put the name of the block after the end tag for better +Jinja allows you to put the name of the block after the end tag for better readability:: {% block sidebar %} @@ -599,7 +599,7 @@ still take place and result in double-escaped characters. If you know you have data that is already safe but not marked, be sure to wrap it in ``Markup`` or use the ``|safe`` filter. -Jinja2 functions (macros, `super`, `self.BLOCKNAME`) always return template +Jinja functions (macros, `super`, `self.BLOCKNAME`) always return template data that is marked as safe. String literals in templates with automatic escaping are considered unsafe @@ -747,7 +747,7 @@ writing `{% set outer_loop = loop %}` after the loop that we want to use recursively. Then, we can call it using `{{ outer_loop(...) }}` Please note that assignments in loops will be cleared at the end of the -iteration and cannot outlive the loop scope. Older versions of Jinja2 had +iteration and cannot outlive the loop scope. Older versions of Jinja had a bug where in some circumstances it appeared that assignments would work. This is not supported. See :ref:`assignments` for more information about how to deal with this. @@ -924,7 +924,7 @@ Here's an example of how a call block can be used with arguments:: Filters ~~~~~~~ -Filter sections allow you to apply regular Jinja2 filters on a block of +Filter sections allow you to apply regular Jinja filters on a block of template data. Just wrap the code in the special `filter` section:: {% filter upper %} @@ -1089,7 +1089,7 @@ Example:: Import ~~~~~~ -Jinja2 supports putting often used code into macros. These macros can go into +Jinja supports putting often used code into macros. These macros can go into different templates and get imported from there. This works similarly to the import statements in Python. It's important to know that imports are cached and imported templates don't have access to the current template variables, @@ -1566,7 +1566,7 @@ The following functions are available in the global scope by default: Extensions ---------- -The following sections cover the built-in Jinja2 extensions that may be +The following sections cover the built-in Jinja extensions that may be enabled by an application. An application could also provide further extensions not covered by this documentation; in which case there should be a separate document explaining said :ref:`extensions @@ -1774,7 +1774,7 @@ behavior of referencing one variable to another had some unintended consequences. In particular one variable could refer to another defined in the same with block's opening statement. This caused issues with the cleaned up scoping behavior and has since been improved. In particular -in newer Jinja2 versions the following code always refers to the variable +in newer Jinja versions the following code always refers to the variable `a` from outside the `with` block:: {% with a={}, b=a.attribute %}...{% endwith %} diff --git a/docs/tricks.rst b/docs/tricks.rst index 4d33e22..78ac408 100644 --- a/docs/tricks.rst +++ b/docs/tricks.rst @@ -3,7 +3,7 @@ Tips and Tricks .. highlight:: html+jinja -This part of the documentation shows some tips and tricks for Jinja2 +This part of the documentation shows some tips and tricks for Jinja templates. @@ -12,7 +12,7 @@ templates. Null-Master Fallback -------------------- -Jinja2 supports dynamic inheritance and does not distinguish between parent +Jinja supports dynamic inheritance and does not distinguish between parent and child template as long as no `extends` tag is visited. While this leads to the surprising behavior that everything before the first `extends` tag including whitespace is printed out instead of being ignored, it can be used diff --git a/examples/bench.py b/examples/bench.py index c648dc6..0193cc1 100644 --- a/examples/bench.py +++ b/examples/bench.py @@ -1,6 +1,6 @@ """\ - This benchmark compares some python templating engines with Jinja 2 so - that we get a picture of how fast Jinja 2 is for a semi real world + This benchmark compares some python templating engines with Jinja so + that we get a picture of how fast Jinja is for a semi real world template. If a template engine is not installed the test is skipped.\ """ import sys diff --git a/examples/rwbench/django/layout.html b/examples/rwbench/django/layout.html index 60039ce..b75cbfb 100644 --- a/examples/rwbench/django/layout.html +++ b/examples/rwbench/django/layout.html @@ -9,7 +9,7 @@ <div class="header"> <h1>RealWorld Benchmark</h1> <blockquote><p> - A less stupid benchmark for Mako and Jinja2 to get an impression how + A less stupid benchmark for Mako and Jinja to get an impression how code changes affect runtime performance. </p></blockquote> </div> diff --git a/examples/rwbench/genshi/layout.html b/examples/rwbench/genshi/layout.html index b12aec4..d56fffd 100644 --- a/examples/rwbench/genshi/layout.html +++ b/examples/rwbench/genshi/layout.html @@ -11,7 +11,7 @@ <div class="header"> <h1>RealWorld Benchmark</h1> <blockquote><p> - A less stupid benchmark for Mako and Jinja2 to get an impression how + A less stupid benchmark for Mako and Jinja to get an impression how code changes affect runtime performance. </p></blockquote> </div> diff --git a/examples/rwbench/jinja/layout.html b/examples/rwbench/jinja/layout.html index 755789e..308ba9d 100644 --- a/examples/rwbench/jinja/layout.html +++ b/examples/rwbench/jinja/layout.html @@ -9,7 +9,7 @@ <div class="header"> <h1>RealWorld Benchmark</h1> <blockquote><p> - A less stupid benchmark for Mako and Jinja2 to get an impression how + A less stupid benchmark for Mako and Jinja to get an impression how code changes affect runtime performance. </p></blockquote> </div> diff --git a/examples/rwbench/mako/layout.html b/examples/rwbench/mako/layout.html index a9c353e..15e9282 100644 --- a/examples/rwbench/mako/layout.html +++ b/examples/rwbench/mako/layout.html @@ -9,7 +9,7 @@ <div class="header"> <h1>RealWorld Benchmark</h1> <blockquote><p> - A less stupid benchmark for Mako and Jinja2 to get an impression how + A less stupid benchmark for Mako and Jinja to get an impression how code changes affect runtime performance. </p></blockquote> </div> diff --git a/examples/rwbench/rwbench.py b/examples/rwbench/rwbench.py index 813dd56..bf1d997 100644 --- a/examples/rwbench/rwbench.py +++ b/examples/rwbench/rwbench.py @@ -3,8 +3,8 @@ RealWorldish Benchmark ~~~~~~~~~~~~~~~~~~~~~~ - A more real-world benchmark of Jinja2. Like the other benchmark in the - Jinja2 repository this has no real-world usefulnes (despite the name). + A more real-world benchmark of Jinja. Like the other benchmark in the + Jinja repository this has no real-world usefulnes (despite the name). Just go away and ignore it. NOW! :copyright: (c) 2009 by the Jinja Team. diff --git a/ext/Vim/jinja.vim b/ext/Vim/jinja.vim index c81f594..5bfdf16 100644 --- a/ext/Vim/jinja.vim +++ b/ext/Vim/jinja.vim @@ -10,7 +10,7 @@ " " Changes: " -" 2008 May 9: Added support for Jinja2 changes (new keyword rules) +" 2008 May 9: Added support for Jinja 2 changes (new keyword rules) " .vimrc variable to disable html highlighting if !exists('g:jinja_syntax_html') diff --git a/ext/django2jinja/django2jinja.py b/ext/django2jinja/django2jinja.py index 824d6a1..d2f3717 100644 --- a/ext/django2jinja/django2jinja.py +++ b/ext/django2jinja/django2jinja.py @@ -3,7 +3,7 @@ Django to Jinja ~~~~~~~~~~~~~~~ - Helper module that can convert django templates into Jinja2 templates. + Helper module that can convert django templates into Jinja templates. This file is not intended to be used as stand alone application but to be used as library. To convert templates you basically create your own diff --git a/ext/djangojinja2.py b/ext/djangojinja2.py index c7b4884..70d60cb 100644 --- a/ext/djangojinja2.py +++ b/ext/djangojinja2.py @@ -3,7 +3,7 @@ djangojinja2 ~~~~~~~~~~~~ - Adds support for Jinja2 to Django. + Adds support for Jinja to Django. Configuration variables: @@ -11,8 +11,8 @@ Key Description ======================= ============================================= `JINJA2_TEMPLATE_DIRS` List of template folders - `JINJA2_EXTENSIONS` List of Jinja2 extensions to use - `JINJA2_CACHE_SIZE` The size of the Jinja2 template cache. + `JINJA2_EXTENSIONS` List of Jinja extensions to use + `JINJA2_CACHE_SIZE` The size of the Jinja template cache. ======================= ============================================= :copyright: (c) 2009 by the Jinja Team. @@ -33,7 +33,7 @@ _jinja_env = None def get_env(): - """Get the Jinja2 env and initialize it if necessary.""" + """Get the Jinja env and initialize it if necessary.""" global _jinja_env if _jinja_env is None: _jinja_env = create_env() @@ -41,7 +41,7 @@ def get_env(): def create_env(): - """Create a new Jinja2 environment.""" + """Create a new Jinja environment.""" searchpath = list(settings.JINJA2_TEMPLATE_DIRS) return Environment(loader=FileSystemLoader(searchpath), auto_reload=settings.TEMPLATE_DEBUG, diff --git a/ext/inlinegettext.py b/ext/inlinegettext.py index 6ff10da..0a54e13 100644 --- a/ext/inlinegettext.py +++ b/ext/inlinegettext.py @@ -3,7 +3,7 @@ Inline Gettext ~~~~~~~~~~~~~~ - An example extension for Jinja2 that supports inline gettext calls. + An example extension for Jinja that supports inline gettext calls. Requires the i18n extension to be loaded. :copyright: (c) 2009 by the Jinja Team. diff --git a/jinja2/__init__.py b/jinja2/__init__.py index bbf1380..9c46e49 100644 --- a/jinja2/__init__.py +++ b/jinja2/__init__.py @@ -3,14 +3,14 @@ jinja2 ~~~~~~ - Jinja2 is a template engine written in pure Python. It provides a + Jinja is a template engine written in pure Python. It provides a Django inspired non-XML syntax but supports inline expressions and an optional sandboxed environment. Nutshell -------- - Here a small example of a Jinja2 template:: + Here a small example of a Jinja template:: {% extends 'base.html' %} {% block title %}Memberlist{% endblock %} diff --git a/jinja2/bccache.py b/jinja2/bccache.py index 713427b..1a7b5bf 100644 --- a/jinja2/bccache.py +++ b/jinja2/bccache.py @@ -140,7 +140,7 @@ class BytecodeCache(object): bucket.write_bytecode(f) A more advanced version of a filesystem based bytecode cache is part of - Jinja2. + Jinja. """ def load_bytecode(self, bucket): @@ -158,7 +158,7 @@ class BytecodeCache(object): raise NotImplementedError() def clear(self): - """Clears the cache. This method is not used by Jinja2 but should be + """Clears the cache. This method is not used by Jinja but should be implemented to allow applications to clear the bytecode cache used by a particular environment. """ diff --git a/jinja2/environment.py b/jinja2/environment.py index 2687889..b467343 100644 --- a/jinja2/environment.py +++ b/jinja2/environment.py @@ -485,7 +485,7 @@ class Environment(object): executable source- or bytecode. This is useful for debugging or to extract information from templates. - If you are :ref:`developing Jinja2 extensions <writing-extensions>` + If you are :ref:`developing Jinja extensions <writing-extensions>` this gives you a good overview of the node tree generated. """ try: diff --git a/jinja2/ext.py b/jinja2/ext.py index 54b0f77..f04b37b 100644 --- a/jinja2/ext.py +++ b/jinja2/ext.py @@ -100,7 +100,7 @@ class Extension(with_metaclass(ExtensionRegistry, object)): :class:`~jinja2.lexer.Token`\\s, but it doesn't have to return a :class:`~jinja2.lexer.TokenStream`. - In the `ext` folder of the Jinja2 source distribution there is a file + In the `ext` folder of the Jinja source distribution there is a file called `inlinegettext.py` which implements a filter that utilizes this method. """ @@ -168,7 +168,7 @@ def _make_new_ngettext(func): class InternationalizationExtension(Extension): - """This extension adds gettext support to Jinja2.""" + """This extension adds gettext support to Jinja.""" tags = {'trans'} # TODO: the i18n extension is currently reevaluating values in a few @@ -416,7 +416,7 @@ class InternationalizationExtension(Extension): class ExprStmtExtension(Extension): - """Adds a `do` tag to Jinja2 that works like the print statement just + """Adds a `do` tag to Jinja that works like the print statement just that it doesn't print the return value. """ tags = set(['do']) diff --git a/jinja2/filters.py b/jinja2/filters.py index 57da050..2b8e950 100644 --- a/jinja2/filters.py +++ b/jinja2/filters.py @@ -668,7 +668,7 @@ def do_truncate(env, s, length=255, killwords=False, end='...', leeway=None): {{ "foo bar baz qux"|truncate(11, False, '...', 0) }} -> "foo bar..." - The default leeway on newer Jinja2 versions is 5 and was 0 before but + The default leeway on newer Jinja versions is 5 and was 0 before but can be reconfigured globally. """ if leeway is None: diff --git a/jinja2/nodes.py b/jinja2/nodes.py index a951d35..9a58d43 100644 --- a/jinja2/nodes.py +++ b/jinja2/nodes.py @@ -105,7 +105,7 @@ def get_eval_context(node, ctx): class Node(with_metaclass(NodeType, object)): - """Baseclass for all Jinja2 nodes. There are a number of nodes available + """Baseclass for all Jinja nodes. There are a number of nodes available of different types. There are four major types: - :class:`Stmt`: statements diff --git a/jinja2/parser.py b/jinja2/parser.py index c91683e..7403b08 100644 --- a/jinja2/parser.py +++ b/jinja2/parser.py @@ -30,7 +30,7 @@ _math_nodes = { class Parser(object): - """This is the central parsing class Jinja2 uses. It's passed to + """This is the central parsing class Jinja uses. It's passed to extensions and can be used to parse expressions or statements. """ @@ -395,7 +395,7 @@ class Parser(object): def parse_assign_target(self, with_tuple=True, name_only=False, extra_end_rules=None, with_namespace=False): - """Parse an assignment target. As Jinja2 allows assignments to + """Parse an assignment target. As Jinja allows assignments to tuples, this function can parse all allowed assignment targets. Per default assignments to tuples are parsed, that can be disable however by setting `with_tuple` to `False`. If only assignments to names are diff --git a/jinja2/tests.py b/jinja2/tests.py index 87f9c0c..aeec860 100644 --- a/jinja2/tests.py +++ b/jinja2/tests.py @@ -87,7 +87,7 @@ def test_true(value): return value is True -# NOTE: The existing Jinja2 'number' test matches booleans and floats +# NOTE: The existing 'number' test matches booleans and floats def test_integer(value): """Return true if the object is an integer. @@ -96,7 +96,7 @@ def test_integer(value): return isinstance(value, integer_types) and value is not True and value is not False -# NOTE: The existing Jinja2 'number' test matches booleans and integers +# NOTE: The existing 'number' test matches booleans and integers def test_float(value): """Return true if the object is a float. diff --git a/jinja2/utils.py b/jinja2/utils.py index fb689dd..5518793 100644 --- a/jinja2/utils.py +++ b/jinja2/utils.py @@ -110,8 +110,8 @@ def consume(iterable): def clear_caches(): - """Jinja2 keeps internal caches for environments and lexers. These are - used so that Jinja2 doesn't have to recreate environments and lexers all + """Jinja keeps internal caches for environments and lexers. These are + used so that Jinja doesn't have to recreate environments and lexers all the time. Normally you don't have to care about that but if you are measuring memory consumption you may want to clean the caches. """ diff --git a/scripts/jinja2-debug.py b/scripts/jinja2-debug.py index d052adc..71daeb9 100755 --- a/scripts/jinja2-debug.py +++ b/scripts/jinja2-debug.py @@ -1,10 +1,10 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- """ - Jinja2 Debug Interface - ~~~~~~~~~~~~~~~~~~~~~~ + Jinja Debug Interface + ~~~~~~~~~~~~~~~~~~~~~ - Helper script for internal Jinja2 debugging. Requires Werkzeug. + Helper script for internal Jinja debugging. Requires Werkzeug. :copyright: Copyright 2010 by Armin Ronacher. :license: BSD. |