Add optional exception for failed tasks in wait_for_task

[chenyujia1024]

Related issue

Fix #747

What does this PR do?

Adds an opt-in raise_on_failure option to wait_for_task.

• Existing behavior remains unchanged by default.
• When raise_on_failure=True, a task with status failed raises MeilisearchTaskFailedError.
• Successful, canceled, and other terminal tasks continue to return Task.
• Existing polling timeout behavior remains unchanged.

raise_on_failure is keyword-only and defaults to False, so existing calls such as:

client.wait_for_task(uid)
client.wait_for_task(uid, 5000, 50)

Summary by CodeRabbit

• New Features
  • Waiting for a task can optionally raise an exception when the task fails. The exception includes the failed task and its error details. This behavior is opt-in; existing behavior remains unchanged by default.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: cc1cb2df-e0ee-409d-abdb-5c18f739a3d6

📥 Commits

Reviewing files that changed from the base of the PR and between cd3c911 and bbb5105.

📒 Files selected for processing: 4

• meilisearch/client.py
• meilisearch/errors.py
• meilisearch/index.py
• tests/test_task_failure.py

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 1 remain after this review.

📝 Walkthrough

Task waiting now accepts an opt-in raise_on_failure option. When enabled, a failed task raises MeilisearchTaskFailedError with the task details. Client and index methods forward the option. The default behavior remains unchanged.

Changes: Task failure handling

Layer / File(s)	Summary
Failure exception and task polling meilisearch/errors.py, meilisearch/task.py, tests/test_task_failure.py	Adds MeilisearchTaskFailedError and raises it when raise_on_failure is enabled and a task fails. Tests cover exception details, fallback messages, polling, success, timeout, and the default behavior.
Client and index forwarding meilisearch/client.py, meilisearch/index.py, tests/test_task_failure.py	Adds the keyword-only raise_on_failure option to both public methods. Each method forwards the option when enabled and preserves the existing call when omitted.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~15 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to bbb51

No actionable merge-blocking issue is identified; the change is mergeable after normal checks.

Security architecture risk: ⚪ Minimal · up to bbb51

The new behavior is explicitly opt-in. Existing calls retain their behavior, and the change does not broaden task access or add privileged operations. No material security risk was identified in the reviewed change.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The added behavior is confined to reporting a task already fetched through the configured handler. It introduces no additional task enumeration, tenant selection, service destination, or credential authority.

Trust Boundaries and Controls

• observed — The caller-controlled option affects only local handling after the existing task retrieval. Server-returned status selects the outcome, and server-returned error text becomes exception text; neither is used by the new branch to select a destination, issue another operation, or execute code.

Resilience and Maintainability Implications

• inferred — Return, failure exception, and timeout are local outcomes of an observer loop. The added branch acquires no ownership or reservation and changes no shared task state, so interruption or repetition introduces no new cleanup or recovery obligation within this implementation.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 20.83% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: adding an optional exception for failed tasks in wait_for_task.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[Strift]

Hello @chenyujia1024 and thanks for this PR 🙌

[djmattyg007]

Wow, thank you 🙂