ap-client 0.7.1.dev0__tar.gz → 0.7.1.dev2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/PKG-INFO +1 -1
  2. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/api.py +231 -199
  3. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/cli.py +532 -76
  4. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/config.py +63 -1
  5. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/dataset_commands.py +45 -335
  6. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/dfs_commands.py +33 -50
  7. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/instance_commands.py +31 -44
  8. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/irepo_sdk.py +0 -57
  9. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/ossutil_io.py +82 -48
  10. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/profile_commands.py +48 -491
  11. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/share_api.py +1 -0
  12. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/pyproject.toml +1 -1
  13. ap_client-0.7.1.dev0/ap_client/profile_cascade_all.py +0 -149
  14. ap_client-0.7.1.dev0/ap_client/profile_cascade_cli.py +0 -356
  15. ap_client-0.7.1.dev0/ap_client/profile_cascade_display.py +0 -279
  16. ap_client-0.7.1.dev0/ap_client/profile_cascade_state.py +0 -207
  17. ap_client-0.7.1.dev0/ap_client/profile_diagnostics.py +0 -117
  18. ap_client-0.7.1.dev0/ap_client/profile_display.py +0 -172
  19. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/__init__.py +0 -0
  20. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/akpool_commands.py +0 -0
  21. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/dataset_name.py +0 -0
  22. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/dataset_register.py +0 -0
  23. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/exporter.py +0 -0
  24. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/fs_commands.py +0 -0
  25. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/fs_storage.py +0 -0
  26. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/fs_transfer.py +0 -0
  27. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/instance_options.py +0 -0
  28. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/managed_ak.py +0 -0
  29. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/manifest_view.py +0 -0
  30. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/ossutil_hash.py +0 -0
  31. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/repo_read_guard.py +0 -0
  32. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/split_publish.py +0 -0
  33. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/tbb.py +0 -0
  34. {ap_client-0.7.1.dev0 → ap_client-0.7.1.dev2}/ap_client/waiter.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: ap-client
3
- Version: 0.7.1.dev0
3
+ Version: 0.7.1.dev2
4
4
  Summary: Agent Platform API Client & CLI
5
5
  Requires-Python: >=3.10
6
6
  Requires-Dist: irepo-artifact==0.2.4
@@ -24,6 +24,17 @@ _DEFAULT_READ_TIMEOUT = 86400
24
24
  TimeoutType = Union[float, tuple[Optional[float], Optional[float]], None]
25
25
 
26
26
 
27
+ def _catalog_output_item(record: Any, description_field: str) -> Any:
28
+ """Add stable CLI/SDK aliases while retaining the resource fields."""
29
+ if not isinstance(record, dict):
30
+ return record
31
+ item = dict(record)
32
+ if "source_id" in item:
33
+ item["id"] = item["source_id"]
34
+ item["desc"] = item.get(description_field)
35
+ return item
36
+
37
+
27
38
  def _validate_credential_source_selection(
28
39
  *,
29
40
  account_pool: Optional[str],
@@ -110,7 +121,6 @@ _RETRYABLE_TRANSPORT_EXCEPTIONS = (
110
121
  requests.exceptions.ChunkedEncodingError,
111
122
  )
112
123
  _HTTP_RETRY_INITIAL_DELAY = 0.5
113
- _HTTP_RETRY_MAX_DELAY = 2.0
114
124
  _HTTP_RETRY_BACKOFF_FACTOR = 2.0
115
125
 
116
126
  # Sentinel for distinguishing "not yet computed" from "computed and None"
@@ -250,13 +260,27 @@ class APIError(Exception):
250
260
  detail: Any,
251
261
  request_id: str,
252
262
  response: Optional[requests.Response],
263
+ *,
264
+ retry_stop_reason: Optional[str] = None,
253
265
  ):
254
266
  self.status_code = status_code
255
267
  self.detail = detail
256
268
  self.request_id = request_id
257
269
  self.response = response
