o 2j c @sUdZddlZddlZddlmZmZddlmZmZm Z ddl m Z ddl m Z mZddlmZd d e jDZeeefed <ed Zee jZeeed <ehdZeeed<eddhZeeed<eddGdddZeddGdddZdede fddZ!ej"dedefddZ#dede fdd Z$d!edefd"d#Z%d$edefd%d&Z&d'edefd(d)Z'd*ed+ede(eedBe dBffd,d-Z)d.ed+ede(e j*effd/d0Z+d.ed1e j*d+edefd2d3Z,d.ed1e j*d+edefd4d5Z-dS)6aCentralized parser for Hugging Face Hub URIs ('hf://...') and mount specifications. A HF URI is a URI-like string that identifies a location on the Hugging Face Hub: a model/dataset/space/kernel repository, a bucket, optionally a revision, and optionally a path inside the repo or bucket. Canonical syntax: ``` hf://[/][@][/] ``` For convenience, [`parse_hf_uri`] also accepts Hugging Face **web URLs** (the ones you copy-paste from your browser), e.g. 'https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv'. They are normalized to the canonical 'hf://' form before parsing. Only unambiguous URLs (repository / bucket pages and file/folder viewer routes) are accepted; any other route is rejected rather than guessed. A HF mount wraps a HF URI with a local mount path and an optional ':ro'/':rw' flag (used by Spaces and Jobs volumes): ``` hf://[/][@][/]:[:ro|:rw] ``` See 'docs/source/en/package_reference/hf_uris.md' for the full grammar and examples. N) dataclassfield)quoteunquoteurlsplit) constants) HfUriErrorHFValidationError)validate_repo_idcCsi|]\}}||qSr ).0kvr r Y/var/www/html/whisper/venv/lib/python3.10/site-packages/huggingface_hub/utils/_hf_uris.py 8sr_TYPE_TO_PREFIXz ^refs/(?:convert/[\w.-]+|pr/\d+)_VALID_URI_TYPES>rawblobtreeblameresolve_URL_REPO_LOCATION_ACTIONSrr_URL_BUCKET_LOCATION_ACTIONST)frozenc@seZdZUdZejed<eed<dZedBed<dZ eed<e ddddd Z edBed <dd d Z e d efddZe d efddZd efddZddedBd efddZdS)HfUriaParsed representation of a Hugging Face Hub URI ('hf://...'). Attributes: type (`str`): One of 'model', 'dataset', 'space', 'kernel' or 'bucket'. id (`str`): The repository id ('namespace/name', e.g. 'my-org/my-model') for repo URIs, or the bucket id ('namespace/name') for bucket URIs. revision (`str`, *optional*): The revision specified after '@' in the URI, URL-decoded. 'None' if no revision was specified, or for bucket URIs (which never carry a revision). Special refs like 'refs/pr/10' and 'refs/convert/parquet' are preserved as-is. path_in_repo (`str`): The path inside the repo or bucket. Empty string if the URI points at the root. typeidNrevision path_in_repoFreprhashcomparedefault_rawreturnc Cs|jpd}|jtvrt|d|jdttdd|jr%|jddkr0t|d|jd d|jd krRzt|jWntyQ}z t|t |d|d}~ww|j dur`|j s`t|d d|jd krp|j durpt|d d|j r|j ds~d |j vrt|d|j dddSdS)Nr zInvalid type 'z'. Must be one of .urimsg/r z"Id must be 'namespace/name', got ''.bucketz%Revision must not be an empty string.z&Bucket URIs do not support a revision.//z+Path must not contain empty segments (got 'z').) r'rrrsortedrcountr r strrr! startswith)selfr+er r r __post_init__ds*      zHfUri.__post_init__cCs |jdkS)z$True if this URI points at a bucket.r/rr5r r r is_bucket zHfUri.is_bucketcCs |jdkS)zJTrue if this URI points at a repository (model, dataset, space or kernel).r/r8r9r r ris_repor;z HfUri.is_repocCsztjt|jd|jg}|jdur,|j}d|vr$t|dur$|dd}| d||j r8| d|j d |S)zRender the URI as a canonical 'hf://' string. The type prefix is always written explicitly (e.g. 'hf://models/my-org/my-model'). r-N%2F@r ) r HF_PROTOCOLrrrr_SPECIAL_REFS_REVISION_REGEX fullmatchreplaceappendr!join)r5partsrr r rto_uris   z HfUri.to_uriendpointcCs|ptjd}t|jdd}|jdkr'|d|j}|r%|d|7}|S|jdkr4|d|jn |dt|jd|j}|j}|durZd|vrZt |durZ| dd}|rk|d |pbtj d|7}|S|durv|d|7}|S) aRender the URI as a Hugging Face **web URL** (the kind you open in a browser). This is the inverse of parsing a URL with [`parse_hf_uri`]. The returned URL points at: - the repository / bucket landing page when no path or revision is set; - the folder viewer ('/tree/') when only a revision is set; - the file viewer ('/blob//') for repository files (revision defaults to 'main'); - the tree route ('/tree/') for bucket files (buckets are not versioned). Args: endpoint (`str`, *optional*): Base endpoint to use. Defaults to 'constants.ENDPOINT' (i.e. 'https://huggingface.co'). Returns: `str`: the web URL. Example: ```py >>> from huggingface_hub import parse_hf_uri >>> parse_hf_uri("hf://datasets/my-org/my-dataset@v1/train.csv").to_url() 'https://huggingface.co/datasets/my-org/my-dataset/blob/v1/train.csv' ``` r-)safer/z /buckets/z/tree/modelNr=z/blob/) rENDPOINTrstriprr!rrrrr@rArBDEFAULT_REVISION)r5rGbasepathurlrr r rto_urls" 6 z HfUri.to_urlr(NN)__name__ __module__ __qualname____doc__r HfUriType__annotations__r3rr!rr'r7propertyboolr:r<rFrPr r r rrNs    rc@sfeZdZUdZeed<eed<dZedBed<e dddddZ edBed<dd d Z d efd d Z dS)HfMountaFA HF URI paired with a local mount path and optional read-only flag. Used by Spaces and Jobs to describe volume mounts. The full syntax is: ``` hf://[/][@][/]:[:ro|:rw] ``` Attributes: source ([`HfUri`]): The parsed HF URI identifying the Hub resource to mount. mount_path (`str`): The local mount path (always starts with '/'). read_only (`bool`, *optional*): True if the mount ends with ':ro', False if it ends with ':rw', 'None' if no flag was provided. source mount_pathN read_onlyFr"r'r(cCs:|jpd}|jdr|jdkrt|d|jdddS)Nr r-zEMount path must be a non-empty absolute path starting with '/', got 'r.r*)r'r]r4r)r5rr r rr7s  zHfMount.__post_init__cCs:|jd|jg}|jdur||jrdndd|S)zqRender the mount as a canonical 'hf://' string. Example: 'hf://models/my-org/my-model:/data:ro' :N:ro:rwr )r\rFr]r^rCrD)r5rEr r rrFs  zHfMount.to_urirQ) rSrTrUrVrrXr3r^rZrr'r7rFr r r rr[s  r[r+r(cCs$zt|WdStyYdSw)zVCheck if a string is a valid HF URI ('hf://...') or a recognized Hugging Face web URL.TF) parse_hf_urirr+r r r is_hf_uris  rdcCs|}|tjr|ttjd}|st|dtjdnt|r't|}nt|dtjdtjdt||d\}}|dkrHt|||dSt |||dS) alParse a Hugging Face Hub URI ('hf://...') or a Hugging Face web URL. A HF URI is a URI-like string identifying a location on the Hugging Face Hub. The full grammar is: ``` hf://[/][@][/] ``` For convenience, Hugging Face **web URLs** (the ones you copy-paste from the website) are also accepted and normalized to the canonical 'hf://' form, e.g. 'https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv'. Only unambiguous URLs (repository / bucket pages and file/folder viewer routes) are accepted; any other route is rejected. See 'docs/source/en/package_reference/hf_uris.md' for the full specification. Args: uri (`str`): The URI to parse. Must start with 'hf://', or be a Hugging Face URL (e.g. 'https://huggingface.co/...'). Returns: [`HfUri`]: the parsed URI. Raises: [`HfUriError`]: If the URI is malformed (missing prefix, invalid type, missing id, unsupported URL route, etc.). Examples: ```py >>> from huggingface_hub.utils import parse_hf_uri >>> parse_hf_uri("hf://my-org/my-model") HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo='') >>> parse_hf_uri("hf://datasets/my-org/my-dataset@refs/pr/3/train.json") HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json') >>> parse_hf_uri("https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv") HfUri(type='dataset', id='my-org/my-dataset', revision='main', path_in_repo='train.csv') ``` NEmpty body after 'r.Must start with 'zQ' or be a Hugging Face URL (e.g. 'https://huggingface.co/...'). Expected format: z#[/][@][/]rr/) r4rr?lenr_looks_like_hf_url_url_to_uri_body _split_type_parse_bucket_body_parse_repo_body)r+rbodytype_locationr r rrbs$'   rbcs.|dr dStfddtjDS)zNReturn True if 'uri' looks like a (possibly scheme-less) Hugging Face web URL.)zhttp://zhttps://Tc3s&|]}|kp|dVqdS)r-N)r4)r hostloweredr r Bs$z%_looks_like_hf_url..)lowerr4anyr HF_URL_HOSTSrcr rrrri<s risegmentcCst|ddS)awPercent-decode a single URL path segment (e.g. 'file%20name.txt' -> 'file name.txt'). A decoded '/' is re-encoded as '%2F' so the segment stays atomic when the normalized body is re-split by the shared parser. This decodes ordinary path characters (spaces, '#', ...) that browsers encode, while keeping '%2F'-encoded revisions (e.g. 'feature%2Ffoo') intact. r-r=)rrB)rxr r r_decode_url_path_segmentEsryrOc Cs|}td|vr |nd|}|jpd}|tjvr&t|d|p |dddd|jd D}|s=t|d |d dd }|d tjvrP|d }|dd }t |dkr`t|d|dd|d d |d}|dd }|dkr|s|d|S|^}} |t vrt|d|d|ddd dd| D} | rd|d | Sd|S|r|d nd} |s| |S|^}} |t vrt|d|d|dd| s| |Sd dd| D} | |d| S)anNormalize a Hugging Face web URL into the body of a 'hf://' URI (everything after 'hf://'). The returned string is fed back into the regular URI parsing logic, so all validation (repo id, revision, empty path segments, ...) is shared with the canonical 'hf://' path. Only unambiguous URLs are accepted: any unrecognized route raises [`HfUriError`]. z://r0r zUnrecognized host 'zC'. Expected a Hugging Face URL (e.g. 'https://huggingface.co/...').r*cSsg|]}|r|qSr r r rxr r r asz$_url_to_uri_body..r-z0Missing repository or bucket identifier in URL 'r.Nrr zCannot parse URL 'z{': expected a '/' repository or bucket. User/organization pages and single-segment URLs are not supported.bucketszbuckets/zCannot parse bucket URL 'z': unsupported '/z /' route.cs|]}t|VqdSrRryrzr r rrt~z#_url_to_uri_body..zl/' route. Only repository pages and file/folder viewer routes (blob, resolve, raw, tree, ...) can be parsed.csr~rRrrzr r rrtrr>) rhostnamerurrwrrNsplitHF_URI_TYPE_PREFIXESrhrrDr) rOrparsedrqsegments type_prefixrepo_idrestactiontailrNprefixdecodedr r rrjOsV        rj mount_strc Cs|tjst|dtjdd|}|ttjd}|s)t|dtjddt||d\}}}|dur[:ro|:rw]'). A mount specification is a HF URI followed by a local mount path and an optional read-only/read-write flag. The full grammar is: ``` hf://[/][@][/]:[:ro|:rw] ``` See 'docs/source/en/package_reference/hf_uris.md' for the full specification. Args: mount_str (`str`): The mount string to parse. Must start with 'hf://' and contain a ':' segment. Returns: [`HfMount`]: the parsed mount. Raises: [`HfUriError`]: If the mount string is malformed (missing mount path, invalid URI, etc.). Examples: ```py >>> from huggingface_hub.utils import parse_hf_mount >>> parse_hf_mount("hf://my-org/my-model:/data:ro") HfMount(source=HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo=''), mount_path='/data', read_only=True) >>> parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:rw") HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', revision=None, path_in_repo='sub/dir'), mount_path='/mnt', read_only=False) ``` rfr.r*NrergzKMissing mount path. Expected ':' (e.g. 'hf://org/model:/data').)r\r]r^r') r4rr?rrh _split_mountrbr,r[) rrrnrpr]r^uri_strr\r6r r rparse_hf_mounts(     rrnrcCs|drd|d}}n|drd|d}}nd}|d}|dkr6|dur1t|dd |ddfS|d|}||d d}|sLt|d d |||fS) zSplit the ':[:ro|:rw]' suffix from 'body'. Returns '(location, mount_path, read_only)' where 'mount_path' is 'None' if no mount segment is present. r`TraFNz:/zb':ro'/':rw' suffix is only valid when a mount path is provided (e.g. 'hf://...:/:ro').r*r z#Missing location before mount path.)endswith removesuffixrfindr)rnrr^idxrpr]r r rrs$       rrpcCs|d}|dkr8|tjvrt|d|dtj|ddt|}dur4t|dtj|d dd |fS|d|}||d d}|tjvrRtj||fSt|}durht|d |d |ddd |fS)zDetect the (optional) type prefix and return '(type, remaining_location)'. A missing type prefix defaults to 'model'. Singular forms ('model/', 'dataset/', etc.) are explicitly rejected with a helpful error. r-rzMissing identifier after 'z '. Expected 'z/'.r*Nz*Type prefix must be plural. Did you mean 'z/...'?rIr z!Type prefix must be plural, got 'z/'. Did you mean 'z/'?)findrrrr?rget)rpr slash_idxsingular_pluralfirstrr r rrks,    rkrocCs|d}|dd}t|dks|dr|ds#t|d|dd|dd|d}d|vr8t|d dt|d krB|dnd }t||d ||d S)z8Parse the body of a bucket URI: 'namespace/name[/path]'.r-r|rr z)Bucket id must be 'namespace/name', got 'r.r*r>z3Bucket URIs do not support a revision marker ('@').r Nrrrr!r')striprrhrr)rprorrE bucket_idpath_in_bucketr r rrls   rlc Cs|d}|s t|dd|d}|dks!|d|ddkrQd}|dd}t|dkr9t|d |d d|d d|d}t|dkrN|dnd }nh|d|}||dd}|sgt|d d|ddkrxt|d |ddt|} | dur| }|t|d d}n|d} | dkr|}d }n|d| }|| dd}t |}|st|ddt |||||dS)z@Parse the body of a repo URI: '[@][/]'.r-zMissing repository id.r*r>rNr r|z-Repository id must be 'namespace/name', got 'z'. rr z!Missing repository id before '@'.r.zEmpty revision after '@'.r) rrrr2rrhr@matchgroup removeprefixrr) rprorat_idxrrErr! rev_and_pathrrr r rrm'sJ           rm).rV functoolsre dataclassesrr urllib.parserrrhuggingface_hubrhuggingface_hub.errorsrr _validatorsr ritemsrdictr3rXcompiler@ frozensetvaluesrrrrr[rZrd lru_cacherbriryrjrtuplerrWrkrlrmr r r rsX   $ }* ;  I(: