Skip to content

Add single-item convenience wrappers for bulk partial-success APIs#211

Draft
fredvisser wants to merge 6 commits into
masterfrom
feature/python-modernization-phase2
Draft

Add single-item convenience wrappers for bulk partial-success APIs#211
fredvisser wants to merge 6 commits into
masterfrom
feature/python-modernization-phase2

Conversation

@fredvisser
Copy link
Copy Markdown
Contributor

Summary

Several SystemLink client APIs only expose bulk operations that return partial-success envelopes (items + failed + error). When callers need to create or update a single item — by far the most common case — they must wrap the call in a list, then manually unpack the response and check for partial failures. This PR eliminates that boilerplate by adding singular convenience methods to six client classes.

What changed

Client New methods
TestMonitorClient create_result, create_step, update_result, update_step
ProductClient create_product, update_product
SpecClient create_spec, update_spec
TestPlanClient create_test_plan, update_test_plan, schedule_test_plan, create_test_plan_template
WorkItemClient create_work_item, update_work_item, schedule_work_item, create_work_item_template, update_work_item_template
AssetManagementClient create_asset

A shared helper unwrap_single_item_partial_success() (in nisystemlink/clients/core/helpers/_partial_success.py) centralizes the unwrap-or-raise logic so each wrapper stays minimal.

Why this is beneficial

  1. Reduces caller boilerplate — common single-item operations go from ~6 lines to 1.
  2. Safer error handling — partial-success failures are translated into ApiException with full error context, rather than silently returning empty lists.
  3. Consistent pattern — all wrappers follow the same contract (raise on failure, return typed item on success), making the API surface predictable.
  4. Non-breaking — the existing bulk methods remain unchanged; the new methods are purely additive.

Testing

  • 24 new unit tests covering the shared helper and all 18 convenience methods.
  • Full CI validation passes: poe check (formatting), poe lint, poe types (mypy, 379 source files), poe test (410 tests passed).

Introduce singular convenience methods (create_result, create_step,
update_result, update_step, create_product, update_product,
create_spec, update_spec, create_test_plan, update_test_plan,
schedule_test_plan, create_test_plan_template, create_asset,
create_work_item, update_work_item, schedule_work_item,
create_work_item_template, update_work_item_template) on their
respective client classes.

Each method wraps the existing bulk API with a one-element list, then
uses the shared unwrap_single_item_partial_success() helper to either
return the created/updated item or raise ApiException with the server
error details.

This eliminates repetitive boilerplate for the common single-item use
case while keeping the bulk methods available for batch operations.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant