SDK-2765: Python - Support handled_check_limit property for checks in IDV sandbox - python

[mehmet-yoti]

Summary

Adds an optional handled_check_limit integer property to the base SandboxCheck class and SandboxCheckBuilder in the Python IDV sandbox SDK. The property controls how many times a configured sandbox check response is used before the sandbox advances to the next response. The field is serialized as handled_check_limit in JSON only when explicitly set, and all 6 concrete check types inherit the behaviour automatically.

Changes

• yoti_python_sandbox/doc_scan/check/sandbox_check.py — Added handled_check_limit parameter to SandboxCheck.__init__, a read-only handled_check_limit property, and conditional JSON serialization in to_json(). Added with_handled_check_limit() fluent builder method to SandboxCheckBuilder.
• sandbox_document_authenticity_check.py, sandbox_document_face_match_check.py, sandbox_document_text_data_check.py, sandbox_id_document_comparison_check.py, sandbox_liveness_check.py, sandbox_supplementary_document_text_data_check.py, sandbox_zoom_liveness_check.py — Updated each concrete check and builder to forward handled_check_limit through to the base class.
• yoti_python_sandbox/tests/doc_scan/check/test_handled_check_limit.py — 31 new tests covering: property present/absent in JSON, property getter on check object, end-to-end scenarios for each check type, and backward-compatibility when the limit is not set.

QA Test Steps

1. Setup — Clone the repo, check out this branch, and install dependencies: pip install -e ".[dev]".
2. Run tests — Execute pytest from the repo root; all 137 tests should pass.
3. Happy path — Instantiate any check builder (e.g., SandboxDocumentAuthenticityCheckBuilder), call .with_handled_check_limit(3).build(), and verify check.handled_check_limit == 3 and check.to_json()["handled_check_limit"] == 3.
4. Edge case — None when unset — Build a check without calling with_handled_check_limit; verify check.handled_check_limit is None and "handled_check_limit" not in check.to_json().
5. Edge case — zero and negative values — Pass 0 and -1 as the limit; confirm the value is serialized (the field is omitted only when the value is None, not falsy).
6. Regression — Verify all pre-existing builder calls (without handled_check_limit) continue to produce identical JSON payloads with no new keys.

Notes

• The property is optional and defaults to None; no breaking changes to existing callers.
• JSON omission follows the if value is not None pattern consistent with other optional fields in the codebase.
• SandboxLivenessCheck (non-Zoom) also inherits the field via SandboxCheck, providing consistency across all liveness check variants.

---

Related Jira: SDK-2765
Auto-generated by Claude dynamic workflow

[Copilot]

Pull request overview

Adds support for an optional handled_check_limit property across the Python IDV sandbox check model/builder layer, enabling callers to control how many times a configured sandbox check response is reused before advancing to the next response, with conditional JSON serialization and accompanying pytest coverage.

Changes:

• Added optional handled_check_limit to SandboxCheck (property + conditional to_json() serialization) and to SandboxCheckBuilder (fluent setter + stored value).
• Threaded handled_check_limit through check constructors/builders for all concrete check types in doc_scan/check.
• Added a new pytest module validating presence/absence in JSON and propagation via all builders.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
yoti_python_sandbox/doc_scan/check/sandbox_check.py	Introduces handled_check_limit on the base check + builder and conditionally serializes it to JSON.
yoti_python_sandbox/doc_scan/check/sandbox_document_check.py	Passes handled_check_limit into the base SandboxCheck for document-based checks.
yoti_python_sandbox/doc_scan/check/sandbox_document_authenticity_check.py	Forwards handled_check_limit from the builder into the constructed check.
yoti_python_sandbox/doc_scan/check/sandbox_document_face_match_check.py	Forwards handled_check_limit from the builder into the constructed check.
yoti_python_sandbox/doc_scan/check/sandbox_document_text_data_check.py	Forwards handled_check_limit from the builder into the constructed check.
yoti_python_sandbox/doc_scan/check/sandbox_id_document_comparison_check.py	Adds handled_check_limit to the check constructor and forwards it from the builder.
yoti_python_sandbox/doc_scan/check/sandbox_liveness_check.py	Adds handled_check_limit to liveness base check and includes it in JSON via parent serialization.
yoti_python_sandbox/doc_scan/check/sandbox_zoom_liveness_check.py	Forwards handled_check_limit through Zoom liveness check + builder.
yoti_python_sandbox/doc_scan/check/sandbox_supplementary_document_text_data_check.py	Forwards handled_check_limit from the builder into the constructed check.
yoti_python_sandbox/tests/doc_scan/check/test_handled_check_limit.py	Adds tests validating JSON omission/inclusion and builder propagation across all check builders.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.