Vamsi-klu opened a new pull request, #60435:
URL: https://github.com/apache/airflow/pull/60435
## Summary
This PR addresses several medium-priority TODO items found in the codebase,
improving documentation, validation, and code organization.
### Changes Made
- **Added OpenAPI documentation to rtif endpoint** - Improves API
documentation completeness with operation_id, summary, and description
- **Added map_index validation in task CLI** - Validates map_index is within
range when running mapped tasks with clear error messages
- **Improved callback log file template** - Changed from flat structure to
hierarchical organization for easier log lookup
- **Fixed outdated TODO comments** - ui_color/ui_fgcolor ARE used by
dot_renderer.py and exposed in API
## Issues Addressed
| File | Issue | Impact |
|------|-------|--------|
| `task_instances.py` | Missing OpenAPI documentation for rtif endpoint |
API consumers couldn't understand the endpoint's purpose |
| `task_command.py` | No validation for map_index parameter | Users could
run tasks with invalid map_index without clear errors |
| `workloads.py` | Poor log file organization | Callback logs were stored in
flat structure making lookup difficult |
| `baseoperator.py` | Outdated TODO suggesting ui_color was unused |
Misleading comment could cause developers to remove needed code |
| `taskgroup.py` | Outdated TODO suggesting ui_color was unused | Same as
above |
## Detailed Changes
### 1. OpenAPI Documentation (task_instances.py)
**Before:**
```python
@ti_id_router.put(
"/{task_instance_id}/rtif",
status_code=status.HTTP_201_CREATED,
# TODO: Add description to the operation
# TODO: Add Operation ID to control the function name in the OpenAPI spec
# TODO: Do we need to use create_openapi_http_exception_doc here?
```
**After:**
```python
@ti_id_router.put(
"/{task_instance_id}/rtif",
status_code=status.HTTP_201_CREATED,
operation_id="put_rtif",
summary="Set Rendered Task Instance Fields",
description="Store the rendered task instance fields (RTIF) for a task
instance. "
"These are the template fields after Jinja rendering has been applied. "
"Called by the worker after task execution begins.",
```
### 2. Map Index Validation (task_command.py)
Added validation that checks if `map_index` is within the valid range when
the mapped task count is known at parse time:
- Provides clear error message: `map_index X is out of range for task 'Y'
which has Z mapped task instance(s)`
- Gracefully handles cases where count depends on XCom values using
`NotMapped` and `NotFullyPopulated` exceptions
### 3. Callback Log File Template (workloads.py)
**Before:** `executor_callbacks/{callback.id}`
**After:** `callbacks/{dag_id}/{run_id}/{callback_id}`
Hierarchical structure makes logs easier to find and organize by DAG and run.
### 4. Fixed Outdated TODOs (baseoperator.py, taskgroup.py)
Research showed that `ui_color` and `ui_fgcolor` ARE actually used:
- `dot_renderer.py` uses them for DAG graph visualization
- They are exposed in the API for UI customization
Changed misleading "Remove the following, they aren't used anymore" comments
to accurate documentation.
## Test plan
- [x] Python syntax validation passed for all 5 files
- [ ] Verify OpenAPI spec is correctly generated
- [ ] Test `airflow tasks run` with invalid map_index shows error
- [ ] Verify callback log files are created in new path structure
- [ ] Verify DAG graph visualization still works with ui_color/ui_fgcolor
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
