SDK-2488: Python - Support dark mode in IDV SDK - python

[mehmet-yoti]

Summary

Extends the SdkConfig and SdkConfigBuilder classes to support dark mode configuration in the IDV (Identity Verification) SDK. Two new optional fields — dark_mode and primary_colour_dark_mode — are added to allow integrators to control the appearance of the web/native client in dark environments. Both fields are omitted from the JSON payload when not set, preserving backward compatibility.

Changes

• yoti_python_sdk/doc_scan/session/create/sdk_config.py

  • Added dark_mode parameter to SdkConfig.__init__ (optional, str: "ON", "OFF", or "AUTO")
  • Added primary_colour_dark_mode parameter to SdkConfig.__init__ (optional, hex colour string)
  • Added dark_mode and primary_colour_dark_mode properties on SdkConfig
  • Both new fields included in to_json() via remove_null_values (omitted when None)
  • Added with_dark_mode(dark_mode) generic setter on SdkConfigBuilder
  • Added convenience methods: with_dark_mode_on(), with_dark_mode_off(), with_dark_mode_auto()
  • Added with_primary_colour_dark_mode(colour) setter on SdkConfigBuilder
  • Updated SdkConfigBuilder.build() to pass the two new fields to SdkConfig

• tests/doc_scan/session/create/test_sdk_config.py

  • 18 new unit tests covering: default None values, each convenience method, generic setter, JSON serialisation (present and absent cases), and property access

QA Test Steps

1. Setup

   • Clone the repo and check out websdk-auto/SDK-2488-python-support-dark-mode-in-idv-sdk
   • Install dependencies: pip install -e ".[dev]"

2. Run the full test suite

   pytest
   

   All 502 tests should pass with no failures or errors.

3. Happy path — dark mode ON

   from yoti_python_sdk.doc_scan.session.create.sdk_config import SdkConfigBuilder
   config = SdkConfigBuilder().with_dark_mode_on().with_primary_colour_dark_mode("#121212").build()
   import json; print(json.dumps(config.to_json()))
   # Expect: {"dark_mode": "ON", "primary_colour_dark_mode": "#121212"}

4. Happy path — dark mode AUTO

   config = SdkConfigBuilder().with_dark_mode_auto().build()
   print(config.to_json())
   # Expect: {"dark_mode": "AUTO"}  (primary_colour_dark_mode absent)

5. Happy path — dark mode OFF

   config = SdkConfigBuilder().with_dark_mode_off().build()
   assert config.to_json().get("dark_mode") == "OFF"

6. Edge case — fields absent when not set

   config = SdkConfigBuilder().build()
   assert "dark_mode" not in config.to_json()
   assert "primary_colour_dark_mode" not in config.to_json()

7. Edge case — generic setter

   config = SdkConfigBuilder().with_dark_mode("AUTO").build()
   assert config.dark_mode == "AUTO"

8. Regression — existing SdkConfig fields unaffected
   Build a SdkConfig with all pre-existing fields and verify JSON output is unchanged compared to before this PR.

Notes

• No SDK-level validation is performed on the dark_mode string value; the backend is responsible for validating accepted values ("ON", "OFF", "AUTO"). This is consistent with how other string fields (e.g. locale, capture methods) are handled.
• primary_colour_dark_mode follows the same hex-colour convention as primary_colour (no format validation in the SDK).
• The to_json() method uses the existing remove_null_values utility, so no API payload changes occur when the fields are not set, maintaining full backward compatibility.
• Follow-up: consider adding a DARK_MODE_ON/OFF/AUTO constants module similar to how capture methods are defined in doc_scan/constants.py.

---

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

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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 dark mode theming support to the Doc Scan IDV SDK configuration by extending SdkConfig/SdkConfigBuilder with optional dark_mode and primary_colour_dark_mode fields that serialize only when set (via existing remove_null_values behavior), plus unit tests to validate defaults and JSON output.

Changes:

• Extend SdkConfig with dark_mode and primary_colour_dark_mode properties and include them in to_json() (omitted when None).
• Extend SdkConfigBuilder with with_dark_mode(...) plus with_dark_mode_on/off/auto() convenience methods, and with_primary_colour_dark_mode(...).
• Add unit tests covering defaults, builder fluency, and JSON serialization for the new fields.

Reviewed changes

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

File	Description
yoti_python_sdk/doc_scan/session/create/sdk_config.py	Adds new dark mode configuration fields, builder setters, and JSON serialization support.
yoti_python_sdk/tests/doc_scan/session/create/test_sdk_config.py	Adds unit tests validating the new fields’ defaults and serialized payload behavior.

---

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

[mehmet-yoti]

Code Review Findings

PR adds dark_mode and primary_colour_dark_mode fields to SdkConfig / SdkConfigBuilder. The implementation is correct and all 38 tests pass. Three minor/nit findings below.

---

Minor

1. test_should_build_correctly does not assert the new fields default to None
yoti_python_sdk/tests/doc_scan/session/create/test_sdk_config.py — existing test at line ~26

The integration-style "build correctly" test already asserts every existing field on the built object but is not updated to assert result.dark_mode is None and result.primary_colour_dark_mode is None. If build() were accidentally wired to pass a non-None default it would go undetected.

# add to test_should_build_correctly
assert result.dark_mode is None
assert result.primary_colour_dark_mode is None

---

Nit

2. No test for dark_mode=None passed explicitly (parity with test_brand_id_absent_from_json_when_none)
yoti_python_sdk/tests/doc_scan/session/create/test_sdk_config.py

The existing suite has test_brand_id_absent_from_json_when_none that calls with_brand_id(None). There is no equivalent for with_dark_mode(None) or with_primary_colour_dark_mode(None). This leaves the explicit-None path of remove_null_values untested for the new fields.

Suggested addition:

def test_dark_mode_absent_from_json_when_none(self):
    result = SdkConfigBuilder().with_dark_mode(None).build()
    serialised = json.loads(json.dumps(result, cls=YotiEncoder))
    assert "dark_mode" not in serialised

def test_primary_colour_dark_mode_absent_from_json_when_none(self):
    result = SdkConfigBuilder().with_primary_colour_dark_mode(None).build()
    serialised = json.loads(json.dumps(result, cls=YotiEncoder))
    assert "primary_colour_dark_mode" not in serialised

---

None

Critical — None
Major — None