270
+ self.retry_stop_reason = retry_stop_reason
271
+ self.pop_request_id = (
272
+ response.headers.get("x-acs-request-id") if response is not None else None
273
+ )
258
274
  super().__init__(self._build_message())
259
275
 
276
+ def __str__(self) -> str:
277
+ message = self._build_message()
278
+ if self.retry_stop_reason:
279
+ message += f" (retry_stop_reason={self.retry_stop_reason})"
280
+ if self.pop_request_id:
281
+ message += f" (pop_request_id={self.pop_request_id})"
282
+ return message
283
+
260
284
  def _build_message(self) -> str:
261
285
  if self.status_code is None:
262
286
  return f"API Network Error: {self.detail} (request_id={self.request_id})"
@@ -405,15 +429,52 @@ class APIClient:
405
429
  ) -> Any:
406
430
  """Send an HTTP request with X-Request-ID and optional verbose logging."""
407
431
  self._require_cluster_config()
432
+ return self._request_http(
433
+ method,
434
+ self._url(path),
435
+ params=params,
436
+ json_body=json_body,
437
+ timeout=timeout,
438
+ deadline=deadline,
439
+ _return_response=_return_response,
440
+ )
441
+
442
+ def _request_http(
443
+ self,
444
+ method: str,
445
+ url: str,
446
+ *,
447
+ params: Optional[dict] = None,
448
+ json_body: Any = None,
449
+ timeout: TimeoutType = None,
450
+ deadline: Optional[float] = None,
451
+ _return_response: bool = False,
452
+ ) -> Any:
453
+ """One retry budget shared by cluster and central requests.
454
+
455
+ Only a fresh gateway pre-forward rejection permits replaying a write.
456
+ JSON bodies and params are reused; this path does not accept streams.
457
+ """
408
458
  if timeout is None:
409
459
  timeout = _default_timeout()
410
460
  else:
411
461
  timeout = _normalize_explicit_timeout(timeout)
412
- url = self._url(path)
413
462
  verbose = self.config.verbose
414
- max_attempts = self._max_attempts_for(method)
463
+ max_attempts = max(1, self.config.http_max_attempts)
464
+ max_wait = self.config.http_max_wait
465
+ read_only = method.upper() in _RETRYABLE_METHODS
466
+ recovery_deadline = None
467
+ last_retry_error = None
415
468
  for attempt in range(1, max_attempts + 1):
416
- attempt_timeout = _deadline_timeout(timeout, deadline)
469
+ effective_deadline = deadline
470
+ if recovery_deadline is not None:
471
+ effective_deadline = (
472
+ min(deadline, recovery_deadline) if deadline is not None else recovery_deadline
473
+ )
474
+ if effective_deadline <= time.monotonic():
475
+ last_retry_error.retry_stop_reason = "recovery_window_exhausted"
476
+ raise last_retry_error
477
+ attempt_timeout = _deadline_timeout(timeout, effective_deadline)
417
478
  request_id = str(uuid.uuid4())
418
479
  headers = {"X-Request-ID": request_id}
419
480
  if verbose:
@@ -445,8 +506,9 @@ class APIClient:
445
506
  duration_ms = (time.perf_counter() - start) * 1000
446
507
  if verbose:
447
508
  self._log_exception(method, url, request_id, duration_ms, exc)
448
- if attempt < max_attempts and _is_retryable_exception(exc):
449
- delay = _retry_delay(attempt)
509
+ if read_only and attempt < max_attempts and _is_retryable_exception(exc):
510
+ delay = _retry_delay(attempt, max_wait=max_wait)
511
+ last_retry_error = APIError(None, str(exc), request_id, None)
450
512
  if verbose:
451
513
  self._log_retry(
452
514
  method,
@@ -457,17 +519,53 @@ class APIClient:
457
519
  delay,
458
520
  error=f"{type(exc).__name__}: {exc}",
459
521
  )
