Python: [vNext] Standardize exception, cancellation, and resource ownership contracts #9627

Maintainer-owned issue. Community contributors: please do not pick up or start implementing this issue. This issue covers observable contract changes in released Python APIs.

Problem

Released execution paths contain broad exception catches, inconsistent domain translation, and lifecycle boundaries where ownership of injected clients or resources is not always explicit. Narrowing catches, propagating cancellation, or changing close behavior can alter observable public behavior.

Use Case and Evidence

Core has more than 100 broad-catch sites requiring triage, with concentrations in agents, hooks, security, observability, workflows, MCP, and serialization. The standard requires preserved cancellation, raise ... from exc, domain-owned exceptions, and closing only resources created by the framework.

Desired Outcome

Define a consistent vNext contract for released packages covering exception families, cancellation propagation, fallback boundaries, context-manager behavior, and caller-versus-framework resource ownership.

Alternatives Considered

Treating this as mechanical cleanup risks silently breaking callers that catch existing exception types or rely on current close behavior. Leaving behavior undocumented perpetuates leaks and inconsistent recovery.

Proposed Direction

Inventory public execution boundaries, characterize current observable behavior, add tests, and stage incompatible exception or ownership changes for vNext with migration guidance.

Scope and Non-Goals

Internal logging-only catches may be fixed independently. Preview package behavior is tracked separately.

Language

Python

Contribution Intent

Maintainer-owned; implementation must wait for maintainer design agreement.

Acknowledgements

• I searched existing issues and did not find a duplicate.
• I will wait for explicit maintainer agreement before starting implementation of a non-trivial change.

Ownership: Core maintainers only; not available for community pickup.