feat(postgrest): add structured execution results

[ragbendra]

Summary

Adds an opt-in, non-throwing execution API that returns structured results similar to the Supabase JavaScript client.

Relates to #1548

What changed

Added execute_result() to PostgREST request builders.

Successful responses return:

ExecuteResult(
    type="success",
    data=...,
    error=None,
    status=200,
    count=...,
)

Failed responses return:

ExecuteResult(
    type="error",
    data=None,
    error={...},
    status=400,
)

• successful requests still return APIResponse
• failed requests still raise APIError

The new API supports normal queries, single(), maybe_single(), and synchronous and asynchronous clients.

Additional changes

• Added the ExecuteResult response model.
• Exported it from the postgrest package.
• Re-exported it through supabase.
• Added response documentation.
• Added sync and async tests covering successful responses, errors, HTTP status codes, empty responses, single(), and maybe_single().

Validation

• Ruff: passed
• Mypy: passed
• Public export validation: passed
• Focused sync/async tests: 14 passed

The complete integration suite was not completed locally. The focused tests and static checks pass, and the remaining validation can be completed by CI.

[Copilot]

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

[Copilot]

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