460
- _deadline_sleep(delay, deadline)
522
+ if (
523
+ effective_deadline is not None
524
+ and delay >= effective_deadline - time.monotonic()
525
+ ):
526
+ last_retry_error.retry_stop_reason = "retry_budget_exhausted"
527
+ raise last_retry_error from exc
528
+ _deadline_sleep(delay, effective_deadline)
461
529
  continue
462
530
  raise APIError(None, str(exc), request_id, None) from exc
463
531
  duration_ms = (time.perf_counter() - start) * 1000
464
- if deadline is not None:
465
- _manifest_budget_remaining(deadline)
466
532
  if verbose:
467
533
  self._log_response(method, url, request_id, resp, duration_ms)
468
534
  if not resp.ok:
469
- if attempt < max_attempts and _is_retryable_status(resp.status_code):
470
- delay = _retry_delay(attempt, resp)
535
+ pop_rejected = _is_pop_rejection(resp)
536
+ if pop_rejected and recovery_deadline is None:
537
+ recovery_deadline = time.monotonic() + self.config.http_retry_window
538
+ error = APIError(resp.status_code, _response_error_detail(resp), request_id, resp)
539
+ last_retry_error = error
540
+ can_retry = pop_rejected or (read_only and _is_retryable_status(resp.status_code))
541
+ if can_retry and attempt < max_attempts:
542
+ if pop_rejected:
543
+ delay = _pop_retry_delay(resp)
544
+ if delay is None:
545
+ # No usable gateway wait hint: stop instead of
546
+ # guessing a local interval.
547
+ error.retry_stop_reason = "invalid_retry_hint"
548
+ resp.close()
549
+ raise error
550
+ else:
551
+ delay = _retry_delay(attempt, resp, max_wait=max_wait)
552
+ if delay > max_wait:
553
+ # A gateway hint longer than the user's ceiling fails fast
554
+ # instead of blocking the caller; never shorten it.
555
+ error.retry_stop_reason = "retry_wait_exceeded"
556
+ resp.close()
557
+ raise error
558
+ retry_deadline = deadline
559
+ if recovery_deadline is not None:
560
+ retry_deadline = (
561
+ min(deadline, recovery_deadline)
562
+ if deadline is not None
563
+ else recovery_deadline
564
+ )
565
+ if retry_deadline is not None and delay >= retry_deadline - time.monotonic():
566
+ error.retry_stop_reason = "retry_budget_exhausted"
567
+ resp.close()
568
+ raise error
471
569
  if verbose:
472
570
  self._log_retry(
473
571
  method,
@@ -478,10 +576,15 @@ class APIClient:
478
576
  delay,
479
577
  status=resp.status_code,
480
578
  )
481
- _deadline_sleep(delay, deadline)
579
+ resp.close()
580
+ _deadline_sleep(delay, retry_deadline)
482
581
  continue
483
- detail = _response_error_detail(resp)
484
- raise APIError(resp.status_code, detail, request_id, resp)
582
+ if can_retry:
583
+ error.retry_stop_reason = "max_attempts_exhausted"
584
+ resp.close()
585
+ raise error
586
+ if deadline is not None and deadline <= time.monotonic():
587
+ _manifest_budget_remaining(deadline)
485
588
  if _return_response:
486
589
  return resp, request_id
487
590
  if not resp.content:
@@ -493,11 +596,6 @@ class APIClient:
493
596
  raise APIError(resp.status_code, detail, request_id, resp) from exc
494
597
  raise RuntimeError("unreachable retry state")
495
598
 
496
- def _max_attempts_for(self, method: str) -> int:
497
- if method.upper() not in _RETRYABLE_METHODS:
498
- return 1
499
- return max(1, self.config.http_max_attempts)
500
-
501
599
  def _require_cluster_config(self) -> None:
502
600
  if has_cluster_header(self.config.headers):
503
601
  return
@@ -571,46 +669,13 @@ class APIClient:
571
669
  the central AP is cluster-agnostic (data syncs to all clusters).
