_Vg`UdZddlmZddlmZmZddlZddlmZm Z m Z m Z m Z m Z mZddlZddlmZmZddlmZGdd e ZGd d e ZiZd ed <iZded<iZded<dgZded<GddeeZd8dZd9d:dZ d;dZ!ddZ#d?dZ$GddZ%Gdd e eZ&d!Z'd"Z(d#Z)d$Z*e&e e'a+e&e!e(a,e&e#e*a-e&e"e)Z.e%eZ/Gd%d&eZ0 d@ dAd'a1 dB dCd(Z2dDd)Z3dEd*Z4dFd+Z5dGd,Z6dGd-Z7dHd.Z8dFd/Z9dId0Z:dJdKd1Z;edLd2ZdNd5Z?dOd6Z@e=eAZBe=eCZDe=eEZFe=eGZHe>eGeIfZJdPd7ZKy)Qa The config module holds package-wide configurables and provides a uniform API for working with them. Overview ======== This module supports the following requirements: - options are referenced using keys in dot.notation, e.g. "x.y.option - z". - keys are case-insensitive. - functions should accept partial/regex keys, when unambiguous. - options can be registered by modules at import time. - options can be registered at init-time (via core.config_init) - options have a default value, and (optionally) a description and validation function associated with them. - options can be deprecated, in which case referencing them should produce a warning. - deprecated options can optionally be rerouted to a replacement so that accessing a deprecated option reroutes to a differently named option. - options can be reset to their default value. - all option can be reset to their default value at once. - all options in a certain sub - namespace can be reset at once. - the user can set / get / reset or ask for the description of an option. - a developer can register and mark an option as deprecated. - you can register a callback to be invoked when the option value is set or reset. Changing the stored value is considered misuse, but is not verboten. Implementation ============== - Data is stored using nested dictionaries, and should be accessed through the provided API. - "Registered options" and "Deprecated options" have metadata associated with them, which are stored in auxiliary dictionaries keyed on the fully-qualified key, e.g. "x.y.z.option". - the config_init module is imported by the package's __init__.py file. placing any register_option() calls there will ensure those options are available as soon as pandas is loaded. If you use register_option in a module, it will only be available after that module is imported, which you should be aware of. - `config_prefix` is a context_manager (for use with the `with` keyword) which can save developers some typing, see the docstring. ) annotations)ContextDecoratorcontextmanagerN)AnyCallableGenericIterableIterator NamedTuplecast)FT)find_stack_levelc6eZdZUded<ded<ded<ded<y)DeprecatedOptionstrkey str | Nonemsgrkey removal_verN__name__ __module__ __qualname____annotations__V/var/www/html/hubwallet-dev/venv/lib/python3.12/site-packages/pandas/_config/config.pyrrLs H O rrc@eZdZUded<ded<ded<ded<ded <y ) RegisteredOptionrrobjectdefvaldocCallable[[object], Any] | None validatorCallable[[str], Any] | NonecbNrrrrr!r!Ss H N H--##rr!zdict[str, DeprecatedOption]_deprecated_optionszdict[str, RegisteredOption]_registered_optionsdict[str, Any]_global_configall list[str]_reserved_keysceZdZdZy) OptionErrorz^ Exception raised for pandas.options. Backwards compatible with KeyError checks. N)rrr__doc__rrrr1r1hsrr1ct|}t|dk(r$|s t|tdt |t|dkDr td|d}|s t|t |}|S)NrzNo such keys(s): zPattern matched multiple keys)_select_optionslen_warn_if_deprecatedr1repr_translate_key)patsilentkeysrs r_get_single_keyr=tss 3 D 4yA~  $-d3i[9:: 4y1}9:: q'C C  C Jrc@t||}t|\}}||SN)r= _get_root)r:r;rrootks r _get_optionrCs& #v &CnGD! 7NrcNt|}|r|dzdk7r td|jdd}|r+t|j d}t d|dt |ddd|dddD]\}}t||}t|}|r|jr|j|t|\} }|| |<|js\|r1tjd 5|j|ddd|j|y#1swYxYw) Nrz4Must provide an even number of non-keyword argumentsr;Fz2_set_option() got an unexpected keyword argument ""r4T)record)r6 ValueErrorpoplistr< TypeErrorzipr=_get_registered_optionr&r@r(warningscatch_warnings) argskwargsnargsr;kwargrBvrorAs r _set_optionrVs IE EAINOPPZZ% (F V[[]#A&LUGSTUVVD1ItADqDz*1a( "3 '  KKNC.aQ 44,,D9DDIS !s ,DD$ ct|}t|dk(r tddj|Dcgc] }t |c}}|r t |y|Scc}w)NrNo such keys(s) )r5r6r1join_build_option_descriptionprint)r: _print_descr<rBss r_describe_optionr_sY 3 D 4yA~+,, >A,Q/>?A a H ?sAct|}t|dk(r tdt|dkDrt|dkr|dk7r td|D]!}t |t |j |#y)NrrXr4r-zYou must specify at least 4 characters when resetting multiple keys, use the special keyword "all" to reset all the options to their default valuer;)r5r6r1rHrVr*r#)r:r;r<rBs r _reset_optionrcs| 3 D 4yA~+,, 4y1}SA#, D  EA*1-44VDErcFt|d}t|jSNTrb)r=rMr#)r:rs rget_default_valrfs #d +C !# & - --rc2eZdZdZdddZd dZd dZd dZy) DictWrapperz/provide attribute-style access to a nested dictc`tj|d|tj|d|y)Ndprefix)r" __setattr__)selfrjrks r__init__zDictWrapper.__init__s&4a(462rctj|d}|r|dz }||z }||jvr*t|j|ts t ||yt d)Nrk.z.You can only set the value of existing options)r"__getattribute__rj isinstancedictrVr1)rmrvalrks rrlzDictWrapper.__setattr__s]((x8  cMF#  $&&=DFF3K!>  $NO Orctj|d}|r|dz }||z } tj|d|}t |t r t ||St|S#t$r}td|d}~wwxYw)NrkrprjzNo such option)r"rqKeyErrorr1rrrsrhrC)rmrrkrTerrs r __getattr__zDictWrapper.__getattr__s((x8  cMF#  9''c237A a q&) )v& &  9./S 8 9sA$$ A>- A99A>cHt|jjSr?)rJrjr<)rms r__dir__zDictWrapper.__dir__sDFFKKM""rN))rjr+rkrreturnNone)rrrtrr|r}rr)r| Iterable[str])rrrr2rnrlrxrzrrrrhrhs93 P '#rrhc.eZdZddZddZeddZy)CallableDynamicDocc ||_||_yr?) __doc_tmpl____func__)rmfuncdoc_tmpls rrnzCallableDynamicDoc.__init__s$ rc&|j|i|Sr?)r)rmrPkwdss r__call__zCallableDynamicDoc.__call__st}}d+d++rctdd}tttj }|j j ||S)Nr-F)r]) opts_desc opts_list)r_pp_options_listrJr*r<rformat)rmrrs rr2zCallableDynamicDoc.__doc__ sC$U> #D)<)A)A)C$DE   '')y'QQrN)rzCallable[..., T]rrr|r})r|r)r|r)rrrrnrpropertyr2rrrrrs",RRrra get_option(pat) Retrieves the value of the specified option. Available options: {opts_list} Parameters ---------- pat : str Regexp which should match a single option. Note: partial matches are supported for convenience, but unless you use the full option name (e.g. x.y.z.option_name), your code may break in future versions if new options with similar names are introduced. Returns ------- result : the value of the option Raises ------ OptionError : if no such option exists Notes ----- Please reference the :ref:`User Guide ` for more information. The available options with its descriptions: {opts_desc} a set_option(pat, value) Sets the value of the specified option. Available options: {opts_list} Parameters ---------- pat : str Regexp which should match a single option. Note: partial matches are supported for convenience, but unless you use the full option name (e.g. x.y.z.option_name), your code may break in future versions if new options with similar names are introduced. value : object New value of option. Returns ------- None Raises ------ OptionError if no such option exists Notes ----- Please reference the :ref:`User Guide ` for more information. The available options with its descriptions: {opts_desc} a describe_option(pat, _print_desc=False) Prints the description for one or more registered options. Call with no arguments to get a listing for all registered options. Available options: {opts_list} Parameters ---------- pat : str Regexp pattern. All matching keys will have their description displayed. _print_desc : bool, default True If True (default) the description(s) will be printed to stdout. Otherwise, the description(s) will be returned as a unicode string (for testing). Returns ------- None by default, the description(s) as a unicode string if _print_desc is False Notes ----- Please reference the :ref:`User Guide ` for more information. The available options with its descriptions: {opts_desc} a} reset_option(pat) Reset one or more options to their default value. Pass "all" as argument to reset all options. Available options: {opts_list} Parameters ---------- pat : str/regex If specified only options matching `prefix*` will be reset. Note: partial matches are supported for convenience, but unless you use the full option name (e.g. x.y.z.option_name), your code may break in future versions if new options with similar names are introduced. Returns ------- None Notes ----- Please reference the :ref:`User Guide ` for more information. The available options with its descriptions: {opts_desc} c(eZdZdZddZddZddZy)option_contexta Context manager to temporarily set options in the `with` statement context. You need to invoke as ``option_context(pat, val, [(pat, val), ...])``. Examples -------- >>> with option_context('display.max_rows', 10, 'display.max_columns', 5): ... pass c t|dzdk7st|dkr tdtt|ddd|ddd|_y)NrErz>Need to invoke as option_context(pat, val, [(pat, val), ...]).r4)r6rHrJrLops)rmrPs rrnzoption_context.__init__sS t9q=A TQP D1ItADqDz23rc |jDcgc]\}}|t|dfc}}|_|jD]\}}t||dycc}}wre)rrCundorV)rmr:rts r __enter__zoption_context.__enter__sQJN((Shc3c;s489S  /HC S . /TsAcb|jr#|jD]\}}t||dyyre)rrV)rmrPr:rts r__exit__zoption_context.__exit__s1 99 II 3SCT2 3 rNr|r})rrrr2rnrrrrrrrs 4/ 3rrc ddl}ddl}|j}|tvrt d|d|t vrt d|d|r|||j d}|D]U}tjd|jzdz|st|d |j|sIt|d t} d } t|dd D]P\} } t| ts-t | j!dj#|d|  | | vri| | <| | } Rt| ts-t | j!dj#|dd  || |d <t%|||||t|<y)a Register an option in the package-wide pandas config object Parameters ---------- key : str Fully-qualified key, e.g. "x.y.option - z". defval : object Default value of the option. doc : str Description of the option. validator : Callable, optional Function of a single argument, should raise `ValueError` if called with a value which is not a legal value for the option. cb a function of a single argument "key", which is called immediately after an option value is set/reset. key is the full name of the option. Raises ------ ValueError if `validator` is specified and `defval` is not a valid value. rNOption 'z' has already been registeredz' is a reserved keyrp^$z is not a valid identifierz is a python keywordz5Path prefix to option '{option}' is already an option)option)rr#r$r&r()keywordtokenizelowerr*r1r/splitrematchNamerH iskeywordr, enumeraterrrsrrZr!) rr#r$r&r(rrpathrBcursorrips rregister_optionrs> ))+C !!HSE)FGHH nHSE)<=>>& 99S>D 9xxhmm+c115s"<=> >   Q s"678 8 9 F AC$s)$1&$'cjjbq0BjCD D F?F1I  fd ##**CHHT#2Y,?*@AAF48 0 C9 rc||j}|tvrtd|dt||||t|<y)a Mark option `key` as deprecated, if code attempts to access this option, a warning will be produced, using `msg` if given, or a default message if not. if `rkey` is given, any access to the key will be re-routed to `rkey`. Neither the existence of `key` nor that if `rkey` is checked. If they do not exist, any subsequence access will fail as usual, after the deprecation warning is given. Parameters ---------- key : str Name of the option to be deprecated. must be a fully-qualified option name (e.g "x.y.z.rkey"). msg : str, optional Warning message to output when the key is referenced. if no message is given a default message will be emitted. rkey : str, optional Name of an option to reroute access to. If specified, any referenced `key` will be re-routed to `rkey` including set/get/reset. rkey must be a fully-qualified option name (e.g "x.y.z.rkey"). used by the default message if no `msg` is specified. removal_ver : str, optional Specifies the version in which this option will be removed. used by the default message if no `msg` is specified. Raises ------ OptionError If the specified key has already been deprecated. rz)' has already been defined as deprecated.N)rr)r1r)rrrrs rdeprecate_optionrsDN ))+C !!HSE)RSTT/S$ Lrc|tvr|gSttj}|dk(r|S|Dcgc]*}tj||tj s)|,c}Scc}w)zb returns a list of keys matching `pat` if pat=="all", returns all registered options r-)r*sortedr<rsearchI)r:r<rBs rr5r5Cs] !!u  %**, -D e|  7!ryya6A 77 7s *A&A&c\|jd}t}|ddD]}||} ||dfS)Nrpr)rr,)rrrrs rr@r@UsA 99S>D F #2Y 48 rc2|j}|tvS)z4Returns True if the given option has been deprecated)rr)rs r_is_deprecatedr]s ))+C % %%rc8 t|}|S#t$rYywxYw)z Retrieves the metadata for a deprecated option, if `key` is deprecated. Returns ------- DeprecatedOption (namedtuple) if key is deprecated, None otherwise N)r)rvrrjs r_get_deprecated_optionrcs,  $ s c,tj|S)z Retrieves the option metadata if `key` is a registered option. Returns ------- RegisteredOption (namedtuple) if key is deprecated, None otherwise )r*getrs rrMrMss  " "3 ''rc@t|}|r|jxs|S|S)z if key id deprecated and a replacement key defined, will return the replacement key, otherwise returns `key` as - is )rrrs rr9r9~s$ s#Avv} rcpt|}|r|jr/tj|jtt yd|d}|j r|d|j z }|jr|d|jdz }n|dz }tj|tt yy ) z Checks if `key` is a deprecated option and if so, prints a warning. Returns ------- bool - True if `key` is deprecated, False otherwise. ) stacklevel'z' is deprecatedz and will be removed in z, please use 'z ' instead.z, please refrain from using it.TF)rrrNwarn FutureWarningrrr)rrjrs rr7r7s s#A 55 MM+- cU/*C}}1!--AAvvxz::88 MM#}9I9K L rcdt|}t|}|d}|jr<|dj|jj j dz }n|dz }|r |d|j dt|ddz }|r#|jxsd}|d z }|d |d z }|d z }|S) zCBuilds a formatted description of a registered option and prints it rYzNo description available.z [default: z] [currently: T]r{z (Deprecatedz, use `z ` instead.)) rMrr$rZstriprr#rCr)rBrUrjr^rs rr[r[sq!Aq!A #QAuu TYYquu{{}**40 11 (( z At8L7MQ OOvv|   wtfJ '' S Hrc ddlm}ddlm d  fd }g}t |Dcgc]}|j ddks|}}|r ||d|z }|Dcgc]}|j ddk\s|}}|t |dD]8\}} t | Dcgc]}|t|dzd } }|||| z }:d j|} |r t| y | Scc}wcc}wcc}w) z@Builds a concise listing of available options, grouped by prefixr)groupby)wrapc|rd|zdznd}dj||dd}|r|dr |r |dd z|d<|S) Nz- z.[r{z, z F)initial_indentsubsequent_indentbreak_long_wordsrr)rZ)namekspfxlswidthrs rppzpp_options_list..ppsY$(dTkD b  IIbM ""   "R&TVc\BrF rrpr{c*|d|jdSNrp)rfind)xs rz!pp_options_list..s.AGGCL0Arr4NrY)rrrrr|r.) itertoolsrtextwraprrfindrJr6rZr\) r<r_printrrrrsinglesrBgrr^rs ` @rrrs! B ,:Q!&&+/q:G: bWo 0!qvvc{a/A 0D 0t &AB1'+Aw /!aA o / / bBi " A  a; 10sC&C&C+1C+C0c#Kdfd }t}t}t}|ta|ta|ta d|a|a|ay#|a|a|awxYww)a contextmanager for multiple invocations of API with a common prefix supported API functions: (register / get / set )__option Warning: This is not thread - safe, and won't work properly if you import the API functions into your module using the "from x import y" construct. Example ------- import pandas._config.config as cf with cf.config_prefix("display.font"): cf.register_option("color", "red") cf.register_option("size", " 5 pt") cf.set_option(size, " 6 pt") cf.get_option(size) ... etc' will register options "display.font.color", "display.font.size", set the value of "display.font.size"... and so on. c4dfd }tt|S)Nc*d|}|g|i|Srr)rrPrpkeyrrks rinnerz*config_prefix..wrap..inners(XQse$D,t,t, ,rr~)r r )rrrks` rrzconfig_prefix..wraps -Au~rN)rr r|r )r get_option set_option)rkr_register_optionrCrVs` r config_prefixrse<'KKj!Jj!J?+O+   *!  *s=AA A AAcdfd }|S)a Parameters ---------- `_type` - a type to be compared against (e.g. type(x) == `_type`) Returns ------- validator - a function of a single argument x , which raises ValueError if type(x) is not equal to `_type` c@t|k7rtddy)NzValue must have type 'r)typerH)r_types rrzis_type_factory..inner+s) 7e 5eWA>? ? rrr)rrs` ris_type_factoryrs@ Lrctttfr+tdjt t ndddfd }|S)z Parameters ---------- `_type` - the type to be checked against Returns ------- validator - a function of a single argument x , which raises ValueError if x is not an instance of `_type` |rc:t|stdy)NzValue must be an instance of )rrrH)rr type_reprs rrz"is_instance_factory..innerEs%!U#z3is_one_of_factory..inner..Ts/qt/srzValue must be one of z or a callable)anyrrZr6rH)rlvaluvals pp_valuesr callables legal_valuess` rrz is_one_of_factory..innerQst L /Y///;++C o% 0 !=sA&r)callable)rrrrs` @ris_one_of_factoryrLsC(8qHQK8I+?!8A;A?L & L9?sAAA A cN|yt|tr|dk\ryd}t|)z Verify that value is None or a positive int. Parameters ---------- value : None or int The `value` to be checked. Raises ------ ValueError When the value is not None or is a negative integer Nrz+Value must be a nonnegative integer or None)rrintrH)valuers ris_nonnegative_intr_s/ } E3  A:  7C S/rc0t|s tdy)z Parameters ---------- `obj` - the object to be checked Returns ------- validator - returns True if object is callable raises ValueError otherwise. zValue must be a callableT)rrH)objs r is_callabler s C=344 r)r:rr;boolr|r)F)r:rr;r r|rr)r{T)r:rr]r r|r)r:rr;r r|r})r:r)r{NN) rrr#r"r$rr&r%r(r'r|r})NNN) rrrrrrrrr|r})r:rr|r.)rrr|ztuple[dict[str, Any], str])rrr|r r~)rrr|r)rBrr|r)PF)r<rrr )r|zIterator[None])rz type[Any]r|Callable[[Any], None])r|r )rr"r|r})r|r )Lr2 __future__r contextlibrrrtypingrrrr r r r rNpandas._typingr rpandas.util._exceptionsrrr!r)rr*r,r/AttributeErrorrvr1r=rCrVr_rcrfrhr_get_option_tmpl_set_option_tmpl_describe_option_tmpl_reset_option_tmplrr reset_optiondescribe_optionoptionsrrrr5r@rrrMr9r7r[rrrrrrris_intr is_boolfloatis_floatris_strbytesis_textr rrrr!sm0d# 5z$z$46054605"$##G #.($@  E$. "#"#\ R R D"H DD -= >  -= > !-1CD $%57LM n % 3%3F04&* H H H H. H $ H  HZ" ,M ,M ,M ,M ,M  ,Mf8$&  ( < 0L/+/+l*4&6   $  5 !   sEl +r