You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by "henry3260 (via GitHub)" <gi...@apache.org> on 2026/09/22 09:22:23 UTC
[PR] Update Go SDK docs for the airflow.Bundle authoring surface [airflow]
henry3260 opened a new pull request, #73528:
URL: https://github.com/apache/airflow/pull/73528
The Go SDK's authoring API was replaced by the `airflow` package (#73277, #73394, #73426), but the docs still taught the removed one. Following them today produces a bundle that does not compile, and handlers the runtime rejects at registration.
This is the migration step that has to land between the new surface and the removal of the old one.
### What changed
`airflow-core/docs/authoring-and-scheduling/language-sdks/go.rst` (user-facing) and `go-sdk/README.md`:
- The entry point is now `airflow.Bundle()` / `Register` / `airflow.TaskHandler(dagId, taskId, fn)` / `Serve`, replacing `bundlev1.BundleProvider` and `RegisterDags`.
- **Both ids are written out explicitly.** The old docs said "task_id is taken from the function name", which silently produces a bundle whose tasks the supervisor cannot find.
- Parameters are no longer injected by type. Every handler takes an `airflow.Context` first and reaches the logger, client, task instance and Dag run through it; declaring an `sdk.Client` or `*slog.Logger` parameter is now rejected. The "Injected value" table became a table of Context methods.
- The rst gained the TaskFlow argument-binding section it never had, plus the `airflow.NewContext` unit-testing story. Binding rules stay single-sourced in the README so the two documents cannot drift.
Also: two stale comments (`example/bundle/concurrentxcom`, `pack_integration_test.go`), and ADR 0007 spelled the shipped interface `Registraterable` rather than `Registerable`.
No Go code changes — `go-sdk/example/` and `kubernetes-tests/lang_sdk/go_example/` were migrated in #73426, and the e2e suite packs the example bundle, so it follows along.
### Deliberately not in scope
ADRs 0002, 0003 and 0005 still describe the old interface. #73426 annotated 0001 with `(removed)` rather than rewriting it; applying that same treatment is a separate, mechanical change and is left for a follow-up PR to keep this one reviewable.
---
##### Was generative AI tooling used to co-author this PR?
- [X] Yes — Claude Code (Opus 5)
Generated-by: Claude Code (Opus 5) following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions)
--
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
Re: [PR] Update Go SDK docs for the airflow.Bundle authoring surface [airflow]
Posted by "henry3260 (via GitHub)" <gi...@apache.org>.
henry3260 commented on code in PR #73528:
URL: https://github.com/apache/airflow/pull/73528#discussion_r4070811554
##########
go-sdk/README.md:
##########
@@ -169,37 +167,55 @@ data parameters is rejected at registration. A sole struct parameter also falls
decoding when it gets exactly one passed argument no field claims, so a task can still take an
upstream object as a single argument.
-### Reading the task runtime context
+### The task context
+
+`airflow.Context` is the first parameter of every task handler -- the Go equivalent of the execution
+context the Python and Java SDKs expose. Everything Airflow gives the task is a method on it:
Review Comment:
> Would it be better to not mention the other SDKs in the Go-SDK README.
oh got it
--
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
Re: [PR] Update Go SDK docs for the airflow.Bundle authoring surface [airflow]
Posted by "henry3260 (via GitHub)" <gi...@apache.org>.
henry3260 commented on code in PR #73528:
URL: https://github.com/apache/airflow/pull/73528#discussion_r4070972240
##########
airflow-core/docs/authoring-and-scheduling/language-sdks/go.rst:
##########
@@ -268,30 +295,74 @@ so you can branch on a missing value with ``errors.Is`` rather than parsing an e
Reading the task runtime context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Declare an ``sdk.TIRunContext`` parameter on a task to read the identifiers and scheduling timestamps of the
-running task instance and its Dag run -- the Go equivalent of the execution context the Python and Java SDKs
-expose. It is an interface that embeds ``context.Context``, so the same ``ctx`` drives cancellation and
-client calls. The runtime binds it by type, just like the other injected parameters:
+``airflow.Context`` carries the identifiers and scheduling timestamps of the running task instance and its
+Dag run -- the Go equivalent of the execution context the Python and Java SDKs expose:
.. code-block:: go
- func extract(ctx sdk.TIRunContext, log *slog.Logger) (any, error) {
- ti := ctx.TaskInstance()
- log.Info("running",
+ func extract(actx airflow.Context) (any, error) {
+ ti := actx.TaskInstance()
+ actx.Logger().InfoContext(actx, "running",
"dag_id", ti.DagID,
"run_id", ti.RunID,
"task_id", ti.TaskID,
"try_number", ti.TryNumber,
- "logical_date", ctx.DagRun().LogicalDate,
+ "logical_date", actx.DagRun().LogicalDate,
)
return nil, nil
}
-``ctx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
-and ``TryNumber``; ``ctx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
+``actx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
+and ``TryNumber``; ``actx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
``LogicalDate``, ``DataIntervalStart``, and ``DataIntervalEnd`` (nil when the run has no such value, e.g. a
manual trigger).
+.. _go-sdk/arguments:
+
+Receiving arguments from the stub Dag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every parameter after the ``airflow.Context`` is a **data parameter**, filled in declaration order from the
+arguments of the Python stub Dag's TaskFlow call. A literal in the Dag file (``transform("uk", ...)``)
+decodes straight into the parameter; an upstream task's output (``transform(..., extract())``) is pulled
+from that task's XCom in the current Dag run. If the argument count does not match, or an argument's
+declared type cannot fill the Go type, the task fails before its body runs.
+
Review Comment:
I put this at the start of the chapter intentionally placing it after the details would lose its guiding effect for readers.
--
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
Re: [PR] Update Go SDK docs for the airflow.Bundle authoring surface [airflow]
Posted by "jason810496 (via GitHub)" <gi...@apache.org>.
jason810496 merged PR #73528:
URL: https://github.com/apache/airflow/pull/73528
--
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
Re: [PR] Update Go SDK docs for the airflow.Bundle authoring surface [airflow]
Posted by "jason810496 (via GitHub)" <gi...@apache.org>.
jason810496 commented on code in PR #73528:
URL: https://github.com/apache/airflow/pull/73528#discussion_r4070592736
##########
airflow-core/docs/authoring-and-scheduling/language-sdks/go.rst:
##########
@@ -268,30 +295,74 @@ so you can branch on a missing value with ``errors.Is`` rather than parsing an e
Reading the task runtime context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Declare an ``sdk.TIRunContext`` parameter on a task to read the identifiers and scheduling timestamps of the
-running task instance and its Dag run -- the Go equivalent of the execution context the Python and Java SDKs
-expose. It is an interface that embeds ``context.Context``, so the same ``ctx`` drives cancellation and
-client calls. The runtime binds it by type, just like the other injected parameters:
+``airflow.Context`` carries the identifiers and scheduling timestamps of the running task instance and its
+Dag run -- the Go equivalent of the execution context the Python and Java SDKs expose:
.. code-block:: go
- func extract(ctx sdk.TIRunContext, log *slog.Logger) (any, error) {
- ti := ctx.TaskInstance()
- log.Info("running",
+ func extract(actx airflow.Context) (any, error) {
+ ti := actx.TaskInstance()
+ actx.Logger().InfoContext(actx, "running",
"dag_id", ti.DagID,
"run_id", ti.RunID,
"task_id", ti.TaskID,
"try_number", ti.TryNumber,
- "logical_date", ctx.DagRun().LogicalDate,
+ "logical_date", actx.DagRun().LogicalDate,
)
return nil, nil
}
-``ctx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
-and ``TryNumber``; ``ctx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
+``actx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
+and ``TryNumber``; ``actx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
``LogicalDate``, ``DataIntervalStart``, and ``DataIntervalEnd`` (nil when the run has no such value, e.g. a
manual trigger).
+.. _go-sdk/arguments:
+
+Receiving arguments from the stub Dag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Review Comment:
```suggestion
Receiving arguments from the stub Task
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
##########
airflow-core/docs/authoring-and-scheduling/language-sdks/go.rst:
##########
@@ -200,37 +204,59 @@ There is no separate Go worker to run: the Airflow worker forks the bundle binar
Writing tasks
-------------
-The runtime inspects a task function's signature and injects arguments by type, so you only declare the
-parameters your task actually needs:
+Every task function takes an ``airflow.Context`` as its first parameter, and reaches what Airflow provides
+through its methods:
.. list-table::
:header-rows: 1
:widths: 35 65
- * - Parameter type
- - Injected value
- * - ``sdk.TIRunContext``
- - The task's execution context: the cancellation/deadline signal plus the task instance identifiers and
- Dag run timestamps. Respect it for long-running work. See :ref:`go-sdk/runtime-context`.
- * - ``*slog.Logger``
- - A logger whose output is routed back to the Airflow task log.
- * - ``sdk.Client`` (or a narrower interface)
- - A client for Airflow Variables, Connections, and XCom.
+ * - Method
+ - What it returns
+ * - ``actx.Logger()``
+ - An ``*slog.Logger`` whose output is routed back to the Airflow task log.
+ * - ``actx.Client()``
+ - A client for Airflow Variables, Connections, and XCom. See :ref:`go-sdk/client`.
+ * - ``actx.TaskInstance()``
+ - The identifiers of the running task instance. See :ref:`go-sdk/runtime-context`.
+ * - ``actx.DagRun()``
+ - The identifiers and scheduling timestamps of its Dag run. See :ref:`go-sdk/runtime-context`.
+
+``airflow.Context`` is itself a ``context.Context``, so pass it straight to a client call or to
+``http.NewRequestWithContext``, and select on ``actx.Done()``, which fires when the supervisor asks the task
+to stop. Respect it for long-running work. Cleanup that must outlive that cancellation runs under
+``context.WithoutCancel(actx)``. A helper typed as a plain ``context.Context`` recovers the same surface
+with ``airflow.FromContext``.
Review Comment:
minor nit regarding the formatting.
```suggestion
to stop. Respect it for long-running work. Cleanup that must outlive that cancellation runs under ``context.WithoutCancel(actx)``.
A helper typed as a plain ``context.Context`` recovers the same surface with ``airflow.FromContext``.
```
##########
airflow-core/docs/authoring-and-scheduling/language-sdks/go.rst:
##########
@@ -268,30 +295,74 @@ so you can branch on a missing value with ``errors.Is`` rather than parsing an e
Reading the task runtime context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Declare an ``sdk.TIRunContext`` parameter on a task to read the identifiers and scheduling timestamps of the
-running task instance and its Dag run -- the Go equivalent of the execution context the Python and Java SDKs
-expose. It is an interface that embeds ``context.Context``, so the same ``ctx`` drives cancellation and
-client calls. The runtime binds it by type, just like the other injected parameters:
+``airflow.Context`` carries the identifiers and scheduling timestamps of the running task instance and its
+Dag run -- the Go equivalent of the execution context the Python and Java SDKs expose:
.. code-block:: go
- func extract(ctx sdk.TIRunContext, log *slog.Logger) (any, error) {
- ti := ctx.TaskInstance()
- log.Info("running",
+ func extract(actx airflow.Context) (any, error) {
+ ti := actx.TaskInstance()
+ actx.Logger().InfoContext(actx, "running",
"dag_id", ti.DagID,
"run_id", ti.RunID,
"task_id", ti.TaskID,
"try_number", ti.TryNumber,
- "logical_date", ctx.DagRun().LogicalDate,
+ "logical_date", actx.DagRun().LogicalDate,
)
return nil, nil
}
-``ctx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
-and ``TryNumber``; ``ctx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
+``actx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
+and ``TryNumber``; ``actx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
``LogicalDate``, ``DataIntervalStart``, and ``DataIntervalEnd`` (nil when the run has no such value, e.g. a
manual trigger).
+.. _go-sdk/arguments:
+
+Receiving arguments from the stub Dag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every parameter after the ``airflow.Context`` is a **data parameter**, filled in declaration order from the
+arguments of the Python stub Dag's TaskFlow call. A literal in the Dag file (``transform("uk", ...)``)
+decodes straight into the parameter; an upstream task's output (``transform(..., extract())``) is pulled
+from that task's XCom in the current Dag run. If the argument count does not match, or an argument's
+declared type cannot fill the Go type, the task fails before its body runs.
+
+.. code-block:: go
+
+ // The stub Dag calls transform("uk", extract()).
Review Comment:
```suggestion
// The Python stub Task calls transform("uk", extract()).
```
##########
airflow-core/docs/authoring-and-scheduling/language-sdks/go.rst:
##########
@@ -268,30 +295,74 @@ so you can branch on a missing value with ``errors.Is`` rather than parsing an e
Reading the task runtime context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Declare an ``sdk.TIRunContext`` parameter on a task to read the identifiers and scheduling timestamps of the
-running task instance and its Dag run -- the Go equivalent of the execution context the Python and Java SDKs
-expose. It is an interface that embeds ``context.Context``, so the same ``ctx`` drives cancellation and
-client calls. The runtime binds it by type, just like the other injected parameters:
+``airflow.Context`` carries the identifiers and scheduling timestamps of the running task instance and its
+Dag run -- the Go equivalent of the execution context the Python and Java SDKs expose:
.. code-block:: go
- func extract(ctx sdk.TIRunContext, log *slog.Logger) (any, error) {
- ti := ctx.TaskInstance()
- log.Info("running",
+ func extract(actx airflow.Context) (any, error) {
+ ti := actx.TaskInstance()
+ actx.Logger().InfoContext(actx, "running",
"dag_id", ti.DagID,
"run_id", ti.RunID,
"task_id", ti.TaskID,
"try_number", ti.TryNumber,
- "logical_date", ctx.DagRun().LogicalDate,
+ "logical_date", actx.DagRun().LogicalDate,
)
return nil, nil
}
-``ctx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
-and ``TryNumber``; ``ctx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
+``actx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
+and ``TryNumber``; ``actx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
``LogicalDate``, ``DataIntervalStart``, and ``DataIntervalEnd`` (nil when the run has no such value, e.g. a
manual trigger).
+.. _go-sdk/arguments:
+
+Receiving arguments from the stub Dag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every parameter after the ``airflow.Context`` is a **data parameter**, filled in declaration order from the
+arguments of the Python stub Dag's TaskFlow call. A literal in the Dag file (``transform("uk", ...)``)
+decodes straight into the parameter; an upstream task's output (``transform(..., extract())``) is pulled
+from that task's XCom in the current Dag run. If the argument count does not match, or an argument's
+declared type cannot fill the Go type, the task fails before its body runs.
+
+.. code-block:: go
+
+ // The stub Dag calls transform("uk", extract()).
+ func transform(actx airflow.Context, country string, extracted map[string]any) error {
+ actx.Logger().InfoContext(actx, "transforming", "country", country)
+ return nil
+ }
+
+Stub parameters the Dag author left at their Python defaults are the exception: they reach the wire but need
+no Go parameter, so adding a defaulted parameter to a stub does not break the Go functions already bound to
+it.
+
+When a task's **sole** data parameter is a struct, its fields bind **by name** instead of by position --
+keyword arguments rather than positional ones. Being the only data parameter is the opt-in; there is no
+marker to add.
+
+.. code-block:: go
+
+ type CombineInput struct {
+ Region string `arg:"region_code"` // renamed
+ Threshold float64
+ }
+
+ // The stub Dag calls combine(region_code="uk", threshold=0.5).
+ func Combine(actx airflow.Context, input CombineInput) (any, error) {
+ return nil, nil
+ }
+
+An exported field binds the argument matching its own Go name, folding case and underscores, so
+``Threshold`` takes ``threshold``; reach for an ``arg:"<name>"`` tag when the names genuinely differ, as
+``Region`` does above. The `Go SDK README
+<https://github.com/apache/airflow/blob/main/go-sdk/README.md>`__ has the full binding rules, including
+how unmatched fields and arguments are treated and when an untagged struct is decoded whole from a single
+argument instead.
+
Review Comment:
```suggestion
Stub parameters the Dag author left at their Python defaults are the exception: they reach the wire but need
no Go parameter, so adding a defaulted parameter to a stub does not break the Go functions already bound to
it.
```
##########
go-sdk/README.md:
##########
@@ -169,37 +167,55 @@ data parameters is rejected at registration. A sole struct parameter also falls
decoding when it gets exactly one passed argument no field claims, so a task can still take an
upstream object as a single argument.
-### Reading the task runtime context
+### The task context
+
+`airflow.Context` is the first parameter of every task handler -- the Go equivalent of the execution
+context the Python and Java SDKs expose. Everything Airflow gives the task is a method on it:
Review Comment:
Would it be better to not mention the other SDKs in the Go-SDK README.
```suggestion
`airflow.Context` is the first parameter of every task handler. Everything Airflow gives the task is a method on it:
```
##########
airflow-core/docs/authoring-and-scheduling/language-sdks/go.rst:
##########
@@ -268,30 +295,74 @@ so you can branch on a missing value with ``errors.Is`` rather than parsing an e
Reading the task runtime context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Declare an ``sdk.TIRunContext`` parameter on a task to read the identifiers and scheduling timestamps of the
-running task instance and its Dag run -- the Go equivalent of the execution context the Python and Java SDKs
-expose. It is an interface that embeds ``context.Context``, so the same ``ctx`` drives cancellation and
-client calls. The runtime binds it by type, just like the other injected parameters:
+``airflow.Context`` carries the identifiers and scheduling timestamps of the running task instance and its
+Dag run -- the Go equivalent of the execution context the Python and Java SDKs expose:
.. code-block:: go
- func extract(ctx sdk.TIRunContext, log *slog.Logger) (any, error) {
- ti := ctx.TaskInstance()
- log.Info("running",
+ func extract(actx airflow.Context) (any, error) {
+ ti := actx.TaskInstance()
+ actx.Logger().InfoContext(actx, "running",
"dag_id", ti.DagID,
"run_id", ti.RunID,
"task_id", ti.TaskID,
"try_number", ti.TryNumber,
- "logical_date", ctx.DagRun().LogicalDate,
+ "logical_date", actx.DagRun().LogicalDate,
)
return nil, nil
}
-``ctx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
-and ``TryNumber``; ``ctx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
+``actx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
+and ``TryNumber``; ``actx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
``LogicalDate``, ``DataIntervalStart``, and ``DataIntervalEnd`` (nil when the run has no such value, e.g. a
manual trigger).
+.. _go-sdk/arguments:
+
+Receiving arguments from the stub Dag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every parameter after the ``airflow.Context`` is a **data parameter**, filled in declaration order from the
+arguments of the Python stub Dag's TaskFlow call. A literal in the Dag file (``transform("uk", ...)``)
+decodes straight into the parameter; an upstream task's output (``transform(..., extract())``) is pulled
+from that task's XCom in the current Dag run. If the argument count does not match, or an argument's
+declared type cannot fill the Go type, the task fails before its body runs.
+
+.. code-block:: go
+
+ // The stub Dag calls transform("uk", extract()).
+ func transform(actx airflow.Context, country string, extracted map[string]any) error {
+ actx.Logger().InfoContext(actx, "transforming", "country", country)
+ return nil
+ }
+
+Stub parameters the Dag author left at their Python defaults are the exception: they reach the wire but need
+no Go parameter, so adding a defaulted parameter to a stub does not break the Go functions already bound to
+it.
Review Comment:
I'd like to move this part after mentioning the struct-base binding.
```suggestion
```
##########
airflow-core/docs/authoring-and-scheduling/language-sdks/go.rst:
##########
@@ -200,37 +204,59 @@ There is no separate Go worker to run: the Airflow worker forks the bundle binar
Writing tasks
-------------
-The runtime inspects a task function's signature and injects arguments by type, so you only declare the
-parameters your task actually needs:
+Every task function takes an ``airflow.Context`` as its first parameter, and reaches what Airflow provides
+through its methods:
.. list-table::
:header-rows: 1
:widths: 35 65
- * - Parameter type
- - Injected value
- * - ``sdk.TIRunContext``
- - The task's execution context: the cancellation/deadline signal plus the task instance identifiers and
- Dag run timestamps. Respect it for long-running work. See :ref:`go-sdk/runtime-context`.
- * - ``*slog.Logger``
- - A logger whose output is routed back to the Airflow task log.
- * - ``sdk.Client`` (or a narrower interface)
- - A client for Airflow Variables, Connections, and XCom.
+ * - Method
+ - What it returns
+ * - ``actx.Logger()``
+ - An ``*slog.Logger`` whose output is routed back to the Airflow task log.
+ * - ``actx.Client()``
+ - A client for Airflow Variables, Connections, and XCom. See :ref:`go-sdk/client`.
+ * - ``actx.TaskInstance()``
+ - The identifiers of the running task instance. See :ref:`go-sdk/runtime-context`.
+ * - ``actx.DagRun()``
+ - The identifiers and scheduling timestamps of its Dag run. See :ref:`go-sdk/runtime-context`.
+
+``airflow.Context`` is itself a ``context.Context``, so pass it straight to a client call or to
+``http.NewRequestWithContext``, and select on ``actx.Done()``, which fires when the supervisor asks the task
+to stop. Respect it for long-running work. Cleanup that must outlive that cancellation runs under
+``context.WithoutCancel(actx)``. A helper typed as a plain ``context.Context`` recovers the same surface
+with ``airflow.FromContext``.
+
+Every parameter after the Context is data, filled from the stub Dag's TaskFlow call; see
Review Comment:
```suggestion
Every parameter after the Context is data, filled from the stub Task's TaskFlow call; see
```
##########
airflow-core/docs/authoring-and-scheduling/language-sdks/go.rst:
##########
@@ -268,30 +295,74 @@ so you can branch on a missing value with ``errors.Is`` rather than parsing an e
Reading the task runtime context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Declare an ``sdk.TIRunContext`` parameter on a task to read the identifiers and scheduling timestamps of the
-running task instance and its Dag run -- the Go equivalent of the execution context the Python and Java SDKs
-expose. It is an interface that embeds ``context.Context``, so the same ``ctx`` drives cancellation and
-client calls. The runtime binds it by type, just like the other injected parameters:
+``airflow.Context`` carries the identifiers and scheduling timestamps of the running task instance and its
+Dag run -- the Go equivalent of the execution context the Python and Java SDKs expose:
.. code-block:: go
- func extract(ctx sdk.TIRunContext, log *slog.Logger) (any, error) {
- ti := ctx.TaskInstance()
- log.Info("running",
+ func extract(actx airflow.Context) (any, error) {
+ ti := actx.TaskInstance()
+ actx.Logger().InfoContext(actx, "running",
"dag_id", ti.DagID,
"run_id", ti.RunID,
"task_id", ti.TaskID,
"try_number", ti.TryNumber,
- "logical_date", ctx.DagRun().LogicalDate,
+ "logical_date", actx.DagRun().LogicalDate,
)
return nil, nil
}
-``ctx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
-and ``TryNumber``; ``ctx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
+``actx.TaskInstance()`` returns ``DagID``, ``RunID``, ``TaskID``, ``MapIndex`` (nil for an unmapped task),
+and ``TryNumber``; ``actx.DagRun()`` returns ``DagID``, ``RunID``, and the ``*time.Time`` fields
``LogicalDate``, ``DataIntervalStart``, and ``DataIntervalEnd`` (nil when the run has no such value, e.g. a
manual trigger).
+.. _go-sdk/arguments:
+
+Receiving arguments from the stub Dag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every parameter after the ``airflow.Context`` is a **data parameter**, filled in declaration order from the
+arguments of the Python stub Dag's TaskFlow call. A literal in the Dag file (``transform("uk", ...)``)
+decodes straight into the parameter; an upstream task's output (``transform(..., extract())``) is pulled
+from that task's XCom in the current Dag run. If the argument count does not match, or an argument's
+declared type cannot fill the Go type, the task fails before its body runs.
+
Review Comment:
How about adding something like (please feel free to rephrase my statement)
```suggestion
There're two ways for receiving the arguments from Python Stub Task side:
1. positional binding
2. struct-based (keyword-based) binding
```
--
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