^ i1ddlmZddlmZddlmZddlmZmZm Z m Z ddl Z ddl Z e j eZee jdd Zdd ZGddZeZddZddZdS)) annotations)files)Path)AnyDictOptionalUnionNvtOptional[Union[str, int]]returnstrc|dSt|trt|St|ddS)a Normalize an observation type identifier (varType) into a canonical string. This function ensures that both satellite/platform identifiers (strings) and conventional observation codes (integers, i.e., *kx* values) are represented in a consistent, lowercase, hyphenated string form. Parameters ---------- vt : str or int or None Observation type identifier. - If ``int`` (e.g., 120), it is returned as a string (``"120"``). - If ``str``, it is normalized: stripped, lowercased, and with underscores converted to hyphens. - If ``None``, returns an empty string. Returns ------- str Normalized observation type identifier. Always a string. Examples -------- >>> _normalize_vartype(120) '120' >>> _normalize_vartype("MetOp_B") 'metop-b' >>> _normalize_vartype(None) '' N_-) isinstanceintr striplowerreplace)r s =/home/caroline.viezel/readDiagGerd/src/gsidiag/datasources.py_normalize_vartypers[> zr"c2ww r77==?? " " * *3 4 44vn Optional[str]c|dSt|ddS)a Normalize a variable or channel family name into a canonical string. This function standardizes variable names (e.g., "amsua", "uv", "t") to a consistent, lowercase, hyphenated format. Parameters ---------- vn : str or None Variable or channel family name. - If ``str``, it is normalized: stripped, lowercased, and with underscores converted to hyphens. - If ``None``, returns an empty string. Returns ------- str Normalized variable name. Always a string. Examples -------- >>> _normalize_varname("Amsua") 'amsua' >>> _normalize_varname("uv_wind") 'uv-wind' >>> _normalize_varname(None) '' Nrrr)r rrr)rs r_normalize_varnamer4s>: zr r77==?? " " * *3 4 44rc<eZdZdZdddZdd ZddZddZddZdS)DataSourcesInfoaParser and accessor for observation metadata defined in ``table.yml``. The YAML is expected to have the following structure: ```yaml observations: - kx: # e.g., "n19", "metop-b", "120" details: - var: # e.g., "amsua", "uv", "t" abbreviation: # short label for legends instrument: # human-friendly instrument/platform description color: # e.g., "#1f77b4" symbol: # plotting symbol, e.g., "x", "s", "*" iuse: "<-1|0|1|2>" # keep as string for compatibility with existing code ``` N yaml_fileOptional[str | Path]r Nonec "i}d}|gt|}td||d}t j|pi}t |}n^ tddz }td||d}t j|pi}d }n#tttf$r}td |tt d}| s0td ttd |td ||d}t j|pi}t |}Yd}~nd}~wwxYwtdt!|dgpg|pdi|_|dgpgD])} | dd} t | } | std| X|j| i} | dgpg} | std| d}| D]`}t |dd}|std| |V|| |<|dz }atd| |+t-d|jD}tdt!|j|i|_|jD]9\}} t5|}n#t6t8f$r|}YnwxYw||j|<:dS)aLoad observation metadata from the packaged YAML table. Parameters ---------- yaml_file : str | Path | None Optional custom path to a YAML file. When `None`, the loader tries: (1) `importlib.resources.files("gsidiag") / "table.yml"` (works in wheels), then (2) a sibling `table.yml` next to this module as a fallback. rNz3Attempting to load table.yml from explicit path: %szutf-8)encodinggsidiagz table.ymlz)Attempting to load packaged table.yml: %szpkg://gsidiag/table.ymlzGPackaged resource not available (%s). Falling back to sibling table.ymlz2Missing 'table.yml' alongside %s and not packaged.zgMissing 'table.yml' inside installed package 'gsidiag'. Make sure build config includes this data file.zLoading sibling table.yml: %sz$Loaded %d observation groups from %s observationsz kxz%Skipping observation without 'kx': %rdetailszkx=%s has no 'details' entriesrvarz*Skipping detail without 'var' in kx=%s: %rz'Registered kx=%s with %d detail entriesc34K|]}t|VdSN)len).0vs r z+DataSourcesInfo.__init__..s(??Q#a&&??????rz9Built lookup with %d platforms (kx) and %d (kx,var) pairs)rloggerdebug read_textyaml safe_loadr rFileNotFoundErrorModuleNotFoundErrorAttributeError__file__ with_nameis_fileerrorinfor-getlookuprwarning setdefaultsumvaluestabitemsr ValueError TypeError)selfr data source_descyml_pathtextresesiblingobsraw_kxr'bucket details_listcountdetailr) total_pairskx_strmappingkx_keys r__init__zDataSourcesInfo.__init__hs, "  IH LLNPX Y Y Y%%w%77D>$''-2Dh--KK +I&&4 H#NNN}}g}66~d++1r7 %':NK + + + ]x..22;??((LLL ,J *>?????  G       @B#{0022 ' 'OFG $'KK *    &DHV    ' 's,/AC G #CGG O++PPvar_typer var_namekeyc|j|i|i|d}|dvrdnt|S)axRetrieve a metadata field from the lookup. Args: var_type: Observation type (e.g., "n19", "metop-a", "120"). var_name: Variable name (e.g., "amsua", "uv", "t"). key: Field to retrieve (e.g., "instrument", "abbreviation", "color"). Returns: The field value as a string, or an empty string if not found. r)Nr)r?r>r )rHr[r\r]vals rr>zDataSourcesInfo.getsSkooh++//"==AA#rJJJ&&rrCHH4r list[str]cNt|jS)z8List all platforms/keys (``kx``) available in the table.)sortedr?keys)rHs r platformszDataSourcesInfo.platformssdk&&(()))rcvt|j|iS)z;List variables available for a given ``var_type`` (``kx``).)rbr?r>rc)rHr[s r variables_forzDataSourcesInfo.variables_fors,dkooh3388::;;;rDict[str, Any]czt|j|i|iS)zHReturn the complete detail dict for a (``var_type``, ``var_name``) pair.)dictr?r>)rHr[r\s rrUzDataSourcesInfo.details0DKOOHb1155hCCDDDrr,)r r!r r")r[r r\r r]r r r )r r`)r[r r r`)r[r r\r r rg) __name__ __module__ __qualname____doc__rZr>rdrfrUrrrrVs"^'^'^'^'^'@ 5 5 5 5****<<<<EEEEEErrvarTypevarNamewhatct|}t|}|pd} t|||}|r-t d||||t|Sn5#t$r(}t d||||Yd}~nd}~wwxYw|dkridddd d d d d ddddddddddddddddddd d!d"d#d$d%d&d'd(d)d*d+}|||pd pd,} t|d-| } t d.||| | S|d/vr/t|} t d0|||| | S|d1vr8|pd pd,} t d0|||| | St d2|||dS)3aReturn user-friendly metadata with YAML-first priority and robust fallbacks. Priority: 1) ``table.yml`` (if an entry exists) 2) Heuristics (e.g., "NOAA-19 AMSU-A" for ``n19``/``amsua``) This function never returns ``None``; it returns an empty string if nothing matches. Args: varType: Observation type identifier (e.g., "n19", "metop-b", "120"). varName: Variable or channel family (e.g., "amsua", "uv", "t"). what: Field to retrieve (case-insensitive), e.g., "instrument", "abbreviation", "platform", "sensor", "color", "symbol", "iuse". Returns: A string with the requested information, or an empty string if unknown. rz%getVarInfo YAML hit: (%s,%s).%s -> %rz%YAML lookup failed for (%s,%s).%s: %sN instrumentamsuazAMSU-AamsubzAMSU-BairsAIRSiasiIASIhirsHIRSmhsMHSssmisSSMISatmsATMScrisCrISzcris-fsrzCrIS FSRgomeGOMEmls30MLSomiOMIsndrd1zGOES Sounder D1sndrd2zGOES Sounder D2sndrd3zGOES Sounder D3sndrd4zGOES Sounder D4z!Atmospheric Motion Vectors (AMVs)zGNSS-RO Bending AnglezGNSS-RO)uvgps_bndgpsSENSOR z0getVarInfo fallback 'instrument' for (%s,%s): %s>platform satellitez(getVarInfo fallback '%s' for (%s,%s): %s>sensorinstrument_namez-getVarInfo unknown field '%s' for (%s,%s): '') rrrr_DS_INFOr>r1r2r Exceptionuppercanonical_platform) rorprqvt_normvn_normr]r_rN sensor_maprouts r getVarInfors$!))G ))G :2     $ $ & &CXll7GS11   LL@'7TWY\ ] ] ]s88O  XXX )>)@)@)LHMM#G,,77v77 GRY[^___  ''' )) ?gwX[\\\  +++}"##%%1 ?gwX[\\\  LL@#wPWXXX 2sA B CCCc|tddSt|}|dd}t |ts|r$d|d}td|||S| d rG|d dr+d |d d}td |||Sd ddd}||vr&||}td|||S| drF| dd}td|||S| pd}td|||S)akReturn a human-friendly platform name given a varType/kx. Examples -------- "n19" -> "NOAA-19" "n20" -> "NOAA-20" "n21" -> "NOAA-21" "npp" -> "Suomi-NPP" "metop-a" -> "MetOp-A" "metop_b" -> "MetOp-B" 120 -> "Conventional (kx=120)" "120" -> "Conventional (kx=120)" None -> "PLATFORM" Nz)canonical_platform: vt=None -> 'PLATFORM'PLATFORMrrzConventional (kx=)z)canonical_platform: conventional %r -> %snr*zNOAA-z&canonical_platform: NOAA-like %r -> %sz Suomi-NPPzNOAA-20zNOAA-21)nppn20n21z#canonical_platform: mapped %r -> %smetopMetopMetOpz'canonical_platform: MetOp-like %r -> %sz$canonical_platform: default %r -> %s) r1r2r rrrrrisdigit startswithtitler)r v_rawr/rrXs rrr2s z @AAAz GGMMOOE c3''A"caiikk*%*** @"cJJJ  ||CQqrrU]]__aeoo =r3GGG G  G||aj :BDDD  ||Gggii11 >CHHH ++-- %:C LL7SAAA Jr)r r r r )rrr r )ror rprrqrr r ) __future__rimportlib.resourcesrpathlibrtypingrrrr loggingr4 getLoggerrjr1 addHandler NullHandlerrrrrrrrnrrrsL""""""%%%%%%------------  8 $ $%'%''(((#5#5#5#5L5555DJEJEJEJEJEJEJEJE\ ?  HHHHV444444r