Rename max_attempts to max_retries, clarify semantics, and deprecate alias

[danielniccoli]

sdk-python/python/restate/context.py

Line 42 in 2aa17da

max_attempts: Optional[int] = None

The current parameter name and docstring for max_attempts are ambiguous: it is unclear whether it counts total attempts (including the initial call) or only retries, and the text mixes “retry attempts” with “maximum number of attempts.” This leads to confusing boundary cases; for example, max_attempts=0 implies the action is never attempted, which conflicts with common expectations.

I propose introducing max_retries: Optional[int] = None with conventional semantics and deprecating max_attempts as an alias. max_retries should count retries after the initial attempt: None means unlimited retries, 0 means no retries (one initial attempt only), and n > 0 allows up to n retries for at most n+1 total attempts. On exhaustion, continue to raise TerminalError. Validate that negative values raise ValueError.

For backward compatibility, accept max_attempts as an alias for one or two releases, map its value directly to max_retries, and emit a deprecation warning. If both parameters are provided, raise a ValueError instructing users to use only max_retries. Update the docstrings and examples to reflect the clarified behavior.

This change aligns with common library conventions, avoids off-by-one confusion, and makes 0 and None behave as users expect.