Jinja Documentation (3.0.X) Release 3.0.0
Total Page:16
File Type:pdf, Size:1020Kb
Jinja Documentation (3.0.x) Release 3.0.0 Pallets May 11, 2021 CONTENTS: 1 Introduction 3 1.1 Prerequisites...............................................3 1.2 Installation................................................3 1.3 Basic API Usage.............................................4 2 API 5 2.1 Basics...................................................5 2.2 Unicode..................................................6 2.3 High Level API..............................................6 2.4 Autoescaping............................................... 13 2.5 Notes on Identifiers............................................ 14 2.6 Undefined Types............................................. 14 2.7 The Context............................................... 17 2.8 Loaders.................................................. 18 2.9 Bytecode Cache............................................. 21 2.10 Async Support.............................................. 23 2.11 Policies.................................................. 23 2.12 Utilities.................................................. 24 2.13 Exceptions................................................ 25 2.14 Custom Filters.............................................. 26 2.15 Evaluation Context............................................ 27 2.16 Custom Tests............................................... 28 2.17 The Global Namespace.......................................... 28 2.18 Low Level API.............................................. 29 2.19 The Meta API.............................................. 30 3 Sandbox 31 3.1 API.................................................... 31 3.2 Operator Intercepting........................................... 33 4 Native Python Types 35 4.1 Examples................................................. 35 4.2 API.................................................... 36 5 Template Designer Documentation 37 5.1 Synopsis................................................. 37 5.2 Variables................................................. 38 5.3 Filters................................................... 39 5.4 Tests................................................... 39 5.5 Comments................................................ 39 i 5.6 Whitespace Control........................................... 39 5.7 Escaping................................................. 41 5.8 Line Statements............................................. 41 5.9 Template Inheritance........................................... 42 5.10 HTML Escaping............................................. 45 5.11 List of Control Structures........................................ 46 5.12 Import Context Behavior......................................... 53 5.13 Expressions................................................ 54 5.14 List of Builtin Filters........................................... 57 5.15 List of Builtin Tests........................................... 67 5.16 List of Global Functions......................................... 69 5.17 Extensions................................................ 71 5.18 Autoescape Overrides.......................................... 74 6 Extensions 77 6.1 Adding Extensions............................................ 77 6.2 i18n Extension.............................................. 77 6.3 Expression Statement.......................................... 79 6.4 Loop Controls.............................................. 79 6.5 With Statement.............................................. 79 6.6 Autoescape Extension.......................................... 79 6.7 Debug Extension............................................. 80 6.8 Writing Extensions............................................ 80 6.9 Example Extensions........................................... 80 6.10 Extension API.............................................. 83 7 Integration 95 7.1 Babel Integration............................................. 95 7.2 Pylons.................................................. 95 7.3 TextMate................................................. 96 7.4 Vim.................................................... 96 8 Switching from other Template Engines 97 8.1 Jinja 1................................................... 97 8.2 Django.................................................. 98 8.3 Mako................................................... 99 9 Tips and Tricks 101 9.1 Null-Master Fallback........................................... 101 9.2 Alternating Rows............................................. 101 9.3 Highlighting Active Menu Items..................................... 101 9.4 Accessing the parent Loop........................................ 102 10 Frequently Asked Questions 103 10.1 Why is it called Jinja?.......................................... 103 10.2 How fast is it?.............................................. 103 10.3 How Compatible is Jinja with Django?................................. 103 10.4 Isn’t it a terrible idea to put Logic into Templates?........................... 104 10.5 Why is Autoescaping not the Default?.................................. 104 10.6 Why is the Context immutable?..................................... 104 10.7 My tracebacks look weird. What’s happening?............................. 105 10.8 Why is there no Python 2.3/2.4/2.5/2.6/3.1/3.2/3.3 support?...................... 105 10.9 My Macros are overridden by something................................ 105 11 Changelog 107 ii 11.1 Version 2.11.3.............................................. 107 11.2 Version 2.11.2.............................................. 107 11.3 Version 2.11.1.............................................. 107 11.4 Version 2.11.0.............................................. 108 11.5 Version 2.10.3.............................................. 109 11.6 Version 2.10.2.............................................. 109 11.7 Version 2.10.1.............................................. 109 11.8 Version 2.10............................................... 110 11.9 Version 2.9.6............................................... 110 11.10 Version 2.9.5............................................... 110 11.11 Version 2.9.4............................................... 111 11.12 Version 2.9.3............................................... 111 11.13 Version 2.9.2............................................... 111 11.14 Version 2.9.1............................................... 112 11.15 Version 2.9................................................ 112 11.16 Version 2.8.1............................................... 113 11.17 Version 2.8................................................ 113 11.18 Version 2.7.3............................................... 113 11.19 Version 2.7.2............................................... 114 11.20 Version 2.7.1............................................... 114 11.21 Version 2.7................................................ 114 11.22 Version 2.6................................................ 115 11.23 Version 2.5.5............................................... 115 11.24 Version 2.5.4............................................... 115 11.25 Version 2.5.3............................................... 116 11.26 Version 2.5.2............................................... 116 11.27 Version 2.5.1............................................... 116 11.28 Version 2.5................................................ 116 11.29 Version 2.4.1............................................... 117 11.30 Version 2.4................................................ 117 11.31 Version 2.3.1............................................... 117 11.32 Version 2.3................................................ 117 11.33 Version 2.2.1............................................... 118 11.34 Version 2.2................................................ 118 11.35 Version 2.1.1............................................... 118 11.36 Version 2.1................................................ 118 11.37 Version 2.0................................................ 119 11.38 Version 2.0rc1.............................................. 119 Python Module Index 121 Index 123 iii iv Jinja Documentation (3.0.x), Release 3.0.0 Jinja is a modern and designer-friendly templating language for Python, modelled after Django’s templates. It is fast, widely used and secure with the optional sandboxed template execution environment: <title>{% block title %}{% endblock %}</title> <ul> {% for user in users %} <li><a href="{{ user.url }}">{{ user.username }}</a></li> {% endfor %} </ul> Features: • sandboxed execution • powerful automatic HTML escaping system for XSS prevention • template inheritance • compiles down to the optimal python code just in time • optional ahead-of-time template compilation • easy to debug. Line numbers of exceptions directly point to the correct line in the template. • configurable syntax CONTENTS: 1 Jinja Documentation (3.0.x), Release 3.0.0 2 CONTENTS: CHAPTER ONE INTRODUCTION 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 Jinja. It’s both designer and developer friendly by sticking to Python’s principles and adding functionality useful for templating environments. 1.1 Prerequisites 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