cMhncNUdZddlmZddlmZmZddlZddlmZm Z m Z m Z m Z m Z ddlZddlmZmZddlmZerddlmZmZGd d e ZGd d e ZiZd ed<iZded<iZded<dgZded<GddeeZ d^dZ!d_d`d Z"dad"Z#dbdcd'Z$d_ddd(Z%ded)Z&Gd*d+Z'Gd,d-e eZ(d.Z)d/Z*d0Z+d1Z,e(e"e)a-e(e#e*a.e(e%e,Z/e(e$e+Z0e'eZ1Gd2d3eZ2 dfdgd<a3 dhdid@Z4djdAZ5dkdCZ6dldDZ7dmdEZ8dmdFZ9dndGZ:dldHZ;dodJZdsdXZ?dtdYZ@dtdZZAdud\ZBe?eCZDe?eEZFe?eGZHe?eIZJe@eIeKfZLdvd]ZMdS)wa 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) TYPE_CHECKINGAnyCallableGeneric NamedTuplecast)FT)find_stack_level) GeneratorIterablec8eZdZUded<ded<ded<ded<dS)DeprecatedOptionstrkey str | Nonemsgrkey removal_verN__name__ __module__ __qualname____annotations__U/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/pandas/_config/config.pyrrQs< HHHOOOrrcBeZdZUded<ded<ded<ded<ded <d S) RegisteredOptionrrobjectdefvaldocCallable[[object], Any] | None validatorCallable[[str], Any] | NonecbNrrrr r"r"XsE HHHNNN HHH----######rr"zdict[str, DeprecatedOption]_deprecated_optionszdict[str, RegisteredOption]_registered_optionsdict[str, Any]_global_configall list[str]_reserved_keysceZdZdZdS) OptionErrorz Exception raised for pandas.options. Backwards compatible with KeyError checks. Examples -------- >>> pd.options.context Traceback (most recent call last): OptionError: No such option N)rrr__doc__rrr r2r2ms    rr2patrsilentboolreturnc>t|}t|dkr0|st|tdt |t|dkrtd|d}|st|t |}|S)NrzNo such keys(s): zPattern matched multiple keys)_select_optionslen_warn_if_deprecatedr2repr_translate_key)r4r5keysrs r _get_single_keyr@s 3  D 4yyA~~ %  $ $ $9d3ii99::: 4yy1}}9::: q'C !C     C JrFrcVt||}t|\}}||SN)r@ _get_root)r4r5rrootks r _get_optionrFs+ #v & &CnnGD! 7NrNonect|}|r |dzdkrtd|dd}|rAtt |}t d|dt|ddd|dddD]\}}t||}t|}|r|j r| |t|\} } || | <|j rZ|rCtjd 5| |dddn #1swxYwY| |dS) Nrz4Must provide an even number of non-keyword argumentsr5Fz2_set_option() got an unexpected keyword argument ""r9T)record)r; ValueErrorpopnextiterr? TypeErrorzipr@_get_registered_optionr'rCr)warningscatch_warnings) argskwargsnargsr5kwargrEvrorDk_roots r _set_optionr\s IIE QEAINNOPPPZZ% ( (F WT&++--(())UUUUUVVVD1ItADqDz**1a(( "3 ' '    KKNNN!~~ fV 4  ,D999DDIIIS !sD>>E E T _print_descrct|}t|dkrtddd|D}|rt |dS|S)NrNo such keys(s) c,g|]}t|Sr)_build_option_description).0rEs r z$_describe_option..s!>>>A,Q//>>>r)r:r;r2joinprint)r4r^r?ss r _describe_optionrisj 3  D 4yyA~~+,,, >>>>>??A at Hrc,t|}t|dkrtdt|dkr(t|dkr|dkrtd|D]$}t |t |j|%dS)Nrr`r9r.zYou must specify at least 4 characters when resetting multiple keys, use the special keyword "all" to reset all the options to their default valuer5)r:r;r2rLr\r+r$)r4r5r?rEs r _reset_optionrms 3  D 4yyA~~+,,, 4yy1}}SA#,, D   EEA*1-4VDDDDDEErcLt|d}t|jSNTrl)r@rRr$)r4rs r get_default_valrps% #d + + +C !# & & --rc@eZdZUdZded<ddd Zdd ZddZddZdS) DictWrapperz/provide attribute-style access to a nested dictr,dr]prefixrr7rGcvt|d|t|d|dS)Nrsrt)r# __setattr__)selfrsrts r __init__zDictWrapper.__init__s84a(((4622222rrvalrct|d}|r|dz }||z }||jvr2t|j|tst ||dSt d)Nrt.z.You can only set the value of existing options)r#__getattribute__rs isinstancedictr\r2)rwrryrts r rvzDictWrapper.__setattr__sw((x88   cMF#  $&==DF3K!>!>=  $ $ $ $ $NOO OrcBt|d}|r|dz }||z } t|d|}n"#t$r}td|d}~wwxYwt |t rt ||St|S)Nrtr{rszNo such option)r#r|KeyErrorr2r}r~rrrF)rwrrtrYerrs r __getattr__zDictWrapper.__getattr__s((x88   cMF#  9''c2237AA 9 9 9.//S 8 9 a   'q&)) )v&& &s!A A*A%%A*r/cNt|jSrB)listrsr?)rws r __dir__zDictWrapper.__dir__sDFKKMM"""rN)r])rsr,rtrr7rG)rrryrr7rGrr)r7r/) rrrr3rrxrvrrrrr rrrrs9933333 P P P P ' ' ' '######rrrc6eZdZd dZd d Zedd Zd S)CallableDynamicDocfuncCallable[..., T]doc_tmplrr7rGc"||_||_dSrB) __doc_tmpl____func__)rwrrs r rxzCallableDynamicDoc.__init__ s$ rr c|j|i|SrB)r)rwrUkwdss r __call__zCallableDynamicDoc.__call__st}d+d+++rctdd}ttt}|j||S)Nr.F)r^) opts_desc opts_list)ripp_options_listrr+r?rformat)rwrrs r r3zCallableDynamicDoc.__doc__sR$U>>> #D)<)A)A)C)C$D$DEE  '')y'QQQrN)rrrrr7rG)r7r )r7r)rrrrxrpropertyr3rrr rr sb,,,,RRRXRRRrra 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} Examples -------- >>> pd.get_option('display.max_columns') # doctest: +SKIP 4 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} Examples -------- >>> pd.set_option('display.max_columns', 4) >>> df = pd.DataFrame([[1, 2, 3, 4, 5], [6, 7, 8, 9, 10]]) >>> df 0 1 ... 3 4 0 1 2 ... 4 5 1 6 7 ... 9 10 [2 rows x 5 columns] >>> pd.reset_option('display.max_columns') 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} Examples -------- >>> pd.describe_option('display.max_columns') # doctest: +SKIP display.max_columns : int If max_cols is exceeded, switch to truncate view... 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} Examples -------- >>> pd.reset_option('display.max_columns') # doctest: +SKIP c*eZdZdZddZddZddZdS) option_contextaF Context manager to temporarily set options in the `with` statement context. You need to invoke as ``option_context(pat, val, [(pat, val), ...])``. Examples -------- >>> from pandas import option_context >>> with option_context('display.max_rows', 10, 'display.max_columns', 5): ... pass r7rGc t|dzdkst|dkrtdtt|ddd|ddd|_dS)NrIrz>Need to invoke as option_context(pat, val, [(pat, val), ...]).r9)r;rLrrQops)rwrUs r rxzoption_context.__init__sm t99q=A  TQP D1ItADqDz2233rcpd|jD|_|jD]\}}t||ddS)Nc6g|]\}}|t|fSr)rF)rdr4rys r rez,option_context.__enter__..s)FFFcc;s++,FFFrTrl)rundor\)rwr4rys r __enter__zoption_context.__enter__sPFFTXFFF  / /HC S . . . . . / /rcV|jr|jD]\}}t||ddSdSro)rr\)rwrUr4rys r __exit__zoption_context.__exit__sM 9 3 I 3 3SCT22222 3 3 3 3rNr7rG)rrrr3rxrrrrr rrsZ  4444//// 333333rrrr$r#r%r'r&r)r(c ddl}ddl}|}|tvrt d|d|t vrt d|d|r |||d}|D][}tjd|j zdz|st|d | |rt|d \t} d } t|dd D]i\} } t| ts>t | d|d|  | | vri| | <| | } jt| ts>t | d|dd  || |d <t%|||||t|<dS)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 keyr{^$z is not a valid identifierz is a python keywordz5Path prefix to option '{option}' is already an option)option)rr$r%r'r))keywordtokenizelowerr+r2r0splitrematchNamerL iskeywordr- enumerater}r~rrfr") rr$r%r'r)rrpathrEcursorrips r register_optionrs>NNNOOO ))++C !!!GSGGGHHH n=S===>>> & 99S>>D 99xhm+c1155 ?===>> >   Q   977788 8 9F AC$ss)$$1&$'' Ecjjbqb0B0BjCCDD D F??F1I fd # #B#**CHHT#2#Y,?,?*@@AAAF48 0 C9   rrrrc|}|tvrtd|dt||||t|<dS)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*r2r)rrrrs r deprecate_optionr6sWN ))++C !!!SSSSSTTT/S$ LLrctvrgStt}dkr|Sfd|DS)zb returns a list of keys matching `pat` if pat=="all", returns all registered options r.cTg|]$}tj|tj"|%Sr)rsearchI)rdrEr4s r rez#_select_options..xs. 7 7 7!rya66 7A 7 7 7r)r+sortedr?)r4r?s` r r:r:is\ !!!u  %**,, - -D e|| 7 7 7 7t 7 7 77rtuple[dict[str, Any], str]cx|d}t}|ddD] }||} ||dfS)Nr{r)rr-)rrrrs r rCrC{sG 99S>>D F #2#Y 48 rc<|}|tvS)z4Returns True if the given option has been deprecated)rr*rs r _is_deprecatedrs ))++C % %%rcD t|}|S#t$rYdSwxYw)z Retrieves the metadata for a deprecated option, if `key` is deprecated. Returns ------- DeprecatedOption (namedtuple) if key is deprecated, None otherwise N)r*rrrss r _get_deprecated_optionrs<  $ tts  c6t|S)z Retrieves the option metadata if `key` is a registered option. Returns ------- RegisteredOption (namedtuple) if key is deprecated, None otherwise )r+getrs r rRrRs  " "3 ' ''rc:t|}|r |jp|S|S)z if key id deprecated and a replacement key defined, will return the replacement key, otherwise returns `key` as - is )rrrs r r>r>s* s##Av} rcPt|}|r|jr.tj|jtt n]d|d}|jr |d|jz }|jr|d|jdz }n|dz }tj|tt dSd S) 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)rrrSwarn FutureWarningrrr)rrsrs r r<r<s s##A 5 M M+--      +c***C} BA!-AAAv 9:::::88 M#}9I9K9K L L L Lt 5rrEcht|}t|}|d}|jrC|d|jdz }n|dz }|r|d|jdt|ddz }|r|jpd}|d z }|d |d z }|d z }|S) zCBuilds a formatted description of a registered option and prints it razNo description available.z [default: z] [currently: T]r]z (Deprecatedz, use `z ` instead.)) rRrr%rfstriprr$rFr)rErZrsrhrs r rcrcsq!!Aq!!A Au) TYYqu{{}}**400 1 11 ((P O O O At8L8L O O OOv|   't ' ' '' S HrPr? Iterable[str]widthint_printc ddlm}ddlm d fd }g}d t |D}|r||d |z }d |D}|t |dD]/\ } fdt |D}|| |z }0d|} |rt| dS| S)z@Builds a concise listing of available options, grouped by prefixr)groupby)wrapnamerksrr7r/c|rd|zdznd}d||dd}|r|dr|r|dd z|d<|S) Nz- z.[r]z, z F)initial_indentsubsequent_indentbreak_long_wordsrr)rf)rrpfxlsrrs r ppzpp_options_list..pps|$(0dTkD  b T IIbMM ""      ""R& "T "Vc\BrF rcDg|]}|ddk|Sr{rfindrdxs r rez#pp_options_list..s':::Q!&&++//q///rr]cDg|]}|ddk|Srrrs r rez#pp_options_list..s, 0 0 0!qvvc{{a//A///rc<|d|dSNr{)rfind)rs r z!pp_options_list..s.AGGCLL.0ArcDg|]}|tdzdS)r9N)r;)rdrrEs r rez#pp_options_list..s+ / / /!aA o / / /rraN)rrrrr7r/) itertoolsrtextwraprrrrfrg) r?rrrrrsinglesgrrhrErs ` @@r rrs#!!!!!!       B::&,,:::G bbWoo 0 0t 0 0 0Dt &A&ABB1 / / / /tAww / / / bbBii " A  arrtGenerator[None, None, None]c#Kdfd }t}t}t}|ta|ta|ta dV|a|a|adS#|a|a|awxYw)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. rr r7c>dfd }tt|S)Nrrc*d|}|g|Ri|Srr)rrUrpkeyrrts r innerz*config_prefix..wrap..inner+s6$$s$$D4,t,,,t,, ,rr)r r )rrrts` r rzconfig_prefix..wrap*s7 - - - - - - -Au~~rN)rr r7r )r get_option set_option)rtr_register_optionrFr\s` r config_prefixr s<'KKj!!Jj!!Jd?++O+   *!  *****s AA$_type type[Any]Callable[[Any], None]cdfd }|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` r7rGcTt|krtdddS)NzValue must have type 'r)typerL)rrs r rzis_type_factory..innerQs6 77e  >e>>>?? ?  rrr)rrs` r is_type_factoryrCs.@@@@@@ Lrctttfr8tdt 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` |rr7rGcLt|stddS)NzValue must be an instance of )r}rL)rr type_reprs r rz"is_instance_factory..innerks9!U## JHYHHII I J Jrr)r}tuplerrfmapr)rrrs` @r is_instance_factoryr Xs%%''!e HHSe__--  LLL JJJJJJJ LrcHdDdDdfd }|S)Nc0g|]}t||Srcallablerdcs r rez%is_one_of_factory..ss#888qHQKK8888rc0g|]}t||Srrrs r rez%is_one_of_factory..ts#???!8A;;?A???rr7rGcvrdtfdDsKdD}d|}d|}tr|dz }t|dSdS)Nc3.K|]}|VdSrBr)rdrrs r z3is_one_of_factory..inner..xs+//qqtt//////rc,g|]}t|Sr)r)rdlvals r rez4is_one_of_factory..inner..ys<<.innervs L ////Y///// &<<|<<<HHUOO 9i99y>>,++C oo% !  & &rrr)rrrs` @r is_one_of_factoryrrsT88L888I??|???L&&&&&&& Lrvaluecf|dSt|tr|dkrdSd}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)r}rrL)rrs r is_nonnegative_intr s? } E3   A:: F 7C S//rcBt|stddS)z Parameters ---------- `obj` - the object to be checked Returns ------- validator - returns True if object is callable raises ValueError otherwise. zValue must be a callableT)rrL)objs r is_callabler#s& C==53444 4r)r4rr5r6r7r)F)r4rr5r6r7rr)r]T)r4rr^r6r7r)r4rr5r6r7rG)r4r)r]NN) rrr$r#r%rr'r&r)r(r7rG)NNN) rrrrrrrrr7rG)r4rr7r/)rrr7r)rrr7r6r)rrr7r)rErr7r)rF)r?rrrrr6)rtrr7r)rrr7r)r7r)rr#r7rG)r7r6)Nr3 __future__r contextlibrrrtypingrrrr r r rSpandas._typingr r pandas.util._exceptionsrcollections.abcrrrr"r*rr+r-r0AttributeErrorrr2r@rFr\rirmrprrr_get_option_tmpl_set_option_tmpl_describe_option_tmpl_reset_option_tmplrr reset_optiondescribe_optionoptionsrrrr:rCrrrRr>r<rcrrrr rr ris_intr6is_boolfloatis_floatris_strbytesis_textr#rrr r9s|000d#""""" 544444 z$$$$$z$$$465555465555"$#####G####     .(   $$@      EEEEE".... $#$#$#$#$#$#$#$#` R R R R R R R R %N-^&P"L  -= > >   -= > > !!-1CDD $$%57LMM +n % % 33333%333H04&* HHHHHZ" ,M,M,M,M,Mf8888$&&&&     ((((    <    0L/+/+/+/+l*4"6    /$   ?5 ! !     sEl + +r