ap-client 0.8.1.dev1__tar.gz → 0.9.0.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 (48) hide show
  1. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/PKG-INFO +3 -3
  2. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/api.py +240 -21
  3. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/canonical_get.py +68 -42
  4. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/canonical_put.py +261 -124
  5. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/cli.py +22 -4
  6. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/cluster_layout_fetcher.py +5 -11
  7. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/cluster_region_resolver.py +12 -15
  8. ap_client-0.9.0.dev2/ap_client/credit_commands.py +256 -0
  9. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/fs_commands.py +254 -103
  10. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/fs_storage.py +52 -13
  11. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/instance_commands.py +281 -26
  12. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/irepo_sdk.py +195 -63
  13. ap_client-0.9.0.dev2/ap_client/managed_ak.py +920 -0
  14. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/ossutil_io.py +32 -10
  15. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/replica_policy.py +8 -8
  16. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/shared_adapter.py +327 -168
  17. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/shared_commands.py +231 -101
  18. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/tool_manifest.py +13 -9
  19. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/pyproject.toml +3 -3
  20. ap_client-0.8.1.dev1/ap_client/managed_ak.py +0 -218
  21. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/__init__.py +0 -0
  22. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/akpool_commands.py +0 -0
  23. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/cli_help.py +0 -0
  24. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/cli_submission_defaults.py +0 -0
  25. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/config.py +0 -0
  26. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/dataset_commands.py +0 -0
  27. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/dataset_name.py +0 -0
  28. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/dataset_register.py +0 -0
  29. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/dfs_commands.py +0 -0
  30. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/exporter.py +0 -0
  31. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/fs_transfer.py +0 -0
  32. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/instance_options.py +0 -0
  33. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/manifest_view.py +0 -0
  34. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/ossutil_hash.py +0 -0
  35. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/profile_cascade_all.py +0 -0
  36. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/profile_cascade_cli.py +0 -0
  37. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/profile_cascade_display.py +0 -0
  38. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/profile_cascade_state.py +0 -0
  39. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/profile_commands.py +0 -0
  40. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/profile_diagnostics.py +0 -0
  41. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/profile_display.py +0 -0
  42. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/profile_references.py +0 -0
  43. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/repo_read_guard.py +0 -0
  44. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/share_api.py +0 -0
  45. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/split_publish.py +0 -0
  46. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/submission_metadata.py +0 -0
  47. {ap_client-0.8.1.dev1 → ap_client-0.9.0.dev2}/ap_client/tbb.py +0 -0
  48. {ap_client-0.8.1.dev1 → ap_client-0.9.0.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.8.1.dev1
3
+ Version: 0.9.0.dev2
4
4
  Summary: Agent Platform API Client & CLI
5
5
  Requires-Python: >=3.10
6
6
  Requires-Dist: click<8.2.0,>=8.1.8
@@ -11,9 +11,9 @@ Requires-Dist: rich>=13.0.0
11
11
  Requires-Dist: typer<0.21.0,>=0.20.1
12
12
  Requires-Dist: websockets>=13.0
13
13
  Provides-Extra: all
14
- Requires-Dist: instance-repo[oss]<2.0.0,>=1.7.0; extra == 'all'
14
+ Requires-Dist: instance-repo[oss]<2.0.0,>=1.7.1; extra == 'all'
15
15
  Provides-Extra: dataset
16
- Requires-Dist: instance-repo[oss]<2.0.0,>=1.7.0; extra == 'dataset'
16
+ Requires-Dist: instance-repo[oss]<2.0.0,>=1.7.1; extra == 'dataset'
17
17
  Description-Content-Type: text/markdown
18
18
 
19
19
  A lightweight Python SDK and command line interface for Agent Platform. It provides helpers for configuring API access and managing templates, datasets, jobs, and groups.
@@ -9,9 +9,10 @@ import socket
9
9
  import sys
10
10
  import threading
11
11
  import time
12
+ import unicodedata
12
13
  import uuid
13
14
  from email.utils import parsedate_to_datetime
14
- from typing import Any, Literal, Optional, Union
15
+ from typing import Any, List, Literal, Optional, Union
15
16
  from urllib.parse import parse_qsl, quote, urlencode, urlsplit, urlunsplit
16
17
 
17
18
  import requests
@@ -461,8 +462,9 @@ class _DeadlineWatchdog:
461
462
  pass
462
463
 
463
464
 
464
- def _read_bounded_control_bytes(resp, limit: int = _DEFAULT_CONTROL_BYTES,
465
- deadline: Optional[float] = None) -> bytes:
465
+ def _read_bounded_control_bytes(
466
+ resp, limit: int = _DEFAULT_CONTROL_BYTES, deadline: Optional[float] = None
467
+ ) -> bytes:
466
468
  """Stream one bounded canonical control response via public requests APIs.
467
469
 
468
470
  Content-Length pre-check plus streamed chunk reads keep memory at
@@ -477,7 +479,7 @@ def _read_bounded_control_bytes(resp, limit: int = _DEFAULT_CONTROL_BYTES,
477
479
  raise CanonicalControlAPIError("deadline")
478
480
  length = resp.headers.get("Content-Length")
479
481
  if isinstance(length, str) and length.isascii() and length.isdecimal():
480
- digits, cap = length.lstrip('0') or '0', str(limit)
482
+ digits, cap = length.lstrip("0") or "0", str(limit)
481
483
  if len(digits) > len(cap) or (len(digits) == len(cap) and digits > cap):
482
484
  raise CanonicalControlAPIError("response_limit", status_code=resp.status_code)
483
485
  data = bytearray()
@@ -491,7 +493,8 @@ def _read_bounded_control_bytes(resp, limit: int = _DEFAULT_CONTROL_BYTES,
491
493
  raise CanonicalControlAPIError("deadline")
492
494
  if len(block) > limit - len(data):
493
495
  raise CanonicalControlAPIError(
494
- "response_limit", status_code=resp.status_code)
496
+ "response_limit", status_code=resp.status_code
497
+ )
495
498
  data.extend(block)
496
499
  except CanonicalControlAPIError:
497
500
  raise
@@ -508,8 +511,9 @@ def _read_bounded_control_bytes(resp, limit: int = _DEFAULT_CONTROL_BYTES,
508
511
  return bytes(data)
509
512
 
510
513
 
511
- def _bounded_response_prefix(resp, limit: int = _DEFAULT_CONTROL_BYTES,
512
- deadline: Optional[float] = None) -> bytes:
514
+ def _bounded_response_prefix(
515
+ resp, limit: int = _DEFAULT_CONTROL_BYTES, deadline: Optional[float] = None
516
+ ) -> bytes:
513
517
  """Read one bounded first block of an error body for typed classification.
514
518
 
515
519
  Oversized bodies contribute only this bounded prefix; their real status
@@ -640,11 +644,173 @@ def _split_paged(payload: Any) -> tuple[list[dict], dict]:
640
644
  _META_TAG_PAGE_SIZE = 200
641
645
 
642
646
 
647
+ class CreditResource:
648
+ """Credit Quota queries and scoped selection tags against the central API."""
649
+
650
+ def __init__(self, client):
651
+ self._client = client
652
+
653
+ def list(
654
+ self,
655
+ *,
656
+ name: Optional[str] = None,
657
+ queue_id: Optional[str] = None,
658
+ role: Optional[str] = None,
659
+ status: Optional[str] = None,
660
+ page: int = 1,
661
+ page_size: int = 20,
662
+ ) -> dict:
663
+ params = {"page": page, "page_size": page_size}
664
+ params.update(
665
+ {
666
+ key: value
667
+ for key, value in {
668
+ "name": name,
669
+ "queue_id": queue_id,
670
+ "role": role,
671
+ "status": status,
672
+ }.items()
673
+ if value is not None
674
+ }
675
+ )
676
+ return self._client._get_central("/credit-quotas", params=params)
677
+
678
+ def get(self, credit_id: str) -> dict:
679
+ if not isinstance(credit_id, str) or not credit_id.strip():
680
+ raise ValueError("Credit ID is required")
681
+ validate_ak_id(credit_id)
682
+ return self._client._get_central(f"/credit-quotas/{quote(credit_id, safe='')}")
683
+
684
+ @staticmethod
685
+ def _tag_path(queue_id: Optional[str]) -> str:
686
+ if queue_id is None:
687
+ return "/users/me/ak-preferences"
688
+ if not isinstance(queue_id, str) or not queue_id.strip() or queue_id != queue_id.strip():
689
+ raise ValueError("Queue ID is required without surrounding whitespace")
690
+ return f"/queues/{quote(queue_id, safe='')}/ak-config"
691
+
692
+ @staticmethod
693
+ def _tag_config(payload: Any, queue_id: Optional[str]) -> dict:
694
+ data = payload.get("data", payload) if isinstance(payload, dict) else None
695
+ prefs = (
696
+ data.get("ak_preferences") if queue_id is not None and isinstance(data, dict) else data
697
+ )
698
+ version = data.get("version") if isinstance(data, dict) else None
699
+ if (
700
+ not isinstance(version, int)
701
+ or isinstance(version, bool)
702
+ or version < 0
703
+ or not isinstance(prefs, dict)
704
+ or "default_ak_id" not in prefs
705
+ or not isinstance(prefs.get("tag_defaults"), dict)
706
+ or (queue_id is not None and prefs.get("version") != version)
707
+ ):
708
+ raise ValueError(
709
+ "Invalid Credit tag configuration; inspect current tags before retrying"
710
+ )
711
+ default = prefs["default_ak_id"]
712
+ tags = prefs["tag_defaults"]
713
+ if (default is not None and (not isinstance(default, str) or not default)) or any(
714
+ not isinstance(tag, str) or not isinstance(value, str) or not value
715
+ for tag, value in tags.items()
716
+ ):
717
+ raise ValueError(
718
+ "Invalid Credit tag configuration; inspect current tags before retrying"
719
+ )
720
+ return {"version": version, "default_ak_id": default, "tag_defaults": dict(tags)}
721
+
722
+ def get_tag_config(self, *, queue_id: Optional[str] = None) -> dict:
723
+ """Read your personal selection tags, or a Queue's selection tags."""
724
+ return self._tag_config(
725
+ self._client._get_central(self._tag_path(queue_id), timeout=30), queue_id
726
+ )
727
+
728
+ def add_tags(
729
+ self,
730
+ credit_id: str,
731
+ tags: List[str],
732
+ *,
733
+ queue_id: Optional[str] = None,
734
+ replace: bool = False,
735
+ ) -> dict:
736
+ """Add selection tags; moving another Credit's tag requires replace=True."""
737
+ return self._change_tags(credit_id, tags, queue_id, remove=False, replace=replace)
738
+
739
+ def remove_tags(
740
+ self,
741
+ credit_id: str,
742
+ tags: List[str],
743
+ *,
744
+ queue_id: Optional[str] = None,
745
+ ) -> dict:
746
+ """Remove only tags currently assigned to this Credit. Unset tags are a no-op."""
747
+ return self._change_tags(credit_id, tags, queue_id, remove=True, replace=False)
748
+
749
+ def _change_tags(self, credit_id, tags, queue_id, *, remove, replace) -> dict:
750
+ if not isinstance(replace, bool):
751
+ raise ValueError("replace must be a boolean")
752
+ if not isinstance(credit_id, str) or not credit_id.strip():
753
+ raise ValueError("Credit ID is required")
754
+ validate_ak_id(credit_id)
755
+ if not isinstance(tags, (list, tuple)) or not tags:
756
+ raise ValueError("At least one tag is required")
757
+ for tag in tags:
758
+ if (
759
+ not isinstance(tag, str)
760
+ or not tag
761
+ or len(tag.encode("utf-8")) > 64
762
+ or any(c in ",@#.$" or c.isspace() or unicodedata.category(c) == "Cc" for c in tag)
763
+ ):
764
+ raise ValueError(
765
+ "Tags must be 1–64 UTF-8 bytes without whitespace, controls or , @ # . $"
766
+ )
767
+ path = self._tag_path(queue_id)
768
+ current = self.get_tag_config(queue_id=queue_id)
769
+ patch = {"expected_version": current["version"]}
770
+ changes = {}
771
+ for tag in dict.fromkeys(tags):
772
+ previous = (
773
+ current["default_ak_id"] if tag == "default" else current["tag_defaults"].get(tag)
774
+ )
775
+ if previous and previous != credit_id and (remove or not replace):
776
+ hint = (
777
+ "specify its current Credit ID"
778
+ if remove
779
+ else "use --replace or replace=True to move it"
780
+ )
781
+ raise ValueError(f"Tag {tag!r} already points to Credit {previous!r}; {hint}")
782
+ if (remove and previous is None) or (not remove and previous == credit_id):
783
+ continue
784
+ value = None if remove else credit_id
785
+ if tag == "default":
786
+ patch["default_ak_id"] = value
787
+ else:
788
+ changes[tag] = value
789
+ if changes:
790
+ patch["tag_defaults"] = changes
791
+ if len(patch) == 1:
792
+ return {**current, "changed": False}
793
+ # One CAS PATCH, no automatic read/merge/retry after a conflict. Never
794
+ # alter Queue bindings, grants, metadata labels or unrelated tag slots.
795
+ response = self._client._request_central("PATCH", path, json_body=patch, timeout=30)
796
+ updated = self._tag_config(response, queue_id)
797
+ if (
798
+ updated["version"] <= current["version"]
799
+ or ("default_ak_id" in patch and updated["default_ak_id"] != patch["default_ak_id"])
800
+ or any(updated["tag_defaults"].get(tag) != value for tag, value in changes.items())
801
+ ):
802
+ raise ValueError(
803
+ "Credit tag update outcome could not be verified; inspect current tags before retrying"
804
+ )
805
+ return {**updated, "changed": True}
806
+
807
+
643
808
  class APIClient:
644
809
  """Agent Platform API client."""
645
810
 
646
811
  def __init__(self, config: Config):
647
812
  self.config = config
813
+ self.credits = CreditResource(self)
648
814
  self.session = requests.Session()
649
815
  headers = dict(config.headers)
650
816
  user_agent = _build_user_agent(headers.get("User-Agent"))
@@ -749,8 +915,14 @@ class APIClient:
749
915
  # Bounded canonical projection (P1 fix): a finite per-request duration
750
916
  # owns ONE deadline across this request's retries, never per attempt,
751
917
  # so a slow byte-drip response cannot outlive its budget.
752
- if _bounded and deadline is None and isinstance(timeout, (int, float)) \
753
- and not isinstance(timeout, bool) and math.isfinite(timeout) and timeout >= 0:
918
+ if (
919
+ _bounded
920
+ and deadline is None
921
+ and isinstance(timeout, (int, float))
922
+ and not isinstance(timeout, bool)
923
+ and math.isfinite(timeout)
924
+ and timeout >= 0
925
+ ):
754
926
  deadline = time.monotonic() + timeout
755
927
  verbose = self.config.verbose
756
928
  max_attempts = 1 if _single_attempt else max(1, self.config.http_max_attempts)
@@ -837,13 +1009,19 @@ class APIClient:
837
1009
  resp_is_error = resp is not None and not 200 <= resp.status_code < 300
838
1010
  if resp_is_error:
839
1011
  resp.close()
840
- reason = "deadline" if (deadline is not None and time.monotonic() >= deadline) else "network"
1012
+ reason = (
1013
+ "deadline"
1014
+ if (deadline is not None and time.monotonic() >= deadline)
1015
+ else "network"
1016
+ )
841
1017
  raise CanonicalControlAPIError(reason) from None
842
1018
  if _single_attempt and resp is not None:
843
1019
  status = resp.status_code
844
1020
  resp.close()
845
1021
  if not 200 <= status < 300:
846
- raise APIError(status, "Incomplete HTTP error response", request_id, resp) from None
1022
+ raise APIError(
1023
+ status, "Incomplete HTTP error response", request_id, resp
1024
+ ) from None
847
1025
  if deadline is not None:
848
1026
  _manifest_budget_remaining(deadline)
849
1027
  duration_ms = (time.perf_counter() - start) * 1000
@@ -891,7 +1069,11 @@ class APIClient:
891
1069
  # auth headers were never sent there. Refuse.
892
1070
  raise CanonicalControlAPIError("redirect", status_code=resp.status_code)
893
1071
  if not 200 <= resp.status_code < 300:
894
- if read_only and attempt < max_attempts and _is_retryable_status(resp.status_code):
1072
+ if (
1073
+ read_only
1074
+ and attempt < max_attempts
1075
+ and _is_retryable_status(resp.status_code)
1076
+ ):
895
1077
  delay = _retry_delay(attempt, resp, max_wait=max_wait)
896
1078
  if not math.isfinite(delay):
897
1079
  delay = _retry_delay(attempt)
@@ -912,12 +1094,46 @@ class APIClient:
912
1094
  # report the deadline, never a late http_error.
913
1095
  raise CanonicalControlAPIError("deadline")
914
1096
  prefix = _bounded_response_prefix(
915
- resp, _DEFAULT_CONTROL_BYTES, deadline=deadline)
1097
+ resp, _DEFAULT_CONTROL_BYTES, deadline=deadline
1098
+ )
916
1099
  code = _bounded_error_biz_code(prefix)
