From cb5bbb147ccb3cc59a952ba3a019ab2e20bab91f Mon Sep 17 00:00:00 2001 From: "zhansheng.lzs" Date: Wed, 18 Nov 2026 17:57:34 +0800 Subject: [PATCH 1/5] ci(unit_test): run 2.0 tests on Python 3.9/3.11/3.13 only Trim the `current` job matrix to the odd CPython legs (drop 3.10/3.12); the archived `legacy` job stays on 3.11. --- .github/workflows/unit_test.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/workflows/unit_test.yml b/.github/workflows/unit_test.yml index 8ec5ac8f..fa132430 100644 --- a/.github/workflows/unit_test.yml +++ b/.github/workflows/unit_test.yml @@ -15,17 +15,14 @@ jobs: runs-on: ${{ matrix.os }} strategy: matrix: + # The 2.0 surface runs on the odd CPython legs only (3.9/3.11/3.13). # ubuntu-latest (26.04) ships no CPython 3.9 build, so pin the # still-supported 3.9 leg to 24.04 and keep the rest on latest. include: - os: ubuntu-24.04 python-version: '3.9' - - os: ubuntu-latest - python-version: '3.10' - os: ubuntu-latest python-version: '3.11' - - os: ubuntu-latest - python-version: '3.12' - os: ubuntu-latest python-version: '3.13' From b03ab54e2ba05ae0fa6af5aaee1f0ec89fd83a08 Mon Sep 17 00:00:00 2001 From: "zhansheng.lzs" Date: Thu, 19 Nov 2026 11:12:41 +0800 Subject: [PATCH 2/5] feat(management): RAM ManagementClient read-only integration layer (G1/G2/G5) Add dashscope.management as an optional [management] extra: a ToB self-service backend integration layer over the ModelStudio/2026-02-10 RAM OpenAPI (ROA). Read-only first release. - G1 atomic layer: 14 read ops only (workspaces/models/limits/permissions, api keys, billing overview/trend, token plan account/members/seats/ subscription/shared-packages). 24 write/out-of-scope ops deferred and catalogued as high-risk in md; no code. - G2 resources: ManagementClient/AsyncManagementClient with sync+async symmetry, raw=True overloads, region binding + with_options(region). - G5 cross-cutting: V3 ACS3-HMAC-SHA256 signing via official alibabacloud_openapi_util; credential chain via alibabacloud_credentials; dual-envelope success gate + RAM error crosswalk; SecretStr redaction; dual pagination (TokenPage nextToken / BasePage PageNo). - Every request carries x-dashscope-sdk-client=python-sdk//management2 + session id + client-request-id, folded into the signed header set. Tests: 120 mock tests (signer gateway oracle, credentials, errors, transport, resources, pagination) + 5 env-gated read-only e2e. Full suite 6498 passed / 51 skipped / 0 failed. pre-commit green. --- dashscope/management/__init__.py | 127 +++ dashscope/management/_credentials.py | 90 ++ dashscope/management/_errors.py | 193 +++++ dashscope/management/_ops.py | 299 +++++++ dashscope/management/_pagination.py | 118 +++ dashscope/management/_parse.py | 179 ++++ dashscope/management/_redaction.py | 100 +++ dashscope/management/_resource.py | 95 +++ dashscope/management/_signer.py | 138 ++++ dashscope/management/_transport.py | 354 ++++++++ dashscope/management/api_keys.py | 354 ++++++++ dashscope/management/billing.py | 424 ++++++++++ dashscope/management/client.py | 293 +++++++ dashscope/management/token_plan.py | 1049 ++++++++++++++++++++++++ dashscope/management/types.py | 476 +++++++++++ dashscope/management/workspaces.py | 813 ++++++++++++++++++ requirements-test.txt | 3 + setup.py | 7 + tests/management_helpers.py | 87 ++ tests/protocols/test_management_e2e.py | 156 ++++ tests/test_management_api_keys.py | 143 ++++ tests/test_management_billing.py | 118 +++ tests/test_management_credentials.py | 134 +++ tests/test_management_errors.py | 191 +++++ tests/test_management_pagination.py | 159 ++++ tests/test_management_signer.py | 254 ++++++ tests/test_management_token_plan.py | 204 +++++ tests/test_management_transport.py | 276 +++++++ tests/test_management_workspaces.py | 188 +++++ 29 files changed, 7022 insertions(+) create mode 100644 dashscope/management/__init__.py create mode 100644 dashscope/management/_credentials.py create mode 100644 dashscope/management/_errors.py create mode 100644 dashscope/management/_ops.py create mode 100644 dashscope/management/_pagination.py create mode 100644 dashscope/management/_parse.py create mode 100644 dashscope/management/_redaction.py create mode 100644 dashscope/management/_resource.py create mode 100644 dashscope/management/_signer.py create mode 100644 dashscope/management/_transport.py create mode 100644 dashscope/management/api_keys.py create mode 100644 dashscope/management/billing.py create mode 100644 dashscope/management/client.py create mode 100644 dashscope/management/token_plan.py create mode 100644 dashscope/management/types.py create mode 100644 dashscope/management/workspaces.py create mode 100644 tests/management_helpers.py create mode 100644 tests/protocols/test_management_e2e.py create mode 100644 tests/test_management_api_keys.py create mode 100644 tests/test_management_billing.py create mode 100644 tests/test_management_credentials.py create mode 100644 tests/test_management_errors.py create mode 100644 tests/test_management_pagination.py create mode 100644 tests/test_management_signer.py create mode 100644 tests/test_management_token_plan.py create mode 100644 tests/test_management_transport.py create mode 100644 tests/test_management_workspaces.py diff --git a/dashscope/management/__init__.py b/dashscope/management/__init__.py new file mode 100644 index 00000000..38aa2d6e --- /dev/null +++ b/dashscope/management/__init__.py @@ -0,0 +1,127 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""ManagementClient -- the RAM OpenAPI (ModelStudio/2026-02-10) surface. + +An optional extra: ``pip install 'dashscope[management]'`` pulls in +``alibabacloud_credentials`` (the multi-tenant credential chain) and +``alibabacloud_openapi_util`` (ACS3-HMAC-SHA256 V3 signing). The core +``dashscope`` package does not import this module, so installing the base +SDK never forces the aliyun cloud libraries. + +This revision is read-only (G1/G2/G5): workspace / API-key / billing / +TokenPlan reads. Write operations are high-risk and deferred. +""" + +from __future__ import annotations + +try: + import alibabacloud_credentials # noqa: F401 + import alibabacloud_openapi_util # noqa: F401 +except ImportError as exc: # pragma: no cover - exercised only without extra + raise ImportError( + "dashscope.management requires the optional 'management' extra " + "(alibabacloud_credentials, alibabacloud_openapi_util). " + "Install it with: pip install 'dashscope[management]'", + ) from exc + +from dashscope.management._credentials import ( + CredentialResolver, + ResolvedCredential, +) +from dashscope.management._errors import ( + Envelope, + check_management_response, + decode_body, + management_error, + read_envelope, +) +from dashscope.management._pagination import TokenPage +from dashscope.management._redaction import ( + REDACTED, + SecretRedactionFilter, + mask_secret, + redact_body, +) +from dashscope.management.client import ( + AsyncManagementClient, + ManagementClient, + ManagementConfig, +) +from dashscope.management.types import ( + ApiKey, + ApiKeyAuth, + BillingGroup, + BillingOverview, + BillingTrend, + CostTotals, + GroupByTotal, + InferenceMetadata, + ManagementModel, + ModelAccessScope, + ModelInfo, + ModelLimit, + ModelPermission, + OrgMember, + OrgMemberPage, + OrgMembership, + Permissions, + Price, + RateLimit, + ResultByTime, + Seat, + SeatPage, + SeatStats, + SharedPackage, + SharedPackagePage, + SubscriptionSeatItem, + SubscriptionStats, + TokenPlanAccount, + Workspace, +) + +__all__ = [ + "REDACTED", + "ApiKey", + "ApiKeyAuth", + "AsyncManagementClient", + "BillingGroup", + "BillingOverview", + "BillingTrend", + "CostTotals", + "CredentialResolver", + "Envelope", + "GroupByTotal", + "InferenceMetadata", + "ManagementClient", + "ManagementConfig", + "ManagementModel", + "ModelAccessScope", + "ModelInfo", + "ModelLimit", + "ModelPermission", + "OrgMember", + "OrgMemberPage", + "OrgMembership", + "Permissions", + "Price", + "RateLimit", + "ResolvedCredential", + "ResultByTime", + "Seat", + "SeatPage", + "SeatStats", + "SecretRedactionFilter", + "SharedPackage", + "SharedPackagePage", + "SubscriptionSeatItem", + "SubscriptionStats", + "TokenPage", + "TokenPlanAccount", + "Workspace", + "check_management_response", + "decode_body", + "management_error", + "mask_secret", + "read_envelope", + "redact_body", +] diff --git a/dashscope/management/_credentials.py b/dashscope/management/_credentials.py new file mode 100644 index 00000000..38d1a018 --- /dev/null +++ b/dashscope/management/_credentials.py @@ -0,0 +1,90 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Multi-tenant credential chain for the management surface. + +Wraps the official ``alibabacloud_credentials`` client so a ToB backend +can hand the SDK any of: an explicit AK/SK (optionally an STS token), a +``Config`` dict for the richer provider types (ECS RAM role, RAM role +ARN, OIDC, credentials URI), a pre-built credentials ``Client``, or +nothing at all to fall through to the library's default chain +(environment, IMDS, ...). Resolution returns a frozen snapshot; the +library owns refresh, so an STS token that expires mid-process is +re-fetched on the next ``resolve()``. + +No secret is ever logged here -- the resolved snapshot is handed +straight to the signer. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any, Mapping, Optional + +from alibabacloud_credentials.client import Client as _CredentialsClient +from alibabacloud_credentials.models import Config as _CredentialsConfig + +__all__ = ["CredentialResolver", "ResolvedCredential"] + + +@dataclass(frozen=True) +class ResolvedCredential: + """One credential snapshot used to sign a single request.""" + + access_key_id: str + access_key_secret: str + security_token: Optional[str] = None + provider_name: Optional[str] = None + + +class CredentialResolver: + """Resolve management credentials through the official chain. + + Precedence: a pre-built ``credential`` client wins, then an explicit + ``config`` dict, then explicit ``access_key_id`` / ``access_key_secret`` + (with ``security_token`` selecting the STS provider type), then the + library default chain. + """ + + def __init__( + self, + *, + access_key_id: Optional[str] = None, + access_key_secret: Optional[str] = None, + security_token: Optional[str] = None, + credential: Optional[Any] = None, + config: Optional[Mapping[str, Any]] = None, + ) -> None: + if credential is not None: + self._client = credential + elif config is not None: + self._client = _CredentialsClient( + _CredentialsConfig(**dict(config)), + ) + elif access_key_id and access_key_secret: + self._client = _CredentialsClient( + _CredentialsConfig( + type="sts" if security_token else "access_key", + access_key_id=access_key_id, + access_key_secret=access_key_secret, + security_token=security_token, + ), + ) + else: + self._client = _CredentialsClient() + + def resolve(self) -> ResolvedCredential: + """Fetch a credential snapshot synchronously.""" + return _snapshot(self._client.get_credential()) + + async def resolve_async(self) -> ResolvedCredential: + """Fetch a credential snapshot without blocking the event loop.""" + return _snapshot(await self._client.get_credential_async()) + + +def _snapshot(model: Any) -> ResolvedCredential: + return ResolvedCredential( + access_key_id=model.access_key_id, + access_key_secret=model.access_key_secret, + security_token=model.security_token, + provider_name=getattr(model, "provider_name", None), + ) diff --git a/dashscope/management/_errors.py b/dashscope/management/_errors.py new file mode 100644 index 00000000..3fa19677 --- /dev/null +++ b/dashscope/management/_errors.py @@ -0,0 +1,193 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""RAM gateway error crosswalk for the management surface. + +Three envelope shapes meet here: the modelstudio lists answer with a +lowercase ``{code, message, success, requestId, httpStatusCode}`` bag, +the tokenplan ops with a PascalCase ``{Code, Message, Success, RequestId, +HttpStatusCode, Data}`` bag, and the aliyun gateway itself rejects bad +credentials with ``{Code, Message, RequestId, Recommend, HostId}`` and no +success flag at all. :func:`read_envelope` normalizes all three. + +The success gate is the load-bearing part: a *successful* modelstudio +call still carries ``code: "200"``, so feeding ``code`` straight into +``ResponseBase`` would trip its ``_flag_business_error`` validator and +report a healthy response as an error. Success is therefore decided by +``success`` / ``Success`` first, and only falls back to the HTTP status +and a known-success code set when neither flag is present. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any, Dict, Mapping, Optional, Type + +import httpx + +from dashscope.errors import ( + AuthenticationError, + BadRequestError, + DashScopeError, + InternalServerError, + NotFoundError, + PermissionDeniedError, + RateLimitError, + ServiceUnavailableError, +) +from dashscope.management._redaction import redact_body + +__all__ = [ + "Envelope", + "check_management_response", + "decode_body", + "management_error", + "read_envelope", +] + +_SUCCESS_CODES = frozenset({"200", "OK", "Success", "0", ""}) +_AUTH_CODES = frozenset( + { + "InvalidAccessKeyId", + "InvalidAccessKeyId.NotFound", + "InvalidAccessKeyId.Inactive", + "SignatureDoesNotMatch", + "InvalidSecurityToken", + "InvalidSecurityToken.Expired", + "InvalidSecurityToken.MismatchWithAccessKey", + "MissingSecurityToken", + }, +) +_FORBIDDEN_CODES = frozenset( + {"Forbidden", "Forbidden.RAM", "NoPermission", "NotAuthorized"}, +) + + +@dataclass(frozen=True) +class Envelope: + """Normalized response envelope, independent of wire casing.""" + + success: bool + code: Optional[str] + message: Optional[str] + request_id: Optional[str] + status_code: int + body: Dict[str, Any] + + +def decode_body(response: httpx.Response) -> Dict[str, Any]: + """Best-effort JSON object decode; a non-object body becomes ``{}``.""" + try: + body = response.json() + except ValueError: + return {} + return body if isinstance(body, dict) else {} + + +def read_envelope(body: Any, status_code: int) -> Envelope: + """Normalize a modelstudio / tokenplan / gateway body into one shape.""" + if not isinstance(body, dict): + body = {} + success = body.get("success") + if success is None: + success = body.get("Success") + code = body.get("code") or body.get("Code") + message = body.get("message") or body.get("Message") + request_id = body.get("requestId") or body.get("RequestId") + return Envelope( + success=_is_success(success, code, status_code), + code=code, + message=message, + request_id=request_id, + status_code=status_code, + body=body, + ) + + +def _is_success(success: Any, code: Any, status_code: int) -> bool: + if success is True: + return True + if success is False: + return False + if not 200 <= status_code < 300: + return False + return code is None or str(code) in _SUCCESS_CODES + + +def management_error( + envelope: Envelope, + headers: Optional[Mapping[str, str]] = None, +) -> DashScopeError: + """Build the dashscope error class matching a failed envelope.""" + error_class = _error_class(envelope.code, envelope.status_code) + return error_class( + envelope.message or "management request failed", + code=envelope.code, + status_code=envelope.status_code, + request_id=envelope.request_id, + body=redact_body(envelope.body), + headers=headers, + ) + + +def _error_class( + code: Optional[str], + status_code: int, +) -> Type[DashScopeError]: + by_code = _class_by_code(code or "") + if by_code is not None: + return by_code + return _class_by_status(status_code) + + +def _class_by_code(code: str) -> Optional[Type[DashScopeError]]: + if code.startswith("Throttling"): + return RateLimitError + if code in _AUTH_CODES: + return AuthenticationError + if code in _FORBIDDEN_CODES: + return PermissionDeniedError + if code.endswith("NotExist") or "NotFound" in code: + return NotFoundError + if code.startswith("InvalidParameter"): + return BadRequestError + return None + + +_STATUS_CLASSES: Dict[int, Type[DashScopeError]] = { + 401: AuthenticationError, + 403: PermissionDeniedError, + 404: NotFoundError, + 429: RateLimitError, + 503: ServiceUnavailableError, +} + + +def _class_by_status(status_code: int) -> Type[DashScopeError]: + exact = _STATUS_CLASSES.get(status_code) + if exact is not None: + return exact + if status_code >= 500: + return InternalServerError + if status_code >= 400: + return BadRequestError + return InternalServerError + + +def check_management_response( + response: httpx.Response, + *, + raise_on_error: bool = True, +) -> Optional[DashScopeError]: + """Apply the success gate; raise (or return) the crosswalked error. + + Returns ``None`` on success. In non-raising mode the error is returned + so the resource can fold ``code`` / ``message`` / ``is_error`` into the + parsed model's envelope instead of throwing. + """ + envelope = read_envelope(decode_body(response), response.status_code) + if envelope.success: + return None + error = management_error(envelope, response.headers) + if raise_on_error: + raise error + return error diff --git a/dashscope/management/_ops.py b/dashscope/management/_ops.py new file mode 100644 index 00000000..992ebc49 --- /dev/null +++ b/dashscope/management/_ops.py @@ -0,0 +1,299 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Atomic read-op registry for the management surface (G1, read-only). + +Only the 14 read ops needed by G2 (workspaces / api_keys / billing) and +G5 (token_plan) are coded here. The other 24 ops of ModelStudio/2026-02-10 +-- 21 writes plus 3 out-of-scope reads -- are deliberately absent and +catalogued as high-risk / deferred in the milestone doc; no write op is +implemented in this revision. + +Each :class:`OpSpec` records the wire contract verified against the live +OpenAPI metadata: HTTP method, ROA path template, and every parameter's +snake_case name, wire name, serialization kind and location. Array +parameters carry the metadata's ``style`` -- ``json`` (a JSON-stringified +value) for providers/capabilities/features/groupBy and the billing +objects, ``flat`` (``Client.query`` ``.N`` expansion) for StatusList and +the model-permission ``filter`` object. +""" + +from __future__ import annotations + +import json +from dataclasses import dataclass +from typing import Any, Dict, Optional, Tuple + +__all__ = ["READ_OPS", "OpSpec", "Param", "build_op_request"] + +SCALAR = "scalar" +BOOL = "bool" +JSON = "json" +FLAT = "flat" +QUERY = "query" +PATH = "path" + + +@dataclass(frozen=True) +class Param: + """One operation parameter's snake_case -> wire mapping.""" + + snake: str + wire: str + kind: str = SCALAR + location: str = QUERY + required: bool = False + + +@dataclass(frozen=True) +class OpSpec: + """A read op's wire contract and response payload location.""" + + action: str + method: str + path: str + params: Tuple[Param, ...] + # Response key holding the payload; ``None`` means the whole body. + data_field: Optional[str] + # "token" (nextToken), "page" (PageNo/PageNum) or "none". + pagination: str = "none" + + +def _p( + snake: str, + wire: str, + kind: str = SCALAR, + location: str = QUERY, + required: bool = False, +) -> Param: + return Param(snake, wire, kind, location, required) + + +_NEXT_TOKEN = _p("next_token", "nextToken") +_MAX_RESULTS = _p("max_results", "maxResults") +_WORKSPACE_ID = _p("workspace_id", "workspaceId") + + +READ_OPS: Dict[str, OpSpec] = { + "ListWorkspaces": OpSpec( + "ListWorkspaces", + "GET", + "/modelstudio/workspaces", + ( + _NEXT_TOKEN, + _MAX_RESULTS, + _p("workspace_name", "workspaceName"), + _WORKSPACE_ID, + ), + "workspaces", + "token", + ), + "ListModels": OpSpec( + "ListModels", + "GET", + "/modelstudio/models", + ( + _p("providers", "providers", JSON), + _p("capabilities", "capabilities", JSON), + _p("features", "features", JSON), + _p("language", "language"), + _p("context_window", "contextWindow"), + _p("name", "name"), + _p("model", "model"), + _NEXT_TOKEN, + _MAX_RESULTS, + ), + "models", + "token", + ), + "ListModelLimits": OpSpec( + "ListModelLimits", + "GET", + "/modelstudio/models/limits", + ( + _NEXT_TOKEN, + _MAX_RESULTS, + _WORKSPACE_ID, + _p("name", "name"), + _p("model", "model"), + ), + "limits", + "token", + ), + "ListModelPermissions": OpSpec( + "ListModelPermissions", + "GET", + "/modelstudio/models/permissions", + ( + _p("workspace_id", "workspaceId", SCALAR, QUERY, True), + _MAX_RESULTS, + _NEXT_TOKEN, + _p("authorization_scope", "authorizationScope"), + _p("model_action", "modelAction"), + _p("filter_", "filter", FLAT), + ), + "list", + "token", + ), + "ListApiKeys": OpSpec( + "ListApiKeys", + "GET", + "/modelstudio/apikeys", + ( + _NEXT_TOKEN, + _MAX_RESULTS, + _WORKSPACE_ID, + _p("api_key_id", "apiKeyId"), + _p("description", "description"), + _p("order_by", "orderBy"), + _p("order", "order"), + ), + "apiKeys", + "token", + ), + "GetApiKey": OpSpec( + "GetApiKey", + "GET", + "/modelstudio/apikeys/{apiKeyId}", + (_p("api_key_id", "apiKeyId", SCALAR, PATH, True),), + "apiKey", + ), + "GetBillingOverview": OpSpec( + "GetBillingOverview", + "GET", + "/modelstudio/billing/overview", + ( + _p("bill_month", "billMonth"), + _p("group_by", "groupBy", JSON), + _p("filter_", "filter", JSON), + _p("top_num", "topNum"), + _p("zero_filter", "zeroFilter", BOOL), + _p("region_id", "regionId"), + _p("locale", "locale"), + _p("granularity", "granularity"), + _p("time_period", "timePeriod", JSON), + ), + "data", + ), + "GetBillingTrend": OpSpec( + "GetBillingTrend", + "GET", + "/modelstudio/billing/trend", + ( + _p("granularity", "granularity"), + _p("time_period", "timePeriod", JSON), + _p("group_by", "groupBy", JSON), + _p("filter_", "filter", JSON), + _p("top_num", "topNum"), + _p("zero_filter", "zeroFilter", BOOL), + _p("include_history_period", "includeHistoryPeriod", BOOL), + _p("region_id", "regionId"), + _p("locale", "locale"), + ), + "data", + ), + "GetTokenPlanAccountDetail": OpSpec( + "GetTokenPlanAccountDetail", + "GET", + "/tokenplan/account", + (), + "Data", + ), + "ListOrganizationMembers": OpSpec( + "ListOrganizationMembers", + "GET", + "/tokenplan/organization/members", + ( + _p("name", "Name"), + _p("status", "Status"), + _p("has_seat", "HasSeat", BOOL), + _p("page_num", "PageNum"), + _p("page_size", "PageSize"), + ), + "Data", + "page", + ), + "GetSubscriptionSeatDetails": OpSpec( + "GetSubscriptionSeatDetails", + "GET", + "/tokenplan/subscription/seat-detail", + ( + _p("page_no", "PageNo"), + _p("page_size", "PageSize"), + _p("status_list", "StatusList", FLAT), + _p("seat_id", "SeatId"), + _p("seat_type", "SeatType"), + _p("query_assigned", "QueryAssigned", BOOL), + ), + "Data", + "page", + ), + "GetOrganizationMemberSeatStats": OpSpec( + "GetOrganizationMemberSeatStats", + "GET", + "/tokenplan/organization/member-seat-stats", + (), + None, + ), + "GetSubscriptionStats": OpSpec( + "GetSubscriptionStats", + "GET", + "/tokenplan/subscription/stats", + (), + "Data", + ), + "ListSubscriptionSharedPackages": OpSpec( + "ListSubscriptionSharedPackages", + "GET", + "/tokenplan/subscription/shared-packages", + ( + _p("page_no", "PageNo"), + _p("page_size", "PageSize"), + _p("status_list", "StatusList", FLAT), + ), + "Data", + "page", + ), +} + + +def build_op_request( + action: str, + **kwargs: Any, +) -> Tuple[str, str, Dict[str, Any]]: + """Map snake_case call kwargs to a wire ``(method, path, query)``. + + Path parameters are substituted into the ROA template (the signer + encodes the whole path once, so values go in raw). Query parameters + are split out and serialized per their metadata style. ``None`` + values are omitted; a missing required parameter raises ``ValueError`` + and an unknown keyword raises ``TypeError`` so a typo fails loudly + rather than silently dropping a filter. + """ + spec = READ_OPS[action] + known = {param.snake for param in spec.params} + unknown = set(kwargs) - known + if unknown: + raise TypeError( + f"unexpected parameter(s) for {action}: {sorted(unknown)}", + ) + path = spec.path + query: Dict[str, Any] = {} + for param in spec.params: + value = kwargs.get(param.snake) + if value is None: + if param.required: + raise ValueError(f"{action} requires '{param.snake}'") + continue + if param.location == PATH: + path = path.replace("{" + param.wire + "}", str(value)) + else: + query[param.wire] = _serialize(value, param.kind) + return spec.method, path, query + + +def _serialize(value: Any, kind: str) -> Any: + if kind == BOOL: + return "true" if value else "false" + if kind == JSON: + return json.dumps(value, ensure_ascii=False, separators=(",", ":")) + return value diff --git a/dashscope/management/_pagination.py b/dashscope/management/_pagination.py new file mode 100644 index 00000000..43ccd4f1 --- /dev/null +++ b/dashscope/management/_pagination.py @@ -0,0 +1,118 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Token (``nextToken``) pagination for the modelstudio list ops. + +The modelstudio lists answer with ``nextToken`` / ``maxResults`` / +``totalCount`` rather than the offset ``page_no`` / ``page_size`` the +tokenplan ops use, so they cannot ride :class:`BasePage`. :class:`TokenPage` +mirrors BasePage's traversal contract exactly -- one class serves both +clients, ``__iter__`` walks the current page's items, ``iter_pages`` +crosses pages -- so the two pagination styles feel identical to callers. + +The fetch callback is a ``PrivateAttr`` injected by the resource after +parsing; it never appears in ``model_dump()``. +""" + +from __future__ import annotations + +from typing import ( + Any, + AsyncIterator, + Callable, + Generic, + Iterator, + List, + Optional, + TypeVar, +) + +from pydantic import AliasChoices, ConfigDict, Field, PrivateAttr + +from dashscope.types.common import ResponseBase +from dashscope.types.pagination import ( + _reject_async_callback, + _reject_awaitable_page, +) + +__all__ = ["TokenPage"] + +T = TypeVar("T") + + +class TokenPage(ResponseBase, Generic[T]): + """One page of a ``nextToken``-paginated list, with traversal helpers.""" + + model_config = ConfigDict(extra="allow", populate_by_name=True) + + items: List[T] = Field(default_factory=list) + next_token: Optional[str] = Field( + None, + validation_alias=AliasChoices("next_token", "nextToken"), + ) + max_results: Optional[int] = Field( + None, + validation_alias=AliasChoices("max_results", "maxResults"), + ) + total_count: Optional[int] = Field( + None, + validation_alias=AliasChoices("total_count", "totalCount"), + ) + + _fetch_next: Optional[Callable[[str], Any]] = PrivateAttr(default=None) + + def bind_pagination( + self, + callback: Optional[Callable[[str], Any]], + ) -> "TokenPage[T]": + """Attach the ``(next_token) -> page`` fetch callback; returns self.""" + self._fetch_next = callback + return self + + def has_next_page(self) -> bool: + """Whether a ``nextToken`` and a fetch callback are both present.""" + return bool(self.next_token) and self._fetch_next is not None + + def next_page(self) -> Optional["TokenPage[T]"]: + """Fetch the following page, or ``None`` at the end of the list.""" + if not self.has_next_page() or self._fetch_next is None: + return None + _reject_async_callback(self._fetch_next) + return _reject_awaitable_page(self._fetch_next(self.next_token)) + + async def next_page_async(self) -> Optional["TokenPage[T]"]: + """Async :meth:`next_page`; awaits the callback when it is a coroutine.""" + if not self.has_next_page() or self._fetch_next is None: + return None + result = self._fetch_next(self.next_token) + if hasattr(result, "__await__"): + result = await result + return result + + def __iter__(self) -> Iterator[T]: + """Iterate this page's items only; use :meth:`iter_pages` to cross pages.""" + return iter(self.items) + + def __aiter__(self) -> AsyncIterator[T]: + """Async counterpart of :meth:`__iter__`: this page's items only.""" + + async def _gen() -> AsyncIterator[T]: + for item in self.items: + yield item + + return _gen() + + def iter_pages(self) -> Iterator["TokenPage[T]"]: + """Yield this page and every following one, advancing via ``next_page``.""" + if self._fetch_next is not None: + _reject_async_callback(self._fetch_next) + page: Optional["TokenPage[T]"] = self + while page is not None: + yield page + page = page.next_page() + + async def iter_pages_async(self) -> AsyncIterator["TokenPage[T]"]: + """Async :meth:`iter_pages`, advancing via ``next_page_async``.""" + page: Optional["TokenPage[T]"] = self + while page is not None: + yield page + page = await page.next_page_async() diff --git a/dashscope/management/_parse.py b/dashscope/management/_parse.py new file mode 100644 index 00000000..cf2c5588 --- /dev/null +++ b/dashscope/management/_parse.py @@ -0,0 +1,179 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Response parsing for the management read surface. + +Centralizes the success gate so no resource can accidentally feed a +healthy ``code: "200"`` into ``ResponseBase`` and have it flagged as an +error. :func:`resolve` reads the normalized envelope once; the builders +then construct the typed model from the payload (success) or an empty +payload carrying the error envelope (non-raising failure), and +:func:`attach_envelope` threads ``request_id`` / ``status_code`` / +``headers`` uniformly. Models are built through the shared fault-tolerant +:func:`~dashscope.types._parse.parse_model`. +""" + +from __future__ import annotations + +from typing import Any, Callable, Dict, List, Optional, Tuple, Type, TypeVar + +import httpx +from pydantic import BaseModel + +from dashscope.management._errors import ( + Envelope, + decode_body, + management_error, + read_envelope, +) +from dashscope.management._pagination import TokenPage +from dashscope.transport._response import APIResponse +from dashscope.types._parse import parse_model +from dashscope.types.common import with_headers +from dashscope.types.pagination import BasePage + +__all__ = [ + "attach_envelope", + "parse_base_page", + "parse_one", + "parse_token_page", + "resolve", +] + +_M = TypeVar("_M", bound=BaseModel) +_T = TypeVar("_T") + + +def resolve( + api_response: APIResponse, + *, + raise_on_error: bool, +) -> Tuple[Envelope, Dict[str, Any], Optional[Any]]: + """Return ``(envelope, body, error)``; raise on failure when asked. + + ``error`` is ``None`` on success. In non-raising mode a failure yields + the crosswalked error so the builder can fold it into the model. + """ + response = api_response.http_response + body = decode_body(response) + envelope = read_envelope(body, response.status_code) + if envelope.success: + return envelope, body, None + error = management_error(envelope, response.headers) + if raise_on_error: + raise error + return envelope, body, error + + +def attach_envelope( + model: _M, + envelope: Envelope, + response: httpx.Response, + error: Optional[Any], +) -> _M: + """Thread envelope fields and headers onto a parsed model.""" + if error is not None: + model.code = envelope.code + model.message = envelope.message + model.is_error = True + if envelope.request_id: + model.request_id = envelope.request_id + model.status_code = envelope.status_code + return with_headers(model, response) + + +def parse_one( + cls: Type[_M], + api_response: APIResponse, + *, + data_field: Optional[str], + strict: bool, + raise_on_error: bool, +) -> _M: + """Parse a single-object response into ``cls``.""" + envelope, body, error = resolve( + api_response, + raise_on_error=raise_on_error, + ) + response = api_response.http_response + if error is not None: + model = parse_model(cls, {}, strict=strict, response=response) + else: + payload = body if data_field is None else body.get(data_field) + data = payload if isinstance(payload, dict) else {} + model = parse_model(cls, data, strict=strict, response=response) + return attach_envelope(model, envelope, response, error) + + +def parse_token_page( + item_cls: Type[_T], + api_response: APIResponse, + *, + data_field: str, + strict: bool, + raise_on_error: bool, + fetch_next: Optional[Callable[[str], Any]] = None, +) -> TokenPage[_T]: + """Parse a ``nextToken`` list response into a bound ``TokenPage``.""" + envelope, body, error = resolve( + api_response, + raise_on_error=raise_on_error, + ) + response = api_response.http_response + page_cls = TokenPage[item_cls] # type: ignore[valid-type] + if error is not None: + page = parse_model(page_cls, {}, strict=strict, response=response) + else: + payload = body.get(data_field) + flat = { + "items": payload if isinstance(payload, list) else [], + "next_token": body.get("nextToken"), + "max_results": body.get("maxResults"), + "total_count": body.get("totalCount"), + } + page = parse_model(page_cls, flat, strict=strict, response=response) + page = attach_envelope(page, envelope, response, error) + if fetch_next is not None: + page.bind_pagination(fetch_next) + return page + + +def parse_base_page( + page_cls: Type[BasePage], + api_response: APIResponse, + *, + items_field: str, + items: List[Any], + page_no: int, + page_size: int, + total_count: int, + strict: bool, + raise_on_error: bool, + fetch_next: Optional[Callable[[int, int], Any]] = None, + requested_no: Optional[int] = None, + requested_size: Optional[int] = None, +) -> BasePage: + """Parse an offset (``PageNo``/``PageNum``) list into a ``BasePage``. + + The resource extracts ``items`` and the pagination integers from the + body (the tokenplan ops disagree on whether they sit at the root or + under ``Data``) and hands them here normalized. + """ + envelope, _body, error = resolve( + api_response, + raise_on_error=raise_on_error, + ) + response = api_response.http_response + if error is not None: + page = parse_model(page_cls, {}, strict=strict, response=response) + else: + flat = { + items_field: items, + "page_no": page_no, + "page_size": page_size, + "total_count": total_count, + } + page = parse_model(page_cls, flat, strict=strict, response=response) + page = attach_envelope(page, envelope, response, error) + if fetch_next is not None: + page.bind_pagination(fetch_next, requested_no, requested_size) + return page diff --git a/dashscope/management/_redaction.py b/dashscope/management/_redaction.py new file mode 100644 index 00000000..23dc9e13 --- /dev/null +++ b/dashscope/management/_redaction.py @@ -0,0 +1,100 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Secret redaction for the management surface. + +Read ops here are not secret-free: ``ListApiKeys`` / ``GetApiKey`` return +the plaintext ``apiKeyValue``. The typed models hold it in a pydantic +``SecretStr`` (masked in ``repr`` / ``model_dump``), but two paths bypass +that field type -- the raw error body attached to an exception, and log +records formatted from a response dict. This module scrubs both so a +key value never reaches a log line, a traceback, or ``err.body``. +""" + +from __future__ import annotations + +import logging +from typing import Any + +__all__ = [ + "REDACTED", + "SecretRedactionFilter", + "mask_secret", + "redact_body", +] + +REDACTED = "***" + +# Lowercased wire keys whose values are credentials. Matched +# case-insensitively so both the modelstudio (``apiKeyValue``) and the +# aliyun gateway (``AccessKeySecret``) spellings are caught. +_SECRET_KEYS = frozenset( + { + "apikeyvalue", + "accesskeysecret", + "accesskeyid", + "securitytoken", + "bearertoken", + "password", + "secret", + }, +) + + +def mask_secret(secret: str) -> str: + """A log-safe rendering of a secret: ``***`` plus its last 4 chars. + + The tail is enough to tell two keys apart in a support ticket without + exposing the credential. Anything shorter than 8 chars is fully + masked -- a short secret has no safe suffix to show. + """ + if not secret or len(secret) < 8: + return REDACTED + return f"{REDACTED}{secret[-4:]}" + + +def redact_body(body: Any) -> Any: + """A deep copy of ``body`` with credential-key values replaced. + + Non-dict/list values pass through untouched; the original is never + mutated, so the caller's parsed model keeps its real ``SecretStr`` + while the error/log copy is safe to print. + """ + if isinstance(body, dict): + return { + key: ( + REDACTED + if str(key).lower() in _SECRET_KEYS + else redact_body(value) + ) + for key, value in body.items() + } + if isinstance(body, list): + return [redact_body(item) for item in body] + return body + + +class SecretRedactionFilter(logging.Filter): + """Scrub credential-looking tokens from a management log record. + + Key-oriented redaction (``redact_body``) cannot catch a secret that + was interpolated into a free-text message, so this filter also masks + ``sk-`` prefixed API key values wherever they appear in the formatted + record. Attached to the management logger only. + """ + + def filter(self, record: logging.LogRecord) -> bool: + message = record.getMessage() + if "sk-" in message: + record.msg = _mask_sk_tokens(message) + record.args = () + return True + + +def _mask_sk_tokens(message: str) -> str: + out = [] + for token in message.split(" "): + if token.startswith("sk-") and len(token) > 7: + out.append(mask_secret(token)) + else: + out.append(token) + return " ".join(out) diff --git a/dashscope/management/_resource.py b/dashscope/management/_resource.py new file mode 100644 index 00000000..aee9b273 --- /dev/null +++ b/dashscope/management/_resource.py @@ -0,0 +1,95 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Shared resource plumbing for the management read surface. + +Each resource holds the client and routes its calls through the atomic +op registry: snake_case kwargs become a wire ``(method, path, query)`` +via :func:`build_op_request`, then the client's transport signs and sends +it. Keeping this in one place means the sync and async resources differ +only in ``await``. +""" + +from __future__ import annotations + +from typing import Any, Dict, Mapping, Optional + +from dashscope.management._ops import build_op_request +from dashscope.transport._options import RequestOptions +from dashscope.transport._response import APIResponse + +__all__ = ["AsyncResource", "SyncResource", "options_kwargs"] + + +def options_kwargs( + timeout: Optional[float], + extra_headers: Optional[Mapping[str, str]], + extra_query: Optional[Mapping[str, Any]], + extra_body: Optional[Mapping[str, Any]], + max_retries: Optional[int], +) -> Dict[str, Any]: + """Bundle the common per-call option tail for forwarding to pagination.""" + return { + "timeout": timeout, + "extra_headers": extra_headers, + "extra_query": extra_query, + "extra_body": extra_body, + "max_retries": max_retries, + } + + +class SyncResource: + def __init__(self, client: Any) -> None: + self._client = client + + def _request( + self, + action: str, + filters: Mapping[str, Any], + options: Optional[RequestOptions], + ) -> APIResponse: + method, path, query = build_op_request(action, **dict(filters)) + return self._client.transport.request_api( + method, + path, + action=action, + params=query, + options=options, + client=self._client, + ) + + @property + def _strict(self) -> bool: + return self._client.config.strict_validation + + @property + def _raise_on_error(self) -> bool: + return self._client.raise_on_error + + +class AsyncResource: + def __init__(self, client: Any) -> None: + self._client = client + + async def _request( + self, + action: str, + filters: Dict[str, Any], + options: Optional[RequestOptions], + ) -> APIResponse: + method, path, query = build_op_request(action, **dict(filters)) + return await self._client.transport.request_api( + method, + path, + action=action, + params=query, + options=options, + client=self._client, + ) + + @property + def _strict(self) -> bool: + return self._client.config.strict_validation + + @property + def _raise_on_error(self) -> bool: + return self._client.raise_on_error diff --git a/dashscope/management/_signer.py b/dashscope/management/_signer.py new file mode 100644 index 00000000..391bd9ce --- /dev/null +++ b/dashscope/management/_signer.py @@ -0,0 +1,138 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""ACS3-HMAC-SHA256 (V3, ROA) request signing for the management surface. + +Delegates the cryptographic canonicalization to the official +``alibabacloud_openapi_util`` client so the signature matches what the +aliyun gateway recomputes. Two invariants make that hold: + +* the signed header set is exactly the sent header set -- the SDK + identity headers (``x-dashscope-sdk-client: python-sdk//management2`` + and friends) are folded in *before* signing, not appended after; +* the canonical query string is also the wire query string, so a + ``nextToken`` carrying ``=``/``+``/``/`` is encoded identically on both + sides instead of drifting between httpx's default quoting and the + signer's ``quote(safe='~')``. +""" + +from __future__ import annotations + +import hashlib +import uuid +from dataclasses import dataclass +from datetime import datetime, timezone +from types import SimpleNamespace +from typing import Any, Dict, Mapping, Optional + +from alibabacloud_openapi_util.client import Client as _OpenApiUtil +from alibabacloud_openapi_util.client import ( + get_canonical_query_string as _canonical_query_string, +) + +from dashscope.management._credentials import ResolvedCredential + +__all__ = ["API_VERSION", "SIGN_TYPE", "SignedRequest", "sign_request"] + +SIGN_TYPE = "ACS3-HMAC-SHA256" +API_VERSION = "2026-02-10" + + +@dataclass(frozen=True) +class SignedRequest: + """A fully signed request ready for httpx to send verbatim.""" + + method: str + url: str + headers: Dict[str, str] + content: Optional[bytes] + + +def sign_request( + *, + method: str, + host: str, + path: str, + action: str, + query: Optional[Mapping[str, Any]], + body: Optional[bytes], + credential: ResolvedCredential, + user_agent: str, + sdk_headers: Mapping[str, str], + extra_headers: Optional[Mapping[str, str]] = None, +) -> SignedRequest: + """Sign one management request and return its wire form. + + ``extra_headers`` are merged in *before* signing (caller wins over the + defaults), so the signed header set stays equal to the sent set. + """ + payload = body or b"" + payload_hex = hashlib.sha256(payload).hexdigest() + flat_query = _OpenApiUtil.query(_normalize_query(query)) + canonical_query = _canonical_query_string(flat_query) + encoded_path = _OpenApiUtil.get_encode_path(path) + + headers = { + "host": host, + "x-acs-version": API_VERSION, + "x-acs-action": action, + "x-acs-date": _utc_timestamp(), + "x-acs-signature-nonce": uuid.uuid4().hex, + "x-acs-content-sha256": payload_hex, + "accept": "application/json", + "user-agent": user_agent, + } + if body is not None: + headers["content-type"] = "application/json" + if credential.security_token: + headers["x-acs-security-token"] = credential.security_token + headers["x-acs-accesskey-id"] = credential.access_key_id + if credential.provider_name: + headers["x-acs-credentials-provider"] = credential.provider_name + headers.update(sdk_headers) + if extra_headers: + headers.update({k.lower(): v for k, v in extra_headers.items()}) + + shim = SimpleNamespace( + method=method.upper(), + pathname=encoded_path, + query=flat_query, + headers=headers, + ) + headers["authorization"] = _OpenApiUtil.get_authorization( + shim, + SIGN_TYPE, + payload_hex, + credential.access_key_id, + credential.access_key_secret, + ) + url = f"https://{host}{encoded_path}" + if canonical_query: + url = f"{url}?{canonical_query}" + return SignedRequest(method.upper(), url, headers, body) + + +def _utc_timestamp() -> str: + return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + + +def _normalize_query( + query: Optional[Mapping[str, Any]], +) -> Dict[str, Any]: + """Lowercase booleans so ``Client.query`` does not emit ``True``. + + ``Client.query`` stringifies scalars with ``str()``, which renders a + Python bool as ``True``/``False``; the gateway expects ``true``/ + ``false``. JSON-style arrays arrive pre-serialized as strings and + flat-style arrays as lists, both left for ``Client.query`` to flatten. + """ + if not query: + return {} + return {key: _normalize_value(value) for key, value in query.items()} + + +def _normalize_value(value: Any) -> Any: + if isinstance(value, bool): + return "true" if value else "false" + if isinstance(value, list): + return [_normalize_value(item) for item in value] + return value diff --git a/dashscope/management/_transport.py b/dashscope/management/_transport.py new file mode 100644 index 00000000..6f69253c --- /dev/null +++ b/dashscope/management/_transport.py @@ -0,0 +1,354 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""httpx sync/async transports for the management (RAM OpenAPI) surface. + +A sibling of ``transport/http.py`` rather than a subclass: the management +gateway signs every request with ACS3-HMAC-SHA256 instead of carrying a +Bearer token, and the signed header set must equal the sent set, so the +header assembly and retry loop are owned here. The retry/backoff policy, +per-request options channel and ``APIResponse`` wrapper are reused +unchanged from the v2 transport. + +Reads retry transparently (default ``max_retries=2``). One client request +id is minted per logical request and reused across attempts; each attempt +re-signs with a fresh date/nonce and a freshly resolved credential, so an +STS token that expired between attempts is refreshed by the chain. +""" + +from __future__ import annotations + +import asyncio +import json +import time +from typing import Any, Mapping, Optional, Union + +import httpx + +from dashscope._config import DEFAULT_TIMEOUT +from dashscope._logging import get_logger +from dashscope.errors import ( + APIConnectionError, + APITimeoutError, + DashScopeError, +) +from dashscope.management._credentials import CredentialResolver +from dashscope.management._signer import sign_request +from dashscope.transport import _ident +from dashscope.transport._options import ( + RequestOptions, + deep_merge, + merge_query, + resolve_max_retries, + resolve_timeout, +) +from dashscope.transport._response import APIResponse +from dashscope.transport._retry import backoff_delay, should_retry +from dashscope.transport.http import default_user_agent + +__all__ = ["AsyncTransport", "SyncTransport"] + +logger = get_logger("management.transport") + +_MODULE = "management" +_DEFAULT_CONNECT_TIMEOUT = 5.0 + + +def _resolve_timeout( + timeout: Union[float, httpx.Timeout, None], + default: float, +) -> httpx.Timeout: + if isinstance(timeout, httpx.Timeout): + return timeout + value = default if timeout is None else timeout + return httpx.Timeout(value, connect=_DEFAULT_CONNECT_TIMEOUT) + + +def _map_transport_error( + exc: httpx.TransportError, + request_id: Optional[str], +) -> DashScopeError: + if isinstance(exc, httpx.TimeoutException): + return APITimeoutError(detail=str(exc), request_id=request_id) + return APIConnectionError(detail=str(exc), request_id=request_id) + + +def _encode_body( + body: Optional[Mapping[str, Any]], + options: Optional[RequestOptions], +) -> Optional[bytes]: + merged: Optional[Mapping[str, Any]] = body + if options is not None and options.extra_body: + merged = deep_merge(body or {}, options.extra_body) + if merged is None: + return None + return json.dumps( + merged, + ensure_ascii=False, + separators=(",", ":"), + ).encode("utf-8") + + +class _Transport: + """Shared configuration and request preparation for both clients.""" + + def __init__( + self, + *, + region: str, + resolver: CredentialResolver, + endpoint: Optional[str] = None, + user_agent: Optional[str] = None, + timeout: Union[float, httpx.Timeout, None] = None, + max_retries: int = 2, + limits: Optional[httpx.Limits] = None, + ) -> None: + self._host = endpoint or f"modelstudio.{region}.aliyuncs.com" + self._resolver = resolver + self._user_agent = user_agent or default_user_agent(_MODULE) + self._timeout = _resolve_timeout(timeout, DEFAULT_TIMEOUT) + self._max_retries = max(max_retries, 0) + self._limits = limits + + @property + def host(self) -> str: + return self._host + + def _prepare( + self, + method: str, + path: str, + *, + action: str, + params: Optional[Mapping[str, Any]], + body: Optional[Mapping[str, Any]], + options: Optional[RequestOptions], + ) -> dict: + client_request_id = _ident.client_request_id() + return { + "method": method, + "path": path, + "action": action, + "client_request_id": client_request_id, + "sdk": _ident.sdk_headers(_MODULE, client_request_id), + "max_retries": resolve_max_retries(self._max_retries, options), + "params": merge_query(params, options), + "content": _encode_body(body, options), + "extra_headers": ( + options.extra_headers if options is not None else None + ), + "timeout": resolve_timeout(self._timeout, options), + } + + def _build_request( + self, + prep: dict, + credential: Any, + http_client: Any, + ) -> httpx.Request: + signed = sign_request( + method=prep["method"], + host=self._host, + path=prep["path"], + action=prep["action"], + query=prep["params"], + body=prep["content"], + credential=credential, + user_agent=self._user_agent, + sdk_headers=prep["sdk"], + extra_headers=prep["extra_headers"], + ) + return http_client.build_request( + signed.method, + signed.url, + headers=signed.headers, + content=signed.content, + timeout=prep["timeout"], + ) + + +class SyncTransport(_Transport): + def __init__( + self, + *, + http_client: Optional[httpx.Client] = None, + **kwargs: Any, + ) -> None: + super().__init__(**kwargs) + self._owns_client = http_client is None + self._client = http_client or httpx.Client( + timeout=self._timeout, + **({"limits": self._limits} if self._limits is not None else {}), + ) + + @property + def http_client(self) -> httpx.Client: + return self._client + + def request( + self, + method: str, + path: str, + *, + action: str, + params: Optional[Mapping[str, Any]] = None, + body: Optional[Mapping[str, Any]] = None, + options: Optional[RequestOptions] = None, + ) -> httpx.Response: + prep = self._prepare( + method, + path, + action=action, + params=params, + body=body, + options=options, + ) + max_retries = prep["max_retries"] + response = None + for attempt in range(max_retries + 1): + credential = self._resolver.resolve() + request = self._build_request(prep, credential, self._client) + try: + response = self._client.send(request, stream=True) + try: + response.read() + finally: + response.close() + except httpx.TransportError as exc: + if attempt >= max_retries: + raise _map_transport_error( + exc, + prep["client_request_id"], + ) from exc + time.sleep(backoff_delay(attempt, None)) + continue + if not should_retry(response.status_code, response.headers): + return response + if attempt >= max_retries: + return response + time.sleep(backoff_delay(attempt, response.headers)) + return response + + def request_api( + self, + method: str, + path: str, + *, + action: str, + params: Optional[Mapping[str, Any]] = None, + body: Optional[Mapping[str, Any]] = None, + options: Optional[RequestOptions] = None, + client: Any = None, + ) -> APIResponse: + response = self.request( + method, + path, + action=action, + params=params, + body=body, + options=options, + ) + return APIResponse(response, client=client) + + def close(self) -> None: + if self._owns_client: + self._client.close() + + def __enter__(self) -> "SyncTransport": + return self + + def __exit__(self, *args: Any) -> None: + self.close() + + +class AsyncTransport(_Transport): + def __init__( + self, + *, + http_client: Optional[httpx.AsyncClient] = None, + **kwargs: Any, + ) -> None: + super().__init__(**kwargs) + self._owns_client = http_client is None + self._client = http_client or httpx.AsyncClient( + timeout=self._timeout, + **({"limits": self._limits} if self._limits is not None else {}), + ) + + @property + def http_client(self) -> httpx.AsyncClient: + return self._client + + async def request( + self, + method: str, + path: str, + *, + action: str, + params: Optional[Mapping[str, Any]] = None, + body: Optional[Mapping[str, Any]] = None, + options: Optional[RequestOptions] = None, + ) -> httpx.Response: + prep = self._prepare( + method, + path, + action=action, + params=params, + body=body, + options=options, + ) + max_retries = prep["max_retries"] + response = None + for attempt in range(max_retries + 1): + credential = await self._resolver.resolve_async() + request = self._build_request(prep, credential, self._client) + try: + response = await self._client.send(request, stream=True) + try: + await response.aread() + finally: + await response.aclose() + except httpx.TransportError as exc: + if attempt >= max_retries: + raise _map_transport_error( + exc, + prep["client_request_id"], + ) from exc + await asyncio.sleep(backoff_delay(attempt, None)) + continue + if not should_retry(response.status_code, response.headers): + return response + if attempt >= max_retries: + return response + await asyncio.sleep(backoff_delay(attempt, response.headers)) + return response + + async def request_api( + self, + method: str, + path: str, + *, + action: str, + params: Optional[Mapping[str, Any]] = None, + body: Optional[Mapping[str, Any]] = None, + options: Optional[RequestOptions] = None, + client: Any = None, + ) -> APIResponse: + response = await self.request( + method, + path, + action=action, + params=params, + body=body, + options=options, + ) + return APIResponse(response, client=client) + + async def aclose(self) -> None: + if self._owns_client: + await self._client.aclose() + + async def __aenter__(self) -> "AsyncTransport": + return self + + async def __aexit__(self, *args: Any) -> None: + await self.aclose() diff --git a/dashscope/management/api_keys.py b/dashscope/management/api_keys.py new file mode 100644 index 00000000..392d6b32 --- /dev/null +++ b/dashscope/management/api_keys.py @@ -0,0 +1,354 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""``client.api_keys`` -- list and inspect workspace API keys. + +Read-only (G2). Even these read ops return the plaintext key value, so +``ApiKey.api_key_value`` is a ``SecretStr``: it is masked in ``repr``, +``model_dump`` and logs, and only ``.get_secret_value()`` reveals it. +Write ops (CreateApiKey / UpdateApiKey / EnableApiKey / DisableApiKey) and +the destructive ResetApiKey / DeleteApiKey are high-risk and deferred to +G3 / G4 -- not implemented here. +""" + +from __future__ import annotations + +from typing import ( + TYPE_CHECKING, + Any, + Literal, + Mapping, + Optional, + Union, + overload, +) + +from dashscope.management._pagination import TokenPage +from dashscope.management._parse import parse_one, parse_token_page +from dashscope.management._resource import ( + AsyncResource, + SyncResource, + options_kwargs, +) +from dashscope.management.types import ApiKey +from dashscope.transport._options import request_options + +if TYPE_CHECKING: + from dashscope.transport._response import APIResponse + +__all__ = ["ApiKeys", "AsyncApiKeys"] + + +class ApiKeys(SyncResource): + @overload + def list( + self, + *, + workspace_id: Optional[str] = None, + api_key_id: Optional[int] = None, + description: Optional[str] = None, + order_by: Optional[str] = None, + order: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPage[ApiKey]: + ... + + @overload + def list( + self, + *, + workspace_id: Optional[str] = None, + api_key_id: Optional[int] = None, + description: Optional[str] = None, + order_by: Optional[str] = None, + order: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + workspace_id: Optional[str] = None, + api_key_id: Optional[int] = None, + description: Optional[str] = None, + order_by: Optional[str] = None, + order: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPage[ApiKey], "APIResponse"]: + """List API keys; ``api_key_value`` is masked on each entry.""" + filters = { + "workspace_id": workspace_id, + "api_key_id": api_key_id, + "description": description, + "order_by": order_by, + "order": order, + "next_token": next_token, + "max_results": max_results, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request("ListApiKeys", filters, request_options(**opts)) + if raw: + return resp + + def fetch(token: str) -> TokenPage[ApiKey]: + return self.list( # type: ignore[call-overload] + **{**filters, "next_token": token}, + **opts, + ) + + return parse_token_page( + ApiKey, + resp, + data_field="apiKeys", + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + ) + + @overload + def get( + self, + api_key_id: int, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> ApiKey: + ... + + @overload + def get( + self, + api_key_id: int, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def get( + self, + api_key_id: int, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ApiKey, "APIResponse"]: + """Fetch one API key by id; ``api_key_value`` stays masked.""" + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "GetApiKey", + {"api_key_id": api_key_id}, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + ApiKey, + resp, + data_field="apiKey", + strict=self._strict, + raise_on_error=self._raise_on_error, + ) + + +class AsyncApiKeys(AsyncResource): + @overload + async def list( + self, + *, + workspace_id: Optional[str] = None, + api_key_id: Optional[int] = None, + description: Optional[str] = None, + order_by: Optional[str] = None, + order: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPage[ApiKey]: + ... + + @overload + async def list( + self, + *, + workspace_id: Optional[str] = None, + api_key_id: Optional[int] = None, + description: Optional[str] = None, + order_by: Optional[str] = None, + order: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + workspace_id: Optional[str] = None, + api_key_id: Optional[int] = None, + description: Optional[str] = None, + order_by: Optional[str] = None, + order: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPage[ApiKey], "APIResponse"]: + filters = { + "workspace_id": workspace_id, + "api_key_id": api_key_id, + "description": description, + "order_by": order_by, + "order": order, + "next_token": next_token, + "max_results": max_results, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "ListApiKeys", + filters, + request_options(**opts), + ) + if raw: + return resp + + async def fetch(token: str) -> TokenPage[ApiKey]: + return await self.list( # type: ignore[call-overload] + **{**filters, "next_token": token}, + **opts, + ) + + return parse_token_page( + ApiKey, + resp, + data_field="apiKeys", + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + ) + + @overload + async def get( + self, + api_key_id: int, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> ApiKey: + ... + + @overload + async def get( + self, + api_key_id: int, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def get( + self, + api_key_id: int, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ApiKey, "APIResponse"]: + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "GetApiKey", + {"api_key_id": api_key_id}, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + ApiKey, + resp, + data_field="apiKey", + strict=self._strict, + raise_on_error=self._raise_on_error, + ) diff --git a/dashscope/management/billing.py b/dashscope/management/billing.py new file mode 100644 index 00000000..8097a941 --- /dev/null +++ b/dashscope/management/billing.py @@ -0,0 +1,424 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""``client.billing`` -- cost overview and trend (read-only, G2). + +Only the two read ops are implemented; there is no purchase / renewal / +payment surface here. ``group_by`` is a JSON-style array and ``filter`` / +``time_period`` are JSON-style objects on the wire. +""" + +from __future__ import annotations + +from typing import ( + TYPE_CHECKING, + Any, + Literal, + Mapping, + Optional, + Union, + overload, +) + +from dashscope.management._parse import parse_one +from dashscope.management._resource import ( + AsyncResource, + SyncResource, + options_kwargs, +) +from dashscope.management.types import BillingOverview, BillingTrend +from dashscope.transport._options import request_options + +if TYPE_CHECKING: + from dashscope.transport._response import APIResponse + +__all__ = ["AsyncBilling", "Billing"] + + +class Billing(SyncResource): + @overload + def overview( + self, + *, + bill_month: Optional[str] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BillingOverview: + ... + + @overload + def overview( + self, + *, + bill_month: Optional[str] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def overview( + self, + *, + bill_month: Optional[str] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BillingOverview, "APIResponse"]: + """Cost overview for a billing month, optionally grouped TopN.""" + filters = { + "bill_month": bill_month, + "group_by": group_by, + "filter_": filter_, + "top_num": top_num, + "zero_filter": zero_filter, + "region_id": region_id, + "locale": locale, + "granularity": granularity, + "time_period": time_period, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "GetBillingOverview", + filters, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + BillingOverview, + resp, + data_field="data", + strict=self._strict, + raise_on_error=self._raise_on_error, + ) + + @overload + def trend( + self, + *, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + include_history_period: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BillingTrend: + ... + + @overload + def trend( + self, + *, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + include_history_period: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def trend( + self, + *, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + include_history_period: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BillingTrend, "APIResponse"]: + """Cost trend over time, optionally grouped and with history.""" + filters = { + "granularity": granularity, + "time_period": time_period, + "group_by": group_by, + "filter_": filter_, + "top_num": top_num, + "zero_filter": zero_filter, + "include_history_period": include_history_period, + "region_id": region_id, + "locale": locale, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "GetBillingTrend", + filters, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + BillingTrend, + resp, + data_field="data", + strict=self._strict, + raise_on_error=self._raise_on_error, + ) + + +class AsyncBilling(AsyncResource): + @overload + async def overview( + self, + *, + bill_month: Optional[str] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BillingOverview: + ... + + @overload + async def overview( + self, + *, + bill_month: Optional[str] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def overview( + self, + *, + bill_month: Optional[str] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BillingOverview, "APIResponse"]: + filters = { + "bill_month": bill_month, + "group_by": group_by, + "filter_": filter_, + "top_num": top_num, + "zero_filter": zero_filter, + "region_id": region_id, + "locale": locale, + "granularity": granularity, + "time_period": time_period, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "GetBillingOverview", + filters, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + BillingOverview, + resp, + data_field="data", + strict=self._strict, + raise_on_error=self._raise_on_error, + ) + + @overload + async def trend( + self, + *, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + include_history_period: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BillingTrend: + ... + + @overload + async def trend( + self, + *, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + include_history_period: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def trend( + self, + *, + granularity: Optional[str] = None, + time_period: Optional[Mapping[str, Any]] = None, + group_by: Optional[Any] = None, + filter_: Optional[Mapping[str, Any]] = None, + top_num: Optional[int] = None, + zero_filter: Optional[bool] = None, + include_history_period: Optional[bool] = None, + region_id: Optional[str] = None, + locale: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BillingTrend, "APIResponse"]: + filters = { + "granularity": granularity, + "time_period": time_period, + "group_by": group_by, + "filter_": filter_, + "top_num": top_num, + "zero_filter": zero_filter, + "include_history_period": include_history_period, + "region_id": region_id, + "locale": locale, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "GetBillingTrend", + filters, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + BillingTrend, + resp, + data_field="data", + strict=self._strict, + raise_on_error=self._raise_on_error, + ) diff --git a/dashscope/management/client.py b/dashscope/management/client.py new file mode 100644 index 00000000..47ad3472 --- /dev/null +++ b/dashscope/management/client.py @@ -0,0 +1,293 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""``ManagementClient`` / ``AsyncManagementClient`` -- the RAM OpenAPI client. + +The ToB integration entry point: a backend service constructs one client +per tenant credential (AK/SK, STS, RAM role, OIDC, or the default chain) +and reaches workspace / API-key / billing / TokenPlan management without +logging into the aliyun console. This revision is read-only (G1/G2/G5); +write ops are high-risk and deferred. + +The client is region-bound (``modelstudio.{region}.aliyuncs.com``); +``with_options(region=...)`` derives a new client with its own connection +pool for cross-region calls. Region strings are validated as safe DNS +labels; an unknown-but-safe region warns rather than hard-fails, leaving +custom endpoints usable. +""" + +from __future__ import annotations + +import re +from dataclasses import dataclass +from typing import Any, Mapping, Optional, Union + +import httpx + +from dashscope._logging import get_logger +from dashscope.management._credentials import CredentialResolver +from dashscope.management._transport import AsyncTransport, SyncTransport +from dashscope.management.api_keys import ApiKeys, AsyncApiKeys +from dashscope.management.billing import AsyncBilling, Billing +from dashscope.management.token_plan import AsyncTokenPlan, TokenPlan +from dashscope.management.workspaces import AsyncWorkspaces, Workspaces + +__all__ = ["AsyncManagementClient", "ManagementClient", "ManagementConfig"] + +logger = get_logger("management.client") + +DEFAULT_REGION = "cn-beijing" +KNOWN_REGIONS = frozenset( + { + "cn-beijing", + "cn-hongkong", + "ap-southeast-1", + "us-east-1", + "eu-central-1", + }, +) +_REGION_LABEL = re.compile(r"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$") + + +def _validate_region(region: str) -> None: + if not _REGION_LABEL.match(region): + raise ValueError( + f"invalid region {region!r}: expected a DNS label like 'cn-beijing'", + ) + if region not in KNOWN_REGIONS: + logger.warning( + "region %r is not a known ModelStudio region; using it as given " + "(endpoint modelstudio.%s.aliyuncs.com)", + region, + region, + ) + + +@dataclass(frozen=True) +class ManagementConfig: + """Immutable client settings, read by resources and ``with_options``.""" + + region: str = DEFAULT_REGION + endpoint: Optional[str] = None + raise_on_error: bool = True + strict_validation: bool = False + timeout: Union[float, httpx.Timeout, None] = None + max_retries: int = 2 + user_agent: Optional[str] = None + + +class ManagementClient: + """Synchronous RAM management client (read-only).""" + + def __init__( + self, + *, + access_key_id: Optional[str] = None, + access_key_secret: Optional[str] = None, + security_token: Optional[str] = None, + region: str = DEFAULT_REGION, + credential: Optional[Any] = None, + config: Optional[Mapping[str, Any]] = None, + endpoint: Optional[str] = None, + timeout: Union[float, httpx.Timeout, None] = None, + max_retries: int = 2, + http_client: Optional[httpx.Client] = None, + user_agent: Optional[str] = None, + raise_on_error: bool = True, + strict_validation: bool = False, + limits: Optional[httpx.Limits] = None, + _resolver: Optional[CredentialResolver] = None, + ) -> None: + _validate_region(region) + self._resolver = _resolver or CredentialResolver( + access_key_id=access_key_id, + access_key_secret=access_key_secret, + security_token=security_token, + credential=credential, + config=config, + ) + self.config = ManagementConfig( + region=region, + endpoint=endpoint, + raise_on_error=raise_on_error, + strict_validation=strict_validation, + timeout=timeout, + max_retries=max_retries, + user_agent=user_agent, + ) + self._transport = SyncTransport( + region=region, + resolver=self._resolver, + endpoint=endpoint, + user_agent=user_agent, + timeout=timeout, + max_retries=max_retries, + http_client=http_client, + limits=limits, + ) + self.workspaces = Workspaces(self) + self.api_keys = ApiKeys(self) + self.billing = Billing(self) + self.token_plan = TokenPlan(self) + + @property + def transport(self) -> SyncTransport: + return self._transport + + @property + def region(self) -> str: + return self.config.region + + @property + def raise_on_error(self) -> bool: + return self.config.raise_on_error + + def with_options( + self, + *, + region: Optional[str] = None, + endpoint: Optional[str] = None, + timeout: Union[float, httpx.Timeout, None] = None, + max_retries: Optional[int] = None, + raise_on_error: Optional[bool] = None, + strict_validation: Optional[bool] = None, + ) -> "ManagementClient": + """Derive a new client (own connection pool) sharing the credential.""" + cfg = self.config + return ManagementClient( + _resolver=self._resolver, + region=region if region is not None else cfg.region, + endpoint=endpoint if endpoint is not None else cfg.endpoint, + timeout=timeout if timeout is not None else cfg.timeout, + max_retries=( + max_retries if max_retries is not None else cfg.max_retries + ), + user_agent=cfg.user_agent, + raise_on_error=( + raise_on_error + if raise_on_error is not None + else cfg.raise_on_error + ), + strict_validation=( + strict_validation + if strict_validation is not None + else cfg.strict_validation + ), + ) + + def close(self) -> None: + self._transport.close() + + def __enter__(self) -> "ManagementClient": + return self + + def __exit__(self, *args: Any) -> None: + self.close() + + +class AsyncManagementClient: + """Asynchronous RAM management client (read-only).""" + + def __init__( + self, + *, + access_key_id: Optional[str] = None, + access_key_secret: Optional[str] = None, + security_token: Optional[str] = None, + region: str = DEFAULT_REGION, + credential: Optional[Any] = None, + config: Optional[Mapping[str, Any]] = None, + endpoint: Optional[str] = None, + timeout: Union[float, httpx.Timeout, None] = None, + max_retries: int = 2, + http_client: Optional[httpx.AsyncClient] = None, + user_agent: Optional[str] = None, + raise_on_error: bool = True, + strict_validation: bool = False, + limits: Optional[httpx.Limits] = None, + _resolver: Optional[CredentialResolver] = None, + ) -> None: + _validate_region(region) + self._resolver = _resolver or CredentialResolver( + access_key_id=access_key_id, + access_key_secret=access_key_secret, + security_token=security_token, + credential=credential, + config=config, + ) + self.config = ManagementConfig( + region=region, + endpoint=endpoint, + raise_on_error=raise_on_error, + strict_validation=strict_validation, + timeout=timeout, + max_retries=max_retries, + user_agent=user_agent, + ) + self._transport = AsyncTransport( + region=region, + resolver=self._resolver, + endpoint=endpoint, + user_agent=user_agent, + timeout=timeout, + max_retries=max_retries, + http_client=http_client, + limits=limits, + ) + self.workspaces = AsyncWorkspaces(self) + self.api_keys = AsyncApiKeys(self) + self.billing = AsyncBilling(self) + self.token_plan = AsyncTokenPlan(self) + + @property + def transport(self) -> AsyncTransport: + return self._transport + + @property + def region(self) -> str: + return self.config.region + + @property + def raise_on_error(self) -> bool: + return self.config.raise_on_error + + def with_options( + self, + *, + region: Optional[str] = None, + endpoint: Optional[str] = None, + timeout: Union[float, httpx.Timeout, None] = None, + max_retries: Optional[int] = None, + raise_on_error: Optional[bool] = None, + strict_validation: Optional[bool] = None, + ) -> "AsyncManagementClient": + """Derive a new async client (own pool) sharing the credential.""" + cfg = self.config + return AsyncManagementClient( + _resolver=self._resolver, + region=region if region is not None else cfg.region, + endpoint=endpoint if endpoint is not None else cfg.endpoint, + timeout=timeout if timeout is not None else cfg.timeout, + max_retries=( + max_retries if max_retries is not None else cfg.max_retries + ), + user_agent=cfg.user_agent, + raise_on_error=( + raise_on_error + if raise_on_error is not None + else cfg.raise_on_error + ), + strict_validation=( + strict_validation + if strict_validation is not None + else cfg.strict_validation + ), + ) + + async def aclose(self) -> None: + await self._transport.aclose() + + async def __aenter__(self) -> "AsyncManagementClient": + return self + + async def __aexit__(self, *args: Any) -> None: + await self.aclose() diff --git a/dashscope/management/token_plan.py b/dashscope/management/token_plan.py new file mode 100644 index 00000000..ffec29ab --- /dev/null +++ b/dashscope/management/token_plan.py @@ -0,0 +1,1049 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""``client.token_plan`` -- TokenPlan account, members, seats, subscription. + +Read-only (G5). The tokenplan ops use the PascalCase envelope and offset +pagination (``PageNo`` / ``PageNum`` / ``PageSize`` / ``Total``), so their +lists ride :class:`~dashscope.types.pagination.BasePage` rather than the +modelstudio ``TokenPage``. Two page shapes occur: ``members`` returns the +item array directly under ``Data`` with pagination at the root, while +``seats`` / ``shared_packages`` nest both under ``Data.Items`` / +``Data.{PageNo,PageSize,Total}``. + +Write ops (invite links, key create/rotate, member add/update/remove, +seat assign/revoke, org update) are high-risk and deferred to G6 -- not +implemented here. +""" + +from __future__ import annotations + +from typing import ( + TYPE_CHECKING, + Any, + Literal, + Mapping, + Optional, + Union, + overload, +) + +from dashscope.management._errors import decode_body +from dashscope.management._parse import parse_base_page, parse_one +from dashscope.management._resource import ( + AsyncResource, + SyncResource, + options_kwargs, +) +from dashscope.management.types import ( + OrgMemberPage, + SeatPage, + SeatStats, + SharedPackagePage, + SubscriptionStats, + TokenPlanAccount, +) +from dashscope.transport._options import request_options + +if TYPE_CHECKING: + from dashscope.transport._response import APIResponse + +__all__ = [ + "AsyncTokenPlan", + "TokenPlan", +] + + +def _root_array_page(body: dict) -> tuple: + items = body.get("Data") + items = items if isinstance(items, list) else [] + return ( + items, + body.get("PageNo", 1), + body.get("PageSize", 10), + body.get("Total", len(items)), + ) + + +def _nested_page(body: dict) -> tuple: + data = body.get("Data") + data = data if isinstance(data, dict) else {} + items = data.get("Items") + items = items if isinstance(items, list) else [] + return ( + items, + data.get("PageNo", 1), + data.get("PageSize", 10), + data.get("Total", len(items)), + ) + + +class _Account(SyncResource): + @overload + def get( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPlanAccount: + ... + + @overload + def get( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def get( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPlanAccount, "APIResponse"]: + """The TokenPlan account detail and its org memberships.""" + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "GetTokenPlanAccountDetail", + {}, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + TokenPlanAccount, + resp, + data_field="Data", + strict=self._strict, + raise_on_error=self._raise_on_error, + ) + + +class _Members(SyncResource): + @overload + def list( + self, + *, + name: Optional[str] = None, + status: Optional[str] = None, + has_seat: Optional[bool] = None, + page_num: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> OrgMemberPage: + ... + + @overload + def list( + self, + *, + name: Optional[str] = None, + status: Optional[str] = None, + has_seat: Optional[bool] = None, + page_num: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + name: Optional[str] = None, + status: Optional[str] = None, + has_seat: Optional[bool] = None, + page_num: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[OrgMemberPage, "APIResponse"]: + """List organization members (``MaskedApiKey`` is already masked).""" + filters = { + "name": name, + "status": status, + "has_seat": has_seat, + "page_num": page_num, + "page_size": page_size, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "ListOrganizationMembers", + filters, + request_options(**opts), + ) + if raw: + return resp + items, no, size, total = _root_array_page( + decode_body(resp.http_response), + ) + + def fetch(next_no: int, next_size: int) -> OrgMemberPage: + return self.list( # type: ignore[call-overload] + **{**filters, "page_num": next_no, "page_size": next_size}, + **opts, + ) + + return parse_base_page( + OrgMemberPage, + resp, + items_field="members", + items=items, + page_no=no, + page_size=size, + total_count=total, + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + requested_no=page_num, + requested_size=page_size, + ) + + +class _Seats(SyncResource): + @overload + def list( + self, + *, + status_list: Optional[Any] = None, + seat_id: Optional[str] = None, + seat_type: Optional[str] = None, + query_assigned: Optional[bool] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> SeatPage: + ... + + @overload + def list( + self, + *, + status_list: Optional[Any] = None, + seat_id: Optional[str] = None, + seat_type: Optional[str] = None, + query_assigned: Optional[bool] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + status_list: Optional[Any] = None, + seat_id: Optional[str] = None, + seat_type: Optional[str] = None, + query_assigned: Optional[bool] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[SeatPage, "APIResponse"]: + """List subscription seat details, paginated by ``PageNo``.""" + filters = { + "status_list": status_list, + "seat_id": seat_id, + "seat_type": seat_type, + "query_assigned": query_assigned, + "page_no": page_no, + "page_size": page_size, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "GetSubscriptionSeatDetails", + filters, + request_options(**opts), + ) + if raw: + return resp + items, no, size, total = _nested_page( + decode_body(resp.http_response), + ) + + def fetch(next_no: int, next_size: int) -> SeatPage: + return self.list( + **{**filters, "page_no": next_no, "page_size": next_size}, + **opts, + ) + + return parse_base_page( + SeatPage, + resp, + items_field="seats", + items=items, + page_no=no, + page_size=size, + total_count=total, + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + requested_no=page_no, + requested_size=page_size, + ) + + @overload + def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> SeatStats: + ... + + @overload + def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[SeatStats, "APIResponse"]: + """Organization member seat statistics (a bare root DTO).""" + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "GetOrganizationMemberSeatStats", + {}, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + SeatStats, + resp, + data_field=None, + strict=self._strict, + raise_on_error=self._raise_on_error, + ) + + +class _Subscription(SyncResource): + @overload + def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> SubscriptionStats: + ... + + @overload + def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[SubscriptionStats, "APIResponse"]: + """Subscription seat totals and remaining credits, by seat type.""" + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "GetSubscriptionStats", + {}, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + SubscriptionStats, + resp, + data_field="Data", + strict=self._strict, + raise_on_error=self._raise_on_error, + ) + + +class _SharedPackages(SyncResource): + @overload + def list( + self, + *, + status_list: Optional[Any] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> SharedPackagePage: + ... + + @overload + def list( + self, + *, + status_list: Optional[Any] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + status_list: Optional[Any] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[SharedPackagePage, "APIResponse"]: + """List subscription shared packages, paginated by ``PageNo``.""" + filters = { + "status_list": status_list, + "page_no": page_no, + "page_size": page_size, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "ListSubscriptionSharedPackages", + filters, + request_options(**opts), + ) + if raw: + return resp + items, no, size, total = _nested_page( + decode_body(resp.http_response), + ) + + def fetch(next_no: int, next_size: int) -> SharedPackagePage: + return self.list( + **{**filters, "page_no": next_no, "page_size": next_size}, + **opts, + ) + + return parse_base_page( + SharedPackagePage, + resp, + items_field="packages", + items=items, + page_no=no, + page_size=size, + total_count=total, + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + requested_no=page_no, + requested_size=page_size, + ) + + +class TokenPlan(SyncResource): + """TokenPlan read surface; sub-resources group the ops by area.""" + + def __init__(self, client: Any) -> None: + super().__init__(client) + self.account = _Account(client) + self.members = _Members(client) + self.seats = _Seats(client) + self.subscription = _Subscription(client) + self.shared_packages = _SharedPackages(client) + + +class _AsyncAccount(AsyncResource): + @overload + async def get( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPlanAccount: + ... + + @overload + async def get( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def get( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPlanAccount, "APIResponse"]: + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "GetTokenPlanAccountDetail", + {}, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + TokenPlanAccount, + resp, + data_field="Data", + strict=self._strict, + raise_on_error=self._raise_on_error, + ) + + +class _AsyncMembers(AsyncResource): + @overload + async def list( + self, + *, + name: Optional[str] = None, + status: Optional[str] = None, + has_seat: Optional[bool] = None, + page_num: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> OrgMemberPage: + ... + + @overload + async def list( + self, + *, + name: Optional[str] = None, + status: Optional[str] = None, + has_seat: Optional[bool] = None, + page_num: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + name: Optional[str] = None, + status: Optional[str] = None, + has_seat: Optional[bool] = None, + page_num: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[OrgMemberPage, "APIResponse"]: + filters = { + "name": name, + "status": status, + "has_seat": has_seat, + "page_num": page_num, + "page_size": page_size, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "ListOrganizationMembers", + filters, + request_options(**opts), + ) + if raw: + return resp + items, no, size, total = _root_array_page( + decode_body(resp.http_response), + ) + + async def fetch(next_no: int, next_size: int) -> OrgMemberPage: + return await self.list( # type: ignore[call-overload] + **{**filters, "page_num": next_no, "page_size": next_size}, + **opts, + ) + + return parse_base_page( + OrgMemberPage, + resp, + items_field="members", + items=items, + page_no=no, + page_size=size, + total_count=total, + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + requested_no=page_num, + requested_size=page_size, + ) + + +class _AsyncSeats(AsyncResource): + @overload + async def list( + self, + *, + status_list: Optional[Any] = None, + seat_id: Optional[str] = None, + seat_type: Optional[str] = None, + query_assigned: Optional[bool] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> SeatPage: + ... + + @overload + async def list( + self, + *, + status_list: Optional[Any] = None, + seat_id: Optional[str] = None, + seat_type: Optional[str] = None, + query_assigned: Optional[bool] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + status_list: Optional[Any] = None, + seat_id: Optional[str] = None, + seat_type: Optional[str] = None, + query_assigned: Optional[bool] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[SeatPage, "APIResponse"]: + filters = { + "status_list": status_list, + "seat_id": seat_id, + "seat_type": seat_type, + "query_assigned": query_assigned, + "page_no": page_no, + "page_size": page_size, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "GetSubscriptionSeatDetails", + filters, + request_options(**opts), + ) + if raw: + return resp + items, no, size, total = _nested_page( + decode_body(resp.http_response), + ) + + async def fetch(next_no: int, next_size: int) -> SeatPage: + return await self.list( + **{**filters, "page_no": next_no, "page_size": next_size}, + **opts, + ) + + return parse_base_page( + SeatPage, + resp, + items_field="seats", + items=items, + page_no=no, + page_size=size, + total_count=total, + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + requested_no=page_no, + requested_size=page_size, + ) + + @overload + async def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> SeatStats: + ... + + @overload + async def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[SeatStats, "APIResponse"]: + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "GetOrganizationMemberSeatStats", + {}, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + SeatStats, + resp, + data_field=None, + strict=self._strict, + raise_on_error=self._raise_on_error, + ) + + +class _AsyncSubscription(AsyncResource): + @overload + async def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> SubscriptionStats: + ... + + @overload + async def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def stats( + self, + *, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[SubscriptionStats, "APIResponse"]: + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "GetSubscriptionStats", + {}, + request_options(**opts), + ) + if raw: + return resp + return parse_one( + SubscriptionStats, + resp, + data_field="Data", + strict=self._strict, + raise_on_error=self._raise_on_error, + ) + + +class _AsyncSharedPackages(AsyncResource): + @overload + async def list( + self, + *, + status_list: Optional[Any] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> SharedPackagePage: + ... + + @overload + async def list( + self, + *, + status_list: Optional[Any] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + status_list: Optional[Any] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[SharedPackagePage, "APIResponse"]: + filters = { + "status_list": status_list, + "page_no": page_no, + "page_size": page_size, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "ListSubscriptionSharedPackages", + filters, + request_options(**opts), + ) + if raw: + return resp + items, no, size, total = _nested_page( + decode_body(resp.http_response), + ) + + async def fetch(next_no: int, next_size: int) -> SharedPackagePage: + return await self.list( + **{**filters, "page_no": next_no, "page_size": next_size}, + **opts, + ) + + return parse_base_page( + SharedPackagePage, + resp, + items_field="packages", + items=items, + page_no=no, + page_size=size, + total_count=total, + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + requested_no=page_no, + requested_size=page_size, + ) + + +class AsyncTokenPlan(AsyncResource): + """Async TokenPlan read surface; mirrors :class:`TokenPlan`.""" + + def __init__(self, client: Any) -> None: + super().__init__(client) + self.account = _AsyncAccount(client) + self.members = _AsyncMembers(client) + self.seats = _AsyncSeats(client) + self.subscription = _AsyncSubscription(client) + self.shared_packages = _AsyncSharedPackages(client) diff --git a/dashscope/management/types.py b/dashscope/management/types.py new file mode 100644 index 00000000..d6af36d8 --- /dev/null +++ b/dashscope/management/types.py @@ -0,0 +1,476 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Public response models for the management read surface. + +Every model is permissive (``extra="allow"``, optional fields with +defaults) so a gateway that adds or renames a field degrades rather than +raises. Wire names are camelCase on the modelstudio ops and PascalCase on +the tokenplan ops; ``Field(validation_alias=...)`` maps each to a +snake_case attribute, and ``populate_by_name=True`` keeps the snake name +usable too. + +``ApiKey.api_key_value`` is a ``SecretStr``: even though these are read +ops, the gateway returns the plaintext key, so it is masked in ``repr``, +``model_dump`` and logs. ``OrgMember.masked_api_key`` is already masked +server-side and stays a plain string. +""" + +from __future__ import annotations + +from typing import Any, List, Optional + +from pydantic import BaseModel, ConfigDict, Field, SecretStr + +from dashscope.types.common import ResponseBase +from dashscope.types.pagination import BasePage + +__all__ = [ + "ApiKey", + "ApiKeyAuth", + "BillingGroup", + "BillingOverview", + "BillingTrend", + "CostTotals", + "GroupByTotal", + "InferenceMetadata", + "ManagementModel", + "ModelAccessScope", + "ModelInfo", + "ModelLimit", + "ModelPermission", + "OrgMember", + "OrgMemberPage", + "OrgMembership", + "Permissions", + "Price", + "RateLimit", + "ResultByTime", + "Seat", + "SeatPage", + "SeatStats", + "SharedPackage", + "SharedPackagePage", + "SubscriptionSeatItem", + "SubscriptionStats", + "TokenPlanAccount", + "Workspace", +] + + +class _Model(BaseModel): + """Permissive base for nested payload models (no envelope).""" + + model_config = ConfigDict(extra="allow", populate_by_name=True) + + +class _Response(ResponseBase): + """Permissive base for top-level responses (carries the envelope).""" + + model_config = ConfigDict(extra="allow", populate_by_name=True) + + +# --- workspaces / models ------------------------------------------------- + + +class Workspace(_Model): + api_host: Optional[str] = Field(None, validation_alias="apiHost") + gmt_create: Optional[int] = Field(None, validation_alias="gmtCreate") + region: Optional[str] = None + service_site: Optional[str] = Field(None, validation_alias="serviceSite") + workspace_id: Optional[str] = Field(None, validation_alias="workspaceId") + workspace_name: Optional[str] = Field( + None, + validation_alias="workspaceName", + ) + + +class InferenceMetadata(_Model): + request_modality: Optional[Any] = Field( + None, + validation_alias="requestModality", + ) + response_modality: Optional[Any] = Field( + None, + validation_alias="responseModality", + ) + + +class ModelInfo(_Model): + context_window: Optional[int] = Field( + None, + validation_alias="contextWindow", + ) + max_input_tokens: Optional[int] = Field( + None, + validation_alias="maxInputTokens", + ) + max_output_tokens: Optional[int] = Field( + None, + validation_alias="maxOutputTokens", + ) + max_reasoning_tokens: Optional[int] = Field( + None, + validation_alias="maxReasoningTokens", + ) + reasoning_max_input_tokens: Optional[int] = Field( + None, + validation_alias="reasoningMaxInputTokens", + ) + reasoning_max_output_tokens: Optional[int] = Field( + None, + validation_alias="reasoningMaxOutputTokens", + ) + + +class Price(_Model): + """A model price entry; fields vary by provider, kept as extras.""" + + +class ManagementModel(_Model): + model: Optional[str] = None + name: Optional[str] = None + description: Optional[str] = None + features: List[str] = Field(default_factory=list) + inference_metadata: Optional[InferenceMetadata] = Field( + None, + validation_alias="inferenceMetadata", + ) + prices: List[Price] = Field(default_factory=list) + published_time: Optional[Any] = Field( + None, + validation_alias="publishedTime", + ) + model_info: Optional[ModelInfo] = Field(None, validation_alias="modelInfo") + provider: Optional[str] = None + capabilities: List[str] = Field(default_factory=list) + + +class RateLimit(_Model): + request_limit: Optional[int] = Field(None, validation_alias="requestLimit") + request_limit_period: Optional[str] = Field( + None, + validation_alias="requestLimitPeriod", + ) + usage_limit: Optional[int] = Field(None, validation_alias="usageLimit") + usage_limit_field: Optional[str] = Field( + None, + validation_alias="usageLimitField", + ) + usage_limit_period: Optional[str] = Field( + None, + validation_alias="usageLimitPeriod", + ) + async_user_queue_limit: Optional[int] = Field( + None, + validation_alias="asyncUserQueueLimit", + ) + async_user_concurrency_limit: Optional[int] = Field( + None, + validation_alias="asyncUserConcurrencyLimit", + ) + + +class ModelLimit(_Model): + model: Optional[str] = None + name: Optional[str] = None + workspace_id: Optional[str] = Field(None, validation_alias="workspaceId") + model_limit: Optional[RateLimit] = Field( + None, + validation_alias="modelLimit", + ) + workspace_limit: Optional[RateLimit] = Field( + None, + validation_alias="workspaceLimit", + ) + + +class Permissions(_Model): + inference: Optional[bool] = None + fine_tune: Optional[bool] = Field(None, validation_alias="fineTune") + deploy: Optional[bool] = None + + +class ModelPermission(_Model): + model: Optional[str] = None + name: Optional[str] = None + permissions: Optional[Permissions] = None + + +# --- api keys ------------------------------------------------------------ + + +class ModelAccessScope(_Model): + accessible_models: List[str] = Field( + default_factory=list, + validation_alias="accessibleModels", + ) + allow_all_models: Optional[bool] = Field( + None, + validation_alias="allowAllModels", + ) + + +class ApiKeyAuth(_Model): + access_ips: List[str] = Field( + default_factory=list, + validation_alias="accessIps", + ) + model_access_scope: Optional[ModelAccessScope] = Field( + None, + validation_alias="modelAccessScope", + ) + type: Optional[str] = None + + +class ApiKey(_Model): + api_key_id: Optional[int] = Field(None, validation_alias="apiKeyId") + api_key_value: Optional[SecretStr] = Field( + None, + validation_alias="apiKeyValue", + ) + auth: Optional[ApiKeyAuth] = None + created_by: Optional[str] = Field(None, validation_alias="createdBy") + description: Optional[str] = None + disabled: Optional[int] = None + gmt_create: Optional[int] = Field(None, validation_alias="gmtCreate") + workspace_id: Optional[str] = Field(None, validation_alias="workspaceId") + workspace_name: Optional[str] = Field( + None, + validation_alias="workspaceName", + ) + + +# --- billing ------------------------------------------------------------- + + +class BillingGroup(_Model): + key: Optional[str] = None + name: Optional[str] = None + article_codes: List[str] = Field( + default_factory=list, + validation_alias="articleCodes", + ) + amount: Optional[str] = None + percentage: Optional[str] = None + + +class BillingOverview(_Response): + currency: Optional[str] = None + total_amount: Optional[str] = Field(None, validation_alias="totalAmount") + pretax_amount: Optional[str] = Field(None, validation_alias="pretaxAmount") + tax_amount: Optional[str] = Field(None, validation_alias="taxAmount") + groups: List[BillingGroup] = Field(default_factory=list) + + +class CostTotals(_Model): + amount: Optional[str] = None + pretax_amount: Optional[str] = Field(None, validation_alias="pretaxAmount") + tax_amount: Optional[str] = Field(None, validation_alias="taxAmount") + currency: Optional[str] = None + + +class GroupByTotal(_Model): + key: Optional[str] = None + name: Optional[str] = None + amount: Optional[str] = None + pretax_amount: Optional[str] = Field(None, validation_alias="pretaxAmount") + tax_amount: Optional[str] = Field(None, validation_alias="taxAmount") + + +class ResultByTime(_Model): + period: Optional[str] = None + total: Optional[Any] = None + period_details: Optional[Any] = Field( + None, + validation_alias="periodDetails", + ) + + +class BillingTrend(_Response): + cost_totals: Optional[CostTotals] = Field( + None, + validation_alias="costTotals", + ) + group_by_total: List[GroupByTotal] = Field( + default_factory=list, + validation_alias="groupByTotal", + ) + result_by_time: List[ResultByTime] = Field( + default_factory=list, + validation_alias="resultByTime", + ) + history_period: Optional[Any] = Field( + None, + validation_alias="historyPeriod", + ) + + +# --- token plan ---------------------------------------------------------- + + +class OrgMembership(_Model): + org_id: Optional[str] = Field(None, validation_alias="OrgId") + member_status: Optional[str] = Field(None, validation_alias="MemberStatus") + role_id: Optional[str] = Field(None, validation_alias="RoleId") + role_code: Optional[str] = Field(None, validation_alias="RoleCode") + workspaces: Optional[Any] = Field(None, validation_alias="Workspaces") + + +class TokenPlanAccount(_Response): + account_id: Optional[str] = Field(None, validation_alias="AccountId") + account_type: Optional[str] = Field(None, validation_alias="AccountType") + is_deleted: Optional[bool] = Field(None, validation_alias="IsDeleted") + name: Optional[str] = Field(None, validation_alias="Name") + aliyun_uid: Optional[str] = Field(None, validation_alias="AliyunUid") + email: Optional[str] = Field(None, validation_alias="Email") + created_at: Optional[str] = Field(None, validation_alias="CreatedAt") + org_memberships: List[OrgMembership] = Field( + default_factory=list, + validation_alias="OrgMemberships", + ) + + +class OrgMember(_Model): + account_id: Optional[str] = Field(None, validation_alias="AccountId") + account_name: Optional[str] = Field(None, validation_alias="AccountName") + account_biz_id: Optional[str] = Field( + None, + validation_alias="AccountBizId", + ) + email: Optional[str] = Field(None, validation_alias="Email") + org_id: Optional[str] = Field(None, validation_alias="OrgId") + status: Optional[str] = Field(None, validation_alias="Status") + roles: List[str] = Field(default_factory=list, validation_alias="Roles") + gmt_create: Optional[Any] = Field(None, validation_alias="GmtCreate") + seat_id: Optional[str] = Field(None, validation_alias="SeatId") + spec_type: Optional[str] = Field(None, validation_alias="SpecType") + api_key_id: Optional[Any] = Field(None, validation_alias="ApiKeyId") + masked_api_key: Optional[str] = Field( + None, + validation_alias="MaskedApiKey", + ) + pack_limit_info: Optional[Any] = Field( + None, + validation_alias="PackLimitInfo", + ) + subscription_info: Optional[Any] = Field( + None, + validation_alias="SubscriptionInfo", + ) + + +class Seat(_Model): + instance_code: Optional[str] = Field(None, validation_alias="InstanceCode") + equity_list: List[Any] = Field( + default_factory=list, + validation_alias="EquityList", + ) + end_time: Optional[Any] = Field(None, validation_alias="EndTime") + seat_id: Optional[str] = Field(None, validation_alias="SeatId") + spec_type: Optional[str] = Field(None, validation_alias="SpecType") + start_time: Optional[Any] = Field(None, validation_alias="StartTime") + assigned_status: Optional[str] = Field( + None, + validation_alias="AssignedStatus", + ) + account_id: Optional[str] = Field(None, validation_alias="AccountId") + account_name: Optional[str] = Field(None, validation_alias="AccountName") + account_email: Optional[str] = Field(None, validation_alias="AccountEmail") + status: Optional[str] = Field(None, validation_alias="Status") + + +class SeatStats(_Response): + org_id: Optional[str] = Field(None, validation_alias="OrgId") + total_member_count: Optional[int] = Field( + None, + validation_alias="TotalMemberCount", + ) + owner_role_user_count: Optional[int] = Field( + None, + validation_alias="OwnerRoleUserCount", + ) + admin_role_user_count: Optional[int] = Field( + None, + validation_alias="AdminRoleUserCount", + ) + member_role_user_count: Optional[int] = Field( + None, + validation_alias="MemberRoleUserCount", + ) + seated_member_count: Optional[int] = Field( + None, + validation_alias="SeatedMemberCount", + ) + unseated_member_count: Optional[int] = Field( + None, + validation_alias="UnseatedMemberCount", + ) + + +class SubscriptionSeatItem(_Model): + seat_type: Optional[str] = Field(None, validation_alias="SeatType") + seat_refresh_time: Optional[int] = Field( + None, + validation_alias="SeatRefreshTime", + ) + total_seats: Optional[int] = Field(None, validation_alias="TotalSeats") + assigned_seats: Optional[int] = Field( + None, + validation_alias="AssignedSeats", + ) + seat_credits: Optional[Any] = Field(None, validation_alias="SeatCredits") + seat_remaining_credits: Optional[Any] = Field( + None, + validation_alias="SeatRemainingCredits", + ) + + +class SubscriptionStats(_Response): + subscription_start_time: Optional[int] = Field( + None, + validation_alias="SubscriptionStartTime", + ) + subscription_end_time: Optional[int] = Field( + None, + validation_alias="SubscriptionEndTime", + ) + items: List[SubscriptionSeatItem] = Field( + default_factory=list, + validation_alias="Items", + ) + + +class SharedPackage(_Model): + instance_code: Optional[str] = Field(None, validation_alias="InstanceCode") + equity_list: List[Any] = Field( + default_factory=list, + validation_alias="EquityList", + ) + status: Optional[str] = Field(None, validation_alias="Status") + + +# --- offset pages (tokenplan) -------------------------------------------- + + +class OrgMemberPage(BasePage[OrgMember]): + members: List[OrgMember] = Field(default_factory=list) + + @property + def items(self) -> List[OrgMember]: + return self.members + + +class SeatPage(BasePage[Seat]): + seats: List[Seat] = Field(default_factory=list) + + @property + def items(self) -> List[Seat]: + return self.seats + + +class SharedPackagePage(BasePage[SharedPackage]): + packages: List[SharedPackage] = Field(default_factory=list) + + @property + def items(self) -> List[SharedPackage]: + return self.packages diff --git a/dashscope/management/workspaces.py b/dashscope/management/workspaces.py new file mode 100644 index 00000000..7a7d77a9 --- /dev/null +++ b/dashscope/management/workspaces.py @@ -0,0 +1,813 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""``client.workspaces`` -- business spaces and their model catalog. + +Read-only (G2). ``workspaces.list`` pages by ``nextToken``; the nested +``models`` / ``model_limits`` / ``model_permissions`` resources list the +model catalog, per-model rate limits and per-model authorization scopes. +Write ops (CreateWorkspace / DeleteWorkspace / UpdateModelLimits / +UpdateModelPermissions) are high-risk and deferred to G3 -- not implemented +here. +""" + +from __future__ import annotations + +from typing import ( + TYPE_CHECKING, + Any, + Literal, + Mapping, + Optional, + Union, + overload, +) + +from dashscope.management._pagination import TokenPage +from dashscope.management._parse import parse_token_page +from dashscope.management._resource import ( + AsyncResource, + SyncResource, + options_kwargs, +) +from dashscope.management.types import ( + ManagementModel, + ModelLimit, + ModelPermission, + Workspace, +) +from dashscope.transport._options import request_options + +if TYPE_CHECKING: + from dashscope.transport._response import APIResponse + +__all__ = [ + "AsyncModelLimits", + "AsyncModelPermissions", + "AsyncModels", + "AsyncWorkspaces", + "ModelLimits", + "ModelPermissions", + "Models", + "Workspaces", +] + + +class Workspaces(SyncResource): + def __init__(self, client: Any) -> None: + super().__init__(client) + self.models = Models(client) + self.model_limits = ModelLimits(client) + self.model_permissions = ModelPermissions(client) + + @overload + def list( + self, + *, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + workspace_name: Optional[str] = None, + workspace_id: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPage[Workspace]: + ... + + @overload + def list( + self, + *, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + workspace_name: Optional[str] = None, + workspace_id: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + workspace_name: Optional[str] = None, + workspace_id: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPage[Workspace], "APIResponse"]: + """List business spaces, paginated by ``nextToken``.""" + filters = { + "next_token": next_token, + "max_results": max_results, + "workspace_name": workspace_name, + "workspace_id": workspace_id, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "ListWorkspaces", + filters, + request_options(**opts), + ) + if raw: + return resp + + def fetch(token: str) -> TokenPage[Workspace]: + return self.list( # type: ignore[call-overload] + **{**filters, "next_token": token}, + **opts, + ) + + return parse_token_page( + Workspace, + resp, + data_field="workspaces", + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + ) + + +class Models(SyncResource): + @overload + def list( + self, + *, + providers: Optional[Any] = None, + capabilities: Optional[Any] = None, + features: Optional[Any] = None, + language: Optional[str] = None, + context_window: Optional[int] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPage[ManagementModel]: + ... + + @overload + def list( + self, + *, + providers: Optional[Any] = None, + capabilities: Optional[Any] = None, + features: Optional[Any] = None, + language: Optional[str] = None, + context_window: Optional[int] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + providers: Optional[Any] = None, + capabilities: Optional[Any] = None, + features: Optional[Any] = None, + language: Optional[str] = None, + context_window: Optional[int] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPage[ManagementModel], "APIResponse"]: + """List the model catalog (public; not scoped to a workspace).""" + filters = { + "providers": providers, + "capabilities": capabilities, + "features": features, + "language": language, + "context_window": context_window, + "name": name, + "model": model, + "next_token": next_token, + "max_results": max_results, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request("ListModels", filters, request_options(**opts)) + if raw: + return resp + + def fetch(token: str) -> TokenPage[ManagementModel]: + return self.list(**{**filters, "next_token": token}, **opts) + + return parse_token_page( + ManagementModel, + resp, + data_field="models", + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + ) + + +class ModelLimits(SyncResource): + @overload + def list( + self, + *, + workspace_id: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPage[ModelLimit]: + ... + + @overload + def list( + self, + *, + workspace_id: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + workspace_id: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPage[ModelLimit], "APIResponse"]: + """List per-model rate limits.""" + filters = { + "workspace_id": workspace_id, + "name": name, + "model": model, + "next_token": next_token, + "max_results": max_results, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "ListModelLimits", + filters, + request_options(**opts), + ) + if raw: + return resp + + def fetch(token: str) -> TokenPage[ModelLimit]: + return self.list( # type: ignore[call-overload] + **{**filters, "next_token": token}, + **opts, + ) + + return parse_token_page( + ModelLimit, + resp, + data_field="limits", + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + ) + + +class ModelPermissions(SyncResource): + @overload + def list( + self, + *, + workspace_id: str, + authorization_scope: Optional[str] = None, + model_action: Optional[str] = None, + filter_: Optional[Mapping[str, Any]] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPage[ModelPermission]: + ... + + @overload + def list( + self, + *, + workspace_id: str, + authorization_scope: Optional[str] = None, + model_action: Optional[str] = None, + filter_: Optional[Mapping[str, Any]] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + workspace_id: str, + authorization_scope: Optional[str] = None, + model_action: Optional[str] = None, + filter_: Optional[Mapping[str, Any]] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPage[ModelPermission], "APIResponse"]: + """List per-model authorization scopes (``workspace_id`` required).""" + filters = { + "workspace_id": workspace_id, + "authorization_scope": authorization_scope, + "model_action": model_action, + "filter_": filter_, + "next_token": next_token, + "max_results": max_results, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = self._request( + "ListModelPermissions", + filters, + request_options(**opts), + ) + if raw: + return resp + + def fetch(token: str) -> TokenPage[ModelPermission]: + return self.list( # type: ignore[call-overload] + **{**filters, "next_token": token}, + **opts, + ) + + return parse_token_page( + ModelPermission, + resp, + data_field="list", + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + ) + + +class AsyncWorkspaces(AsyncResource): + def __init__(self, client: Any) -> None: + super().__init__(client) + self.models = AsyncModels(client) + self.model_limits = AsyncModelLimits(client) + self.model_permissions = AsyncModelPermissions(client) + + @overload + async def list( + self, + *, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + workspace_name: Optional[str] = None, + workspace_id: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPage[Workspace]: + ... + + @overload + async def list( + self, + *, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + workspace_name: Optional[str] = None, + workspace_id: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + workspace_name: Optional[str] = None, + workspace_id: Optional[str] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPage[Workspace], "APIResponse"]: + filters = { + "next_token": next_token, + "max_results": max_results, + "workspace_name": workspace_name, + "workspace_id": workspace_id, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "ListWorkspaces", + filters, + request_options(**opts), + ) + if raw: + return resp + + async def fetch(token: str) -> TokenPage[Workspace]: + return await self.list( # type: ignore[call-overload] + **{**filters, "next_token": token}, + **opts, + ) + + return parse_token_page( + Workspace, + resp, + data_field="workspaces", + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + ) + + +class AsyncModels(AsyncResource): + @overload + async def list( + self, + *, + providers: Optional[Any] = None, + capabilities: Optional[Any] = None, + features: Optional[Any] = None, + language: Optional[str] = None, + context_window: Optional[int] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPage[ManagementModel]: + ... + + @overload + async def list( + self, + *, + providers: Optional[Any] = None, + capabilities: Optional[Any] = None, + features: Optional[Any] = None, + language: Optional[str] = None, + context_window: Optional[int] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + providers: Optional[Any] = None, + capabilities: Optional[Any] = None, + features: Optional[Any] = None, + language: Optional[str] = None, + context_window: Optional[int] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPage[ManagementModel], "APIResponse"]: + filters = { + "providers": providers, + "capabilities": capabilities, + "features": features, + "language": language, + "context_window": context_window, + "name": name, + "model": model, + "next_token": next_token, + "max_results": max_results, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "ListModels", + filters, + request_options(**opts), + ) + if raw: + return resp + + async def fetch(token: str) -> TokenPage[ManagementModel]: + return await self.list( + **{**filters, "next_token": token}, + **opts, + ) + + return parse_token_page( + ManagementModel, + resp, + data_field="models", + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + ) + + +class AsyncModelLimits(AsyncResource): + @overload + async def list( + self, + *, + workspace_id: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPage[ModelLimit]: + ... + + @overload + async def list( + self, + *, + workspace_id: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + workspace_id: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPage[ModelLimit], "APIResponse"]: + filters = { + "workspace_id": workspace_id, + "name": name, + "model": model, + "next_token": next_token, + "max_results": max_results, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "ListModelLimits", + filters, + request_options(**opts), + ) + if raw: + return resp + + async def fetch(token: str) -> TokenPage[ModelLimit]: + return await self.list( # type: ignore[call-overload] + **{**filters, "next_token": token}, + **opts, + ) + + return parse_token_page( + ModelLimit, + resp, + data_field="limits", + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + ) + + +class AsyncModelPermissions(AsyncResource): + @overload + async def list( + self, + *, + workspace_id: str, + authorization_scope: Optional[str] = None, + model_action: Optional[str] = None, + filter_: Optional[Mapping[str, Any]] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> TokenPage[ModelPermission]: + ... + + @overload + async def list( + self, + *, + workspace_id: str, + authorization_scope: Optional[str] = None, + model_action: Optional[str] = None, + filter_: Optional[Mapping[str, Any]] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + workspace_id: str, + authorization_scope: Optional[str] = None, + model_action: Optional[str] = None, + filter_: Optional[Mapping[str, Any]] = None, + next_token: Optional[str] = None, + max_results: Optional[int] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[TokenPage[ModelPermission], "APIResponse"]: + filters = { + "workspace_id": workspace_id, + "authorization_scope": authorization_scope, + "model_action": model_action, + "filter_": filter_, + "next_token": next_token, + "max_results": max_results, + } + opts = options_kwargs( + timeout, + extra_headers, + extra_query, + extra_body, + max_retries, + ) + resp = await self._request( + "ListModelPermissions", + filters, + request_options(**opts), + ) + if raw: + return resp + + async def fetch(token: str) -> TokenPage[ModelPermission]: + return await self.list( # type: ignore[call-overload] + **{**filters, "next_token": token}, + **opts, + ) + + return parse_token_page( + ModelPermission, + resp, + data_field="list", + strict=self._strict, + raise_on_error=self._raise_on_error, + fetch_next=fetch, + ) diff --git a/requirements-test.txt b/requirements-test.txt index 961088fc..082cab7d 100644 --- a/requirements-test.txt +++ b/requirements-test.txt @@ -15,3 +15,6 @@ rich>=13.0.0 dashscope-agenticx[tui]>=1.0.0,<2; python_version >= "3.10" PyYAML>=6.0 tomli>=2.0; python_version < "3.11" +# Optional [management] extra exercised by the ManagementClient tests +alibabacloud_credentials>=1.0.0 +alibabacloud_openapi_util>=0.2.0 diff --git a/setup.py b/setup.py index 45f5fabc..cac13cc7 100644 --- a/setup.py +++ b/setup.py @@ -130,6 +130,13 @@ def run(self): "numpy>=1.20", "opencv-python-headless>=4.5", ], + # RAM OpenAPI ManagementClient (read-only G1/G2/G5). The credential + # chain needs the 1.0.x model-based get_credential[_async] API; + # openapi_util supplies ACS3-HMAC-SHA256 V3 signing. + "management": [ + "alibabacloud_credentials>=1.0.0", + "alibabacloud_openapi_util>=0.2.0", + ], }, zip_safe=False, cmdclass=cmdclass, diff --git a/tests/management_helpers.py b/tests/management_helpers.py new file mode 100644 index 00000000..a4ecac5d --- /dev/null +++ b/tests/management_helpers.py @@ -0,0 +1,87 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Shared fixtures/helpers for the ManagementClient (module G) tests. + +Not collected by pytest (no ``test_`` prefix). Every management test +module calls ``pytest.importorskip`` on the alibabacloud libs *before* +importing this module, so the optional ``[management]`` extra stays +optional for the rest of the suite. +""" + +from __future__ import annotations + +from typing import Any, Callable, Dict, Mapping, Optional + +import httpx + +from dashscope.management import AsyncManagementClient, ManagementClient + +# Fake credentials -- never real keys (detect-private-key safe). +AK = "ak-test" +SK = "sk-test" +STS_TOKEN = "sts-token-test" + +MS_ENVELOPE: Dict[str, Any] = { + "code": "200", + "success": True, + "requestId": "req-ms", + "httpStatusCode": 200, +} +TP_ENVELOPE: Dict[str, Any] = { + "Success": True, + "Code": "200", + "Message": "OK", + "RequestId": "req-tp", + "HttpStatusCode": 200, +} + + +def ms_body(**kw: Any) -> Dict[str, Any]: + """A successful modelstudio (lowercase) envelope plus payload fields.""" + return {**MS_ENVELOPE, **kw} + + +def tp_body(**kw: Any) -> Dict[str, Any]: + """A successful tokenplan (PascalCase) envelope plus payload fields.""" + return {**TP_ENVELOPE, **kw} + + +def make_client( + handler: Callable[[httpx.Request], httpx.Response], + **kwargs: Any, +) -> ManagementClient: + http_client = httpx.Client(transport=httpx.MockTransport(handler)) + kwargs.setdefault("access_key_id", AK) + kwargs.setdefault("access_key_secret", SK) + return ManagementClient(http_client=http_client, **kwargs) + + +def make_async_client( + handler: Callable[[httpx.Request], httpx.Response], + **kwargs: Any, +) -> AsyncManagementClient: + http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler)) + kwargs.setdefault("access_key_id", AK) + kwargs.setdefault("access_key_secret", SK) + return AsyncManagementClient(http_client=http_client, **kwargs) + + +def action_handler( + bodies: Mapping[str, Any], + *, + status: int = 200, + seen: Optional[list] = None, +) -> Callable[[httpx.Request], httpx.Response]: + """Return ``bodies[x-acs-action]`` for each request, recording actions.""" + + def handler(request: httpx.Request) -> httpx.Response: + action = request.headers["x-acs-action"] + if seen is not None: + seen.append(action) + return httpx.Response(status, json=bodies[action]) + + return handler + + +def query_of(request: httpx.Request) -> Dict[str, str]: + return dict(request.url.params) diff --git a/tests/protocols/test_management_e2e.py b/tests/protocols/test_management_e2e.py new file mode 100644 index 00000000..89f55d3b --- /dev/null +++ b/tests/protocols/test_management_e2e.py @@ -0,0 +1,156 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Live e2e for the read-only ManagementClient surface (G1/G2/G5). + +Skipped unless RAM credentials are exported. Only public read ops are +exercised -- ListWorkspaces, ListModels, GetBillingOverview and +GetTokenPlanAccountDetail -- so a run never creates, mutates or deletes +anything. The point is to prove the V3 ACS3-HMAC-SHA256 signature (with +the ``management2`` sdk headers folded in) is accepted by the real +``modelstudio.{region}.aliyuncs.com`` gateway and that the dual envelope +parses into typed models:: + + ALIBABA_CLOUD_ACCESS_KEY_ID=... ALIBABA_CLOUD_ACCESS_KEY_SECRET=... \\ + DASHSCOPE_MGMT_REGION=cn-beijing \\ + pytest tests/protocols/test_management_e2e.py + +``DASHSCOPE_MGMT_AK`` / ``DASHSCOPE_MGMT_SK`` (and ``DASHSCOPE_MGMT_STS_TOKEN`` +for STS) are accepted as alternatives to the standard aliyun env vars. A +business error (account not enrolled in TokenPlan, no billing data, RAM +permission) skips the case rather than failing it; only a rejected +signature -- the one thing the SDK controls -- fails loud. +""" + +from __future__ import annotations + +import os + +import pytest + +# pylint: disable=wrong-import-position +pytest.importorskip("alibabacloud_credentials") +pytest.importorskip("alibabacloud_openapi_util") + +from dashscope.management import ( # noqa: E402 + AsyncManagementClient, + BillingOverview, + ManagementClient, + ManagementModel, + TokenPage, + TokenPlanAccount, + Workspace, +) + +# A gateway signature rejection means the SDK signed wrong -- a real bug. +# Every other business error is environmental (eligibility / permission), +# so the case skips instead of failing. +_SIGNATURE_ERROR_CODES = frozenset( + { + "SignatureDoesNotMatch", + "InvalidSignature", + "IncompleteSignature", + }, +) + + +def _creds(): + ak = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID") or os.environ.get( + "DASHSCOPE_MGMT_AK", + ) + sk = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET") or os.environ.get( + "DASHSCOPE_MGMT_SK", + ) + if not ak or not sk: + pytest.skip("RAM access key id / secret not set") + token = os.environ.get("ALIBABA_CLOUD_SECURITY_TOKEN") or os.environ.get( + "DASHSCOPE_MGMT_STS_TOKEN", + ) + return ak, sk, token + + +def _region(): + return ( + os.environ.get("DASHSCOPE_MGMT_REGION") + or os.environ.get("ALIBABA_CLOUD_REGION") + or "cn-beijing" + ) + + +def _make_client(): + ak, sk, token = _creds() + return ManagementClient( + access_key_id=ak, + access_key_secret=sk, + security_token=token, + region=_region(), + max_retries=1, + raise_on_error=False, + ) + + +def _make_async_client(): + ak, sk, token = _creds() + return AsyncManagementClient( + access_key_id=ak, + access_key_secret=sk, + security_token=token, + region=_region(), + max_retries=1, + raise_on_error=False, + ) + + +def _assert_accepted(result): + """Fail on a rejected signature, skip on other business errors.""" + if result.is_error: + if result.code in _SIGNATURE_ERROR_CODES: + pytest.fail( + f"V3 signature rejected by gateway: " + f"{result.code} {result.message}", + ) + pytest.skip( + f"account not eligible for this read op: " + f"{result.code} {result.message}", + ) + assert result.request_id, "gateway response carried no request id" + + +def test_list_workspaces(): + with _make_client() as client: + page = client.workspaces.list(max_results=10) + _assert_accepted(page) + assert isinstance(page, TokenPage) + for workspace in page: + assert isinstance(workspace, Workspace) + + +def test_list_models(): + with _make_client() as client: + page = client.workspaces.models.list(max_results=10) + _assert_accepted(page) + assert isinstance(page, TokenPage) + for model in page: + assert isinstance(model, ManagementModel) + + +def test_billing_overview(): + with _make_client() as client: + overview = client.billing.overview() + _assert_accepted(overview) + assert isinstance(overview, BillingOverview) + + +def test_token_plan_account(): + with _make_client() as client: + account = client.token_plan.account.get() + _assert_accepted(account) + assert isinstance(account, TokenPlanAccount) + + +async def test_async_list_models(): + async with _make_async_client() as client: + page = await client.workspaces.models.list(max_results=10) + _assert_accepted(page) + assert isinstance(page, TokenPage) + for model in page: + assert isinstance(model, ManagementModel) diff --git a/tests/test_management_api_keys.py b/tests/test_management_api_keys.py new file mode 100644 index 00000000..544ae068 --- /dev/null +++ b/tests/test_management_api_keys.py @@ -0,0 +1,143 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""``client.api_keys`` read tests -- SecretStr redaction is the focus.""" + +from __future__ import annotations + +import json +import logging + +import httpx +import pytest + +# pylint: disable=wrong-import-position +pytest.importorskip("alibabacloud_credentials") +pytest.importorskip("alibabacloud_openapi_util") + +from dashscope.management._redaction import ( # noqa: E402 + SecretRedactionFilter, + mask_secret, +) +from dashscope.management.types import ApiKey # noqa: E402 +from dashscope.transport._response import APIResponse # noqa: E402 + +from tests.management_helpers import ( # noqa: E402 + action_handler, + make_async_client, + make_client, + ms_body, +) + +SECRET = "sk-PLAINTEXTSECRET123456" +BODIES = { + "ListApiKeys": ms_body( + apiKeys=[ + {"apiKeyId": 1, "apiKeyValue": SECRET, "workspaceId": "ws-1"}, + ], + totalCount=1, + ), + "GetApiKey": ms_body( + apiKey={"apiKeyId": 1, "apiKeyValue": SECRET, "description": "demo"}, + ), +} + + +def test_list_typed_and_masked_repr(): + client = make_client(action_handler(BODIES)) + page = client.api_keys.list() + key = page.items[0] + assert isinstance(key, ApiKey) + assert key.api_key_id == 1 + assert SECRET not in repr(key) + assert SECRET not in str(key) + client.close() + + +def test_get_path_substitution_and_masking(): + seen = [] + + def handler(request): + seen.append(request) + return httpx.Response(200, json=BODIES["GetApiKey"]) + + client = make_client(handler) + key = client.api_keys.get(1) + assert seen[0].url.path == "/modelstudio/apikeys/1" + assert seen[0].headers["x-acs-action"] == "GetApiKey" + assert key.description == "demo" + assert SECRET not in repr(key) + client.close() + + +def test_secret_value_only_via_get_secret_value(): + client = make_client(action_handler(BODIES)) + key = client.api_keys.get(1) + assert key.api_key_value.get_secret_value() == SECRET + client.close() + + +def test_model_dump_masks_secret(): + client = make_client(action_handler(BODIES)) + key = client.api_keys.get(1) + dumped = json.dumps(key.model_dump(), default=str) + assert SECRET not in dumped + assert "**********" in dumped + client.close() + + +def test_model_dump_mode_json_masks_secret(): + client = make_client(action_handler(BODIES)) + key = client.api_keys.get(1) + dumped = key.model_dump(mode="json") + assert SECRET not in json.dumps(dumped) + client.close() + + +def test_logging_model_repr_does_not_leak(caplog): + client = make_client(action_handler(BODIES)) + key = client.api_keys.get(1) + logger = logging.getLogger("test.management.apikeys") + with caplog.at_level(logging.INFO, logger="test.management.apikeys"): + logger.info("fetched key %r", key) + assert SECRET not in caplog.text + client.close() + + +def test_redaction_filter_masks_free_text_sk_token(): + filt = SecretRedactionFilter() + record = logging.LogRecord( + "t", + logging.INFO, + __file__, + 1, + "key is %s", + (SECRET,), + None, + ) + assert filt.filter(record) is True + assert SECRET not in record.getMessage() + assert mask_secret(SECRET) in record.getMessage() + + +def test_mask_secret_short_fully_masked(): + assert mask_secret("short") == "***" + assert mask_secret(SECRET) == "***" + SECRET[-4:] + + +def test_raw_overload(): + client = make_client(action_handler(BODIES)) + resp = client.api_keys.get(1, raw=True) + assert isinstance(resp, APIResponse) + # The raw body still carries the plaintext -- caller's responsibility. + assert resp.http_response.json()["apiKey"]["apiKeyValue"] == SECRET + client.close() + + +async def test_async_list_and_get_masked(): + client = make_async_client(action_handler(BODIES)) + page = await client.api_keys.list() + assert SECRET not in repr(page.items[0]) + key = await client.api_keys.get(1) + assert key.api_key_value.get_secret_value() == SECRET + assert SECRET not in repr(key) + await client.aclose() diff --git a/tests/test_management_billing.py b/tests/test_management_billing.py new file mode 100644 index 00000000..676dcbf7 --- /dev/null +++ b/tests/test_management_billing.py @@ -0,0 +1,118 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""``client.billing`` read tests (overview + trend, sync + async).""" + +from __future__ import annotations + +import httpx +import pytest + +# pylint: disable=wrong-import-position +pytest.importorskip("alibabacloud_credentials") +pytest.importorskip("alibabacloud_openapi_util") + +from dashscope.management.types import ( # noqa: E402 + BillingOverview, + BillingTrend, +) +from dashscope.transport._response import APIResponse # noqa: E402 + +from tests.management_helpers import ( # noqa: E402 + action_handler, + make_async_client, + make_client, + ms_body, + query_of, +) + +BODIES = { + "GetBillingOverview": ms_body( + data={ + "currency": "CNY", + "totalAmount": "12.50", + "groups": [{"key": "g1", "name": "model", "amount": "12.50"}], + }, + ), + "GetBillingTrend": ms_body( + data={ + "costTotals": {"amount": "30.00", "currency": "CNY"}, + "groupByTotal": [{"key": "g1", "amount": "30.00"}], + "resultByTime": [{"period": "2026-02", "total": "30.00"}], + }, + ), +} + + +def test_overview_typed(): + client = make_client(action_handler(BODIES)) + overview = client.billing.overview(bill_month="2026-02") + assert isinstance(overview, BillingOverview) + assert overview.total_amount == "12.50" + assert overview.currency == "CNY" + assert overview.groups[0].key == "g1" + assert overview.is_error is False + client.close() + + +def test_trend_typed(): + client = make_client(action_handler(BODIES)) + trend = client.billing.trend(granularity="MONTHLY") + assert isinstance(trend, BillingTrend) + assert trend.cost_totals.amount == "30.00" + assert trend.group_by_total[0].amount == "30.00" + assert trend.result_by_time[0].period == "2026-02" + client.close() + + +def test_overview_bool_and_json_query(): + seen = [] + + def handler(request): + seen.append(request) + return httpx.Response(200, json=BODIES["GetBillingOverview"]) + + client = make_client(handler) + client.billing.overview( + zero_filter=True, + group_by=["model"], + filter_={"workspaceId": "ws-1"}, + time_period={"start": "2026-02-01", "end": "2026-02-28"}, + ) + q = query_of(seen[0]) + assert q["zeroFilter"] == "true" + assert q["groupBy"] == '["model"]' + assert q["filter"] == '{"workspaceId":"ws-1"}' + assert q["timePeriod"] == '{"start":"2026-02-01","end":"2026-02-28"}' + assert seen[0].url.path == "/modelstudio/billing/overview" + client.close() + + +def test_trend_include_history_bool_false(): + seen = [] + + def handler(request): + seen.append(request) + return httpx.Response(200, json=BODIES["GetBillingTrend"]) + + client = make_client(handler) + client.billing.trend(include_history_period=False, zero_filter=False) + q = query_of(seen[0]) + assert q["includeHistoryPeriod"] == "false" + assert q["zeroFilter"] == "false" + client.close() + + +def test_overview_raw_overload(): + client = make_client(action_handler(BODIES)) + resp = client.billing.overview(raw=True) + assert isinstance(resp, APIResponse) + client.close() + + +async def test_async_overview_and_trend(): + client = make_async_client(action_handler(BODIES)) + overview = await client.billing.overview() + assert overview.total_amount == "12.50" + trend = await client.billing.trend() + assert trend.cost_totals.amount == "30.00" + await client.aclose() diff --git a/tests/test_management_credentials.py b/tests/test_management_credentials.py new file mode 100644 index 00000000..78e4fe22 --- /dev/null +++ b/tests/test_management_credentials.py @@ -0,0 +1,134 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Credential-chain resolution tests for the management surface.""" + +from __future__ import annotations + +import logging +from types import SimpleNamespace + +import pytest + +# pylint: disable=wrong-import-position +pytest.importorskip("alibabacloud_credentials") +pytest.importorskip("alibabacloud_openapi_util") + +from dashscope.management._credentials import ( # noqa: E402 + CredentialResolver, + ResolvedCredential, +) + +AK = "ak-test" +SK = "sk-test" +TOKEN = "sts-token-test" + + +class _FakeCredentialClient: + """Stands in for a pre-built alibabacloud credentials Client.""" + + def __init__(self, ak="fake-ak", sk="fake-sk", token=None, provider=None): + self._model = SimpleNamespace( + access_key_id=ak, + access_key_secret=sk, + security_token=token, + provider_name=provider, + ) + + def get_credential(self): + return self._model + + async def get_credential_async(self): + return self._model + + +def test_access_key_resolution(): + resolver = CredentialResolver(access_key_id=AK, access_key_secret=SK) + cred = resolver.resolve() + assert isinstance(cred, ResolvedCredential) + assert cred.access_key_id == AK + assert cred.access_key_secret == SK + assert cred.security_token is None + + +def test_sts_resolution_carries_token(): + resolver = CredentialResolver( + access_key_id=AK, + access_key_secret=SK, + security_token=TOKEN, + ) + cred = resolver.resolve() + assert cred.security_token == TOKEN + + +def test_config_dict_resolution(): + resolver = CredentialResolver( + config={ + "type": "access_key", + "access_key_id": AK, + "access_key_secret": SK, + }, + ) + cred = resolver.resolve() + assert cred.access_key_id == AK + assert cred.access_key_secret == SK + + +def test_prebuilt_credential_wins_over_ak(): + fake = _FakeCredentialClient(ak="prebuilt-ak", sk="prebuilt-sk") + resolver = CredentialResolver( + credential=fake, + access_key_id="ignored-ak", + access_key_secret="ignored-sk", + ) + cred = resolver.resolve() + assert cred.access_key_id == "prebuilt-ak" + + +def test_config_wins_over_ak(): + resolver = CredentialResolver( + config={ + "type": "access_key", + "access_key_id": "config-ak", + "access_key_secret": "config-sk", + }, + access_key_id="ignored-ak", + access_key_secret="ignored-sk", + ) + assert resolver.resolve().access_key_id == "config-ak" + + +def test_provider_name_propagates(): + fake = _FakeCredentialClient(provider="ecs_ram_role") + cred = CredentialResolver(credential=fake).resolve() + assert cred.provider_name == "ecs_ram_role" + + +async def test_resolve_async_matches_sync(): + resolver = CredentialResolver(access_key_id=AK, access_key_secret=SK) + sync_cred = resolver.resolve() + async_cred = await resolver.resolve_async() + assert async_cred == sync_cred + + +async def test_prebuilt_credential_async(): + fake = _FakeCredentialClient(ak="async-ak", token=TOKEN) + cred = await CredentialResolver(credential=fake).resolve_async() + assert cred.access_key_id == "async-ak" + assert cred.security_token == TOKEN + + +def test_secret_never_logged(caplog): + resolver = CredentialResolver(access_key_id=AK, access_key_secret=SK) + with caplog.at_level(logging.DEBUG): + resolver.resolve() + assert SK not in caplog.text + assert AK not in caplog.text + + +def test_snapshot_is_frozen(): + cred = CredentialResolver( + access_key_id=AK, + access_key_secret=SK, + ).resolve() + with pytest.raises(Exception): + cred.access_key_id = "mutated" diff --git a/tests/test_management_errors.py b/tests/test_management_errors.py new file mode 100644 index 00000000..31cc245f --- /dev/null +++ b/tests/test_management_errors.py @@ -0,0 +1,191 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""RAM error crosswalk + success-gate tests for the management surface.""" + +from __future__ import annotations + +import httpx +import pytest + +# pylint: disable=wrong-import-position +pytest.importorskip("alibabacloud_credentials") +pytest.importorskip("alibabacloud_openapi_util") + +from dashscope.errors import ( # noqa: E402 + AuthenticationError, + BadRequestError, + InternalServerError, + NotFoundError, + PermissionDeniedError, + RateLimitError, + ServiceUnavailableError, +) +from dashscope.management._errors import ( # noqa: E402 + check_management_response, + management_error, + read_envelope, +) +from dashscope.management._redaction import REDACTED # noqa: E402 + + +def _response(body, status=200, headers=None): + return httpx.Response(status, json=body, headers=headers or {}) + + +# --- success gate --------------------------------------------------------- + + +def test_http200_code200_success_true_is_not_error(): + body = {"code": "200", "success": True, "requestId": "r1"} + env = read_envelope(body, 200) + assert env.success is True + assert check_management_response(_response(body)) is None + + +def test_tokenplan_success_true_is_not_error(): + body = {"Success": True, "Code": "200", "RequestId": "r2"} + assert read_envelope(body, 200).success is True + + +def test_success_false_is_error_even_at_http200(): + body = {"code": "200", "success": False, "message": "boom"} + env = read_envelope(body, 200) + assert env.success is False + + +def test_no_flag_success_code_at_http200_is_success(): + assert read_envelope({"code": "OK"}, 200).success is True + assert read_envelope({}, 200).success is True + + +def test_no_flag_non_success_code_at_http200_is_error(): + assert read_envelope({"code": "500"}, 200).success is False + + +def test_non_2xx_without_flag_is_error(): + assert read_envelope({}, 500).success is False + + +def test_request_id_normalized_both_casings(): + assert read_envelope({"requestId": "a"}, 200).request_id == "a" + assert read_envelope({"RequestId": "b"}, 200).request_id == "b" + + +def test_non_dict_body_degrades_to_empty(): + assert read_envelope(["not", "a", "dict"], 200).success is True + assert read_envelope(None, 500).success is False + + +# --- crosswalk by code ---------------------------------------------------- + + +@pytest.mark.parametrize( + "code,expected", + [ + ("Throttling.User", RateLimitError), + ("Throttling", RateLimitError), + ("InvalidAccessKeyId", AuthenticationError), + ("InvalidAccessKeyId.NotFound", AuthenticationError), + ("SignatureDoesNotMatch", AuthenticationError), + ("InvalidSecurityToken.Expired", AuthenticationError), + ("Forbidden.RAM", PermissionDeniedError), + ("NoPermission", PermissionDeniedError), + ("WorkspaceNotExist", NotFoundError), + ("ResourceNotFound", NotFoundError), + ("InvalidParameter.WorkspaceId", BadRequestError), + ], +) +def test_crosswalk_by_code(code, expected): + env = read_envelope({"code": code, "success": False}, 400) + assert isinstance(management_error(env), expected) + + +@pytest.mark.parametrize( + "status,expected", + [ + (401, AuthenticationError), + (403, PermissionDeniedError), + (404, NotFoundError), + (429, RateLimitError), + (500, InternalServerError), + (503, ServiceUnavailableError), + (400, BadRequestError), + ], +) +def test_crosswalk_by_status(status, expected): + env = read_envelope({}, status) + assert isinstance(management_error(env), expected) + + +def test_code_takes_precedence_over_status(): + env = read_envelope({"Code": "Throttling.User"}, 500) + assert isinstance(management_error(env), RateLimitError) + + +def test_gateway_error_without_success_flag(): + body = { + "Code": "InvalidAccessKeyId", + "Message": "ak not found", + "RequestId": "gw-1", + "Recommend": "https://example", + "HostId": "modelstudio.cn-beijing.aliyuncs.com", + } + err = check_management_response(_response(body, 404), raise_on_error=False) + assert isinstance(err, AuthenticationError) + assert err.request_id == "gw-1" + assert err.code == "InvalidAccessKeyId" + + +# --- raise vs return ------------------------------------------------------ + + +def test_check_raises_by_default(): + body = {"success": False, "code": "Forbidden", "message": "no"} + with pytest.raises(PermissionDeniedError): + check_management_response(_response(body, 403)) + + +def test_check_returns_error_when_not_raising(): + body = {"success": False, "code": "Forbidden", "message": "no"} + err = check_management_response( + _response(body, 403), + raise_on_error=False, + ) + assert isinstance(err, PermissionDeniedError) + assert err.message == "no" + + +# --- redaction ------------------------------------------------------------ + + +def test_error_body_redacts_secret_keys(): + body = { + "success": False, + "code": "InvalidParameter", + "apiKeyValue": "sk-PLAINTEXTSECRET123", + "nested": {"AccessKeySecret": "super-secret-value"}, + } + env = read_envelope(body, 400) + err = management_error(env) + assert err.body["apiKeyValue"] == REDACTED + assert err.body["nested"]["AccessKeySecret"] == REDACTED + assert "sk-PLAINTEXTSECRET123" not in str(err.body) + assert "super-secret-value" not in str(err.body) + + +def test_redaction_does_not_mutate_original(): + body = {"apiKeyValue": "sk-PLAINTEXTSECRET123", "success": False} + env = read_envelope(body, 400) + management_error(env) + assert body["apiKeyValue"] == "sk-PLAINTEXTSECRET123" + + +def test_error_message_and_status_threaded(): + env = read_envelope( + {"success": False, "code": "Throttling", "message": "slow down"}, + 429, + ) + err = management_error(env, headers={"x-request-id": "h1"}) + assert err.status_code == 429 + assert err.message == "slow down" + assert err.code == "Throttling" diff --git a/tests/test_management_pagination.py b/tests/test_management_pagination.py new file mode 100644 index 00000000..e85d87fe --- /dev/null +++ b/tests/test_management_pagination.py @@ -0,0 +1,159 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Dual-pagination traversal tests: TokenPage (nextToken) + BasePage (PageNo).""" + +from __future__ import annotations + +import httpx +import pytest + +# pylint: disable=wrong-import-position +pytest.importorskip("alibabacloud_credentials") +pytest.importorskip("alibabacloud_openapi_util") + +from tests.management_helpers import ( # noqa: E402 + make_async_client, + make_client, + ms_body, + query_of, + tp_body, +) + + +def _token_handler(seen): + """Three single-item pages chained by nextToken t2 -> t3 -> None.""" + pages = { + None: ("ws-1", "t2"), + "t2": ("ws-2", "t3"), + "t3": ("ws-3", None), + } + + def handler(request): + q = query_of(request) + seen.append(q) + ws, nxt = pages[q.get("nextToken")] + return httpx.Response( + 200, + json=ms_body( + workspaces=[{"workspaceId": ws}], + nextToken=nxt, + maxResults=1, + totalCount=3, + ), + ) + + return handler + + +def test_token_page_iter_current_only(): + seen = [] + client = make_client(_token_handler(seen)) + page = client.workspaces.list(max_results=1) + assert [w.workspace_id for w in page] == ["ws-1"] + assert len(seen) == 1 # iterating does not fetch ahead + client.close() + + +def test_token_page_iter_pages_crosses_all(): + seen = [] + client = make_client(_token_handler(seen)) + page = client.workspaces.list(max_results=1) + all_ids = [w.workspace_id for pg in page.iter_pages() for w in pg] + assert all_ids == ["ws-1", "ws-2", "ws-3"] + assert len(seen) == 3 + client.close() + + +def test_token_page_next_page_and_has_next(): + seen = [] + client = make_client(_token_handler(seen)) + page = client.workspaces.list(max_results=1) + assert page.has_next_page() is True + second = page.next_page() + assert [w.workspace_id for w in second] == ["ws-2"] + third = second.next_page() + assert [w.workspace_id for w in third] == ["ws-3"] + assert third.has_next_page() is False + client.close() + + +def test_token_page_forwards_filters_across_pages(): + seen = [] + client = make_client(_token_handler(seen)) + page = client.workspaces.list(max_results=1, workspace_name="demo") + list(page.iter_pages()) + assert all(q.get("workspaceName") == "demo" for q in seen) + client.close() + + +def _page_handler(seen): + """Three single-item member pages by PageNum, Total=3.""" + + def handler(request): + q = query_of(request) + seen.append(q) + no = int(q.get("PageNum", "1")) + return httpx.Response( + 200, + json=tp_body( + Data=[{"AccountId": f"m{no}"}], + PageNo=no, + PageSize=1, + Total=3, + ), + ) + + return handler + + +def test_base_page_iter_pages_crosses_all(): + seen = [] + client = make_client(_page_handler(seen)) + page = client.token_plan.members.list(page_size=1) + all_ids = [m.account_id for pg in page.iter_pages() for m in pg] + assert all_ids == ["m1", "m2", "m3"] + assert len(seen) == 3 + client.close() + + +def test_base_page_next_page_and_has_next(): + seen = [] + client = make_client(_page_handler(seen)) + page = client.token_plan.members.list(page_size=1) + assert page.has_next_page() is True + second = page.next_page() + assert [m.account_id for m in second] == ["m2"] + third = second.next_page() + assert third.has_next_page() is False + client.close() + + +def test_base_page_forwards_filters_across_pages(): + seen = [] + client = make_client(_page_handler(seen)) + page = client.token_plan.members.list(page_size=1, name="alice") + list(page.iter_pages()) + assert all(q.get("Name") == "alice" for q in seen) + client.close() + + +async def test_async_token_page_iter_pages(): + seen = [] + client = make_async_client(_token_handler(seen)) + page = await client.workspaces.list(max_results=1) + all_ids = [ + w.workspace_id async for pg in page.iter_pages_async() for w in pg + ] + assert all_ids == ["ws-1", "ws-2", "ws-3"] + await client.aclose() + + +async def test_async_base_page_iter_pages(): + seen = [] + client = make_async_client(_page_handler(seen)) + page = await client.token_plan.members.list(page_size=1) + all_ids = [ + m.account_id async for pg in page.iter_pages_async() for m in pg + ] + assert all_ids == ["m1", "m2", "m3"] + await client.aclose() diff --git a/tests/test_management_signer.py b/tests/test_management_signer.py new file mode 100644 index 00000000..f666e370 --- /dev/null +++ b/tests/test_management_signer.py @@ -0,0 +1,254 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""V3 ACS3-HMAC-SHA256 signing tests for the management surface. + +The oracle here recomputes the signature the way the aliyun gateway does +-- from the *wire* URL and headers, with hashlib/hmac directly, independent +of openapi_util -- so a drift between what we sign and what we send fails +loudly. A second check compares against openapi_util.get_authorization. +""" + +from __future__ import annotations + +import hashlib +import hmac +from urllib.parse import urlsplit + +import pytest + +# pylint: disable=wrong-import-position +pytest.importorskip("alibabacloud_credentials") +pytest.importorskip("alibabacloud_openapi_util") + +from alibabacloud_openapi_util.client import ( # noqa: E402 + Client as OpenApiUtil, +) +from alibabacloud_openapi_util.client import ( # noqa: E402 + get_canonical_query_string, +) + +from dashscope.management import _signer # noqa: E402 +from dashscope.management._credentials import ResolvedCredential # noqa: E402 +from dashscope.management._signer import sign_request # noqa: E402 + +AK = "ak-test" +SK = "sk-test" +HOST = "modelstudio.cn-beijing.aliyuncs.com" +SDK_HEADERS = { + "x-dashscope-sdk-client": "python-sdk/2.0.0/management2", + "x-dashscope-sdk-session-id": "sess-test", + "x-dashscope-client-request-id": "crid-test", +} + + +def _credential(token=None, provider=None): + return ResolvedCredential( + access_key_id=AK, + access_key_secret=SK, + security_token=token, + provider_name=provider, + ) + + +def _sign(**kw): + params = { + "method": "GET", + "host": HOST, + "path": "/modelstudio/workspaces", + "action": "ListWorkspaces", + "query": None, + "body": None, + "credential": _credential(), + "user_agent": "dashscope-sdk-python/2.0.0 management", + "sdk_headers": SDK_HEADERS, + } + params.update(kw) + return sign_request(**params) + + +def _gateway_recompute(signed, ak=AK, sk=SK): + """Independently rebuild the Authorization from the wire form.""" + parts = urlsplit(signed.url) + canonical_uri = parts.path + canonical_query = parts.query + headers = { + k.lower(): v + for k, v in signed.headers.items() + if k.lower() != "authorization" + } + keys = sorted(headers) + canonical_headers = "".join( + f"{k}:{str(headers[k]).strip()}\n" for k in keys + ) + signed_headers = ";".join(keys) + payload = headers["x-acs-content-sha256"] + canonical_request = ( + f"{signed.method}\n{canonical_uri}\n{canonical_query}\n" + f"{canonical_headers}\n{signed_headers}\n{payload}" + ) + hashed = hashlib.sha256(canonical_request.encode("utf-8")).hexdigest() + string_to_sign = f"ACS3-HMAC-SHA256\n{hashed}" + signature = hmac.new( + sk.encode("utf-8"), + string_to_sign.encode("utf-8"), + hashlib.sha256, + ).hexdigest() + return ( + f"ACS3-HMAC-SHA256 Credential={ak}," + f"SignedHeaders={signed_headers},Signature={signature}" + ) + + +def _signed_header_set(signed): + auth = signed.headers["authorization"] + fragment = auth.split("SignedHeaders=", 1)[1].split(",", 1)[0] + return set(fragment.split(";")) + + +def test_signature_matches_gateway_oracle(monkeypatch): + monkeypatch.setattr( + _signer, + "_utc_timestamp", + lambda: "2026-02-10T00:00:00Z", + ) + signed = _sign(query={"maxResults": 10, "workspaceName": "demo"}) + assert signed.headers["authorization"] == _gateway_recompute(signed) + + +def test_signature_matches_openapi_util_oracle(): + signed = _sign(query={"maxResults": 10}) + parts = urlsplit(signed.url) + headers = { + k: v for k, v in signed.headers.items() if k.lower() != "authorization" + } + shim = type( + "Shim", + (), + { + "method": signed.method, + "pathname": parts.path, + "query": dict( + pair.split("=", 1) for pair in parts.query.split("&") + ), + "headers": headers, + }, + )() + expected = OpenApiUtil.get_authorization( + shim, + "ACS3-HMAC-SHA256", + headers["x-acs-content-sha256"], + AK, + SK, + ) + assert signed.headers["authorization"] == expected + + +def test_signed_headers_equal_sent_headers(): + signed = _sign(query={"maxResults": 5}) + sent = {k.lower() for k in signed.headers if k.lower() != "authorization"} + assert _signed_header_set(signed) == sent + + +def test_sdk_headers_are_signed(): + signed = _sign() + signed_set = _signed_header_set(signed) + assert "x-dashscope-sdk-client" in signed_set + assert "x-dashscope-sdk-session-id" in signed_set + assert signed.headers["x-dashscope-sdk-client"].endswith("management2") + + +def test_special_char_query_wire_matches_canonical(): + token = "abc=+/def~ghi jkl" + signed = _sign(query={"nextToken": token, "maxResults": 10}) + parts = urlsplit(signed.url) + flat = OpenApiUtil.query({"nextToken": token, "maxResults": "10"}) + canonical = get_canonical_query_string(flat) + assert parts.query == canonical + assert signed.headers["authorization"] == _gateway_recompute(signed) + + +def test_path_is_encoded(): + signed = _sign(path="/modelstudio/apikeys/123", action="GetApiKey") + assert urlsplit(signed.url).path == "/modelstudio/apikeys/123" + encoded = _sign(path="/modelstudio/a b/c~d") + assert urlsplit(encoded.url).path == OpenApiUtil.get_encode_path( + "/modelstudio/a b/c~d", + ) + + +def test_bool_query_lowercased_on_wire(): + signed = _sign( + action="GetBillingOverview", + path="/modelstudio/billing/overview", + query={"zeroFilter": True, "includeHistoryPeriod": False}, + ) + query = urlsplit(signed.url).query + assert "zeroFilter=true" in query + assert "includeHistoryPeriod=false" in query + assert "True" not in query and "False" not in query + + +def test_sts_token_headers_present_and_signed(): + signed = _sign(credential=_credential(token="sts-token-test")) + assert signed.headers["x-acs-security-token"] == "sts-token-test" + assert signed.headers["x-acs-accesskey-id"] == AK + signed_set = _signed_header_set(signed) + assert "x-acs-security-token" in signed_set + assert signed.headers["authorization"] == _gateway_recompute(signed) + + +def test_credentials_provider_header_when_named(): + signed = _sign(credential=_credential(provider="ecs_ram_role")) + assert signed.headers["x-acs-credentials-provider"] == "ecs_ram_role" + assert "x-acs-credentials-provider" in _signed_header_set(signed) + + +def test_empty_body_payload_hash(): + signed = _sign() + assert ( + signed.headers["x-acs-content-sha256"] + == hashlib.sha256( + b"", + ).hexdigest() + ) + assert signed.content is None + assert "content-type" not in signed.headers + + +def test_json_body_payload_hash_and_content_type(): + body = b'{"workspaceName":"demo"}' + signed = _sign(method="POST", body=body) + assert ( + signed.headers["x-acs-content-sha256"] + == hashlib.sha256( + body, + ).hexdigest() + ) + assert signed.headers["content-type"] == "application/json" + assert signed.content == body + assert signed.headers["authorization"] == _gateway_recompute(signed) + + +def test_extra_headers_merged_before_signing(): + signed = _sign(extra_headers={"X-Custom": "v"}) + assert signed.headers["x-custom"] == "v" + assert "x-custom" in _signed_header_set(signed) + assert signed.headers["authorization"] == _gateway_recompute(signed) + + +def test_authorization_format(): + signed = _sign() + auth = signed.headers["authorization"] + assert auth.startswith(f"ACS3-HMAC-SHA256 Credential={AK},") + signature = auth.split("Signature=", 1)[1] + assert len(signature) == 64 + int(signature, 16) # valid hex + + +def test_acs_version_and_action_headers(): + signed = _sign(action="ListWorkspaces") + assert signed.headers["x-acs-version"] == "2026-02-10" + assert signed.headers["x-acs-action"] == "ListWorkspaces" + assert signed.headers["host"] == HOST + assert signed.headers["x-acs-date"] + assert signed.headers["x-acs-signature-nonce"] diff --git a/tests/test_management_token_plan.py b/tests/test_management_token_plan.py new file mode 100644 index 00000000..302fa1a7 --- /dev/null +++ b/tests/test_management_token_plan.py @@ -0,0 +1,204 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""``client.token_plan`` read tests (G5, sync + async).""" + +from __future__ import annotations + +import httpx +import pytest + +# pylint: disable=wrong-import-position +pytest.importorskip("alibabacloud_credentials") +pytest.importorskip("alibabacloud_openapi_util") + +from dashscope.management.types import ( # noqa: E402 + OrgMember, + OrgMemberPage, + Seat, + SeatPage, + SeatStats, + SharedPackage, + SharedPackagePage, + SubscriptionStats, + TokenPlanAccount, +) +from dashscope.transport._response import APIResponse # noqa: E402 + +from tests.management_helpers import ( # noqa: E402 + action_handler, + make_async_client, + make_client, + query_of, + tp_body, +) + +BODIES = { + "GetTokenPlanAccountDetail": tp_body( + Data={ + "AccountId": "acc-1", + "Name": "demo-org", + "OrgMemberships": [{"OrgId": "org-1", "RoleCode": "owner"}], + }, + ), + "ListOrganizationMembers": tp_body( + Data=[ + { + "AccountId": "m1", + "MaskedApiKey": "sk-***abc", + "Status": "active", + }, + ], + PageNo=1, + PageSize=20, + Total=1, + ), + "GetSubscriptionSeatDetails": tp_body( + Data={ + "Items": [{"SeatId": "s1", "SpecType": "basic"}], + "PageNo": 1, + "PageSize": 20, + "Total": 1, + }, + ), + "GetOrganizationMemberSeatStats": { + "OrgId": "org-1", + "TotalMemberCount": 5, + "SeatedMemberCount": 3, + }, + "GetSubscriptionStats": tp_body( + Data={ + "SubscriptionStartTime": 1700000000, + "Items": [{"SeatType": "basic", "TotalSeats": 5}], + }, + ), + "ListSubscriptionSharedPackages": tp_body( + Data={ + "Items": [{"InstanceCode": "p1", "Status": "active"}], + "PageNo": 1, + "PageSize": 20, + "Total": 1, + }, + ), +} + + +def test_account_get_typed(): + client = make_client(action_handler(BODIES)) + account = client.token_plan.account.get() + assert isinstance(account, TokenPlanAccount) + assert account.account_id == "acc-1" + assert account.org_memberships[0].org_id == "org-1" + assert account.is_error is False + client.close() + + +def test_members_root_array_page(): + client = make_client(action_handler(BODIES)) + page = client.token_plan.members.list() + assert isinstance(page, OrgMemberPage) + assert isinstance(page.items[0], OrgMember) + assert page.items[0].account_id == "m1" + assert page.items[0].masked_api_key == "sk-***abc" + assert page.page_no == 1 + assert page.total_count == 1 + client.close() + + +def test_members_wire_pascal_and_bool(): + seen = [] + + def handler(request): + seen.append(request) + return httpx.Response(200, json=BODIES["ListOrganizationMembers"]) + + client = make_client(handler) + client.token_plan.members.list(name="alice", has_seat=True, page_num=2) + q = query_of(seen[0]) + assert q["Name"] == "alice" + assert q["HasSeat"] == "true" + assert q["PageNum"] == "2" + assert seen[0].url.path == "/tokenplan/organization/members" + client.close() + + +def test_seats_nested_page(): + client = make_client(action_handler(BODIES)) + page = client.token_plan.seats.list() + assert isinstance(page, SeatPage) + assert isinstance(page.items[0], Seat) + assert page.items[0].seat_id == "s1" + assert page.total_count == 1 + client.close() + + +def test_seats_flat_status_list_query(): + seen = [] + + def handler(request): + seen.append(request) + return httpx.Response(200, json=BODIES["GetSubscriptionSeatDetails"]) + + client = make_client(handler) + client.token_plan.seats.list( + status_list=["active", "expired"], + query_assigned=True, + ) + q = query_of(seen[0]) + assert q["StatusList.1"] == "active" + assert q["StatusList.2"] == "expired" + assert q["QueryAssigned"] == "true" + client.close() + + +def test_seat_stats_bare_root(): + client = make_client(action_handler(BODIES)) + stats = client.token_plan.seats.stats() + assert isinstance(stats, SeatStats) + assert stats.org_id == "org-1" + assert stats.total_member_count == 5 + assert stats.seated_member_count == 3 + assert stats.is_error is False + client.close() + + +def test_subscription_stats_typed(): + client = make_client(action_handler(BODIES)) + stats = client.token_plan.subscription.stats() + assert isinstance(stats, SubscriptionStats) + assert stats.subscription_start_time == 1700000000 + assert stats.items[0].seat_type == "basic" + assert stats.items[0].total_seats == 5 + client.close() + + +def test_shared_packages_nested_page(): + client = make_client(action_handler(BODIES)) + page = client.token_plan.shared_packages.list() + assert isinstance(page, SharedPackagePage) + assert isinstance(page.items[0], SharedPackage) + assert page.items[0].instance_code == "p1" + client.close() + + +def test_account_raw_overload(): + client = make_client(action_handler(BODIES)) + resp = client.token_plan.account.get(raw=True) + assert isinstance(resp, APIResponse) + client.close() + + +async def test_async_token_plan_full_surface(): + client = make_async_client(action_handler(BODIES)) + account = await client.token_plan.account.get() + assert account.account_id == "acc-1" + members = await client.token_plan.members.list() + assert members.items[0].account_id == "m1" + seats = await client.token_plan.seats.list() + assert seats.items[0].seat_id == "s1" + stats = await client.token_plan.seats.stats() + assert stats.total_member_count == 5 + sub = await client.token_plan.subscription.stats() + assert sub.items[0].total_seats == 5 + packages = await client.token_plan.shared_packages.list() + assert packages.items[0].instance_code == "p1" + await client.aclose() diff --git a/tests/test_management_transport.py b/tests/test_management_transport.py new file mode 100644 index 00000000..bfc705de --- /dev/null +++ b/tests/test_management_transport.py @@ -0,0 +1,276 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Wire-level transport tests for the management surface (sync + async).""" + +from __future__ import annotations + +import httpx +import pytest + +# pylint: disable=wrong-import-position +pytest.importorskip("alibabacloud_credentials") +pytest.importorskip("alibabacloud_openapi_util") + +from dashscope.errors import APIConnectionError # noqa: E402 +from dashscope.management import _transport # noqa: E402 +from dashscope.management import ( # noqa: E402 + AsyncManagementClient, + ManagementClient, +) + +from tests.management_helpers import ( # noqa: E402 + AK, + SK, + STS_TOKEN, + make_async_client, + make_client, + ms_body, + query_of, +) + +WORKSPACES = ms_body(workspaces=[{"workspaceId": "ws-1"}], totalCount=1) + + +@pytest.fixture(autouse=True) +def _no_sleep(monkeypatch): + monkeypatch.setattr(_transport.time, "sleep", lambda *_: None) + monkeypatch.setattr(_transport.asyncio, "sleep", _async_noop) + + +async def _async_noop(*_): + return None + + +def _capture_handler(record, body=None, status=200): + payload = WORKSPACES if body is None else body + + def handler(request): + record.append(request) + return httpx.Response(status, json=payload) + + return handler + + +# --- wire form ------------------------------------------------------------ + + +def test_wire_method_path_action_version(): + seen = [] + client = make_client(_capture_handler(seen)) + client.workspaces.list(max_results=10) + req = seen[0] + assert req.method == "GET" + assert req.url.path == "/modelstudio/workspaces" + assert req.url.host == "modelstudio.cn-beijing.aliyuncs.com" + assert req.headers["x-acs-action"] == "ListWorkspaces" + assert req.headers["x-acs-version"] == "2026-02-10" + assert query_of(req)["maxResults"] == "10" + client.close() + + +def test_wire_authorization_and_sdk_headers(): + seen = [] + client = make_client(_capture_handler(seen)) + client.workspaces.list() + req = seen[0] + assert req.headers["authorization"].startswith("ACS3-HMAC-SHA256 ") + assert req.headers["x-dashscope-sdk-client"].endswith("management2") + assert req.headers["x-dashscope-sdk-session-id"] + assert req.headers["x-dashscope-client-request-id"] + assert ( + "authorization" + not in req.headers["authorization"].split( + "SignedHeaders=", + )[1] + ) + client.close() + + +def test_no_bearer_authorization(): + seen = [] + client = make_client(_capture_handler(seen)) + client.workspaces.list() + assert "Bearer" not in seen[0].headers["authorization"] + client.close() + + +def test_special_char_next_token_survives_httpx(): + seen = [] + client = make_client(_capture_handler(seen)) + token = "abc=+/def~ghi" + client.workspaces.list(next_token=token) + # httpx must not re-encode the canonical query the signer produced. + assert "nextToken=abc%3D%2B%2Fdef~ghi" in str(seen[0].url) + client.close() + + +def test_sts_token_on_wire(): + seen = [] + client = make_client( + _capture_handler(seen), + security_token=STS_TOKEN, + ) + client.workspaces.list() + assert seen[0].headers["x-acs-security-token"] == STS_TOKEN + assert seen[0].headers["x-acs-accesskey-id"] == AK + client.close() + + +def test_sdk_headers_kill_switch(monkeypatch): + monkeypatch.setenv("DASHSCOPE_DISABLE_SDK_HEADERS", "1") + seen = [] + client = make_client(_capture_handler(seen)) + client.workspaces.list() + assert "x-dashscope-sdk-client" not in seen[0].headers + assert "x-dashscope-client-request-id" not in seen[0].headers + # Still signed and sent correctly without the identity headers. + assert seen[0].headers["authorization"].startswith("ACS3-HMAC-SHA256 ") + client.close() + + +# --- endpoint / region ---------------------------------------------------- + + +def test_default_region_endpoint(): + client = ManagementClient(access_key_id=AK, access_key_secret=SK) + assert client.transport.host == "modelstudio.cn-beijing.aliyuncs.com" + client.close() + + +def test_custom_endpoint_override(): + seen = [] + client = make_client( + _capture_handler(seen), + endpoint="modelstudio-vpc.cn-beijing.aliyuncs.com", + ) + client.workspaces.list() + assert seen[0].url.host == "modelstudio-vpc.cn-beijing.aliyuncs.com" + client.close() + + +def test_with_options_region_changes_endpoint(): + client = ManagementClient(access_key_id=AK, access_key_secret=SK) + other = client.with_options(region="ap-southeast-1") + assert other.transport.host == "modelstudio.ap-southeast-1.aliyuncs.com" + assert other.region == "ap-southeast-1" + # Independent connection pool, shared credential resolver. + assert other.transport.http_client is not client.transport.http_client + assert other._resolver is client._resolver + client.close() + other.close() + + +def test_invalid_region_rejected(): + with pytest.raises(ValueError): + ManagementClient( + access_key_id=AK, + access_key_secret=SK, + region="bad_region!", + ) + + +def test_unknown_safe_region_warns(caplog): + import logging + + with caplog.at_level(logging.WARNING): + client = ManagementClient( + access_key_id=AK, + access_key_secret=SK, + region="cn-shanghai", + ) + assert "cn-shanghai" in caplog.text + client.close() + + +# --- retry ---------------------------------------------------------------- + + +def test_retries_on_429_then_succeeds(): + calls = {"n": 0} + + def handler(request): + calls["n"] += 1 + if calls["n"] < 3: + return httpx.Response(429, json={"code": "Throttling"}) + return httpx.Response(200, json=WORKSPACES) + + client = make_client(handler, max_retries=2) + page = client.workspaces.list() + assert [w.workspace_id for w in page] == ["ws-1"] + assert calls["n"] == 3 + client.close() + + +def test_no_retry_when_max_retries_zero(): + calls = {"n": 0} + + def handler(request): + calls["n"] += 1 + return httpx.Response(503, json={"code": "ServiceUnavailable"}) + + client = make_client(handler, max_retries=0) + with pytest.raises(Exception): + client.workspaces.list() + assert calls["n"] == 1 + client.close() + + +def test_retry_resigns_but_reuses_client_request_id(): + seen = [] + + def handler(request): + seen.append(request) + if len(seen) < 2: + return httpx.Response(500, json={}) + return httpx.Response(200, json=WORKSPACES) + + client = make_client(handler, max_retries=2) + client.workspaces.list() + assert len(seen) == 2 + nonce1 = seen[0].headers["x-acs-signature-nonce"] + nonce2 = seen[1].headers["x-acs-signature-nonce"] + assert nonce1 != nonce2 + assert seen[0].headers["authorization"] != seen[1].headers["authorization"] + crid1 = seen[0].headers["x-dashscope-client-request-id"] + crid2 = seen[1].headers["x-dashscope-client-request-id"] + assert crid1 == crid2 + client.close() + + +def test_connection_error_maps_to_dashscope_error(): + def handler(request): + raise httpx.ConnectError("boom", request=request) + + client = make_client(handler, max_retries=0) + with pytest.raises(APIConnectionError): + client.workspaces.list() + client.close() + + +# --- async ---------------------------------------------------------------- + + +async def test_async_wire_and_retry(): + seen = [] + + def handler(request): + seen.append(request) + if len(seen) < 2: + return httpx.Response(429, json={}) + return httpx.Response(200, json=WORKSPACES) + + client = make_async_client(handler, max_retries=2) + page = await client.workspaces.list() + assert [w.workspace_id for w in page] == ["ws-1"] + assert seen[0].headers["x-acs-action"] == "ListWorkspaces" + assert seen[0].headers["x-dashscope-sdk-client"].endswith("management2") + assert len(seen) == 2 + await client.aclose() + + +async def test_async_with_options_region(): + client = AsyncManagementClient(access_key_id=AK, access_key_secret=SK) + other = client.with_options(region="eu-central-1") + assert other.transport.host == "modelstudio.eu-central-1.aliyuncs.com" + await client.aclose() + await other.aclose() diff --git a/tests/test_management_workspaces.py b/tests/test_management_workspaces.py new file mode 100644 index 00000000..e657f36b --- /dev/null +++ b/tests/test_management_workspaces.py @@ -0,0 +1,188 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""``client.workspaces`` read-resource tests (sync + async).""" + +from __future__ import annotations + +import httpx +import pytest + +# pylint: disable=wrong-import-position +pytest.importorskip("alibabacloud_credentials") +pytest.importorskip("alibabacloud_openapi_util") + +from dashscope.errors import PermissionDeniedError # noqa: E402 +from dashscope.management._pagination import TokenPage # noqa: E402 +from dashscope.management.types import ( # noqa: E402 + ManagementModel, + ModelLimit, + ModelPermission, + Workspace, +) +from dashscope.transport._response import APIResponse # noqa: E402 + +from tests.management_helpers import ( # noqa: E402 + action_handler, + make_async_client, + make_client, + ms_body, + query_of, +) + +BODIES = { + "ListWorkspaces": ms_body( + workspaces=[{"workspaceId": "ws-1", "workspaceName": "demo"}], + nextToken="t2", + maxResults=10, + totalCount=25, + ), + "ListModels": ms_body( + models=[{"model": "qwen-plus", "provider": "dashscope"}], + totalCount=1, + ), + "ListModelLimits": ms_body( + limits=[{"model": "qwen-plus", "workspaceId": "ws-1"}], + totalCount=1, + ), + "ListModelPermissions": ms_body( + list=[{"model": "qwen-plus", "permissions": {"inference": True}}], + totalCount=1, + ), +} + + +def test_workspaces_list_typed_and_paginated(): + client = make_client(action_handler(BODIES)) + page = client.workspaces.list(max_results=10) + assert isinstance(page, TokenPage) + assert isinstance(page.items[0], Workspace) + assert page.items[0].workspace_id == "ws-1" + assert page.items[0].workspace_name == "demo" + assert page.next_token == "t2" + assert page.total_count == 25 + assert page.has_next_page() is True + assert page.is_error is False + assert page.request_id == "req-ms" + client.close() + + +def test_workspaces_list_wire_query(): + seen = [] + + def handler(request): + seen.append(request) + return httpx.Response(200, json=BODIES["ListWorkspaces"]) + + client = make_client(handler) + client.workspaces.list(workspace_name="demo", max_results=10) + q = query_of(seen[0]) + assert q["workspaceName"] == "demo" + assert q["maxResults"] == "10" + assert seen[0].url.path == "/modelstudio/workspaces" + client.close() + + +def test_models_list_json_array_query(): + seen = [] + + def handler(request): + seen.append(request) + return httpx.Response(200, json=BODIES["ListModels"]) + + client = make_client(handler) + page = client.workspaces.models.list(providers=["dashscope"]) + assert isinstance(page.items[0], ManagementModel) + assert page.items[0].model == "qwen-plus" + # json-style array is one JSON-stringified query value. + assert query_of(seen[0])["providers"] == '["dashscope"]' + client.close() + + +def test_model_limits_list_typed(): + client = make_client(action_handler(BODIES)) + page = client.workspaces.model_limits.list(workspace_id="ws-1") + assert isinstance(page.items[0], ModelLimit) + assert page.items[0].workspace_id == "ws-1" + client.close() + + +def test_model_permissions_requires_workspace_id(): + client = make_client(action_handler(BODIES)) + # Mandatory in the signature ... + with pytest.raises(TypeError): + client.workspaces.model_permissions.list() + # ... and rejected by the op registry when explicitly None. + with pytest.raises(ValueError): + client.workspaces.model_permissions.list(workspace_id=None) + client.close() + + +def test_model_permissions_flat_filter_query(): + seen = [] + + def handler(request): + seen.append(request) + return httpx.Response(200, json=BODIES["ListModelPermissions"]) + + client = make_client(handler) + page = client.workspaces.model_permissions.list( + workspace_id="ws-1", + filter_={"model": "qwen-plus"}, + ) + assert isinstance(page.items[0], ModelPermission) + assert page.items[0].permissions.inference is True + q = query_of(seen[0]) + assert q["workspaceId"] == "ws-1" + # flat-style object expands to dotted subkeys via Client.query. + assert q["filter.model"] == "qwen-plus" + client.close() + + +def test_workspaces_raw_overload(): + client = make_client(action_handler(BODIES)) + resp = client.workspaces.list(raw=True) + assert isinstance(resp, APIResponse) + assert resp.http_response.status_code == 200 + client.close() + + +def test_workspaces_error_raises(): + body = {"success": False, "code": "Forbidden", "message": "no"} + client = make_client(action_handler({"ListWorkspaces": body})) + with pytest.raises(PermissionDeniedError): + client.workspaces.list() + client.close() + + +def test_workspaces_error_non_raising_folds_envelope(): + body = {"success": False, "code": "Forbidden", "message": "no"} + client = make_client( + action_handler({"ListWorkspaces": body}), + raise_on_error=False, + ) + page = client.workspaces.list() + assert page.is_error is True + assert page.code == "Forbidden" + assert page.message == "no" + assert page.items == [] + client.close() + + +async def test_async_workspaces_and_subresources(): + client = make_async_client(action_handler(BODIES)) + page = await client.workspaces.list() + assert page.items[0].workspace_id == "ws-1" + models = await client.workspaces.models.list() + assert models.items[0].model == "qwen-plus" + limits = await client.workspaces.model_limits.list() + assert isinstance(limits.items[0], ModelLimit) + perms = await client.workspaces.model_permissions.list(workspace_id="ws-1") + assert isinstance(perms.items[0], ModelPermission) + await client.aclose() + + +async def test_async_workspaces_raw_overload(): + client = make_async_client(action_handler(BODIES)) + resp = await client.workspaces.list(raw=True) + assert isinstance(resp, APIResponse) + await client.aclose() From 586ba3a9565918cc8e6a1bf89e34c87c11ed4aba Mon Sep 17 00:00:00 2001 From: luk384090-cloud Date: Fri, 20 Nov 2026 18:09:00 +0800 Subject: [PATCH 3/5] fix(management): enforce explicit credential completeness to prevent identity swap - Raise error if partial access_key_id or access_key_secret is provided alone - Prevent fallback to ambient host credentials when partial AK is detected - Convert numeric error codes to string to avoid AttributeError in error mapping - Improve secret redaction by matching sk- tokens with regex and applying filter on management loggers - Introduce get_management_logger to attach secret redaction filter to all management loggers - Limit transparent retries to safe HTTP methods to avoid duplicate side effects on write ops - Support per-call timeout overrides and preserve injected client timeout settings in transport - Add tests for partial explicit credential rejection, management logger redaction, retry behavior on write methods, and timeout handling with client and per-call overrides --- dashscope/management/_credentials.py | 14 ++- dashscope/management/_errors.py | 3 + dashscope/management/_redaction.py | 37 ++++++-- dashscope/management/_transport.py | 57 +++++++++--- dashscope/management/client.py | 4 +- tests/test_management_api_keys.py | 61 +++++++++++++ tests/test_management_credentials.py | 29 ++++++ tests/test_management_errors.py | 10 +++ tests/test_management_transport.py | 126 +++++++++++++++++++++++++++ 9 files changed, 316 insertions(+), 25 deletions(-) diff --git a/dashscope/management/_credentials.py b/dashscope/management/_credentials.py index 38d1a018..7157a79f 100644 --- a/dashscope/management/_credentials.py +++ b/dashscope/management/_credentials.py @@ -42,7 +42,9 @@ class CredentialResolver: Precedence: a pre-built ``credential`` client wins, then an explicit ``config`` dict, then explicit ``access_key_id`` / ``access_key_secret`` (with ``security_token`` selecting the STS provider type), then the - library default chain. + library default chain. A *partial* explicit AK (id without secret, or + a lone token) raises instead of falling through: silently signing with + ambient host credentials would swap a tenant's identity. """ def __init__( @@ -60,7 +62,15 @@ def __init__( self._client = _CredentialsClient( _CredentialsConfig(**dict(config)), ) - elif access_key_id and access_key_secret: + elif access_key_id or access_key_secret or security_token: + # Fail loudly on a partial explicit credential: the default + # chain below picks up the host's env/IMDS identity, which in + # a multi-tenant backend is a silent cross-tenant swap. + if not (access_key_id and access_key_secret): + raise ValueError( + "access_key_id and access_key_secret must be provided " + "together; refusing to fall back to ambient credentials", + ) self._client = _CredentialsClient( _CredentialsConfig( type="sts" if security_token else "access_key", diff --git a/dashscope/management/_errors.py b/dashscope/management/_errors.py index 3fa19677..125b3e9f 100644 --- a/dashscope/management/_errors.py +++ b/dashscope/management/_errors.py @@ -140,6 +140,9 @@ def _error_class( def _class_by_code(code: str) -> Optional[Type[DashScopeError]]: + # Coerce like _is_success: a numeric code in a failure envelope must + # not crash the crosswalk with an AttributeError. + code = str(code) if code.startswith("Throttling"): return RateLimitError if code in _AUTH_CODES: diff --git a/dashscope/management/_redaction.py b/dashscope/management/_redaction.py index 23dc9e13..b8b25149 100644 --- a/dashscope/management/_redaction.py +++ b/dashscope/management/_redaction.py @@ -13,11 +13,15 @@ from __future__ import annotations import logging +import re from typing import Any +from dashscope._logging import get_logger + __all__ = [ "REDACTED", "SecretRedactionFilter", + "get_management_logger", "mask_secret", "redact_body", ] @@ -79,7 +83,8 @@ class SecretRedactionFilter(logging.Filter): Key-oriented redaction (``redact_body``) cannot catch a secret that was interpolated into a free-text message, so this filter also masks ``sk-`` prefixed API key values wherever they appear in the formatted - record. Attached to the management logger only. + record. Attached to every management logger via + ``get_management_logger``. """ def filter(self, record: logging.LogRecord) -> bool: @@ -90,11 +95,27 @@ def filter(self, record: logging.LogRecord) -> bool: return True +# Word-bounded so keys adjacent to '=' or embedded in JSON are caught +# without touching lookalikes such as "task-123". {5,} keeps the old +# space-split threshold (token length > 7). +_SK_RE = re.compile(r"\bsk-[A-Za-z0-9_-]{5,}") + + def _mask_sk_tokens(message: str) -> str: - out = [] - for token in message.split(" "): - if token.startswith("sk-") and len(token) > 7: - out.append(mask_secret(token)) - else: - out.append(token) - return " ".join(out) + return _SK_RE.sub(lambda m: mask_secret(m.group()), message) + + +_SECRET_FILTER = SecretRedactionFilter() + + +def get_management_logger(name: str) -> logging.Logger: + """A core SDK logger with the management secret filter attached. + + Logger-level filters only run on the emitting logger (not on records + propagated from children), so every management module must fetch its + logger through here rather than calling ``get_logger`` directly. + """ + logger = get_logger(name) + if _SECRET_FILTER not in logger.filters: + logger.addFilter(_SECRET_FILTER) + return logger diff --git a/dashscope/management/_transport.py b/dashscope/management/_transport.py index 6f69253c..e54fbb17 100644 --- a/dashscope/management/_transport.py +++ b/dashscope/management/_transport.py @@ -25,13 +25,13 @@ import httpx from dashscope._config import DEFAULT_TIMEOUT -from dashscope._logging import get_logger from dashscope.errors import ( APIConnectionError, APITimeoutError, DashScopeError, ) from dashscope.management._credentials import CredentialResolver +from dashscope.management._redaction import get_management_logger from dashscope.management._signer import sign_request from dashscope.transport import _ident from dashscope.transport._options import ( @@ -47,11 +47,18 @@ __all__ = ["AsyncTransport", "SyncTransport"] -logger = get_logger("management.transport") +logger = get_management_logger("management.transport") _MODULE = "management" _DEFAULT_CONNECT_TIMEOUT = 5.0 +# Transparent retries are limited to safe methods. Write ops (G3/G4) +# must never be replayed on a transport error or 5xx -- a retried +# create/reset/delete can duplicate a billable or destructive side +# effect -- so non-read methods get a single attempt until an op +# explicitly opts into idempotent retry. +_RETRYABLE_METHODS = frozenset({"GET", "HEAD"}) + def _resolve_timeout( timeout: Union[float, httpx.Timeout, None], @@ -101,11 +108,19 @@ def __init__( timeout: Union[float, httpx.Timeout, None] = None, max_retries: int = 2, limits: Optional[httpx.Limits] = None, + injected_client: bool = False, ) -> None: self._host = endpoint or f"modelstudio.{region}.aliyuncs.com" self._resolver = resolver self._user_agent = user_agent or default_user_agent(_MODULE) - self._timeout = _resolve_timeout(timeout, DEFAULT_TIMEOUT) + self._default_timeout = _resolve_timeout(timeout, DEFAULT_TIMEOUT) + # An injected client keeps its own timeout unless the caller set + # one explicitly here (mirrors transport/http.py). + self._request_timeout = ( + None + if injected_client and timeout is None + else self._default_timeout + ) self._max_retries = max(max_retries, 0) self._limits = limits @@ -136,7 +151,9 @@ def _prepare( "extra_headers": ( options.extra_headers if options is not None else None ), - "timeout": resolve_timeout(self._timeout, options), + # Call-level options win; the client default is applied in + # _build_request only when the call set no timeout. + "timeout": resolve_timeout(None, options), } def _build_request( @@ -157,12 +174,18 @@ def _build_request( sdk_headers=prep["sdk"], extra_headers=prep["extra_headers"], ) + timeout = prep["timeout"] + if timeout is None: + timeout = self._request_timeout + # httpx reads an explicit timeout=None as "disable timeouts"; + # the kwarg must be omitted to keep the client-level default. + timeout_kwarg = {} if timeout is None else {"timeout": timeout} return http_client.build_request( signed.method, signed.url, headers=signed.headers, content=signed.content, - timeout=prep["timeout"], + **timeout_kwarg, ) @@ -173,10 +196,10 @@ def __init__( http_client: Optional[httpx.Client] = None, **kwargs: Any, ) -> None: - super().__init__(**kwargs) + super().__init__(injected_client=http_client is not None, **kwargs) self._owns_client = http_client is None self._client = http_client or httpx.Client( - timeout=self._timeout, + timeout=self._default_timeout, **({"limits": self._limits} if self._limits is not None else {}), ) @@ -203,6 +226,7 @@ def request( options=options, ) max_retries = prep["max_retries"] + retryable = method.upper() in _RETRYABLE_METHODS response = None for attempt in range(max_retries + 1): credential = self._resolver.resolve() @@ -214,14 +238,17 @@ def request( finally: response.close() except httpx.TransportError as exc: - if attempt >= max_retries: + if not retryable or attempt >= max_retries: raise _map_transport_error( exc, prep["client_request_id"], ) from exc time.sleep(backoff_delay(attempt, None)) continue - if not should_retry(response.status_code, response.headers): + if not retryable or not should_retry( + response.status_code, + response.headers, + ): return response if attempt >= max_retries: return response @@ -267,10 +294,10 @@ def __init__( http_client: Optional[httpx.AsyncClient] = None, **kwargs: Any, ) -> None: - super().__init__(**kwargs) + super().__init__(injected_client=http_client is not None, **kwargs) self._owns_client = http_client is None self._client = http_client or httpx.AsyncClient( - timeout=self._timeout, + timeout=self._default_timeout, **({"limits": self._limits} if self._limits is not None else {}), ) @@ -297,6 +324,7 @@ async def request( options=options, ) max_retries = prep["max_retries"] + retryable = method.upper() in _RETRYABLE_METHODS response = None for attempt in range(max_retries + 1): credential = await self._resolver.resolve_async() @@ -308,14 +336,17 @@ async def request( finally: await response.aclose() except httpx.TransportError as exc: - if attempt >= max_retries: + if not retryable or attempt >= max_retries: raise _map_transport_error( exc, prep["client_request_id"], ) from exc await asyncio.sleep(backoff_delay(attempt, None)) continue - if not should_retry(response.status_code, response.headers): + if not retryable or not should_retry( + response.status_code, + response.headers, + ): return response if attempt >= max_retries: return response diff --git a/dashscope/management/client.py b/dashscope/management/client.py index 47ad3472..7026601c 100644 --- a/dashscope/management/client.py +++ b/dashscope/management/client.py @@ -23,8 +23,8 @@ import httpx -from dashscope._logging import get_logger from dashscope.management._credentials import CredentialResolver +from dashscope.management._redaction import get_management_logger from dashscope.management._transport import AsyncTransport, SyncTransport from dashscope.management.api_keys import ApiKeys, AsyncApiKeys from dashscope.management.billing import AsyncBilling, Billing @@ -33,7 +33,7 @@ __all__ = ["AsyncManagementClient", "ManagementClient", "ManagementConfig"] -logger = get_logger("management.client") +logger = get_management_logger("management.client") DEFAULT_REGION = "cn-beijing" KNOWN_REGIONS = frozenset( diff --git a/tests/test_management_api_keys.py b/tests/test_management_api_keys.py index 544ae068..0e7380f3 100644 --- a/tests/test_management_api_keys.py +++ b/tests/test_management_api_keys.py @@ -16,6 +16,7 @@ from dashscope.management._redaction import ( # noqa: E402 SecretRedactionFilter, + get_management_logger, mask_secret, ) from dashscope.management.types import ApiKey # noqa: E402 @@ -124,6 +125,66 @@ def test_mask_secret_short_fully_masked(): assert mask_secret(SECRET) == "***" + SECRET[-4:] +def test_management_logger_carries_redaction_filter(): + logger = get_management_logger("management.test") + assert any( + isinstance(f, SecretRedactionFilter) for f in logger.filters + ) + # Idempotent: a second fetch must not stack duplicate filters. + again = get_management_logger("management.test") + assert again is logger + assert ( + sum(isinstance(f, SecretRedactionFilter) for f in logger.filters) == 1 + ) + + +def test_management_logger_masks_short_sk_token(caplog): + # 11 chars: below the core filter's 16-char threshold, so only the + # management filter stands between this token and the log line. + short_key = "sk-short123" + logger = get_management_logger("management.test") + with caplog.at_level(logging.INFO, logger=logger.name): + logger.info("using key %s", short_key) + assert short_key not in caplog.text + assert mask_secret(short_key) in caplog.text + + +def test_redaction_filter_masks_sk_token_at_any_boundary(): + # Short keys adjacent to '=' or embedded in JSON must not leak; + # space-split masking only caught whitespace-delimited tokens. + short_key = "sk-short123" + filt = SecretRedactionFilter() + for template in ("using key=%s", 'body: {"apiKey": "%s"}'): + record = logging.LogRecord( + "t", + logging.INFO, + __file__, + 1, + template, + (short_key,), + None, + ) + assert filt.filter(record) is True + assert short_key not in record.getMessage() + assert mask_secret(short_key) in record.getMessage() + + +def test_redaction_filter_leaves_sk_lookalikes_alone(): + # "task-123456" embeds "sk-123456" but is not a key token. + filt = SecretRedactionFilter() + record = logging.LogRecord( + "t", + logging.INFO, + __file__, + 1, + "finished task-123456 ok", + (), + None, + ) + assert filt.filter(record) is True + assert record.getMessage() == "finished task-123456 ok" + + def test_raw_overload(): client = make_client(action_handler(BODIES)) resp = client.api_keys.get(1, raw=True) diff --git a/tests/test_management_credentials.py b/tests/test_management_credentials.py index 78e4fe22..3d674055 100644 --- a/tests/test_management_credentials.py +++ b/tests/test_management_credentials.py @@ -13,6 +13,7 @@ pytest.importorskip("alibabacloud_credentials") pytest.importorskip("alibabacloud_openapi_util") +from dashscope.management import _credentials # noqa: E402 from dashscope.management._credentials import ( # noqa: E402 CredentialResolver, ResolvedCredential, @@ -97,6 +98,34 @@ def test_config_wins_over_ak(): assert resolver.resolve().access_key_id == "config-ak" +@pytest.mark.parametrize( + "kwargs", + [ + {"access_key_id": AK}, + {"access_key_secret": SK}, + {"security_token": TOKEN}, + {"access_key_id": AK, "security_token": TOKEN}, + {"access_key_id": AK, "access_key_secret": ""}, + ], +) +def test_partial_explicit_credential_rejected(kwargs): + # A partial AK must fail loudly, never sign with ambient credentials. + with pytest.raises(ValueError, match="together"): + CredentialResolver(**kwargs) + + +def test_default_chain_only_without_explicit_credential(monkeypatch): + seen = [] + + class _StubClient: + def __init__(self, config=None): + seen.append(config) + + monkeypatch.setattr(_credentials, "_CredentialsClient", _StubClient) + CredentialResolver() + assert seen == [None] + + def test_provider_name_propagates(): fake = _FakeCredentialClient(provider="ecs_ram_role") cred = CredentialResolver(credential=fake).resolve() diff --git a/tests/test_management_errors.py b/tests/test_management_errors.py index 31cc245f..7e46770c 100644 --- a/tests/test_management_errors.py +++ b/tests/test_management_errors.py @@ -122,6 +122,16 @@ def test_code_takes_precedence_over_status(): assert isinstance(management_error(env), RateLimitError) +def test_non_string_code_falls_back_to_status(): + # A numeric code must not crash the crosswalk with AttributeError; + # _class_by_code coerces like _is_success does. + env = read_envelope( + {"success": False, "code": 500, "message": "boom"}, + 500, + ) + assert isinstance(management_error(env), InternalServerError) + + def test_gateway_error_without_success_flag(): body = { "Code": "InvalidAccessKeyId", diff --git a/tests/test_management_transport.py b/tests/test_management_transport.py index bfc705de..d4e032a6 100644 --- a/tests/test_management_transport.py +++ b/tests/test_management_transport.py @@ -11,6 +11,7 @@ pytest.importorskip("alibabacloud_credentials") pytest.importorskip("alibabacloud_openapi_util") +from dashscope._config import DEFAULT_TIMEOUT # noqa: E402 from dashscope.errors import APIConnectionError # noqa: E402 from dashscope.management import _transport # noqa: E402 from dashscope.management import ( # noqa: E402 @@ -247,6 +248,104 @@ def handler(request): client.close() +def test_write_method_not_retried_on_5xx(): + calls = {"n": 0} + + def handler(request): + calls["n"] += 1 + return httpx.Response(500, json={"code": "InternalError"}) + + client = make_client(handler, max_retries=2) + resp = client.transport.request( + "POST", + "/modelstudio/workspaces", + action="CreateWorkspace", + body={"name": "prod"}, + ) + assert resp.status_code == 500 + assert calls["n"] == 1 + client.close() + + +def test_write_method_not_retried_on_transport_error(): + calls = {"n": 0} + + def handler(request): + calls["n"] += 1 + raise httpx.ConnectError("boom", request=request) + + client = make_client(handler, max_retries=2) + with pytest.raises(APIConnectionError): + client.transport.request( + "DELETE", + "/modelstudio/apikeys/1", + action="DeleteApiKey", + ) + assert calls["n"] == 1 + client.close() + + +# --- timeout ---------------------------------------------------------------- + + +def test_per_call_timeout_overrides_client_timeout(): + seen = [] + client = make_client(_capture_handler(seen), timeout=30.0) + client.workspaces.list(timeout=1.5) + assert seen[0].extensions["timeout"]["read"] == 1.5 + client.close() + + +def test_client_timeout_applies_without_per_call_override(): + seen = [] + client = make_client(_capture_handler(seen), timeout=30.0) + client.workspaces.list() + timeout = seen[0].extensions["timeout"] + assert timeout["read"] == 30.0 + assert timeout["connect"] == 5.0 + client.close() + + +def test_default_timeout_without_any_override(monkeypatch): + # The helper injects a client (whose own httpx default would apply), + # so force the SDK-owned path: keep the constructor kwargs but swap + # in a mock transport. + seen = [] + real_client = httpx.Client + + def mock_client(*args, **kwargs): + kwargs["transport"] = httpx.MockTransport(_capture_handler(seen)) + return real_client(*args, **kwargs) + + monkeypatch.setattr(httpx, "Client", mock_client) + client = ManagementClient(access_key_id=AK, access_key_secret=SK) + client.workspaces.list() + timeout = seen[0].extensions["timeout"] + assert timeout["read"] == DEFAULT_TIMEOUT + assert timeout["connect"] == 5.0 + client.close() + + +def test_injected_client_timeout_preserved(): + seen = [] + http_client = httpx.Client( + transport=httpx.MockTransport(_capture_handler(seen)), + timeout=99.0, + ) + client = ManagementClient( + http_client=http_client, + access_key_id=AK, + access_key_secret=SK, + ) + client.workspaces.list() + assert seen[0].extensions["timeout"]["read"] == 99.0 + # A per-call override still wins over the injected client default. + client.workspaces.list(timeout=2.0) + assert seen[1].extensions["timeout"]["read"] == 2.0 + client.close() + http_client.close() + + # --- async ---------------------------------------------------------------- @@ -274,3 +373,30 @@ async def test_async_with_options_region(): assert other.transport.host == "modelstudio.eu-central-1.aliyuncs.com" await client.aclose() await other.aclose() + + +async def test_async_write_method_not_retried(): + calls = {"n": 0} + + def handler(request): + calls["n"] += 1 + return httpx.Response(503, json={}) + + client = make_async_client(handler, max_retries=2) + resp = await client.transport.request( + "POST", + "/modelstudio/workspaces", + action="CreateWorkspace", + body={"name": "prod"}, + ) + assert resp.status_code == 503 + assert calls["n"] == 1 + await client.aclose() + + +async def test_async_per_call_timeout_overrides_client_timeout(): + seen = [] + client = make_async_client(_capture_handler(seen), timeout=30.0) + await client.workspaces.list(timeout=1.5) + assert seen[0].extensions["timeout"]["read"] == 1.5 + await client.aclose() From 75c34d96f7d2c556056bc4bc3015b11a530741f6 Mon Sep 17 00:00:00 2001 From: luk384090-cloud Date: Fri, 20 Nov 2026 18:17:47 +0800 Subject: [PATCH 4/5] test(logging): fix formatting in management logger filter assertions - Removed unnecessary newlines in assertion statements - Improved readability by simplifying multiline assertions - Ensured consistent assert formatting in test_management_logger_carries_redaction_filter --- tests/test_management_api_keys.py | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/tests/test_management_api_keys.py b/tests/test_management_api_keys.py index 0e7380f3..982aa1aa 100644 --- a/tests/test_management_api_keys.py +++ b/tests/test_management_api_keys.py @@ -127,15 +127,11 @@ def test_mask_secret_short_fully_masked(): def test_management_logger_carries_redaction_filter(): logger = get_management_logger("management.test") - assert any( - isinstance(f, SecretRedactionFilter) for f in logger.filters - ) + assert any(isinstance(f, SecretRedactionFilter) for f in logger.filters) # Idempotent: a second fetch must not stack duplicate filters. again = get_management_logger("management.test") assert again is logger - assert ( - sum(isinstance(f, SecretRedactionFilter) for f in logger.filters) == 1 - ) + assert sum(isinstance(f, SecretRedactionFilter) for f in logger.filters) == 1 def test_management_logger_masks_short_sk_token(caplog): From 71e8b51040b55748052392639a5808f080a1c503 Mon Sep 17 00:00:00 2001 From: luk384090-cloud Date: Fri, 20 Nov 2026 18:24:23 +0800 Subject: [PATCH 5/5] style(tests): format assertion with multiline parentheses --- tests/test_management_api_keys.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/test_management_api_keys.py b/tests/test_management_api_keys.py index 982aa1aa..dfd1830d 100644 --- a/tests/test_management_api_keys.py +++ b/tests/test_management_api_keys.py @@ -131,7 +131,9 @@ def test_management_logger_carries_redaction_filter(): # Idempotent: a second fetch must not stack duplicate filters. again = get_management_logger("management.test") assert again is logger - assert sum(isinstance(f, SecretRedactionFilter) for f in logger.filters) == 1 + assert ( + sum(isinstance(f, SecretRedactionFilter) for f in logger.filters) == 1 + ) def test_management_logger_masks_short_sk_token(caplog):