feat: success callback + success_log for post-retry recovery

[MohammedAnasNathani]

Summary

Fixes the long-standing gap behind #531 / SO: people wire after= expecting a “retry_success” log, but after only runs on failed attempts that may still be retried.

@retry(
    stop=stop_after_attempt(5),
    success=success_log(logger, logging.INFO),  # only if attempt_number > 1
)
def might_fail():
    ...

API

Hook	When it runs
before	before each attempt
after	after a failed attempt that may retry / stop
before_sleep	after failure, before wait
success (new)	when the call ultimately succeeds

• success_log(logger, level, only_if_retried=True) — built-in helper for the common “log recovery only” case
• Wired through BaseRetrying, AsyncRetrying, and @retry (kwargs pass-through)
• No change to existing after semantics

Tests

• Recovery fires success with final attempt_number
• First-try success still fires (for custom callbacks)
• Exhausted retries → success never called
• Regression: after still only on failed attempts
• success_log respects only_if_retried

Local: 174 passed (tornado not installed in this env; CI has it)

Docs

index.rst documents the after vs success distinction with a short example.

Closes #531

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[jd]

Noise, avoid this please.