1100
+ reason = "http_error"
1101
+ route_path = urlsplit(url).path
1102
+ # Only a complete, standard plain-text 404 is route evidence.
1103
+ # A prefix of a larger/chunked response is not sufficient.
1104
+ if (
1105
+ resp.status_code == 404
1106
+ and code is None
1107
+ and (
1108
+ route_path
1109
+ in {
1110
+ "/apis/v1/user-data/storage-layout",
1111
+ "/apis/v1/user-data/entries",
1112
+ "/apis/v1/user-data/directories",
1113
+ "/apis/v1/user-data/reads/resolve",
1114
+ "/apis/v1/user-data/writes/begin",
1115
+ }
1116
+ or re.fullmatch(
1117
+ r"/apis/v1/user-data/writes/[A-Za-z0-9_-]{1,128}(?:/commit)?",
1118
+ route_path,
1119
+ )
1120
+ )
1121
+ and resp.headers.get("Content-Type", "")
1122
+ .partition(";")[0]
1123
+ .strip()
1124
+ .lower()
1125
+ == "text/plain"
1126
+ and "Transfer-Encoding" not in resp.headers
1127
+ and resp.headers.get("Content-Length") == str(len(prefix))
1128
+ and prefix.strip() in {b"404 page not found", b"page not found"}
1129
+ ):
1130
+ reason = "server_route_missing"
917
1131
  raise CanonicalControlAPIError(
918
- "http_error", status_code=resp.status_code, biz_code=code)
1132
+ reason, status_code=resp.status_code, biz_code=code
1133
+ )
919
1134
  data = _read_bounded_control_bytes(
920
- resp, _DEFAULT_CONTROL_BYTES, deadline=deadline)
1135
+ resp, _DEFAULT_CONTROL_BYTES, deadline=deadline
1136
+ )
921
1137
  if not data:
