SDK-2792: Python - Add support for retrieving the extraction_image_ids field from the IDV pages - python

[mehmet-yoti]

Summary

Adds support for the new extraction_image_ids field on IDV page responses, exposing the list of media IDs used for automated extraction. The field is parsed from the document scan session response and returned via a new property on PageResponse, defaulting to an empty list when absent or null.

Changes

• yoti_python_sdk/doc_scan/session/retrieve/page_response.py: Parse extraction_image_ids from the raw data dict and expose it through a new extraction_image_ids property (list[str]). Defaults to [] when the field is missing or None.
• yoti_python_sdk/tests/doc_scan/session/retrieve/test_page_response.py: Added assertions to existing test_should_parse_correctly and test_should_parse_with_none tests, plus four new tests covering single UUID, empty array, null value, and absent-field cases.
• yoti_python_sdk/tests/fixtures/response_get_docs_scan_session.txt: Added extraction_image_ids array to the fixture page entry to reflect the new API field.

QA Test Steps

1. Check out the branch and install dev dependencies: pip install -e . and pip install -r requirements.txt.
2. Run the targeted test module to confirm all PageResponse tests pass:
   python -m pytest yoti_python_sdk/tests/doc_scan/session/retrieve/test_page_response.py -v
   • Verify the following tests pass: test_should_parse_correctly, test_should_parse_with_none, test_should_parse_extraction_image_ids_with_single_uuid, test_should_parse_extraction_image_ids_with_empty_array, test_should_parse_extraction_image_ids_with_null, test_should_parse_extraction_image_ids_when_field_absent.
3. Run the full doc_scan test suite to verify no regressions:
   python -m pytest yoti_python_sdk/tests/doc_scan/ -v
4. Happy path verification (REPL or script):

   from yoti_python_sdk.doc_scan.session.retrieve.page_response import PageResponse
   page = PageResponse({"capture_method": "CAMERA", "extraction_image_ids": ["066a9372-1ab9-49f0-b390-1b58e08f17f6"]})
   assert page.extraction_image_ids == ["066a9372-1ab9-49f0-b390-1b58e08f17f6"]

5. Edge case checks:
   • PageResponse({}).extraction_image_ids should return [] (field absent).
   • PageResponse({"extraction_image_ids": None}).extraction_image_ids should return [] (null).
   • PageResponse({"extraction_image_ids": []}).extraction_image_ids should return [] (empty array).
   • PageResponse(None).extraction_image_ids should return [] (no data at all).
6. Regression: confirm existing capture_method, media, and frames properties on PageResponse still behave as before when consuming the updated fixture in response_get_docs_scan_session.txt.
7. (Optional) Run an end-to-end retrieval against a sandbox IDV session that returns extraction_image_ids on pages and confirm the IDs are accessible via page.extraction_image_ids on each PageResponse.

Notes

• The implementation mirrors the existing pattern used for frames (default to empty list when missing), and additionally guards against an explicit None value via data.get("extraction_image_ids") or [].
• The list is copied via list(...) to prevent external mutation of the underlying input dict's list reference.
• No public API removed; this is an additive change and should be backwards compatible.
• The field is exposed as a list[str] of media IDs; resolving those IDs to actual media still goes through existing media retrieval endpoints — no new fetch helper was added in this change.

---

Related Jira: SDK-2792
Auto-generated by n8n + Claude CLI

[mehmet-yoti]

🤖 Claude Code Review

Code Review Findings

Critical

None

Major

None

Minor

• yoti_python_sdk/doc_scan/session/retrieve/page_response.py:26 — Inconsistent with the file's existing parsing style. The rest of PageResponse.__init__ (and every neighbouring response class in doc_scan/session/retrieve/) uses the pattern data.get("key", default) or a key-presence check, not data.get(...) or []. Using or [] also conflates "field absent", "field is None", and "field is an empty list/falsy value" which silently coerces malformed input rather than letting it surface. For consistency with the rest of the module, prefer data.get("extraction_image_ids", []) and treat None from the API as a contract issue, matching how frames, pages, etc. are handled.
• yoti_python_sdk/tests/doc_scan/session/retrieve/test_page_response.py:27 — Pre-existing usage of is for string equality (assert result.capture_method is self.SOME_CAPTURE_METHOD) is untouched, but the new test code at line 32–35 correctly uses ==. Worth aligning the style across the file (use == everywhere) while the file is being modified.

Nit

• yoti_python_sdk/doc_scan/session/retrieve/page_response.py:61 — Docstring says "list of media IDs used for automated extraction"; the API field is extraction_image_ids. Consider clarifying that these are image/media IDs that can be cross-referenced with MediaResponse.id so consumers know how to use them (matches the doc style of frames/media properties just above).
• yoti_python_sdk/tests/doc_scan/session/retrieve/test_page_response.py:45-71 — The four added cases (single_uuid, empty_array, null, field_absent) are good defensive coverage, but single_uuid overlaps with the assertions already in test_should_parse_correctly. Could be trimmed without losing signal; keeping it is also fine.
• yoti_python_sdk/tests/fixtures/response_get_docs_scan_session.txt:32 — The fixture only adds extraction_image_ids to the id_documents page, not to the supplementary_documents page (if one exists later in the file) or other page-bearing resources. Worth verifying parity so integration-style tests exercise the field across all page contexts; not blocking.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Adds support in the Doc Scan session retrieval models for the new extraction_image_ids field on IDV page responses, allowing SDK consumers to access the list of media IDs used for automated extraction.

Changes:

• Parse extraction_image_ids from page response data and expose it via a new PageResponse.extraction_image_ids property (defaults to [] when missing/None).
• Extend and add unit tests to cover populated, empty, null, and absent extraction_image_ids cases.
• Update the existing session fixture to include the new field on a page entry.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
yoti_python_sdk/doc_scan/session/retrieve/page_response.py	Adds parsing/storage + public property for extraction_image_ids.
yoti_python_sdk/tests/doc_scan/session/retrieve/test_page_response.py	Adds assertions and new tests covering extraction_image_ids scenarios.
yoti_python_sdk/tests/fixtures/response_get_docs_scan_session.txt	Updates the sample session response fixture to include extraction_image_ids.

---

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