feat: deprecate initial in favor of multiplier in wait_exponential_jitter#629
Conversation
|
This pull request is part of a stack:
|
jd
force-pushed
the
devs/jd/feat/wait-exponential-jitter-multiplier/I63d23f41e58627085118b633a009c86ff2807f79
branch
from
a4d1d2e to
129d1a5
Compare
…al_jitter` Every other exponential wait class uses `multiplier`. Having `initial` only on `wait_exponential_jitter` is confusing. Add `multiplier` param and deprecate `initial` as its alias. - Add `multiplier` parameter (default 1) - Emit `DeprecationWarning` when `initial` is used - Raise `ValueError` if both `initial` and `multiplier` are specified Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Change-Id: I63d23f41e58627085118b633a009c86ff2807f79
jd
force-pushed
the
devs/jd/feat/wait-exponential-jitter-multiplier/I63d23f41e58627085118b633a009c86ff2807f79
branch
from
129d1a5 to
333c1b5
Compare
mergify
bot
deleted the
devs/jd/feat/wait-exponential-jitter-multiplier/I63d23f41e58627085118b633a009c86ff2807f79
branch
Merge Queue Status
This pull request spent 11 seconds in the queue, including 1 second running CI. Required conditions to merge |
There was a problem hiding this comment.
Pull request overview
This PR aligns wait_exponential_jitter with other exponential wait strategies by introducing a multiplier parameter and deprecating the older initial parameter (as an alias), including tests and a release note entry.
Changes:
- Added
multiplierparameter towait_exponential_jitterand migrated internal computation to use it. - Added
DeprecationWarningwheninitialis used, plus aValueErrorfor conflicting configuration. - Updated unit tests and added release notes covering the deprecation and new parameter.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
tenacity/wait.py |
Adds multiplier, emits deprecation warning for initial, updates jitter backoff formula implementation. |
tests/test_tenacity.py |
Updates existing test to assert deprecation warning and adds new tests for multiplier and conflict behavior. |
releasenotes/notes/deprecate-initial-for-multiplier-c7b4e2d9f1a83065.yaml |
Documents the deprecation of initial and the new multiplier parameter. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| if initial != 1: | ||
| warnings.warn( | ||
| "The 'initial' parameter is deprecated, use 'multiplier' instead", | ||
| DeprecationWarning, | ||
| stacklevel=2, | ||
| ) |
There was a problem hiding this comment.
Deprecation warnings are currently only emitted when initial != 1. If a caller explicitly uses the deprecated parameter with the default value (e.g. initial=1), no DeprecationWarning is raised even though the deprecated API is being used. If the intent is to warn whenever initial is supplied, switch initial to a sentinel/None default and check initial is not None (then map it to multiplier).
| if initial != 1 and multiplier != 1: | ||
| raise ValueError( | ||
| "Cannot specify both 'initial' and 'multiplier' — use 'multiplier' only" | ||
| ) | ||
|
|
There was a problem hiding this comment.
The ValueError guard only triggers when both arguments are non-default (initial != 1 and multiplier != 1). This means callers can still pass both parameters without an error when initial is explicitly provided as the default (e.g. wait_exponential_jitter(initial=1, multiplier=10)), which contradicts the PR's stated behavior. Consider using a sentinel/None default for initial (or another way to detect whether it was provided) so you can reliably raise whenever initial is specified alongside multiplier.
Every other exponential wait class uses
multiplier. Havinginitialonly on
wait_exponential_jitteris confusing. Addmultiplierparamand deprecate
initialas its alias.multiplierparameter (default 1)DeprecationWarningwheninitialis usedValueErrorif bothinitialandmultiplierare specifiedCo-Authored-By: Claude Opus 4.6 noreply@anthropic.com