922
1138
  resp.close()
923
1139
  return None
@@ -932,8 +1148,7 @@ class APIClient:
932
1148
  except (ValueError, RecursionError):
933
1149
  refusal = "invalid_json"
934
1150
  if refusal is not None:
935
- raise CanonicalControlAPIError(
936
- refusal, status_code=resp.status_code)
1151
+ raise CanonicalControlAPIError(refusal, status_code=resp.status_code)
937
1152
  if deadline is not None and time.monotonic() >= deadline:
938
1153
  # Refuse a late success; the budget is already spent.
939
1154
  raise CanonicalControlAPIError("deadline")
@@ -1052,11 +1267,11 @@ class APIClient:
1052
1267
 
1053
1268
  def _post(self, path: str, data: Any, timeout: TimeoutType = None) -> Any:
1054
1269
  """Send a POST request."""
1055
- from .managed_ak import parameter_ak_usage, require_parameter_ak_ack
1270
+ from .managed_ak import require_parameter_ak_ack, submission_ak_references
1056
1271
 
1057
- references, selectors = parameter_ak_usage(data) if path == "/jobs" else (set(), set())
1272
+ references = submission_ak_references(data) if path == "/jobs" else []
1058
1273
  result = self._request("POST", path, json_body=data, timeout=timeout)
