Merge branch 'stable'

.github/workflows/publish.yaml

@@ -23,7 +23,7 @@ jobs:
       - name: generate hash
         id: hash
         run: cd dist && echo "hash=$(sha256sum * | base64 -w0)" >> $GITHUB_OUTPUT
-      - uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
+      - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
         with:
           path: ./dist
   provenance:
@@ -64,10 +64,6 @@ jobs:
       id-token: write
     steps:
       - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
-      - uses: pypa/gh-action-pypi-publish@f7600683efdcb7656dec5b29656edb7bc586e597 # v1.10.3
-        with:
-          repository-url: https://test.pypi.org/legacy/
-          packages-dir: artifact/
-      - uses: pypa/gh-action-pypi-publish@f7600683efdcb7656dec5b29656edb7bc586e597 # v1.10.3
+      - uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
         with:
           packages-dir: artifact/

.github/workflows/tests.yaml

@@ -42,7 +42,7 @@ jobs:
           cache: pip
           cache-dependency-path: requirements*/*.txt
       - name: cache mypy
-        uses: actions/cache@6849a6489940f00c2f30c0fb92c6274307ccb58a # v4.1.2
+        uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0
         with:
           path: ./.mypy_cache
           key: mypy|${{ hashFiles('pyproject.toml') }}

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.7.1
+    rev: v0.8.4
     hooks:
       - id: ruff
       - id: ruff-format

CHANGES.rst

@@ -14,8 +14,16 @@ Unreleased
 Version 3.1.5
 -------------
 
-Unreleased
-
+Released 2024-12-21
+
+-   The sandboxed environment handles indirect calls to ``str.format``, such as
+    by passing a stored reference to a filter that calls its argument.
+    :ghsa:`q2x7-8rv6-6q7h`
+-   Escape template name before formatting it into error messages, to avoid
+    issues with names that contain f-string syntax.
+    :issue:`1792`, :ghsa:`gmj6-6f8f-6699`
+-   Sandbox does not allow ``clear`` and ``pop`` on known mutable sequence
+    types. :issue:`2032`
 -   Calling sync ``render`` for an async template uses ``asyncio.run``.
     :pr:`1952`
 -   Avoid unclosed ``auto_aiter`` warnings. :pr:`1960`
@@ -25,6 +33,32 @@ Unreleased
     ``Template.generate_async``. :pr:`1960`
 -   Avoid leaving async generators unclosed in blocks, includes and extends.
     :pr:`1960`
+-   The runtime uses the correct ``concat`` function for the current environment
+    when calling block references. :issue:`1701`
+-   Make ``|unique`` async-aware, allowing it to be used after another
+    async-aware filter. :issue:`1781`
+-   ``|int`` filter handles ``OverflowError`` from scientific notation.
+    :issue:`1921`
+-   Make compiling deterministic for tuple unpacking in a ``{% set ... %}``
+    call. :issue:`2021`
+-   Fix dunder protocol (`copy`/`pickle`/etc) interaction with ``Undefined``
+    objects. :issue:`2025`
+-   Fix `copy`/`pickle` support for the internal ``missing`` object.
+    :issue:`2027`
+-   ``Environment.overlay(enable_async)`` is applied correctly. :pr:`2061`
+-   The error message from ``FileSystemLoader`` includes the paths that were
+    searched. :issue:`1661`
+-   ``PackageLoader`` shows a clearer error message when the package does not
+    contain the templates directory. :issue:`1705`
+-   Improve annotations for methods returning copies. :pr:`1880`
+-   ``urlize`` does not add ``mailto:`` to values like `@a@b`. :pr:`1870`
+-   Tests decorated with `@pass_context`` can be used with the ``|select``
+    filter. :issue:`1624`
+-   Using ``set`` for multiple assignment (``a, b = 1, 2``) does not fail when the
+    target is a namespace attribute. :issue:`1413`
+-   Using ``set`` in all branches of ``{% if %}{% elif %}{% else %}`` blocks
+    does not cause the variable to be considered initially undefined.
+    :issue:`1253`
 
 
 Version 3.1.4
@@ -1012,7 +1046,7 @@ Released 2008-07-17, codename Jinjavitus
     evaluates to ``false``.
 -   Improved error reporting for undefined values by providing a
     position.
--   ``filesizeformat`` filter uses decimal prefixes now per default and
+-   ``filesizeformat`` filter uses decimal prefixes now by default and
     can be set to binary mode with the second parameter.
 -   Fixed bug in finalizer
 

docs/api.rst

@@ -666,8 +666,8 @@ Now it can be used in templates:
 
 .. sourcecode:: jinja
 
-    {{ article.pub_date|datetimeformat }}
-    {{ article.pub_date|datetimeformat("%B %Y") }}
+    {{ article.pub_date|datetime_format }}
+    {{ article.pub_date|datetime_format("%B %Y") }}
 
 Some decorators are available to tell Jinja to pass extra information to
 the filter. The object is passed as the first argument, making the value

docs/conf.py

@@ -24,7 +24,7 @@
 extlinks = {
     "issue": ("https://github.com/pallets/jinja/issues/%s", "#%s"),
     "pr": ("https://github.com/pallets/jinja/pull/%s", "#%s"),
-    "ghsa": ("https://github.com/advisories/GHSA-%s", "GHSA-%s"),
+    "ghsa": ("https://github.com/pallets/jinja/security/advisories/GHSA-%s", "GHSA-%s"),
 }
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),

docs/faq.rst

@@ -70,6 +70,8 @@ these document types.
 
 While automatic escaping means that you are less likely have an XSS
 problem, it also requires significant extra processing during compiling
-and rendering, which can reduce performance. Jinja uses MarkupSafe for
+and rendering, which can reduce performance. Jinja uses `MarkupSafe`_ for
 escaping, which provides optimized C code for speed, but it still
 introduces overhead to track escaping across methods and formatting.
+
+.. _MarkupSafe: https://markupsafe.palletsprojects.com/

docs/nativetypes.rst

@@ -55,6 +55,17 @@ Foo
 >>> print(result.value)
 15
 
+Sandboxed Native Environment
+----------------------------
+
+You can combine :class:`.SandboxedEnvironment` and :class:`NativeEnvironment` to
+get both behaviors.
+
+.. code-block:: python
+
+    class SandboxedNativeEnvironment(SandboxedEnvironment, NativeEnvironment):
+        pass
+
 API
 ---
 

docs/templates.rst

@@ -202,27 +202,33 @@ option can also be set to strip tabs and spaces from the beginning of a
 line to the start of a block. (Nothing will be stripped if there are
 other characters before the start of the block.)
 
-With both `trim_blocks` and `lstrip_blocks` enabled, you can put block tags
-on their own lines, and the entire block line will be removed when
-rendered, preserving the whitespace of the contents.  For example,
-without the `trim_blocks` and `lstrip_blocks` options, this template::
+With both ``trim_blocks`` and ``lstrip_blocks`` disabled (the default), block
+tags on their own lines will be removed, but a blank line will remain and the
+spaces in the content will be preserved. For example, this template:
+
+.. code-block:: jinja
 
     <div>
         {% if True %}
             yay
         {% endif %}
     </div>
 
-gets rendered with blank lines inside the div::
+With both ``trim_blocks`` and ``lstrip_blocks`` disabled, the template is
+rendered with blank lines inside the div:
+
+.. code-block:: text
 
     <div>
 
             yay
 
     </div>
 
-But with both `trim_blocks` and `lstrip_blocks` enabled, the template block
-lines are removed and other whitespace is preserved::
+With both ``trim_blocks`` and ``lstrip_blocks`` enabled, the template block
+lines are completely removed:
+
+.. code-block:: text
 
     <div>
             yay
@@ -522,8 +528,8 @@ However, the name after the `endblock` word must match the block name.
 Block Nesting and Scope
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Blocks can be nested for more complex layouts.  However, per default blocks
-may not access variables from outer scopes::
+Blocks can be nested for more complex layouts. By default, a block may not
+access variables from outside the block (outer scopes)::
 
     {% for item in seq %}
         <li>{% block loop_item %}{{ item }}{% endblock %}</li>
@@ -1080,34 +1086,34 @@ Assignments use the `set` tag and can have multiple targets::
 Block Assignments
 ~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 2.8
+It's possible to use `set` as a block to assign the content of the block to a
+variable. This can be used to create multi-line strings, since Jinja doesn't
+support Python's triple quotes (``"""``, ``'''``).
 
-Starting with Jinja 2.8, it's possible to also use block assignments to
-capture the contents of a block into a variable name.  This can be useful
-in some situations as an alternative for macros.  In that case, instead of
-using an equals sign and a value, you just write the variable name and then
-everything until ``{% endset %}`` is captured.
+Instead of using an equals sign and a value, you only write the variable name,
+and everything until ``{% endset %}`` is captured.
 
-Example::
+.. code-block:: jinja
 
     {% set navigation %}
         <li><a href="/">Index</a>
         <li><a href="/downloads">Downloads</a>
     {% endset %}
 
-The `navigation` variable then contains the navigation HTML source.
-
-.. versionchanged:: 2.10
-
-Starting with Jinja 2.10, the block assignment supports filters.
+Filters applied to the variable name will be applied to the block's content.
 
-Example::
+.. code-block:: jinja
 
     {% set reply | wordwrap %}
         You wrote:
         {{ message }}
     {% endset %}
 
+.. versionadded:: 2.8
+
+.. versionchanged:: 2.10
+
+    Block assignment supports filters.
 
 .. _extends:
 
@@ -1406,28 +1412,32 @@ Comparisons
 Logic
 ~~~~~
 
-For ``if`` statements, ``for`` filtering, and ``if`` expressions, it can be useful to
-combine multiple expressions:
+For ``if`` statements, ``for`` filtering, and ``if`` expressions, it can be
+useful to combine multiple expressions.
 
 ``and``
-    Return true if the left and the right operand are true.
+    For ``x and y``, if ``x`` is false, then the value is ``x``, else ``y``. In
+    a boolean context, this will be treated as ``True`` if both operands are
+    truthy.
 
 ``or``
-    Return true if the left or the right operand are true.
+    For ``x or y``, if ``x`` is true, then the value is ``x``, else ``y``. In a
+    boolean context, this will be treated as ``True`` if at least one operand is
+    truthy.
 
 ``not``
-    negate a statement (see below).
-
-``(expr)``
-    Parentheses group an expression.
-
-.. admonition:: Note
+    For ``not x``, if ``x`` is false, then the value is ``True``, else
+    ``False``.
 
-    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:
+    Prefer negating ``is`` and ``in`` using their infix notation:
+    ``foo is not bar`` instead of ``not foo is bar``; ``foo not in bar`` instead
+    of ``not foo in bar``. All other expressions require prefix notation:
     ``not (foo and bar).``
 
+``(expr)``
+    Parentheses group an expression. This is used to change evaluation order, or
+    to make a long expression easier to read or less ambiguous.
+
 
 Other Operators
 ~~~~~~~~~~~~~~~
@@ -1668,6 +1678,9 @@ The following functions are available in the global scope by default:
 
     .. versionadded:: 2.10
 
+    .. versionchanged:: 3.2
+        Namespace attributes can be assigned to in multiple assignment.
+
 
 Extensions
 ----------
@@ -1778,7 +1791,7 @@ It's possible to translate strings in expressions with these functions:
 
 -   ``_(message)``: Alias for ``gettext``.
 -   ``gettext(message)``: Translate a message.
--   ``ngettext(singluar, plural, n)``: Translate a singular or plural
+-   ``ngettext(singular, plural, n)``: Translate a singular or plural
     message based on a count variable.
 -   ``pgettext(context, message)``: Like ``gettext()``, but picks the
     translation based on the context string.

docs/tricks.rst

@@ -21,7 +21,7 @@ for a neat trick.
 Usually child templates extend from one template that adds a basic HTML
 skeleton.  However it's possible to put the `extends` tag into an `if` tag to
 only extend from the layout template if the `standalone` variable evaluates
-to false which it does per default if it's not defined.  Additionally a very
+to false, which it does by default if it's not defined.  Additionally a very
 basic skeleton is added to the file so that if it's indeed rendered with
 `standalone` set to `True` a very basic HTML skeleton is added::
 

examples/basic/test.py

@@ -6,9 +6,9 @@
         {
             "child.html": """\
 {% extends default_layout or 'default.html' %}
-{% include helpers = 'helpers.html' %}
+{% import 'helpers.html' as helpers %}
 {% macro get_the_answer() %}42{% endmacro %}
-{% title = 'Hello World' %}
+{% set title = 'Hello World' %}
 {% block body %}
     {{ get_the_answer() }}
     {{ helpers.conspirate() }}

requirements/build.txt

@@ -6,7 +6,7 @@
 #
 build==1.2.2.post1
     # via -r build.in
-packaging==24.1
+packaging==24.2
     # via build
 pyproject-hooks==1.2.0
     # via build