(airflow) 09/12: Add documentation for context parameter (#55377)

[ka...@apache.org]

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

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

commit 107c1f70d08a9e3b214cc9b3cc7528f9f650fdf7
Author: Karthik S <83...@users.noreply.github.com>
AuthorDate: Sun Sep 14 08:38:57 2025 +0530

    Add documentation for context parameter  (#55377)
    
    * Update operators.rst
    
    - Clarified usage of the `context` parameter in callables.
    - Expanded context variable documentation and examples.
    
    * Update operators.rst
    
    Incorporating feedback. Removing specific examples and adding link to the Context docs. Using typed dict for context.
    
    * Update operators.rst
    
    Added additional syntax
    
    * Update operators.rst
    
    - Clarified usage of the `context` parameter in callables.
    - Expanded context variable documentation and examples.
    
    * Update operators.rst
    
    Incorporating feedback. Removing specific examples and adding link to the Context docs. Using typed dict for context.
    
    * Update operators.rst
    
    Added additional syntax
    
    * Update operators.rst
    
    Pushing modifications based on review comments. Removing Git links as they are prone to changes and linking python specific code to its relevant docs on python.
    
    (cherry picked from commit 34b190791c2268f384842dbdcfc781a47ebedd5a)
---
 airflow-core/docs/core-concepts/operators.rst | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/airflow-core/docs/core-concepts/operators.rst b/airflow-core/docs/core-concepts/operators.rst
index 256613537b4..2e8b82713d3 100644
--- a/airflow-core/docs/core-concepts/operators.rst
+++ b/airflow-core/docs/core-concepts/operators.rst
@@ -84,11 +84,25 @@ Here, ``{{ ds }}`` is a templated variable, and because the ``env`` parameter of
 
 You can also pass in a callable instead when Python is more readable than a Jinja template. The callable must accept two named arguments ``context`` and ``jinja_env``:
 
+The ``context`` parameter is an Airflow's ``Context`` object that provides runtime information for the current task execution. Its contents can be accessed with Python's standard `dict syntax <https://docs.python.org/3/library/stdtypes.html#mapping-types-dict>`_. It includes all variables available in Jinja templates and is read-only from the perspective of template rendering - while you can access and use its values, modifications won't affect the task execution environment.
+
+For a complete list of available context variables see :ref:`Templates reference <templates:variables>`.
+
 .. code-block:: python
 
-    def build_complex_command(context, jinja_env):
+    from typing import TYPE_CHECKING
+
+    if TYPE_CHECKING:
+        import jinja2
+        from airflow.sdk import Context
+
+
+    def build_complex_command(context: Context, jinja_env: jinja2.Environment) -> str:
+        # Access runtime information from the context dictionary
+        task_id = context["ti"].task_id
+        execution_date = context["ds"]
         with open("file.csv") as f:
-            return do_complex_things(f)
+            return do_complex_things(f, task_id, execution_date)
 
 
     t = BashOperator(
@@ -101,7 +115,7 @@ Since each template field is only rendered once, the callable's return value wil
 
 .. code-block:: python
 
-    def build_complex_command(context, jinja_env):
+    def build_complex_command(context: Context, jinja_env: jinja2.Environment) -> str:
         with open("file.csv") as f:
             data = do_complex_things(f)
         return context["task"].render_template(data, context, jinja_env)