1059
- require_parameter_ak_ack(result, references, selectors)
1274
+ require_parameter_ak_ack(result, set(), references=references)
1060
1275
  return result
1061
1276
 
1062
1277
  def _delete(self, path: str, *, params: Optional[dict] = None) -> Any:
@@ -2936,6 +3151,10 @@ class APIClient:
2936
3151
  timeout: TimeoutType = None,
2937
3152
  ) -> dict:
2938
3153
  """Retry a terminal job."""
3154
+ from .managed_ak import validate_ak_selection
3155
+
3156
+ # Retry returns the existing Job, not a create submission receipt.
3157
+ validate_ak_selection(None, params, None, None)
2939
3158
  body = None
2940
3159
  if params is not None or delete_params:
2941
3160
  body = {}
@@ -4096,7 +4315,7 @@ def _response_error_detail(resp: requests.Response) -> Any:
4096
4315
  inner = err_data["detail"]
4097
4316
  if isinstance(inner, dict):
4098
4317
  return inner # FastAPI detail=dict:内层即结构化错误体
4099
- return inner # detail=str:旧语义
4318
+ return inner # detail=str:旧语义
4100
4319
  if "code" in err_data:
4101
4320
  # Go 裸信封 {code, message, data}:保留完整结构化错误体
4102
4321
  return err_data
