docs: clarify after_return behavior for retried tasks#10192
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Clarifies Celery’s user documentation around when Task.after_return runs, specifically to avoid implying it executes on every retry attempt, and points readers to task_postrun for per-attempt hooks.
Changes:
- Update the task lifecycle diagram caption to indicate
after_return()runs only for terminal outcomes. - Clarify in the “Key points” section that
after_returndoes not run forRETRY,REJECTED, orIGNORED. - Expand the
after_returnhandler reference docs to reiterate the above and suggesttask_postrunfor every-attempt hooks.
You can also share your feedback on Copilot code review. Take the survey.
Co-authored-by: Copilot <[email protected]>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.
You can also share your feedback on Copilot code review. Take the survey.
auvipy
approved these changes
Mar 12, 2026
Nusnus
pushed a commit
that referenced
this pull request
Mar 26, 2026
* docs: clarify after_return behavior for retried tasks
* Update docs/userguide/tasks.rst
* docs: clarify after_return ordering for terminal states
---------
Co-authored-by: Asif Saif Uddin {"Auvi":"অভি"} <[email protected]>
Nusnus
pushed a commit
that referenced
this pull request
Mar 26, 2026
* docs: clarify after_return behavior for retried tasks
* Update docs/userguide/tasks.rst
* docs: clarify after_return ordering for terminal states
---------
Co-authored-by: Asif Saif Uddin {"Auvi":"অভি"} <[email protected]>
Nusnus
pushed a commit
that referenced
this pull request
Mar 26, 2026
* docs: clarify after_return behavior for retried tasks
* Update docs/userguide/tasks.rst
* docs: clarify after_return ordering for terminal states
---------
Co-authored-by: Asif Saif Uddin {"Auvi":"অভি"} <[email protected]>
736-c41-2c1-e464fc974
pushed a commit
to Swiss-Armed-Forces/Loom
that referenced
this pull request
Mar 29, 2026
This MR contains the following updates: | Package | Type | Update | Change | OpenSSF | |---|---|---|---|---| | [celery](https://docs.celeryq.dev/) ([source](https://github.com/celery/celery), [changelog](https://docs.celeryq.dev/en/stable/changelog.html)) | dependencies | patch | `5.6.2` → `5.6.3` | [](https://securityscorecards.dev/viewer/?uri=github.com/celery/celery) | --- ### Release Notes <details> <summary>celery/celery (celery)</summary> ### [`v5.6.3`](https://github.com/celery/celery/releases/tag/v5.6.3) [Compare Source](celery/celery@v5.6.2...v5.6.3) #### What's Changed - Fix Django worker recursion bug + defensive checks for pool\_cls.**module** by [@​maycuatroi1](https://github.com/maycuatroi1) in [#​10048](celery/celery#10048) - Docs: Update user\_preload\_options example to use click. by [@​jorsyk](https://github.com/jorsyk) in [#​10056](celery/celery#10056) - Fix invalid configuration key "bootstrap\_servers" in Kafka demo by [@​jorsyk](https://github.com/jorsyk) in [#​10060](celery/celery#10060) - Fix broken images on PyPI page by [@​Timour-Ilyas](https://github.com/Timour-Ilyas) in [#​10066](celery/celery#10066) - Remove broken reference. by [@​sueannioanis](https://github.com/sueannioanis) in [#​10071](celery/celery#10071) - Removed --dist=loadscope from smoke tests by [@​Nusnus](https://github.com/Nusnus) in [#​10073](celery/celery#10073) - Docs: Clarify task\_retry signal args may be None by [@​GangEunzzang](https://github.com/GangEunzzang) in [#​10076](celery/celery#10076) - Update example for Django by [@​sbc-khacnha](https://github.com/sbc-khacnha) in [#​10081](celery/celery#10081) - Make tests compatible with pymongo >= 4.16 by [@​cjwatson](https://github.com/cjwatson) in [#​10074](celery/celery#10074) - fix: source install of cassandra-driver by [@​Izzette](https://github.com/Izzette) in [#​10105](celery/celery#10105) - fix: register task cross-reference role in Sphinx extension by [@​veeceey](https://github.com/veeceey) in [#​10100](celery/celery#10100) - fix: avoid cycle detection in native delayed delivery by [@​Izzette](https://github.com/Izzette) in [#​10095](celery/celery#10095) - fix(asynpool): avoid AttributeError when proc lacks \_sentinel\_poll by [@​mriddle](https://github.com/mriddle) in [#​10086](celery/celery#10086) - fix dusk\_astronomical horizon sign (+18 -> -18) by [@​Mr-Neutr0n](https://github.com/Mr-Neutr0n) in [#​10121](celery/celery#10121) - Fix/10106 onupdate col use lambda func by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10108](celery/celery#10108) - Fix warm shutdown RuntimeError with eventlet>=0.37.0 ([#​10083](celery/celery#10083)) by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10123](celery/celery#10123) - Fix 10109 db backend connection health by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10124](celery/celery#10124) - Database Backend filter unsupport sql engine arguments with nullpool [#​7355](celery/celery#7355) by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10134](celery/celery#10134) - fix(beat): correct argument order in Service.**reduce** by [@​bysiber](https://github.com/bysiber) in [#​10137](celery/celery#10137) - ci: declare explicit read-only token permissions in workflow jobs by [@​Rohan5commit](https://github.com/Rohan5commit) in [#​10139](celery/celery#10139) - chore: 'boto3to' to 'boto3 to' by [@​cuiweixie](https://github.com/cuiweixie) in [#​10133](celery/celery#10133) - Database Backend: Add missing index on date\_done (Fixes [#​10097](celery/celery#10097)) by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10098](celery/celery#10098) - docs: fix typo in CONTRIBUTING.rst by [@​Rohan5commit](https://github.com/Rohan5commit) in [#​10141](celery/celery#10141) - Refer to Flower / Prometheus for monitoring by [@​WilliamDEdwards](https://github.com/WilliamDEdwards) in [#​10140](celery/celery#10140) - docs: remove duplicated words in broker and routing docs by [@​Rohan5commit](https://github.com/Rohan5commit) in [#​10146](celery/celery#10146) - docs: fix stale version reference and grammar in README by [@​kelsonbrito50](https://github.com/kelsonbrito50) in [#​10145](celery/celery#10145) - docs: fix wording in Celery 5.3 worker pool notes by [@​Rohan5commit](https://github.com/Rohan5commit) in [#​10149](celery/celery#10149) - docs: fix duplicated wording in 3.1 changelog entry by [@​Rohan5commit](https://github.com/Rohan5commit) in [#​10152](celery/celery#10152) - docs: fix changelog typo in context manager wording by [@​Rohan5commit](https://github.com/Rohan5commit) in [#​10144](celery/celery#10144) - Fix/10096 worker fails to reconnect after redis failover by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10151](celery/celery#10151) - Improve on\_after\_finalize signal documentation by [@​Br1an67](https://github.com/Br1an67) in [#​10155](celery/celery#10155) - Add non-commutative example to clarify partial arg ordering in canvas docs by [@​Br1an67](https://github.com/Br1an67) in [#​10157](celery/celery#10157) - Remove redundant test\_isa\_mapping test (fixes [#​10077](celery/celery#10077)) by [@​daniel7an](https://github.com/daniel7an) in [#​10103](celery/celery#10103) - Upgrade pytest-celery to >=1.3.0 and adopt PYTEST\_CELERY\_PKG build arg by [@​Nusnus](https://github.com/Nusnus) in [#​10162](celery/celery#10162) - Remove deprecated args from redis get\_connection call by [@​JaeHyuckSa](https://github.com/JaeHyuckSa) in [#​10036](celery/celery#10036) - Fix [#​6912](celery/celery#6912) rpc backend reconnection error by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10179](celery/celery#10179) - Fix NameError with TYPE\_CHECKING annotations on Python 3.14+ (PEP 649) by [@​drichardson](https://github.com/drichardson) in [#​10165](celery/celery#10165) - docs: Add elaboration on prefetch multiplier settings (worker\_prefetch\_multiplier) and worker\_eta\_task\_limit by [@​tsangwailam](https://github.com/tsangwailam) in [#​10181](celery/celery#10181) - Fix O(K²) message bloat in a chain of chords by [@​Borzik](https://github.com/Borzik) in [#​10171](celery/celery#10171) - Fix mock connection interfaces to prevent `TypeError` during exception handling by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10178](celery/celery#10178) - fix(trace): dispatch chain/callbacks on dedup fast-path for redelivered tasks by [@​aurangzaib048](https://github.com/aurangzaib048) in [#​10159](celery/celery#10159) - Extract `reconnect_on_error` to `BaseResultConsumer` by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10189](celery/celery#10189) - pep 649 by [@​ericbuehl](https://github.com/ericbuehl) in [#​10187](celery/celery#10187) - [Fix#9722](https://github.com/Fix/celery/issues/9722) friendly status errors for CLI by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10190](celery/celery#10190) - docs: clarify after\_return behavior for retried tasks by [@​KianAnbarestani](https://github.com/KianAnbarestani) in [#​10192](celery/celery#10192) - Add compression header to message protocol docs by [@​Br1an67](https://github.com/Br1an67) in [#​10156](celery/celery#10156) - docs: fix duplicated word in bootsteps comment by [@​Rohan5commit](https://github.com/Rohan5commit) in [#​10153](celery/celery#10153) - Remove outdated autoreloader section from extending docs by [@​Br1an67](https://github.com/Br1an67) in [#​10154](celery/celery#10154) - Fix: prioritize request ignore\_result over task definition by [@​patri27826](https://github.com/patri27826) in [#​10184](celery/celery#10184) - fix: clear the timer while catch the exception by [@​ChickenBenny](https://github.com/ChickenBenny) in [#​10218](celery/celery#10218) - Prepare for release: v5.6.3 by [@​Nusnus](https://github.com/Nusnus) in [#​10221](celery/celery#10221) #### New Contributors - [@​maycuatroi1](https://github.com/maycuatroi1) made their first contribution in [#​10048](celery/celery#10048) - [@​jorsyk](https://github.com/jorsyk) made their first contribution in [#​10056](celery/celery#10056) - [@​Timour-Ilyas](https://github.com/Timour-Ilyas) made their first contribution in [#​10066](celery/celery#10066) - [@​sueannioanis](https://github.com/sueannioanis) made their first contribution in [#​10071](celery/celery#10071) - [@​GangEunzzang](https://github.com/GangEunzzang) made their first contribution in [#​10076](celery/celery#10076) - [@​sbc-khacnha](https://github.com/sbc-khacnha) made their first contribution in [#​10081](celery/celery#10081) - [@​veeceey](https://github.com/veeceey) made their first contribution in [#​10100](celery/celery#10100) - [@​mriddle](https://github.com/mriddle) made their first contribution in [#​10086](celery/celery#10086) - [@​Mr-Neutr0n](https://github.com/Mr-Neutr0n) made their first contribution in [#​10121](celery/celery#10121) - [@​ChickenBenny](https://github.com/ChickenBenny) made their first contribution in [#​10108](celery/celery#10108) - [@​bysiber](https://github.com/bysiber) made their first contribution in [#​10137](celery/celery#10137) - [@​Rohan5commit](https://github.com/Rohan5commit) made their first contribution in [#​10139](celery/celery#10139) - [@​cuiweixie](https://github.com/cuiweixie) made their first contribution in [#​10133](celery/celery#10133) - [@​kelsonbrito50](https://github.com/kelsonbrito50) made their first contribution in [#​10145](celery/celery#10145) - [@​Br1an67](https://github.com/Br1an67) made their first contribution in [#​10155](celery/celery#10155) - [@​daniel7an](https://github.com/daniel7an) made their first contribution in [#​10103](celery/celery#10103) - [@​drichardson](https://github.com/drichardson) made their first contribution in [#​10165](celery/celery#10165) - [@​tsangwailam](https://github.com/tsangwailam) made their first contribution in [#​10181](celery/celery#10181) - [@​Borzik](https://github.com/Borzik) made their first contribution in [#​10171](celery/celery#10171) - [@​aurangzaib048](https://github.com/aurangzaib048) made their first contribution in [#​10159](celery/celery#10159) - [@​ericbuehl](https://github.com/ericbuehl) made their first contribution in [#​10187](celery/celery#10187) - [@​KianAnbarestani](https://github.com/KianAnbarestani) made their first contribution in [#​10192](celery/celery#10192) - [@​patri27826](https://github.com/patri27826) made their first contribution in [#​10184](celery/celery#10184) **Full Changelog**: <celery/celery@v5.6.2...v5.6.3> </details> --- - [ ] <!-- rebase-check -->If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My45OS4wIiwidXBkYXRlZEluVmVyIjoiNDMuOTkuMCIsInRhcmdldEJyYW5jaCI6Im1haW4iLCJsYWJlbHMiOlsiZGVwZW5kZW5jaWVzIiwicmVub3ZhdGUiXX0=--> See merge request swiss-armed-forces/cyber-command/cea/loom!419
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR clarifies the documented behavior of
after_return.The previous wording could be interpreted as if
after_returnruns for every task attempt. In practice, it runs when the task reaches a terminal state and does not run forRETRY,REJECTED, orIGNORED.The docs now also reference
task_postrunfor cases where a hook is needed on every attempt.Reason
This aligns the documentation with the current behavior and avoids implying a potentially backward-incompatible behavior change.
Related discussion: #10046