572
670
  Uses /apis/v1 prefix instead of /api.
573
671
  """
574
- if timeout is None:
575
- timeout = _default_timeout()
576
- else:
577
- timeout = _normalize_explicit_timeout(timeout)
578
- url = self._url_central(path)
579
- request_id = str(uuid.uuid4())
580
- headers = {"X-Request-ID": request_id}
581
- verbose = self.config.verbose
582
- if verbose:
583
- request_headers = dict(self.session.headers)
584
- request_headers.update(headers)
585
- self._log_request(method, url, request_id, request_headers, params, json_body)
586
- start = time.perf_counter()
587
- try:
588
- resp = self.session.request(
589
- method,
590
- url,
591
- params=params,
592
- json=json_body,
593
- headers=headers,
594
- timeout=timeout,
595
- )
596
- except requests.RequestException as exc:
597
- if verbose:
598
- duration_ms = (time.perf_counter() - start) * 1000
599
- self._log_exception(method, url, request_id, duration_ms, exc)
600
- raise APIError(None, str(exc), request_id, None) from exc
601
- duration_ms = (time.perf_counter() - start) * 1000
602
- if verbose:
603
- self._log_response(method, url, request_id, resp, duration_ms)
604
- if not resp.ok:
605
- detail = _response_error_detail(resp)
606
- raise APIError(resp.status_code, detail, request_id, resp)
607
- if not resp.content:
608
- return None
609
- try:
610
- return resp.json()
611
- except ValueError as exc:
612
- detail = _unexpected_non_json_response_detail(resp)
613
- raise APIError(resp.status_code, detail, request_id, resp) from exc
672
+ return self._request_http(
673
+ method,
674
+ self._url_central(path),
675
+ params=params,
676
+ json_body=json_body,
677
+ timeout=timeout,
678
+ )
614
679
 
615
680
  def _get_central(
616
681
  self, path: str, params: Optional[dict] = None, timeout: TimeoutType = None
@@ -795,6 +860,19 @@ class APIClient:
795
860
  params["agenthub_revision"] = self.config.agenthub_ref
796
861
  return self._get(f"/templates/{quote(name)}", params=params)
797
862
 
863
+ def list_benchmarks_page(self, *, page: int = 1, page_size: int = 20) -> dict:
864
+ """Fetch one central benchmark page without collecting subsequent pages."""
865
+ if type(page) is not int or page < 1:
866
+ raise ValueError("page must be a positive integer")
867
+ if type(page_size) is not int or not 1 <= page_size <= 200:
868
+ raise ValueError("page_size must be an integer between 1 and 200")
869
+ payload = self._get("/apis/v1/benchmarks", params={"page": page, "page_size": page_size})
870
+ records, pagination = _split_paged(payload)
871
+ return {
872
+ "items": [_catalog_output_item(record, "description") for record in records],
873
+ "pagination": pagination,
874
+ }
875
+
798
876
  def list_benchmarks(self) -> list:
799
877
  """List all benchmarks from the central registry, preserving legacy IDs."""
800
878
  benchmarks = []
@@ -808,10 +886,7 @@ class APIClient:
808
886
  )
809
887
  records, pagination = _split_paged(payload)
810
888
  for record in records:
811
- item = dict(record)
812
- if "source_id" in item:
813
- item.setdefault("id", item["source_id"])
814
- benchmarks.append(item)
889
+ benchmarks.append(_catalog_output_item(record, "description"))
815
890
  if not records or not pagination:
816
891
  break
817
892
  try:
@@ -827,8 +902,8 @@ class APIClient:
827
902
  return benchmarks
828
903
 
829
904
  def get_benchmark(self, name: str) -> dict:
830
- """Get a single benchmark by exact name."""
831
- return self._get(f"/benchmarks/{quote(name, safe='')}")
905
+ """Get a benchmark by stable source ID or exact name (ID takes precedence)."""
906
+ return _catalog_output_item(self._get(f"/benchmarks/{quote(name, safe='')}"), "description")
832
907
 
833
908
  # ==================== Checkpoint operations ====================
834
909
 
@@ -1043,7 +1118,7 @@ class APIClient:
1043
1118
  与 ``list_meta_tags`` 同样自动翻页,避免值目录被单页默认大小截断。
1044
1119
  """
