[GitHub] [airflow] dstandish commented on a diff in pull request #33296: add concrete examples for accessing context variables from TaskFlow tasks

["dstandish (via GitHub)" <gi...@apache.org>]

dstandish commented on code in PR #33296:
URL: https://github.com/apache/airflow/pull/33296#discussion_r1290724368


##########
docs/apache-airflow/templates-ref.rst:
##########
@@ -81,6 +81,18 @@ Variable                                    Type                  Description
     The DAG run's logical date, and values derived from it, such as ``ds`` and
     ``ts``, **should not** be considered unique in a DAG. Use ``run_id`` instead.
 
+Accessing Airflow context variables from TaskFlow tasks 
+-------------------------------------------------------
+
+While ``@task`` decorated tasks don't support rendering jinja templates passed as arguments, 

Review Comment:
   Not sure it makes sense to lead off talking about templating being unsupported in a section about context vars.  Might be better to go straight into the content of the section.  
   
   Maybe add a section or a `.. note:` mentioning that templating is not supported in taskflow. 



##########
docs/apache-airflow/core-concepts/taskflow.rst:
##########
@@ -66,9 +66,16 @@ If you want to learn more about using TaskFlow, you should consult :doc:`the Tas
 Context
 -------
 
-When running your callable, Airflow will pass a set of keyword arguments that can be used in your function. This set of kwargs correspond exactly to the :ref:`context variables<templates:variables>` you can use in your Jinja templates.
+When running a ``@task`` decorated Python function, Airflow can pass a set of keyword arguments to the function.
+These keyword arguments correspond exactly to the :ref:`context variables<templates:variables>` that can be used in 
+Jinja templates.
+
+To access all of these context variables, pass ``**kwargs`` to the function's parameters and access them from the ``kwargs`` 
+dictionary (e.g. ``kwargs["task_instance"]``). Alternatively, you can add a specific keyword argument you would like to access. 
+For example, to access a task's ``task_instance`` object at runtime, you could do so as follows:
+
+.. include:: ../../shared/template-examples/taskflow.rst
 

Review Comment:
   ```suggestion
   You can access Airflow :ref:`context variables <templates:variables>` by adding them as keyword arguments as shown in the following example:
   
   .. include:: ../../shared/template-examples/taskflow.rst
   
   Alternatively you may add `**kwargs` to the signature of your task and all Airflow context variables will be accessible in the `kwargs` dict.
   
   .. include:: ../../shared/template-examples/taskflow-kwargs.rst
   
   For a full list of context variables, see :ref:`context variables <templates:variables>`.
   ```
   
   
   Thought something like this might be simpler.
   
   Because when e.g. you read this:
   
   > When running a ``@task`` decorated Python function, Airflow can pass a set of keyword arguments to the function.
   
   You're like "what the heck do you mean 'airflow can pass set of keyword arguments'".  So i'm being more explicit by saying "you can access context vars in your taskflow".  What are context vars? Also a fair question.  I am not sure if it's appropriate here but if yo feel it's appropriate, could add one sentence like explaining what they are.  Either that or assume that user already knows or will follow the link to find out. 
   
   Note also i'm suggesting here to add an example for `kwargs` to lean heavier on example than explanation for that cus it ends up being a lot of text to digest.



##########
docs/shared/template-examples/taskflow.rst:
##########
@@ -0,0 +1,6 @@
+ .. code-block:: python
+
+    @task
+    def print_ti_info(task_instance=None):

Review Comment:
   maybe add one or two more variables



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org