5pjf(%SrSSKJr SSKJrJr SSKJr SSKJ r J r J r SSK J r SSKJr SS KJr SS KJr SS KJr SS KJr SS KJrJr SSKJr SSKJr SSKJ r SSK!J"r"J#r# SSK$J%r%J&r&J'r' SSK(J)r)J*r*J+r+J,r,J-r-J.r. SSK/J0r0J1r1J2r2J3r3J4r4J5r5 SSK6J7r7 S/r8\7"S5r9Sr:S\;S'\<"\&Rz\&R|\&R~\&R15rAS\;S'\<"\&R~\&R15rBS\;S'\<"\&Rz\&R|\&R~\&R15rCS\;S'SS S!S"S#S$S%S&S'S(S)S*S+S,S-S..rDS/\;S0'S1S20rES/\;S3'\<"1S4k5rFS5\;S6'"S7S5rGg8)9u;High-level public API facade for the ModelScope Hub SDK. :class:`HubApi` is the **only** entry point users should construct. It composes the low-level :class:`OpenAPIClient`, :class:`LegacyClient`, :class:`DownloadManager`, :class:`UploadManager` and the cache helpers into a unified, OpenAPI-first surface. Design principles ----------------- * **OpenAPI-first** — every operation that has an OpenAPI counterpart goes through :mod:`._openapi`. Legacy endpoints are used only as a transparent fallback when no OpenAPI equivalent exists. * **Unified repo pattern** — every repository operation accepts a ``repo_type`` parameter; there are no type-specific methods like ``create_model`` or ``get_dataset``. * **Transparent fallback** — callers do not need to know which path served their request. * **Lazy clients** — the underlying HTTP clients are instantiated on demand so that ``HubApi()`` never fails just because no token is present. * **SOLID** — :class:`HubApi` only routes and orchestrates; concrete network logic lives in the injected dependencies. ) annotations)IterableMapping)Path)AnyBinaryIO TypeAlias)urlparse)RequestsCookieJar)_resolve_verification_root) clear_cache) scan_cache) verify_cache)DownloadManagerProgressCallback) LegacyClient) OpenAPIClient) UploadManager) HubConfigget_default_config)DEFAULT_ENDPOINTRepoType Visibility)AuthenticationErrorHubErrorInvalidParameter NetworkError NotExistErrorNotSupportedError) CacheInfoCacheVerificationFileInfo PagedResultRepoInfoUserInfo) get_loggerHubApiapizstr | RepoTyper RepoTypeLikezfrozenset[RepoType]_CREATABLE_TYPES_OPENAPI_CREATE_TYPES_OPENAPI_DETAIL_TYPESz apache-2.0mitzgpl-2.0zgpl-3.0zlgpl-2.1zlgpl-3.0zafl-3.0zecl-2.0z bsd-2-clausez bsd-3-clausez cc-by-4.0z cc-by-sa-4.0z cc-by-nc-4.0zcc0-1.0 unlicense)zApache License 2.0z MIT LicensezGPL-2.0zGPL-3.0zLGPL-2.1zLGPL-3.0zAFL-3.0zECL-2.0z BSD-2-Clausez BSD-3-Clausez CC-BY-4.0z CC-BY-SA-4.0z CC-BY-NC-4.0zCC0-1.0 Unlicensezdict[str, str]_LICENSE_DISPLAY_TO_SPDX cover_image coverImage_STUDIO_FIELD_RENAMES>NamerOwnerzfrozenset[str]_RESERVED_EXTRA_FIELDSc \rSrSrSrSUSSS.SVSjjjr\SWSj5r\SXSj5r\SYSj5r \SZS j5r \ S[S j5r S\S jr \ S]S j5r\ S^S j5rSr\"1Sk5r\ S_Sj5r\ SSS.S`Sjj5rSUSS.SaSjjjrSbSjrScSjrSdSjrSeSjr\ SfSj5rSgSjrShSjrSSSSSS.SiSjjrSS.SjS jjrSSSS!S"S#.SkS$jjrSlS%jr SmS&jr!S'SS(.SnS)jjr"SoS*jr#SSSS+SS,.SpS-jjr$S.SSSSSSS/SSS0. SqS1jjr%SSSSSSSS2.SrS3jjr&SSSSSS4SSSS5. SsS6jjr'SS/S7.StS8jjr(SSS9.SuS:jjr)SvS;jr*SS.SwS<jjr+\,RZ4SS=.SxS>jjjr.\,RZ4SyS?jjr/\,RZ4S@S!SASSSSB.SzSCjjjr0S{SDjr1\,RZ4SvSEjjr2\,RZ4S|SFjjr3\,RZ4S|SGjjr4\,RZ4S}SHjjr5SS!S"SI.S~SJjjr6SSK.SSLjjr7SS=.SSMjjr8SSNjr9SSSSSO.SSPjjjr:SUSSQjjr;SSSSR.SSSjjr>> from modelscope_hub import HubApi >>> api = HubApi(token="ms-xxxxxxxx") >>> user = api.whoami() >>> user.username 'alice' Create and manage repositories: >>> api.create_repo("alice/my-model", repo_type="model", visibility="private") >>> api.upload_file("alice/my-model", "model", "./weights.bin", "weights.bin") >>> path = api.download_file("alice/my-model", "model", "weights.bin") NendpointtokenczU=(d [5nUc&UcUb SSKJn URnU"U5nXdlX@lUb6[ R "U5URlSURlUb!X0RlSURl SUl SUl SUl SUl g)Nr)replaceT)r dataclassesr>_endpoint_overridden_configrnormalize_endpointr;r<_token_overridden_openapi_legacy _downloader _uploader)selfconfigr;r<baser>was_overriddens N/var/www/html/pdf-tiff/venv/lib/python3.13/site-packages/modelscope_hub/api.py__init__HubApi.__init__s-+- >x3u7H +!66N4=D)7 %  $-$@$@$JDLL !04DLL -  !&LL -1DLL *.2 ,0 37/3chURc[UR5UlUR$)z"Lazily-constructed OpenAPI client.)rDrrArHs rLopenapiHubApi.openapis( == )$,,7DM}}rOcURcuSSKJn [URR URR =(d [U"URR55S9UlUR$URR URR :wa%URR URlUR$)z-Lazily-constructed legacy ``/api/v1`` client.r )build_user_agent)r<r; user_agent) rEutilsrUrrAr<r;rget_session_id)rHrUs rLlegacy HubApi.legacys <<  /'ll((..B2B+DLL,G,G,IJDL|| \\  4<<#5#5 5"&!3!3DLL ||rOc~URc%[URUR5UlUR$)z,Lazily-constructed :class:`DownloadManager`.)rFrrYrArQs rL downloaderHubApi.downloaders3    #.t{{DLLID rOcURc9[URURURUR S9UlUR$)uLazily-constructed :class:`UploadManager`. The OpenAPI client is injected so small files (≤ 5 MiB) flow through ``POST /files/upload`` instead of the legacy commit endpoint. )create_repo_fn)rGrrYrArR_create_repo_exist_okrQs rLuploaderHubApi.uploadersD >> !*   #99 DN ~~rOcU(aSU;a[SU<S35eURS5upnU(aU(d[SU<S35eX4$)z@Split a canonical ``owner/name`` identifier into its two halves./zrepo_id z% should be in format of 'owner/name'.zL should be in format of 'owner/name': owner and name must both be non-empty.)r partition)repo_idowner_names rL_parse_repo_idHubApi._parse_repo_ids`#W,"Xg[8]#^_ _ **3/$D"7+%qr {rOcHURX5 g![a gf=f)zEAuto-create the repo if it doesn't exist, silently ignore if it does.N) create_reporrHrf repo_types rLr`HubApi._create_repo_exist_oks'    W 0     !!c[U[5(aU$[[U5R55$![a5nSR S[55n[ SU<SUS35UeSnAff=f)zCCoerce a ``str`` or :class:`RepoType` value to a :class:`RepoType`., c38# UHoRv M g7fNvalue.0ts rL .HubApi._normalize_repo_type..s:AzUnknown repo_type z. Expected one of: .N) isinstancerstrlower ValueErrorjoinr)roexcalloweds rL_normalize_repo_typeHubApi._normalize_repo_types} i * *  mC N0023 3 mii:::G"%7 }DWX_W``a#bcil l ms!; A:0A55A:cUcg[U[5(a [U5$[U[5(aU$[[R"[ U555$)z8Normalise visibility input to its integer wire encoding.N)rrint from_labelr) visibilitys rL_normalize_visibilityHubApi._normalize_visibilitysQ   j* - -z? " j# & & :((Z9::rO) itemslistdataresultsmodelsdatasetsskillsserversmcp_server_listModelsDatasetsSkillsServers> pagesizeTotaltotalPageSize page_size PageNumber TotalCount page_number total_countc^[T[5(aT[T5S[T54$[T[5(d/SSS4$/n[R H.n[TR U5[5(dM)TUn OJ TR5H4up#[U[5(dMU[R;dM2Un O SU4SjjnU"S[U55nU"SS5nU"S[U55nXXg4$)a2Decode a paginated OpenAPI response into ``(items, total, page, size)``. The ModelScope API returns item arrays under type-specific keys (``models``, ``datasets``, ``skills``, ``servers``). This method checks known keys first, then falls back to the first list-valued key that is not pagination metadata. r rc\>UH$nTRU5nUcM[U5s $ U$ru)getr)keysdefaultkvpayloads rL_first%HubApi._extract_paged.._first?s/KKN=q6MNrO)rrr)rrr)rrr)rztuple[str, ...]rrreturnr) rrlendictr(_PAGED_ITEM_KEYSrr_PAGED_META_KEYS)rrkeyrwrrrrs` rL_extract_pagedHubApi._extract_paged&s gt $ $CL!S\9 9'4((q!Q; **C'++c*D11 + &mmo eT**s&:Q:Q/Q!E.  =s5zJ;Q?7UDT''rO owner_hint name_hintcZ[U=(d 05n0nSSSSSSSSSS S S S S S S .nUR5HupgXtURXf5'M URS5c~URS 5n[U[5(a/U(a[ R US'O=[ RUS'O)URS5(a[ R US'URS5n [U [5(aTSU ;aNU RSS5n URS5(dU SUS'URS5(dU SUS'URS5(dX$S'URS5(dX4S'XS'[R"U5$)zBuild a :class:`RepoInfo` from an arbitrary API payload. The legacy and OpenAPI surfaces use different field-naming conventions (PascalCase vs snake_case). This helper normalises both into the SDK's canonical dataclass. idrgrirlicense description downloadslikes created_at last_modifiedtags)Idrr5r6rLicense Description DownloadsLikes CreatedAt UpdatedAt LastModifiedr updated_atTagsprivategatedrdr rro) rrrrboolrPRIVATEPUBLICrsplitr% from_dict) rrorr normalisedaliasesrrw private_flagid_valpartss rL_repo_info_from_payloadHubApi._repo_info_from_payloadKsDJB%' & ($%(+,) "**,JC05w{{3, -' >>, ' /%>>)4L,--/9/A/AJ|,/9/@/@J|,((+5+=+= <(% fc " "sf}LLa(E>>'**&+Ah 7#>>&))%*1X 6"~~g&&",w ~~f%%!*v "+;!!*--rOF)cookies_requiredcU=(d URRnU(aO[URR5R=(d Sn[ 5nUR SX4SS9 U$[URSS5(dURR5nUbU$U(a [S5eg) a Get cookies for authentication from token or local cache. Resolution order: 1. Explicit ``access_token`` argument 2. Token from config (explicit arg > env var > persisted cookie) 3. Saved cookies from ``~/.modelscope/credentials/cookies`` When a token is available (steps 1-2), a fresh :class:`~requests.cookies.RequestsCookieJar` with ``m_session_id`` is built. Otherwise the locally cached cookies from a prior ``login()`` call are loaded. Parameters ---------- access_token : str, optional Explicit token override. cookies_required : bool, optional When ``True``, raise :class:`AuthenticationError` if no credentials are available. Default is ``False``. Returns ------- RequestsCookieJar or None Cookie jar for authentication, or ``None`` when no credentials are available and ``cookies_required`` is ``False``. Raises ------ AuthenticationError When ``cookies_required`` is ``True`` and no credentials found. Examples -------- >>> cookies = api.get_cookies() >>> cookies['m_session_id'] 'ms-xxxxxxxx' m_session_idrd)domainpathrCFNzNo credentials found. Pass --token, call HubApi.login(), or set MODELSCOPE_API_TOKEN. Your token is available at https://modelscope.cn/my/myaccesstoken) rAr<r r;hostnamer setgetattr load_cookiesr)rH access_tokenrr<rjarcookiess rL get_cookiesHubApi.get_cookiessV2 2 2 dll334==CF#%C GGNEsG CJt||%8%@@ll//1G" %T  rOc`U(aUR5(d [S5eUR5nURRnURRnXRlSURlSUlUR bXR lURRU5upEURSS5nURSS5n URSS5n URRU5 U(aURRU5 U (a$URRX=(d S5 UR!5$![a.nURX#5 URX5nXvLaeXveSnAff=f)aAuthenticate and persist credentials locally. Calls ``POST /api/v1/login`` to obtain server-issued session cookies and a git access token, then saves them to ``~/.modelscope/credentials/`` (compatible with the old modelscope SDK). Parameters ---------- token : str ModelScope API token. Must be non-empty after stripping. Returns ------- UserInfo Profile of the authenticated user. Raises ------ InvalidParameter When ``token`` is empty or whitespace-only. AuthenticationError When the server rejects the token. The server's own explanation is preserved, and an endpoint hint is appended when the token turns out to be valid on the peer ModelScope site. HubError Transport, timeout and server-side failures propagate unchanged -- they are never reported as a rejected token. Notes ----- A failed attempt leaves persisted credentials untouched. Until the server has accepted the new token, the stored credential is still the caller's only working one, so revoking it on failure would turn a mistyped token into an unintended logout. Examples -------- >>> api = HubApi() >>> user = api.login("ms-xxxxxxxx") >>> user.username 'alice' z token must be a non-empty stringFN AccessTokenrUsernameEmail)striprrAr< _logged_outrDrErYloginr_restore_credential_state_explain_login_failurer save_cookiessave_git_tokensave_user_infowhoami) rHr<previous_tokenprevious_logged_outrrr explained git_tokenusernameemails rLr HubApi.loginsQVEKKMM"#EF F ++"ll66" #(   << #!&LL  % KK--e4MDHH]B/ 88J+"% !!'*  LL ' ' 2  LL ' '+2 >{{}# %  * *> O33E?I $  %s*E55 F-?)F((F-cXRlX RlSUlURbXRlgg)a Roll the in-memory credential back to its pre-login value. Persisted credentials are deliberately left alone; only this instance's transient state is rewound, so a failed attempt leaves the object exactly as it was found instead of poisoning it with a rejected token. N)rAr<rrDrE)rHr< logged_outs rLr HubApi._restore_credential_states8# #-   << #!&LL  $rOc 2[U[5(dU$UR5nUbURX5(dU$[URSUSUSUS3UR UR URURURS9$)a2Return the exception to surface for a failed login attempt. Only authentication failures are re-worded. Network, timeout and server-side errors are handed back untouched, because presenting them as a rejected token would send the caller after the wrong remedy. The two ModelScope sites keep separate account systems and answer an unknown token with the same business code, so the server cannot tell "invalid token" apart from "token issued by the other site". Only the client knows which site it addressed, which is why that disambiguation has to happen here. z This token is valid on z instead; retry with --endpoint z (or set MODELSCOPE_ENDPOINT=).) status_code request_id response_bodyurlmethod) rr_peer_site_endpoint_token_valid_onmessagerrrrr)rHr<rpeers rLrHubApi._explain_login_failure+s#233J'') .site_keyRs>SM**0b779D#v6648 @D @rO)rrrr)rAr@ constantsrr;r)rHrrcurrent candidates rLrHubApi._peer_site_endpointGsb << , ,4 A4<<00D4DE*,ABI "g-  CrOclSSKJn [SUUSS9nURU5 g![a gf=f)a<Best-effort check of whether *token* authenticates against *endpoint*. Runs on the failure path only and is strictly advisory: any error means "cannot confirm", so a probe outage degrades to the plain server message rather than producing a misleading hint. Retries are disabled to keep the failure path responsive. r )API_CONNECT_TIMEOUTNr)r<r;timeout max_retriesFT)rrrr Exception)r<r;rprobes rLr HubApi._token_valid_on\sG 3'     KK   s & 33cURR5 SUlURbSURlgg)zClear the locally persisted token. Cached HTTP clients are reset so subsequent calls behave as if no credential was ever provided. Examples -------- >>> api.logout() N)rA clear_tokenrDrEr<rQs rLlogout HubApi.logoutss6   " << #!%DLL  $rOcURR5n[R"[ U[ 5(aU5$05$)aReturn the profile for the currently authenticated user. Returns ------- UserInfo Authenticated user profile (username, email, avatar, ...). Raises ------ AuthenticationError When no token is configured or the token is invalid. Examples -------- >>> from modelscope_hub import HubApi >>> api = HubApi(token="ms-xxxxxxxx") >>> user = api.whoami() >>> print(user.username, user.email) alice alice@example.com )rRget_current_userr&rrr)rHrs rLr HubApi.whoamis;*,,//1!!Z-F-F'OOBOOrO)rr chinese_namer gated_modec URU5n U [;aBSR[S[555n [ SU R <SU S35eUR U5upURU5n Ub[RXD5nU [;GaU SL=(a U [[R5:HnU [RLaU U S.nU bXS'UbX_S 'OU U S .nU bXS'UbX_S 'UbXOS 'UbXoS '[ R#5H"unnUU;dMUR%U5UU'M$ UR'U5 U [RLaUR(R+U5OUR(R-U5nUR/UXU S 9$U [R0La-U U U bU O[[R25U=(d SS.nO,U U U bU O[[R25U=(d SS.nUbUUS'UbUUS'UbqU c-[[R5n U US'U(aSOSUS'OAU [[R5:XaU(aSOSUS'O[4R7S5 0nUR#5H-unnU[8;a[4R7SU5 M(UUU'M/ SU;a@USn[;U[5(a[<5(dUS;a [?S5eUR'U5 UR@RC[EU 5US9nUR/UXU S 9$)u@Create a new repository. Routing is decided by ``repo_type``: * ``studio`` / ``skill`` → OpenAPI ``POST /studios`` / ``POST /skills`` * ``model`` / ``dataset`` → legacy ``POST /api/v1/{type}s`` Parameters ---------- repo_id : str Canonical ``owner/name`` identifier. repo_type : str or RepoType One of ``"model"``, ``"dataset"``, ``"studio"``, ``"skill"``. visibility : int, str or Visibility, optional Visibility level. Accepts the integer wire encoding, a label (``"public"`` / ``"private"``) or a :class:`Visibility` value. Defaults to public. license : str, optional SPDX-style license identifier (e.g. ``"apache-2.0"``). chinese_name : str, optional Chinese display name shown on the Hub UI. description : str, optional Short description of the repository. gated_mode : bool, optional Enable gated (application-based download) mode for private repos. True = gated, False = normal private. Only effective when visibility is PRIVATE; ignored otherwise. **extra : Any Additional fields forwarded verbatim to the underlying client. Returns ------- RepoInfo Metadata of the newly created repository. Raises ------ InvalidParameter When ``repo_id`` does not have the ``owner/name`` shape. AuthenticationError When the token is missing or invalid. Examples -------- Create a private model repository: >>> info = api.create_repo( ... "alice/llama-7b-finetuned", ... repo_type="model", ... visibility="private", ... license="apache-2.0", ... description="A LoRA fine-tune of LLaMA-7B", ... ) >>> info.repo_id 'alice/llama-7b-finetuned' Create a private gated dataset: >>> api.create_repo("alice/my-data", "dataset", visibility="private", gated_mode=True) Create a public Studio space: >>> api.create_repo("alice/chat-demo", repo_type="studio", visibility="public") rsc38# UHoRv M g7frurvrxs rLr{%HubApi.create_repo..s(K:JQ:Jr}z'create_repo does not support repo_type=z. Supported types: r~N)rg repo_namer display_name)rg skill_namerrrz Apache-2.0)r6r5rr)rr5rr ChineseNamerrr  ProtectedModezAgated_mode is only effective when visibility is PRIVATE, ignored.z@Reserved field %r in extra ignored (controlled by method params))r r0zQProtectedMode must be int 1 (gated) or 2 (off); use gated_mode=True/False instead)robody)#rr+rsortedr rwrjrr1rr,rrrrSTUDIOr4rpopupdaterR create_studio create_skillrDATASETrloggerwarningr7rrrrYrmr)rHrfrorrr'rr(extrart supportedrgrivis is_privaterold_keynew_keyrr2filteredrrpms rLrmHubApi.create_reposvX & &y 1 % % &(K:J(K"KLI#9"((EXYbXccde ))'2 ((4  .227DG & &DKSC 8J8J4K-KJX__$"!%+?)3I&+.:N+#"&?)3I&+.:N+"%, "&)4 &$9$?$?$A e#%*YYw%7E'N%B NN5 !:<:O4<<--g6UYUaUaUnUnovUwD//bVZ/[ [ !! !%(_c#j>O>O:P"2l $D%(_c#j>O>O:P"2l D  #".D   ""-D   !{*,,-%(\"-7Q_%J..//-7Q_%bc$&KKMDAq**acdeHQK " h &/*Bb#&&*R*>*>"FBR !tuu H{{&&Rt&D++D"RV+WWrO)revisioncvURU5nURU5upVU[RLaURR XV5nOU[RLaURRXV5nOU[RLaURRXV5nOvU[R La!URR#USU35nOBU[R$La!URR'USU35nO[)SU35eUR+XtXVS9$![ a( URRU[U55nNAf=f![ a? [RSUU5 URRU[U55nNf=f)aFetch a repository's metadata via the OpenAPI surface. Parameters ---------- repo_id : str Canonical ``owner/name`` identifier. repo_type : str or RepoType One of ``"model"``, ``"dataset"``, ``"studio"``, ``"skill"``, ``"mcp"``. revision : str, optional Reserved for future use; currently ignored. Returns ------- RepoInfo Repository metadata (id, owner, name, visibility, stats, ...). Raises ------ NotExistError When the repository does not exist or is not visible to the caller. AuthenticationError When the request requires auth and the token is missing or invalid. Examples -------- >>> info = api.get_repo("alice/llama-7b", repo_type="model") >>> info.visibility 'public' >>> info.downloads 1234 z>Dataset %s/%s not found in OpenAPI, falling back to legacy APIrdzget_repo not supported for r)rrjrMODELrR get_modelrrY get_repo_inforr9 get_datasetr:debugr4 get_studioSKILL get_skillMCPget_mcp_serverr r)rHrfrorFr=rgrirs rLget_repoHubApi.get_repoCsL & &y 1))'2    C||--e:8## # C||//<8?? "<<**57D 8>> !<<))UG1TF*;>> page = api.list_repos("model", search="llama", page_size=5) >>> page.total_count 42 >>> [r.repo_id for r in page.items] ['meta-llama/Llama-2-7b', ...] List datasets owned by an organisation: >>> api.list_repos("dataset", owner="my_org", page_number=2) N)rUrgrVrrfiltersrg)rUrrrX)rUrrfilterz> !((%8ll..'#%- /G 8<< ll33'#$, 4G 8?? "#$bc c#&CB4$HI I#'#6#6w#? dD  DDDIJED--dB7EJ NNH   j NNH LL)   ""2w/EW[loppo)\\Ks HHHcSSKnURS[SS9 URU5nUR U5 UR R U[U5S9 g)aDelete a repository. .. deprecated:: Programmatic repository deletion is not currently supported by the Hub API for security reasons. This method will be restored in a future release once proper token-scoped authentication is available. To delete a repository now, use the web console at https://modelscope.cn. Parameters ---------- repo_id : str Canonical ``owner/name`` identifier. repo_type : str or RepoType Repository type (``"model"``, ``"dataset"``, etc.). rNzThis function is deprecated due to security reasons, and will be recovered in future versions with proper token authentication. Please go to https://modelscope.cn to delete repositories via the web console.r0) stacklevelrfro)warningswarnDeprecationWarningrrjrY delete_repor)rHrfrorir=s rLrlHubApi.delete_reposa"   ]    & &y 1 G$ 3r7CrOcHURX5 g![a gf=f)zReturn ``True`` iff the repository exists and is visible to the caller. This is a thin wrapper around :meth:`get_repo` that converts a :class:`NotExistError` into a boolean. Examples -------- >>> api.repo_exists("alice/my-model", "model") True TF)rRrrns rL repo_existsHubApi.repo_existss(  MM' -  rqmodel)ror<cSSKJnJnJnJn UR R (aUR R=(d U$U=(d UR RnU"US5n U (aUOUn U (aUOUn [XS9n U RX5(aU $[XS9n U RX5(a[RSUU U 5 U $[SUSU SU 35e) aResolve the best endpoint for read operations (download, list, get). 1. If the endpoint was explicitly configured (via constructor arg, ``MODELSCOPE_ENDPOINT``, or the deprecated ``MODELSCOPE_DOMAIN``), trust the user's configuration and return it directly (no probe). 2. If ``MODELSCOPE_PREFER_AI_SITE=true``, check ``.ai`` first, then fall back to ``.cn``. 3. Otherwise (default), check ``.cn`` first, then fall back to ``.ai``. Parameters ---------- token : str, optional Explicit token for the probe requests. Falls back to the token stored in this instance's config. Returns ------- str The endpoint URL where the repo exists. Raises ------ NotExistError If the repo is not found on any checked endpoint. r )rrENV_PREFER_AI_SITE _env_boolFr:z*Repo %s not found on %s, using %s instead.zRepo z not found on either z or )rrrrsrtrAr@r;r<r(ror:r;r)rHrfror<rrrsrteffective_token prefer_aiprimaryfallback primary_probefallback_probes rLresolve_endpoint_for_read HubApi.resolve_endpoint_for_read&s@   << , ,<<((<,< <54<<#5#50%8 +4':J'0#6KG  $ $W 8 8NI  % %g 9 9 NN<   OeG9,A'$xjYZZrOc>URRUS9nUS$)zUpload a file (max 5 MiB) via OpenAPI and return the file ID. This is a generic upload not tied to any repository. The returned ID can be used in subsequent API calls (e.g. ``skill_file`` when creating a skill). )filer)rR upload_file)rHr~rs rLupload_file_to_openapiHubApi.upload_file_to_openapiis%||''T'2DzrO)commit_messagecommit_descriptionrFbuffer_size_mb disable_tqdmc URU5n URRU[U 5UUU=(d SUU=(d SUU S9 $)a^Upload a single file to a repository. LFS files upload/reuse their blob first, then commit an LFS pointer. Normal files are committed directly with inline base64 content. LFS mode is determined by file suffix and size threshold. Parameters ---------- repo_id : str Canonical ``owner/name`` identifier. repo_type : str or RepoType Repository type (``"model"``, ``"dataset"``, ...). path_or_fileobj : str, Path, bytes or BinaryIO Local path, raw bytes, or a binary file-like object. path_in_repo : str Destination path inside the repository. commit_message : str, optional Commit message. Defaults to ``"Upload file"``. commit_description : str, optional Extended commit description. revision : str, optional Branch to commit on. Defaults to ``"master"``. buffer_size_mb : int, optional Buffer size in MiB for reading file data. Default 16. disable_tqdm : bool, optional Disable progress bar. Default False. Returns ------- dict Commit info from the server. Raises ------ AuthenticationError When the token is missing or invalid. NotExistError When the target repository does not exist. Examples -------- >>> api.upload_file( ... "alice/llama-7b", ... repo_type="model", ... path_or_fileobj="./pytorch_model.bin", ... path_in_repo="pytorch_model.bin", ... commit_message="Add fine-tuned weights", ... ) z Upload filemaster) rfropath_or_fileobj path_in_reporrrFrr)rrarr) rHrfrorrrrrFrrr=s rLrHubApi.upload_filessZ| & &y 1}}(("g+%):]1))%)  rOrT) rrrrFallow_patternsignore_patterns max_workers use_cachersync_remote_repoc URU5nURRU[U5UUU=(d SUU=(d SUU U U U U S9 $)aUpload an entire folder to a repository with resumable support. Files are walked recursively from ``folder_path`` and uploaded in parallel with adaptive batching, per-file retry, and ReAct progressive retry fallback. Parameters ---------- repo_id : str Canonical ``owner/name`` identifier. repo_type : str or RepoType Repository type. folder_path : str or Path Local directory whose contents will be uploaded. path_in_repo : str, optional Destination prefix inside the repository. Defaults to the repo root. commit_message : str, optional Commit message. Defaults to ``"Upload folder"``. commit_description : str, optional Extended commit description. revision : str, optional Branch to commit on. Defaults to ``"master"``. allow_patterns : list of str, optional If given, only files matching at least one pattern are uploaded. ignore_patterns : list of str, optional Files matching any pattern are skipped. max_workers : int, optional Concurrency for parallel uploads. Defaults to adaptive. use_cache : bool, optional Use ``.ms_upload_cache`` for resumable uploads. Default True. disable_tqdm : bool, optional Disable progress bars. Default False. sync_remote_repo : bool, optional If True, delete remote files that are not present locally after a successful upload (sync semantics). Default False. Returns ------- None If all files were already committed (nothing to do). dict If only one batch was committed. list of dict If multiple batches were committed. Examples -------- >>> api.upload_folder( ... "alice/llama-7b", ... repo_type="model", ... folder_path="./checkpoint-1000", ... ignore_patterns=["*.optim", "events.out.*"], ... max_workers=8, ... ) z Upload folderr) rfro folder_pathrrrrFrrrrrr)rra upload_folderr)rHrfrorrrrrFrrrrrrr=s rLrHubApi.upload_foldersfP & &y 1}}**"g#%)<_1))+#%-+  rO)rF cache_dir local_dirforceexpected_sha256local_files_onlyrVc URU5n U [RLa[SUS35eURR U[ U 5UU=(d SU(a [U5OSU(a [U5OSUUU U S9 $)aDownload a single file from a repository. The file is fetched into the local cache and a path pointing at the cached blob is returned. Subsequent calls reuse the cached copy unless ``force=True``. Parameters ---------- repo_id : str Canonical ``owner/name`` identifier. repo_type : str or RepoType Repository type. file_path : str Path of the file inside the repository. revision : str, optional Branch, tag or commit SHA. Defaults to ``"master"``. cache_dir : str or Path, optional Override the default cache directory. local_dir : str or Path, optional When set, download directly into this directory instead of cache. force : bool, optional Re-download even if a cached copy exists. Default is ``False``. expected_sha256 : str, optional When provided, verify downloaded file hash and use it for cache hit validation. On mismatch, re-download up to 3 times. local_files_only : bool, optional When ``True``, return the cached path without network access. Raises :class:`CacheNotFound` if the file is not cached. user_agent : dict, str or None, optional Custom user-agent info appended to the default UA string. Returns ------- Path Absolute path to the downloaded file on disk. Raises ------ NotExistError When the file or repository does not exist. Examples -------- >>> path = api.download_file( ... "alice/llama-7b", ... repo_type="model", ... file_path="config.json", ... ) >>> path.read_text()[:30] '{ "architectures": [ "Ll' File download is not supported for studio repositories. Studios are application containers without a file listing API. To access studio source code, use: git clone https://modelscope.cn/studios/.gitrN) rfro file_pathrFrrrrrrV)rrr4r r\ download_filerr) rHrfrorrFrrrrrrVr=s rLrHubApi.download_filesB & &y 1  #^^e]ffjl  ,,"g))2d9o)2d9o+-!-  rOr) rFrrrrrrrVprogress_callbacksc URU5n U [RLa[SUS35eURR U[ U 5U=(d SU(a [U5OSU(a [U5OSUUUU U U S9 $)a-Download an entire repository snapshot. All files at the given ``revision`` are fetched into the local cache in parallel. The returned path is the snapshot root directory. Parameters ---------- repo_id : str Canonical ``owner/name`` identifier. repo_type : str or RepoType Repository type. revision : str, optional Branch, tag or commit SHA. Defaults to ``"master"``. cache_dir : str or Path, optional Override the default cache directory. local_dir : str or Path, optional When set, download directly into this directory instead of cache. allow_patterns : list of str, optional If given, only matching files are downloaded. ignore_patterns : list of str, optional Matching files are skipped. max_workers : int, optional Concurrency for parallel downloads. Default is 4. local_files_only : bool, optional When ``True``, return the cached snapshot path without network. user_agent : dict, str or None, optional Custom user-agent info for download headers. progress_callbacks : list of ProgressCallback subclasses, optional Callback *classes* (not instances); each is instantiated per file to report byte-level download progress. Returns ------- Path Absolute path to the snapshot/local directory. Examples -------- Download only the tokenizer assets of a model: >>> root = api.download_repo( ... "alice/llama-7b", ... repo_type="model", ... allow_patterns=["tokenizer*", "*.json"], ... max_workers=8, ... ) >>> sorted(p.name for p in root.iterdir()) ['config.json', 'tokenizer.json', 'tokenizer_config.json'] rrrN) rfrorFrrrrrrrVr)rrr4r r\ download_reporr) rHrfrorFrrrrrrrVrr=s rLrHubApi.download_repols@ & &y 1  #^^e]ffjl  ,,"g))2d9o)2d9o)+#-!1-  rOrF recursivec URU5nURRU[U5U=(d SUS9n/nUGHnUR S5=(d2 UR S5=(d UR S5=(d S[ UR S5=(d UR S5=(d S 5UR S 5=(d) UR S 5=(d UR S 5UR S 5=(d UR S 5UR S5=(d UR S5=(d SUR S5=(d UR S5UR S5=(d UR S5S.n UR [R"U 55 GM U$)upList files inside a repository (legacy — no OpenAPI equivalent). Parameters ---------- repo_id : str Canonical ``owner/name`` identifier. repo_type : str or RepoType Repository type. revision : str, optional Branch, tag or commit SHA. Defaults to ``"master"``. recursive : bool, optional Walk subdirectories recursively. Default is ``True``. Returns ------- list of FileInfo File metadata entries (path, size, blob id, last modified, ...). Examples -------- >>> files = api.list_repo_files("alice/llama-7b", "model") >>> [f.path for f in files][:3] ['README.md', 'config.json', 'pytorch_model.bin'] r)rfrorFrrrr5rSizerrBlobIdblob_idSha256sha256Typetypeblob CommittedDaterLfslfs)rrrrrrr) rrYlist_repo_filesrrrappendr#r) rHrfrorFrr=rawfilesrars rLrHubApi.list_repo_filessa@ & &y 1kk))"g) *  !#D(VDHHV,<V@PVTVDHHV,E0@EAF88H-Z)1DZQYHZ((8,B0B(FDHHV,<F!%/!:!Wdhh>Wxx9$((5/J LL++J7 8 rO)rrFcURU5nUVs/sH ow(dM UPM nnU(d [S5e//pUHCnURRU[ U5UU=(d SS9 U R U5 ME X[U5S.$s snf![ [4a U R U5 e[a U R U5 Mf=f)aDelete one or more files from a repository. .. note:: File deletion is restricted by the server to cookie-based session auth (interactive login). API tokens (``ms-...``) may receive a 401 "token no longer supports deletion operations" error. Parameters ---------- repo_id : str Canonical ``owner/name`` identifier. repo_type : str or RepoType Repository type. file_paths : iterable of str Paths of files to remove. Empty entries are ignored. commit_message : str, optional Unused (kept for API compatibility). revision : str, optional Branch to delete from. Defaults to ``"master"``. Returns ------- dict Summary with ``deleted_files`` and ``failed_files`` lists. Raises ------ InvalidParameter When ``file_paths`` resolves to an empty list. Examples -------- >>> api.delete_files( ... "alice/llama-7b", ... "model", ... ["old_weights.bin", "deprecated/config.json"], ... ) z4file_paths must contain at least one non-empty path.r)rfrorrF) deleted_files failed_files total_files) rrrY delete_filerrrrrr) rHrfro file_pathsrrFr=ppathsdeletedfaileds rL delete_filesHubApi.delete_filess^ & &y 1&,Jq!J,"#YZ ZbA ! ''#!"g%1 ( q!")QTUZQ[\\)-(6  a  ! a  !s BB?B>> revs = api.list_repo_revisions("alice/llama-7b", "model") >>> [r["name"] for r in revs] ['master', 'v1.0', 'experimental'] rh)rrYlist_revisionsr)rHrfror=s rLlist_repo_revisionsHubApi.list_repo_revisions?s2 & &y 1{{))'SW)MMrOcURU5nURRU[U5UU=(d SS9$)zCreate a tag pointing at ``revision`` (defaults to ``master``). Examples -------- >>> api.create_repo_tag("alice/llama-7b", "model", "v1.0") r)rfrotagrF)rrY create_tagr)rHrfrorrFr=s rLcreate_repo_tagHubApi.create_repo_tagKsE & &y 1{{%%"g) &  rO)rc8URU5nU[RLa/URU5upVURR XVU5$U[R LaURRX5$[SUR<S35e)aDeploy a Studio space or an MCP server. Parameters ---------- repo_id : str For Studios, an ``owner/name`` pair. For MCP servers, the server identifier accepted by the OpenAPI surface. repo_type : str or RepoType, optional ``"studio"`` (default) or ``"mcp"``. payload : Mapping, optional Deployment configuration forwarded verbatim to the backend (hardware tier, env vars, ...). Returns ------- dict Deployment response payload (deployment id, status URL, ...). Raises ------ NotSupportedError When ``repo_type`` is neither ``"studio"`` nor ``"mcp"``. Examples -------- Deploy a Studio space on a GPU instance: >>> api.deploy_repo( ... "alice/chat-demo", ... repo_type="studio", ... payload={"instance_type": "GPU-A10", "min_replicas": 1}, ... ) z+deploy_repo is not supported for repo_type=r~) rrr4rjrR deploy_studiorPdeploy_mcp_serverr rw)rHrfrorr=rgris rL deploy_repoHubApi.deploy_repodsP & &y 1  --g6KE<<--e7C C  <<11'C C"Mbhh\YZ [\\rOc6URU5nU[RLa.URU5upEURR XE5$U[R LaURRU5$[SUR<S35e)z}Stop a running Studio or undeploy an MCP server. Examples -------- >>> api.stop_repo("alice/chat-demo", repo_type="studio") z)stop_repo is not supported for repo_type=r~) rrr4rjrR stop_studiorPundeploy_mcp_serverr rw)rHrfror=rgris rL stop_repoHubApi.stop_repos & &y 1  --g6KE<<++E8 8  <<33G< <"KBHH>> logs = api.get_repo_logs( ... "alice/chat-demo", ... log_type="run", ... keyword="ERROR", ... page_size=50, ... ) z:get_repo_logs is currently only supported for studio (got r)rrrrr)rrr4r rwrjrRget_studio_logs) rHrfrorrrrrrr=rgris rL get_repo_logsHubApi.get_repo_logssd & &y 1 X__ $#&`acaiai`lln$op p))'2 ||++   +',  rOc URU5nURU5upV[R5HupxXs;dM UR U5X8'M! U[ R LaURRXVU5$U[ RLaURRXVU5$[SUR<S35e)a1Update repo settings (Studio or Skill). Parameters ---------- repo_id : str Canonical ``owner/name`` identifier. repo_type : str or RepoType Either ``"studio"`` or ``"skill"``. **settings : Any Setting key/value pairs forwarded to the backend. Returns ------- dict Updated settings payload. Raises ------ NotSupportedError When ``repo_type`` is neither studio nor skill. Examples -------- >>> api.update_repo_settings( ... "alice/chat-demo", ... repo_type="studio", ... visibility="public", ... hardware="GPU-A10", ... ) z4update_repo_settings is not supported for repo_type=r~) rrjr4rr5rr4rRupdate_studio_settingsrNupdate_skill_settingsr rw) rHrfrosettingsr=rgrirArBs rLupdate_repo_settingsHubApi.update_repo_settingssH & &y 1))'2  5 ; ; = G"$,LL$9!!>  <<66uHM M  <<55e8L L"VWYW_W_Vbbc deerOcURU5nU[RLa[SUR<S35eUR U5upEUR RXE5n[U[5(aU$[U[5(a3SH-n[URU5[5(dM)Xgs $ /$)zList secrets attached to a Studio. Examples -------- >>> api.list_secrets("alice/chat-demo") [{'key': 'OPENAI_API_KEY', 'updated_at': 1712345678}, ...] z4Secret management is only supported for studio (got r)rsecretsr) rrr4r rwrjrRlist_studio_secretsrrrr)rHrfror=rgrirrs rL list_secretsHubApi.list_secretss & &y 1 X__ $#&Z[][c[cZffh$ij j))'2 ||//< dD ! !K dD ! !3dhhsmT229$4 rOcURU5nU[RLa [S5eUR U5upgUR R XgX#5$)zsAdd a new secret to a Studio. Examples -------- >>> api.add_secret("alice/chat-demo", "OPENAI_API_KEY", "sk-...") "Only studio secrets are supported.)rrr4r rjrRadd_studio_secretrHrfrrwror=rgris rL add_secretHubApi.add_secret/sU & &y 1 X__ $#$HI I))'2 ||--e3FFrOcURU5nU[RLa [S5eUR U5upgUR R XgX#5$)z}Update an existing secret value. Examples -------- >>> api.update_secret("alice/chat-demo", "OPENAI_API_KEY", "sk-new-...") r)rrr4r rjrRupdate_studio_secretrs rL update_secretHubApi.update_secretBsU & &y 1 X__ $#$HI I))'2 ||00cIIrOcURU5nU[RLa [S5eUR U5upVUR R XVU5$)zmDelete a secret from a Studio. Examples -------- >>> api.delete_secret("alice/chat-demo", "OPENAI_API_KEY") r)rrr4r rjrRdelete_studio_secret)rHrfrror=rgris rL delete_secretHubApi.delete_secretUsU & &y 1 X__ $#$HI I))'2 ||00cBBrO)rUrrc URRUUUUR5VVs0sH upVUcM XV_M snn=(d SS9nURU5upp[ [ U5XU S9$s snnf)aList MCP servers via the OpenAPI surface. Parameters ---------- search : str, optional Free-text search query. page_number : int, optional 1-based page index. Default is 1. page_size : int, optional Items per page. Default is 10. **extra : Any Additional filter fields. ``None`` values are dropped. Returns ------- PagedResult[dict] Paginated MCP server listing. Examples -------- >>> page = api.list_mcp_servers(search="weather", page_size=5) >>> page.total_count 12 N)rUrrr<)rrrr)rRr_rrr$r) rHrUrrr<rrrrrrrs rLr_HubApi.list_mcp_serversjs}@,,//#$)KKMCMDAQ414MCKt 0  $(#6#6w#? de%]abbDs A6A6get_operational_urlc4URRXS9$)aFetch a single MCP server's metadata. Parameters ---------- server_id : str MCP server identifier. get_operational_url : bool, optional When ``True``, the response includes the live runtime URL. Returns ------- dict MCP server metadata. Examples -------- >>> info = api.get_mcp_server("alice/weather-mcp", get_operational_url=True) >>> info["operational_url"] 'https://...' r)rRrQ)rH server_idrs rLrQHubApi.get_mcp_servers4||**9*^^rOc8URRX5$)zDeploy or redeploy an MCP server. Examples -------- >>> api.deploy_mcp_server("alice/weather-mcp", payload={"region": "cn-hangzhou"}) )rRr)rHrrs rLrHubApi.deploy_mcp_servers||--iAArOc8URRU5$)zcUndeploy a running MCP server. Examples -------- >>> api.undeploy_mcp_server("alice/weather-mcp") )rRr)rHrs rLrHubApi.undeploy_mcp_servers||// ::rOrFrrc UbUb [S5eURU5n[U[U5UUUS9upxUR XUSS9n U V s0sH?oR (aMU R (dM(U R U R_MA n n [U[U5U UU(a [U5OSU(a [U5S9$SS9$s sn f)zEVerify local repository files against SHA-256 checksums from the Hub.Nz.cache_dir and local_dir are mutually exclusiverTr) rrr rris_dirrr _verify_cacher) rHrfrorFrrr=rhresolved_revisionrr~expecteds rLrHubApi.verify_caches  Y%:"#ST T  & &y 19  G  $$W;LX\$]7<^utKK*TXT]T]*DIIt{{*u^  G &)2d9o)2d9o   9=   _sC(C;CcD[U(a[U55$S5$)aInspect the local cache directory. Parameters ---------- cache_dir : str or Path, optional Override the default cache root. Returns ------- CacheInfo Aggregated cache stats (total bytes, repo entries, ...). Examples -------- >>> info = api.scan_cache() >>> info.size_on_disk 12345678 >>> [r.repo_id for r in info.repos][:3] ['alice/llama-7b', 'bob/imagenet', 'carol/whisper-base'] N) _scan_cacher)rHrs rLrHubApi.scan_caches*i4 ?BBTBBrOrrorfczSnUb[URU55n[U(a [U5OSUUS9$)a Remove cached data and return the number of bytes freed. Parameters ---------- cache_dir : str or Path, optional Override the default cache root. repo_type : str or RepoType, optional Restrict deletion to a single repository type. repo_id : str, optional Restrict deletion to a single repository id. Returns ------- int Number of bytes reclaimed from disk. Examples -------- Wipe the cache for a single model: >>> api.clear_cache(repo_type="model", repo_id="alice/llama-7b") 4823412 Wipe everything: >>> api.clear_cache() Nr)rr _clear_cacher)rHrrorfrt_values rLrHubApi.clear_cachesCD $  444Y?@H)2d9o  rO)rArFrErDrGru)rIzHubConfig | Noner; str | Noner<rrNone)rr)rr)rr)rr)rfrrztuple[str, str])rfrrorrr)ror*rr)rint | str | Visibility | Noner int | None)rrrztuple[list[Any], int, int, int]) rMapping[str, Any] | Nonerorrrrrrr%)rrrrrzRequestsCookieJar | None)r<rrr&)r<rrrrr)r<rrrrr)rr)r<rr;rrr)rr)rr&)rfrror*rrrrr'rrrr( bool | Noner<rrr%)rfrror*rFrrr%)ror*rgrrUrrVrrrrrrXrrzPagedResult[RepoInfo])rfrror*rr)rfrror*rr)rfrror*r<rrr)r~zstr | Path | BinaryIOrr)rfrror*rzstr | Path | bytes | BinaryIOrrrrrrrFrrrrrrr)rfrror*rz str | PathrrrrrrrFrrlist[str] | Nonerrrrrrrrrrrzdict | list[dict] | None)rfrror*rrrFrrstr | Path | NonerrrrrrrrrVdict | str | Nonerr)rfrror*rFrrrrrrrrrrrrrrVrrz#list[type[ProgressCallback]] | Nonerr) rfrror*rFrrrrzlist[FileInfo]) rfrror*rz Iterable[str]rrrFrrr)rfrror*rz list[dict]) rfrror*rrrFrrr)rfrror*rrrr)rfrror*rr)rfrror*rrrrrrrrrrrrrr)rfrror*rrrr) rfrrrrwrror*rr)rfrrrror*rr) rUrrrrrr<rrzPagedResult[dict])rrrrrr)rrrrrr)rrrr)rq) rfrror*rFrrrrrrr")rrrr!)rrrozRepoTypeLike | Nonerfrrr)>__name__ __module__ __qualname____firstlineno____doc__rMpropertyrRrYr\ra staticmethodrjr`rrr frozensetrrrrrrrrr r"rrmrRrdrlror{rrrrrrrrrrr4rrrrrrrrr_rQrrrrr__static_attributes__rOrLr(r(cs &T$(4 $ 4 4 4  4  4B      $  mm;;!  "("(H "& $ @.&@.@. @.  @.  @.@.N$(?"' ? ? ? " ?BJX ' 8*, &P@59"#'"&"&dXdX dX 2 dX  dX!dX dX dXdX dXV $ AXAX AX  AX  AXN!!oqoq oq  oq  oqoqoqoq oqbD<*#* >[>[ >[  >[ >[F"&*)-# "I I  I 7 I  I #I 'I I I I  I b%))-#+/,0"&"!&W W  W  W  W #W 'W W )W *W  W W W W "!W ~ $'+'+&*!&(,S S  S  S  S %S %S S $S S &S  S t $'+'++/,0!&(,BFS S  S  S % S %S )S *S S S &S @S  S t $ 33 3  3  3 3v&*#D]D] D]" D] # D]D] D]R N$ $           8#+//.] -1 .].] .] * .]  .]f#+//[[ [  [,#+//? "&*$(? ?  ?  ?  ? ? ? $? "?  ? B-f-f -f -f  -fdDL??4#+// GGG G  G  G0#+// JJJ J  J  J.#+// CCC C  C0" 'c'c 'c  'c  'c 'cZ,0 __) _  _8X\B;#* $'+'+      %  %   >C4(,)-" ) %) ' )  ) ) ) rON)Hr! __future__rcollections.abcrrpathlibrtypingrrr urllib.parser requests.cookiesr _cache_managerr rrrr rr _downloadrr _legacy_apirrDr_uploadrrIrrrrrrerrorsrrrrrr typesr!r"r#r$r%r& utils.loggerr'__all__r:r*__annotations__r$rHr9r4rNr+r,r-r1r4r7r(r&rOrLr6si.#-++!.67598%#"1==[Z$ * E * i* )28>>8CSCSU]UdUdfnftft2u(v%v-67X-Y*Y-6 ^^X%%xG.*'"""",.(<)~ *33L)MM@ @ rO