(airflow) branch v3-3-test updated: [v3-3-test] Document native template rendering type coercion (#34641) (#69152) (#69389)

[po...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch v3-3-test
in repository https://gitbox.apache.org/repos/asf/airflow.git


The following commit(s) were added to refs/heads/v3-3-test by this push:
     new 05df5501a02 [v3-3-test] Document native template rendering type coercion (#34641) (#69152) (#69389)
05df5501a02 is described below

commit 05df5501a028fb14376fc233899eea03309e2522
Author: github-actions[bot] <41...@users.noreply.github.com>
AuthorDate: Sun Jul 5 15:52:22 2026 +0200

    [v3-3-test] Document native template rendering type coercion (#34641) (#69152) (#69389)
    
    (cherry picked from commit b5a60ceae6b6bbe4434782d682aba275d4034e17)
    
    Co-authored-by: Deepak Jain <de...@users.noreply.github.com>
---
 airflow-core/docs/core-concepts/operators.rst | 7 +++++++
 airflow-core/docs/core-concepts/params.rst    | 5 +++++
 2 files changed, 12 insertions(+)

diff --git a/airflow-core/docs/core-concepts/operators.rst b/airflow-core/docs/core-concepts/operators.rst
index ac460183c2f..6bcf4a3c714 100644
--- a/airflow-core/docs/core-concepts/operators.rst
+++ b/airflow-core/docs/core-concepts/operators.rst
@@ -303,6 +303,13 @@ Alternatively, Jinja can also be instructed to render a native Python object. Th
             python_callable=transform,
         )
 
+.. note::
+
+    ``NativeEnvironment`` renders values according to Python literal rules. This is useful when a template
+    should produce a list, dict, number, or boolean, but it also means a string that looks like a number,
+    such as ``"42"``, can be rendered as the integer ``42``. Keep the default string rendering, use a
+    callable template field, or add explicit quoting if the task needs the value to stay a string.
+
 
 .. _concepts:reserved-keywords:
 
diff --git a/airflow-core/docs/core-concepts/params.rst b/airflow-core/docs/core-concepts/params.rst
index ac5df462fac..2f70611e88c 100644
--- a/airflow-core/docs/core-concepts/params.rst
+++ b/airflow-core/docs/core-concepts/params.rst
@@ -145,6 +145,11 @@ This way, the :class:`~airflow.sdk.definitions.param.Param`'s type is respected
         ),
     )
 
+Because ``render_template_as_native_obj=True`` uses Jinja's native rendering, values that look like
+Python literals can also be converted. For example, a string value of ``"42"`` may be rendered as the
+integer ``42``. Leave native rendering disabled, use a callable template field, or quote the value
+explicitly when the task must receive a string.
+
 Another way to access your param is via a task's ``context`` kwarg.
 
 .. code-block::