EivPUddlmZddlZddlmZmZmZmZddlm Z m Z ddl m Z m Z m Z mZmZddlmZmZmZmZddlmZddlmZmZdd lmZdd lmZerdd lmZe ee zZ!ee e!fee"e e!fzZ#d Z$d e%d<dZ&d e%d<e$e&gZ'de%d<e(e$e&gZ)de%d<e GddZ*d,dZ+d-dZ,e dddejZZ.de%d<dZ/de%d<d e/zZ0de%d!<e d"ddZ1de%d#<d.d$Z2d/d%Z3d0d&Z4e Gd'd(ee e fZ5d1d)Z6 d2d*Z7 d3d+Z8y)4) annotationsN)IterableIteratorMappingMutableMapping) dataclassfield)datedatetimetime timedeltatimezone) TYPE_CHECKINGAnyFinalcast)parse)StreamlitAPIException!StreamlitQueryParamDictValueError) ForwardMsg)get_script_run_ctx)SupportsKeysAndGetItemembedz Final[str]EMBED_QUERY_PARAM embed_optionsEMBED_OPTIONS_QUERY_PARAMzFinal[list[str]]EMBED_QUERY_PARAMS_KEYSzFinal[frozenset[str]]PROTECTED_QUERY_PARAMSc:eZdZUdZded<ded<ded<ded<y) WidgetBindingzz%is_empty_url_value..Ss%=!a2g%=sr/)r0r1lenall)r2s r-is_empty_url_valuer=Ds6%5zA~=#%=u%="== B;r,itzinfor _UTC_EPOCHi@B_SECONDS_TO_MICROSiQ_DAYS_TO_MICROSi_TIME_BASE_DATEcj|j|jtzz|jtzzSN) microsecondssecondsrBdaysrC)deltas r-_delta_to_microsrK_s5  --, , - ** & 'r,cd|vr\ tj|}|jytt |j t jtz Sd|vr_ tj|}tj|tt j}tt |tz Sd|vrh tj|}|jytjt|t j}tt |tz Sy#t$rYywxYw#t$rYywxYw#t$rYywxYw)aTry to parse an ISO date/time/datetime string to microsecond timestamp. Supports the same ISO formats used by date/time slider URL parameters: - DATE: ``YYYY-MM-DD`` - TIME: ``HH:MM`` or ``HH:MM:SS`` - DATETIME: ``YYYY-MM-DDTHH:MM`` or ``YYYY-MM-DDTHH:MM:SS`` Returns the microsecond float if parsing succeeds, or ``None`` if the string doesn't match any recognized format. TNr?-:)r fromisoformatr@floatrKreplacerutcrA ValueErrorr combiner rD)sdtdts r-_try_parse_iso_to_microsrZis6 ax ''*Byy$)"**HLL**IJ*VWX X  ax ""1%A!!!TVHLLAB)"z/:; ;  ax ""1%Axx#!!/1X\\JB)"z/:; ; /      sB!D18D1&AE !E+AE1 D=<D= E  E  EEc t|tr|dn|}t|r%|xxdk(rgSxdk(rgSxdk(rgSdk(ry y|xdk(r+|j}|d k(ry |d k(ry t d |xdk(r  t |Sxdk(r t |Sxdk(r|Sxdk(r t|Sxdk(r0g}t|D]} |jt ||Sdk(r/g}t|D]} |jt ||S |S#t$r|cYSwxYw#t$r3t|}||j|n|j|YwxYw#t$r|j|YwxYw)aConvert URL param to Python value based on WidgetState value type. Parameters ---------- value : str | list[str] The URL parameter value(s). value_type : str The WidgetState value type (e.g., "bool_value", "string_value"). Returns ------- Any The parsed Python value appropriate for the widget type. For empty URL params (e.g., ?foo=): - Array types return [] - string_value returns "" (empty string is valid) - Other types return None (signaling "cleared" state) Raises ------ ValueError If the value cannot be parsed for the given type. string_array_valueint_array_valuedouble_array_value string_valuer/N bool_valuetrueTfalseFzInvalid boolean value: int_value double_value) r0r1r=lowerrTintrQr5appendrZ)r2r$val lower_val result_doublepartmicros result_ints r-parse_url_paramros2"%.%)EC% P%P ):P =QP Q   IF"G#6se<= =   3x:  J !&e, , !02M*51 3 3!((t5 3! +-J*51 ,,%%c$i0 ,   JM   ""36d;F)%,,V4%,,T23 ",%%d+,s6 D D1?E0 D.-D.19E-,E-0F  F ceZdZUdZeeZded<eeZded<eeZ ded<eeZ ded <d*d Z d+d Z d,d Z d,d Zd-dZ d. d/dZd0dZd1dZd2dZd3dZd3dZd4dZ d5dZd6dZd7d8dZ d9dZd:dZd:dZd;dZdd"Z#d3d#Z$d?d$Z%d@d%Z&d@d&Z' dA dBd(Z( dC dDd)Z)y')E QueryParamszA lightweight wrapper of a dict that sends forwardMsgs when state changes. It stores str keys with str and List[str] values. Also manages widget bindings to query parameters for the bind="query-params" feature. )default_factorydict[str, list[str] | str] _query_paramszdict[str, WidgetBinding]_bindings_by_param_bindings_by_widgetzdict[str, list[str]]_initial_query_paramsc:td|jDS)Nc3LK|]}|jtvr|ywrF)rfr)r8keys r-r:z'QueryParams.__iter__..s' yy{"99  s"$)iterrtselfs r-__iter__zQueryParams.__iter__s" ))   r,c|jtvrtt| |j|}t |t rt|dk(ry|dS|S#t$rtt|wxYw)zRetrieves a value for a given key in query parameters. Returns the last item in a list or an empty string if empty. If the key is not present, raise KeyError. rr/r\)rfrKeyErrormissing_key_error_messagertr0r1r;r}rzr2s r- __getitem__zQueryParams.__getitem__ s 99;1 14S9: : ;&&s+E%&u:?Ry L ;4S9: : ;s-A!A!A!!A?c|j|rtd|d|j|||jy)N%Cannot directly set query parameter '=' - it is bound to a widget. Modify the widget value instead.)is_boundr_set_item_internal_send_query_param_msgrs r- __setitem__zQueryParams.__setitem__sL == '7u=LM  U+ ""$r,c2t|j||yrF)_set_item_in_dictrtrs r-rzQueryParams._set_item_internal)s$,,c59r,c|jtvrtt||j |rt d|d |j |=|jy#t$rtt|wxYw)Nz(Cannot directly delete query parameter 'r)rfrrrrrrtrr}rzs r- __delitem__zQueryParams.__delitem__,s 99;1 14S9: : == ':3%@LM  ;""3'  & & ( ;4S9: : ;s A**Bc 4t|drFt|dr:td|}t|j}|Dcgc] }|||f }}n t|}|Dcgc]\}}| } }}| j |j| D]"}|j |st d|d|D]\}} |j|| |jD]\}} |j|| |jycc}wcc}}w)Nkeysr0SupportsKeysAndGetItem[str, str | Iterable[str]]rr) hasattrrr1rextendrrritemsr) r}otherkwds other_dictrk other_as_listrz_keys_to_updater2s r-updatezQueryParams.update;s, 5& !ge]&CPRWXJ )*D9=>AaA/>M>!KM-::&#q#::diik*" C}}S!+;C5APQ ( 0JC  # #C / 0**, 0JC  # #C / 0 ""$-? ;s D# Dc||jvs|jtvrgS|j|}t|tr|S|gSrF)rtrfrr0r1rs r-get_allzQueryParams.get_alldsI d(( (CIIK;R,RI""3'"5$/u.s;T!W;szA. Modify the widget values instead, or remove the bind parameter.Tpreserve_embed)rtrrjoinclear_with_no_forward_msgr)r}rz bound_paramss r-clearzQueryParams.clears'+'9'9PT]]3=OP P 'V99;l;;<=RS  &&d&; ""$Qs A6A6ct|jDcic]}|jtvr||| c}Scc}wrF)rtrfrrs r-to_dictzQueryParams.to_dictsA)) yy{"99 cN   s#5c|jj}|jd |j|y#t$r ||_wxYw)NTr)rtcopyrrr)r}_dict old_values r- from_dictzQueryParams.from_dictsT &&++-  &&d&;  KK $ !*D   s AAc"||j|<yrFrt)r}rzris r-set_with_no_forward_msgz#QueryParams.set_with_no_forward_msgs"%3r,c|jjDcic] \}}|jtvr|r||"c}}|_ycc}}wrF)rtrrfr)r}rrzr2s r-rz%QueryParams.clear_with_no_forward_msgsL#00668 Uyy{55. J  s%A c h|jtvrtd|dtdtd|j j |}|r5|j|k7r&|jj|jdt||||}||j |<||j|<y)aRegister a widget binding to a query parameter. If another widget was previously bound to this param_key, its binding is replaced. The old widget's entry in _bindings_by_widget is cleaned up to prevent orphaned references. Parameters ---------- param_key : str The query parameter key (same as the widget's user key). widget_id : str The unique widget ID. value_type : str The WidgetState value type (e.g., "bool_value", "string_value"). script_hash : str The script hash for MPA support. Raises ------ StreamlitAPIException If the parameter is protected (embed, embed_options). z)Cannot bind to reserved query parameter 'z'. 'z' and 'z:' are used internally for Streamlit's embed functionality.N)r"r#r$r%) rfrrrrrugetr"rvpopr )r}r#r"r$r% old_bindingbindings r- bind_widgetzQueryParams.bind_widgets: ??  6 6';I;G%&g.G-HIGH --11)< ;00I=  $ $ ( ()>)> E!#   .5 *.5  +r,c|jj|d}|r'|jj|jdyy)zRemove a widget binding. Parameters ---------- widget_id : str The unique widget ID. N)rvrrur#)r}r"rs r- unbind_widgetzQueryParams.unbind_widgets@**..y$?   # # ' '(9(94 @ r,c|jj|}|y|j}|j|||jvr|j|=|j yy)aRemove a widget binding and its associated query param from the URL. Unlike ``unbind_widget`` which only removes the internal tracking, this method also deletes the query parameter value and sends a forward message so the frontend URL is updated. It is a no-op when no binding exists for *widget_id*. Parameters ---------- widget_id : str The unique widget ID. N)rvrr#rrtr)r}r"rr#s r-unbind_and_clear_paramz"QueryParams.unbind_and_clear_paramsh**..y9 ? %%  9% ** *""9-  & & ( +r,c||jvS)aCheck if a query parameter is bound to a widget. Note: This check is case-sensitive, meaning "Foo" and "foo" are treated as different parameters. This is intentional because Python keys are case-sensitive and users explicitly choose their parameter names via the widget's `key` argument. This differs from embed parameter checks which are case-insensitive for URL compatibility. Parameters ---------- param_key : str The query parameter key (case-sensitive). Returns ------- bool True if the parameter is bound to a widget. )rur}r#s r-rzQueryParams.is_bounds&D3333r,c8|jj|S)aGet the binding for a query parameter. Parameters ---------- param_key : str The query parameter key. Returns ------- WidgetBinding | None The binding if found, None otherwise. )rurrs r-get_binding_for_paramz!QueryParams.get_binding_for_params&&**955r,c8|jj|S)zGet the binding for a widget. Parameters ---------- widget_id : str The unique widget ID. Returns ------- WidgetBinding | None The binding if found, None otherwise. )rvr)r}r"s r-get_binding_for_widgetz"QueryParams.get_binding_for_widget's''++I66r,c||jvS)z2Return whether a query parameter currently exists.rrs r- has_paramzQueryParams.has_param6sD....r,c\||jvr|j|=|jyy)aRemove a query parameter without protection checks. This is an internal method for use by SessionState when clearing invalid URL-seeded values. It bypasses the bound param protection since the binding system itself needs to clear these values. Parameters ---------- param_key : str The query parameter key to remove. Returns ------- bool True if the param was removed, False if it didn't exist. TF)rtrrs r- remove_paramzQueryParams.remove_param:s2" ** *""9-  & & (r,c<||jvr|j|=yy)zRemove a query parameter without sending a forward message. This is used for backend-only cache cleanup when the frontend URL has already removed the parameter (for example, default-value collapse on a same-page rerun). TFrrs r-discard_param_no_forward_msgz(QueryParams.discard_param_no_forward_msgQs& ** *""9-r,c@tj|d}||_y)zStore the initial query params from the URL for session state seeding. Parameters ---------- query_string : str The URL query string (without the leading '?'). Tkeep_blank_valuesN)rparse_qsrw)r}rparseds r-set_initial_query_paramsz$QueryParams.set_initial_query_params]s E%+"r,c |jjDcic]\}}|t|tr|n|gc}}|_ycc}}w)aSet _initial_query_params from the current filtered _query_params. This is called after MPA page transitions where populate_from_query_string() has filtered out params bound to widgets on other pages. Using this ensures widget seeding only uses params that are valid for the current page, preventing stale values from previous pages from leaking through. N)rtrr0r1rw)r}rr9s r-%set_initial_query_params_from_currentz1QueryParams.set_initial_query_params_from_currenthsG>B=O=O=U=U=W& 59QAJq$'qaS 0& "& s Ach|jj|}|yt|dk(r|dS|S)a`Get the initial URL value for a query parameter. This is used for seeding session state on initial page load. Parameters ---------- param_key : str The query parameter key. Returns ------- str | list[str] | None The initial value(s) if present, None otherwise. Nr>r)rwrr;)r}r#valuess r-get_initial_valuezQueryParams.get_initial_valuevs=++// : > v;! !9  r,cdd}|dvrst|ttfrD|Dcgc]}|dk(r||n t|c}|j|<|j y|dk(r||n t|}n:|dk(r*t|t rt|j}n t|}||j|<|j ycc}w)aSet a corrected value for a query parameter. This is called when URL auto-correction is needed (e.g., after clamping a value to min/max bounds). It updates both the internal query params and sends a forward message to update the frontend URL. Parameters ---------- param_key : str The query parameter key. value : Any The corrected value to set. value_type : str The WidgetState value type (e.g., "double_value", "int_value"). ct|tr7tj|r"|t |k(rt t |St |S)zFormat a number, using integer format if value is a whole number. Examples: 5.0 -> "5", 5.5 -> "5.5", 5 -> "5" Handles special float values (NaN, Inf) by returning them as-is. )r0rQmathisfinitergr!)r9s r- format_numberz6QueryParams.set_corrected_value..format_numbers:!U# a(8Q#a&[3q6{"q6Mr,>r^r_r]r_Nra)r9rreturnr!)r0r1tupler!rtrboolrf)r}r#r2r$rr9 str_values r-set_corrected_valuezQueryParams.set_corrected_values"    %$/#1)36J(JM!$PSTUPVV1""9-**,!55e$Z  < 'Jud,CE ((*IE I(19% ""$#1sCc*|j|||yrF)r)r}r#r2r$s r-_set_corrected_valuez QueryParams._set_corrected_values   E:>r,Nc,tj|d}|jg}|jD]\}}|jj |}d}|-|+|j |vr|j|jd}|sUt|dk(r|j|dwt|dk(r|j||d |j|||D]} |j| |r|jyy) aPopulate query params from a URL query string. Clears current params and repopulates from the URL. When valid_script_hashes is provided (for MPA page transitions), filters out params bound to other pages. Parameters ---------- query_string : str The raw query string from the URL (e.g., "foo=bar&baz=qux"). valid_script_hashes : set[str] | None If provided, only keep params that are: - Unbound (no widget binding) - Bound to a widget with script_hash in this set Params bound to other pages are filtered out. If None, all params are kept (no filtering). TrNFrr/)rir>r\) rrrrrurr%rhr"r;rrr) r}rvalid_script_hashesparsed_query_paramsstale_widget_idsrzrir should_keepr"s r-populate_from_query_stringz&QueryParams.populate_from_query_strings*$nn\TR &&(&(+113 ;HC--11#6GK$/'''/BB!''(9(9:# s8q=00"0=X]00#b'0B00c:) ;.* *I   y ) *   & & ( r,cg}|jD]>}||vr|r$|r"|j|}|r|j|vr.|j|@d}|D]Y}|jj|}|r)|j} | |j vr|j | =d}|j |[|r|jyy)aRemove bindings and URL params for widgets that are no longer active. This cleans up query params for conditional widgets that have been unmounted. For fragment runs, widgets outside the running fragment(s) are preserved. Note: Page-based cleanup for MPA navigation is handled separately via populate_from_query_string() which is called before the script runs. Parameters ---------- active_widget_ids : set[str] Set of widget IDs that are currently active/rendered. fragment_ids_this_run : list[str] | None List of fragment IDs being run, or None for full script runs. widget_metadata : dict[str, Any] | None Widget metadata dict to check fragment IDs. FTN)rvr fragment_idrhr#rtrr) r}active_widget_idsfragment_ids_this_runwidget_metadatarr"metadataparams_removedrr#s r-remove_stale_bindingsz!QueryParams.remove_stale_bindingss.11 /I--%*..y9 4 4@'%;'%  '%  '%R=  '  %  ;   & 060606 06  06  06d A).4* 6 7/.  ,  ,7%t? 046)6)-6)  6)v3715 3)#3) 03)/ 3)  3)r,rqcd|dS)Nzst.query_params has no key "z".r+)rzs r-rr7s )#b 11r,ct|tr t||jtvr t dt|t r-t|ts|Dcgc] }t|c}||<yt|||<ycc}w)zSet an item in a dictionary.zVQuery param embed and embed_options (case-insensitive) cannot be set programmatically.N)r0rrrfrrrr!) target_dictrzr2items r-rr;sy%/44 yy{--# d  %":eS+A278$CI8 Cu: C9s!B c Di}t|dr@t|dr4td|}|jD]}||}t|||n|D]\}}||vrt |t r t |||}t |ts|g}t |tr9t |ts)|j|Dcgc] }t|c}n|jt||||<t|||tj|dScc}w)z5Convert query params into a URL-encoded query string.rrrTr)rrrrr0rrr1rr!rrhrr) query_paramsprocessed_paramsrzr2 current_valrs r-process_query_paramsr Ns! 46|V$})M >   $$& rs# GG(>>22U5V0 %3/08E#BVQ& &&"97"9 "9r,