1045
1120
  records, pagination = self._get_meta_tag_catalog("/meta-tags", {"key": key})
1046
- result = {"items": records}
1121
+ result = {"items": [_catalog_output_item(item, "desc") for item in records]}
1047
1122
  if pagination:
1048
1123
  result["pagination"] = pagination
1049
1124
  return result
@@ -1684,16 +1759,48 @@ class APIClient:
1684
1759
  source_mode: str = "terminal_only",
1685
1760
  start_paused: Optional[bool] = None,
1686
1761
  trials: Optional[int] = None,
1762
+ group_patch: Optional[dict] = None,
1687
1763
  target_group: Optional[dict] = None,
1688
1764
  job_patch: Optional[dict] = None,
1765
+ agenthub_revision: Optional[str] = None,
1689
1766
  resource_mappings: Optional[dict] = None,
1690
1767
  idempotency_key: Optional[str] = None,
1691
1768
  ) -> dict:
1769
+ if group_patch is not None and target_group is not None:
1770
+ raise ConfigurationError("group_patch and target_group are mutually exclusive")
1771
+ if trials is not None and (
1772
+ isinstance(trials, bool) or not isinstance(trials, int) or not 1 <= trials <= 100
1773
+ ):
1774
+ raise ConfigurationError("trials must be an integer between 1 and 100")
1775
+ # Preserve explicit clears while omitting nullable fields that only inherit.
1776
+ group_key = "target_group" if target_group is not None else "group_patch"
1777
+ group = target_group if target_group is not None else group_patch
1778
+ group = {
1779
+ key: value
1780
+ for key, value in (group or {}).items()
1781
+ if value is not None
1782
+ or key in {"model_base_url_collection", "eval_config", "group_post_process"}
1783
+ }
1784
+ job = {
1785
+ key: value
1786
+ for key, value in (job_patch or {}).items()
1787
+ if value is not None
1788
+ or key in {"account_pool", "credential_type", "overrides", "quota_id"}
1789
+ }
1790
+ if job.get("quota_id") is not None:
1791
+ quota_id = job["quota_id"]
1792
+ if not isinstance(quota_id, str) or not quota_id.strip():
1793
+ raise ConfigurationError("quota_id must be a nonempty string or null")
1794
+ job["quota_id"] = quota_id.strip()
1795
+ if job.get("credential_type") and job.get("account_pool"):
1796
+ raise ConfigurationError("credential_type and account_pool are mutually exclusive")
1692
1797
  body: dict[str, Any] = {
1693
1798
  "source_mode": source_mode,
1694
- "target_group": target_group or {},
1695
- "job_patch": job_patch or {},
1799
+ group_key: group,
1800
+ "job_patch": job,
1696
1801
  }
1802
+ if agenthub_revision is not None:
1803
+ body["agenthub_revision"] = agenthub_revision
1697
1804
  if source_cluster is not None:
1698
1805
  body["source_cluster"] = source_cluster
1699
1806
  if start_paused is not None:
@@ -1721,7 +1828,7 @@ class APIClient:
1721
1828
  source_group_id: str,
1722
1829
  **kwargs: Any,
1723
1830
  ) -> dict:
1724
- """Clone locally, or cross-cluster when source_cluster is supplied."""
1831
+ """Clone Jobs verbatim, or the latest configuration per instance with explicit trials."""
1725
1832
 
1726
1833
  body = self._unified_group_clone_body(**kwargs)
1727
1834
  return self._post(f"/groups/{quote(source_group_id)}/clone", body)