@@ -5,11 +5,12 @@ This module owns the invocation's absolute budget, operator input guards,
5
5
  matching typed results and honest per-file display. It does not replace the
6
6
  runtime fs_get entry before the cross-repository integration gates pass.
7
7
  """
8
+
8
9
  from __future__ import annotations
9
10
 
10
11
  import math
11
- from pathlib import Path
12
12
  import time
13
+ from pathlib import Path
13
14
  from typing import Any, Optional
14
15
 
15
16
  from .canonical_put import _bind_operation_deadline
@@ -28,9 +29,15 @@ class CanonicalReadOrchestrationError(Exception):
28
29
  class ReadOutcome:
29
30
  """Presentation result; only a matching SDK verified result is verified."""
30
31
 
31
- def __init__(self, mode: str, *, canonical_key: str = "",
32
- legacy_profile: str = "", verified: bool = False,
33
- target: Optional[Path] = None):
32
+ def __init__(
33
+ self,
34
+ mode: str,
35
+ *,
36
+ canonical_key: str = "",
37
+ legacy_profile: str = "",
38
+ verified: bool = False,
39
+ target: Optional[Path] = None,
40
+ ):
34
41
  self.mode = mode
35
42
  self.canonical_key = canonical_key
36
43
  self.legacy_profile = legacy_profile
@@ -58,14 +65,16 @@ def _remaining(absolute: Optional[float]) -> Optional[float]:
58
65
  remaining = absolute - time.monotonic()
59
66
  if remaining <= 0:
60
67
  raise CanonicalReadOrchestrationError(
61
- "budget_exhausted", "the read operation exceeded its time budget")
68
+ "budget_exhausted", "the read operation exceeded its time budget"
69
+ )
62
70
  return remaining
63
71
 
64
72
 
65
73
  def _reader_failure() -> None:
66
74
  # No repr of a resolution/result: they can contain signed URLs.
67
75
  raise CanonicalReadOrchestrationError(
68
- "reader_failure", "the SDK reader returned an inconsistent typed result")
76
+ "reader_failure", "the SDK reader returned an inconsistent typed result"
77
+ )
69
78
 
70
79
 
71
80
  class _ReadProgress:
@@ -123,31 +132,40 @@ def get_user_data(
123
132
  """
124
133
  if reader is None:
125
134
  raise CanonicalReadOrchestrationError(
126
- "reader_missing", "the typed user-data SDK reader is not available")
127
- if (any(not isinstance(v, str) or not v
128
- for v in (owner, relative_path, cluster))
129
- or any(char.isspace() for value in (owner, cluster) for char in value)):
135
+ "reader_missing", "the typed user-data SDK reader is not available"
136
+ )
137
+ if any(not isinstance(v, str) or not v for v in (owner, relative_path, cluster)) or any(
138
+ char.isspace() for value in (owner, cluster) for char in value
139
+ ):
130
140
  raise CanonicalReadOrchestrationError(
131
- "invalid_input", "owner and cluster must be nonempty without whitespace; relative_path must be nonempty")
141
+ "invalid_input",
142
+ "owner and cluster must be nonempty without whitespace; relative_path must be nonempty",
143
+ )
132
144
  # A relative path is an exact object identity. Leading/trailing spaces are
133
145
  # legal bytes and must reach the SDK unchanged; validation rejects aliases
134
146
  # instead of silently selecting a different object.
135
147
  if deadline is not None and (
136
- isinstance(deadline, bool) or not isinstance(deadline, (int, float))
137
- or not math.isfinite(deadline)):
148
+ isinstance(deadline, bool)
149
+ or not isinstance(deadline, (int, float))
150
+ or not math.isfinite(deadline)
151
+ ):
138
152
  raise CanonicalReadOrchestrationError(
139
- "invalid_input", "the read deadline must be a finite absolute monotonic time")
140
- if not isinstance(overwrite, bool) or (
141
- progress is not None and not isinstance(progress, bool)):
153
+ "invalid_input", "the read deadline must be a finite absolute monotonic time"
154
+ )
155
+ if not isinstance(overwrite, bool) or (progress is not None and not isinstance(progress, bool)):
142
156
  raise CanonicalReadOrchestrationError(
143
- "invalid_input", "overwrite and progress must be boolean options")
157
+ "invalid_input", "overwrite and progress must be boolean options"
158
+ )
144
159
  if not callable(getattr(reader, "resolve", None)) or not callable(
145
- getattr(reader, "download", None)):
160
+ getattr(reader, "download", None)
161
+ ):
146
162
  _reader_failure()
147
163
 
148
164
  from instance_repo.clients.user_data_reads import (
149
- CanonicalReadResolution, LegacyReadResolution,
150
- VerifiedReadResult, LegacyReadResult,
165
+ CanonicalReadResolution,
166
+ LegacyReadResolution,
167
+ LegacyReadResult,
168
+ VerifiedReadResult,
151
169
  )
152
170
 
153
171
  _remaining(deadline)
@@ -155,8 +173,8 @@ def get_user_data(
155
173
  if transport is not None:
156
174
  _bind_operation_deadline(transport, deadline)
157
175
  resolution = reader.resolve(
158
- owner=owner, relative_path=relative_path, cluster=cluster,
159
- deadline=_remaining(deadline))
176
+ owner=owner, relative_path=relative_path, cluster=cluster, deadline=_remaining(deadline)
177
+ )
160
178
  _remaining(deadline)
161
179
 
162
180
  if type(resolution) is CanonicalReadResolution:
@@ -170,38 +188,46 @@ def get_user_data(
170
188
  else:
171
189
  _reader_failure()
172
190
  if (resolution.owner, resolution.relative_path, resolution.cluster) != (
173
- owner, relative_path, cluster):
191
+ owner,
192
+ relative_path,
193
+ cluster,
194
+ ):
174
195
  _reader_failure()
175
196
 
176
197
  target = Path(target)
177
198
  with _ReadProgress(progress, key, size) as display:
178
199
  result = reader.download(
179
- resolution, target, overwrite=overwrite, deadline=_remaining(deadline))
200
+ resolution, target, overwrite=overwrite, deadline=_remaining(deadline)
201
+ )
180
202
  _remaining(deadline)
181
203
  if type(resolution) is CanonicalReadResolution:
182
204
  if type(result) is not VerifiedReadResult or (
183
- result.mode != "canonical"
184
- or result.canonical_key != resolution.canonical_key
185
- or result.anchor != resolution.anchor
186
- or result.sha256_verified != resolution.anchor.sha256
187
- or type(result.bytes_written) is not int
188
- or result.bytes_written != size
189
- or result.target != target):
205
+ result.mode != "canonical"
206
+ or result.canonical_key != resolution.canonical_key
207
+ or result.anchor != resolution.anchor
208
+ or result.sha256_verified != resolution.anchor.sha256
209
+ or type(result.bytes_written) is not int
210
+ or result.bytes_written != size
211
+ or result.target != target
212
+ ):
190
213
  _reader_failure()
191
- outcome = ReadOutcome("canonical", canonical_key=key,
192
- verified=True, target=target)
214
+ outcome = ReadOutcome("canonical", canonical_key=key, verified=True, target=target)
193
215
  else:
194
216
  if type(result) is not LegacyReadResult or (
195
- result.mode != "legacy-unanchored"
196
- or result.legacy_key != resolution.legacy_key
197
- or result.unanchored is not True
198
- or type(result.bytes_written) is not int
199
- or result.bytes_written != size
200
- or result.target != target):
217
+ result.mode != "legacy-unanchored"
218
+ or result.legacy_key != resolution.legacy_key
219
+ or result.unanchored is not True
220
+ or type(result.bytes_written) is not int
221
+ or result.bytes_written != size
222
+ or result.target != target
223
+ ):
201
224
  _reader_failure()
202
- outcome = ReadOutcome("legacy-unanchored",
203
- legacy_profile=resolution.legacy_profile,
204
- verified=False, target=target)
225
+ outcome = ReadOutcome(
226
+ "legacy-unanchored",
227
+ legacy_profile=resolution.legacy_profile,
228
+ verified=False,
229
+ target=target,
230
+ )
205
231
  _remaining(deadline)
206
232
  display.finish()
207
233
  # Display completion/cleanup belongs to this invocation too. Never report