@@ -1734,24 +1841,26 @@ class APIClient:
1734
1841
  source_mode: str = "terminal_only",
1735
1842
  start_paused: bool = True,
1736
1843
  trials: Optional[int] = None,
1844
+ group_patch: Optional[dict] = None,
1737
1845
  target_group: Optional[dict] = None,
1738
1846
  job_patch: Optional[dict] = None,
1847
+ agenthub_revision: Optional[str] = None,
1739
1848
  resource_mappings: Optional[dict] = None,
1740
1849
  idempotency_key: Optional[str] = None,
1741
1850
  ) -> dict:
1742
- body = {
1743
- "source_cluster": source_cluster,
1744
- "source_group_id": source_group_id,
1745
- "source_mode": source_mode,
1746
- "start_paused": start_paused,
1747
- "target_group": target_group or {},
1748
- "job_patch": job_patch or {},
1749
- "resource_mappings": resource_mappings or {},
1750
- }
1751
- if trials is not None:
1752
- body["trials"] = trials
1753
- if idempotency_key is not None:
1754
- body["idempotency_key"] = idempotency_key
1851
+ body = APIClient._unified_group_clone_body(
1852
+ source_cluster=source_cluster,
1853
+ source_mode=source_mode,
1854
+ start_paused=start_paused,
1855
+ trials=trials,
1856
+ group_patch=group_patch,
1857
+ target_group=target_group,
1858
+ job_patch=job_patch,
1859
+ agenthub_revision=agenthub_revision,
1860
+ resource_mappings=resource_mappings or {},
1861
+ idempotency_key=idempotency_key,
1862
+ )
1863
+ body["source_group_id"] = source_group_id
1755
1864
  return body
1756
1865
 
1757
1866
  def preview_cross_cluster_group_clone(
@@ -2963,8 +3072,6 @@ class APIClient:
2963
3072
  account_pool: Optional[str] = None,
2964
3073
  metadata: Optional[dict] = None,
2965
3074
  tags: Optional[list[str]] = None,
2966
- parents: Optional[list[str | dict]] = None,
2967
- auto_follow_parents: Optional[list[str]] = None,
2968
3075
  ) -> dict:
2969
3076
  """Create a new submission profile."""
2970
3077
  body: dict = {"name": name, "spec": spec}
@@ -2976,10 +3083,6 @@ class APIClient:
2976
3083
  body["metadata"] = metadata
2977
3084
  if tags is not None:
2978
3085
  body["tags"] = tags
2979
- if parents is not None:
2980
- body["parents"] = parents
2981
- if auto_follow_parents is not None:
2982
- body["auto_follow_parents"] = auto_follow_parents
2983
3086
  return self._post(self._PROFILES_BASE, body)
2984
3087
 
2985
3088
  def list_profiles(
@@ -3121,9 +3224,6 @@ class APIClient:
3121
3224
  account_pool: Optional[str] = None,
3122
3225
  metadata: Optional[dict] = None,
3123
3226
  reason: Optional[str] = None,
3124
- version: Optional[int] = None,
3125
- parents: Optional[list[str | dict]] = None,
3126
- auto_follow_parents: Optional[list[str]] = None,
3127
3227
  ) -> dict:
3128
3228
  """Update a submission profile, preserving an omitted default Pool.
3129
3229
 
@@ -3139,108 +3239,7 @@ class APIClient:
3139
3239
  body["metadata"] = metadata
3140
3240
  if reason is not None:
3141
3241
  body["reason"] = reason
3142
- if version is not None:
3143
- if type(version) is not int or version < 1:
3144
- raise ValueError("version must be a positive integer")
3145
- body["version"] = version
3146
- if parents is not None:
3147
- body["parents"] = parents
3148
- if auto_follow_parents is not None:
3149
- body["auto_follow_parents"] = auto_follow_parents
3150
- return self._put(f"{self._PROFILES_BASE}/{quote(profile_id, safe='')}", body)
3151
-
3152
- def patch_profile(self, profile_id: str, fields: dict) -> dict:
3153
- """Patch own definition; callers should supply their original version."""
3154
- return self._request(
3155
- "PATCH", f"{self._PROFILES_BASE}/{quote(profile_id, safe='')}", json_body=fields
3156
- )
3157
-
3158
- def resolve_profile(self, identifier: str, *, version: Optional[int] = None) -> dict:
3159
- return self._get(
3160
- f"{self._PROFILES_BASE}/{quote(identifier, safe='')}/resolved",
3161
- params={"version": version} if version is not None else None,
3162
- )
3163
-
3164
- def preview_profile(self, draft: dict) -> dict:
3165
- return self._post(f"{self._PROFILES_BASE}/resolve", draft)
3166
-
3167
- def profile_children(
3168
- self,
3169
- identifier: str,
3170
- *,
3171
- page: int = 1,
3172
- page_size: int = 20,
3173
- target_version: Optional[int] = None,
3174
- eligible_only: bool = False,
3175
- current_only: bool = False,
3176
- ) -> dict:
3177
- params = {"page": page, "page_size": page_size}
3178
- if target_version is not None:
3179
- params["target_version"] = target_version
3180
- if eligible_only:
3181
- params["eligible_only"] = "true"
3182
- if current_only:
3183
- params["current_only"] = "true"
3184
- return self._get(
3185
- f"{self._PROFILES_BASE}/{quote(identifier, safe='')}/children",
3186
- params=params,
3187
- )
3188
-
3189
- def profile_diff(
3190
- self,
3191
- identifier: str,
3192
- from_version: Optional[int] = None,
3193
- to_version: Optional[int] = None,
3194
- view: str = "own",
3195
- *,
3196
- compare_to: Optional[str] = None,
3197
- ) -> dict:
3198
- """Compare versions of one Profile, or two Profiles (omitted versions use current)."""
3199
- params = {"from": from_version, "to": to_version, "view": view}
3200
- if compare_to is not None:
3201
- params["compare_to"] = compare_to
3202
- result = self._get(
3203
- f"{self._PROFILES_BASE}/{quote(identifier, safe='')}/diff",
3204
- params=params,
3205
- )
3206
- if compare_to is not None:
3207
- # Older servers ignore unknown query fields. Do not present their
3208
- # single-Profile response as a successful cross-Profile comparison.
3209
- for field in ("from_profile", "to_profile"):
3210
- ref = result.get(field) if isinstance(result, dict) else None
3211
- if (
3212
- not isinstance(ref, dict)
3213
- or not isinstance(ref.get("profile_id"), str)
3214
- or not ref["profile_id"].startswith("sp-")
3215
- or type(ref.get("version")) is not int
3216
- or ref["version"] < 1
3217
- ):
3218
- raise APIError(
3219
- 200,
3220
- "Server did not confirm cross-Profile diff support; upgrade the server before comparing different Profiles",
3221
- None,
3222
- None,
3223
- )
3224
- return result
3225
-
3226
- def cascade_profiles(self, identifier: str, request: dict) -> dict:
3227
- return self._post(f"{self._PROFILES_BASE}/{quote(identifier, safe='')}/cascades", request)
3228
-
3229
- def get_profile_cascade(self, operation_id: str) -> dict:
3230
- return self._get(f"/apis/v1/profile-cascades/{quote(operation_id, safe='')}")
3231
-
3232
- def profile_cascade_history(
3233
- self, profile_id: str, *, page: int = 1, page_size: int = 20
3234
- ) -> dict:
3235
- return self._get(
3236
- f"{self._PROFILES_BASE}/{quote(profile_id, safe='')}/cascades",
3237
- params={"page": page, "page_size": page_size},
3238
- )
3239
-
3240
- def retry_profile_cascade(self, operation_id: str, items: list[dict]) -> dict:
3241
- return self._post(
3242
- f"/apis/v1/profile-cascades/{quote(operation_id, safe='')}/retry", {"items": items}
3243
- )
3242
+ return self._put(f"{self._PROFILES_BASE}/{quote(profile_id)}", body)
3244
3243
 
3245
3244
  def delete_profile(self, profile_id: str) -> dict:
3246
3245
  """Delete a submission profile."""
@@ -3545,9 +3544,18 @@ def _is_retryable_status(status_code: int) -> bool:
3545
3544
  return status_code in _RETRYABLE_STATUS_CODES
3546
3545
 
3547
3546
 
3548
- def _retry_delay(attempt: int, resp: requests.Response | None = None) -> float:
3549
- delay = _HTTP_RETRY_INITIAL_DELAY * (_HTTP_RETRY_BACKOFF_FACTOR ** max(0, attempt - 1))
3550
- delay = min(delay, _HTTP_RETRY_MAX_DELAY)
3547
+ def _retry_delay(
3548
+ attempt: int,
3549
+ resp: requests.Response | None = None,
3550
+ *,
3551
+ max_wait: float | None = None,
3552
+ ) -> float:
3553
+ delay = _HTTP_RETRY_INITIAL_DELAY * (
3554
+ _HTTP_RETRY_BACKOFF_FACTOR ** min(2, max(0, attempt - 1))
3555
+ )
3556
+ # Local backoff may be shortened to the wait ceiling; a gateway hint never is.
3557
+ if max_wait is not None:
3558
+ delay = min(delay, max_wait)
3551
3559
  if resp is not None:
3552
3560
  retry_after = _retry_after_delay(resp)
3553
3561
  if retry_after is not None:
@@ -3555,6 +3563,26 @@ def _retry_delay(attempt: int, resp: requests.Response | None = None) -> float:
3555
3563
  return delay
3556
3564
 
3557
3565
 
3566
+ def _is_pop_rejection(resp: requests.Response) -> bool:
3567
+ # The gateway contract reserves this marker for rejection before AP forwarding.
3568
+ return resp.status_code == 400 and not resp.history and "x-acs-retry-after" in resp.headers
3569
+
3570
+
3571
+ def _pop_retry_delay(resp: requests.Response) -> float | None:
3572
+ value = resp.headers.get("x-acs-retry-after", "").strip()
3573
+ if not re.fullmatch(r"[0-9]+", value):
3574
+ # No usable hint: the caller stops instead of guessing a local interval.
3575
+ return None
3576
+ # Parse without int(): Python limits huge decimal conversions. Infinite
3577
+ # waits exceed the finite retry window and stop without replay.
3578
+ try:
3579
+ delay = float(value) / 1000
3580
+ except OverflowError:
3581
+ delay = math.inf
3582
+ standard = _retry_after_delay(resp)
3583
+ return max(delay, standard) if standard is not None else delay
3584
+
3585
+
3558
3586
  def _retry_after_delay(resp: requests.Response) -> float | None:
3559
3587
  value = resp.headers.get("Retry-After")
3560
3588
  if value is None:
@@ -3563,14 +3591,18 @@ def _retry_after_delay(resp: requests.Response) -> float | None:
3563
3591
  if not value:
3564
3592
  return None
3565
3593
  try:
3566
- return max(0.0, float(value))
3594
+ seconds = float(value)
3595
+ return max(0.0, seconds) if math.isfinite(seconds) else None
3567
3596
  except ValueError:
3568
3597
  pass
3569
3598
  try:
3570
3599
  retry_at = parsedate_to_datetime(value)
3571
- except (TypeError, ValueError):
3600
+ except (TypeError, ValueError, OverflowError):
3601
+ return None
3602
+ try:
3603
+ return max(0.0, retry_at.timestamp() - time.time())
3604
+ except (ValueError, OverflowError, OSError):
3572
3605
  return None
3573
- return max(0.0, retry_at.timestamp() - time.time())
3574
3606
 
3575
3607
 
3576
3608
  def _safe_decode(raw: bytes) -> str: