a Sic`@sUdZddlmZddlmZmZddlZddlmZm Z m Z m Z m Z m Z mZddlZddlmZmZddlmZGdd d e ZGd d d e ZiZd ed <iZded<iZded<dgZded<GdddeeZddddddZdmddddddZ d d!d"d#Z!dnddd&d'd(d)Z"doddd dd*d+Z#dd,d-d.Z$Gd/d0d0Z%Gd1d2d2e eZ&d3Z'd4Z(d5Z)d6Z*e&e e'a+e&e!e(a,e&e#e*a-e&e"e)Z.e%eZ/Gd7d8d8eZ0dpdd9dd:d;d d<d=d>a1dqdd&d&d&d d?d@dAZ2dddBdCdDZ3ddEdFdGdHZ4dddFdIdJZ5ddKdLdMZ6ddKdNdOZ7dddFdPdQZ8dddFdRdSZ9dddTdUdVZ:drdXddYdZd[Z;ed\d!d]d^Zd`d!dfdgZ?d9d dhdidjZ@e=eAZBe=eCZDe=eEZFe=eGZHe>eGeIfZJdd!dkdlZKdS)sa 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_levelc@s.eZdZUded<ded<ded<ded<dS)DeprecatedOptionstrkey str | Nonemsgrkey removal_verN__name__ __module__ __qualname____annotations__rrQ/var/www/html/django/DPS/env/lib/python3.9/site-packages/pandas/_config/config.pyrLs rc@s6eZdZUded<ded<ded<ded<ded <d S) RegisteredOptionrrobjectdefvaldocCallable[[object], Any] | None validatorCallable[[str], Any] | NonecbNrrrrrrSs rzdict[str, DeprecatedOption]_deprecated_optionszdict[str, RegisteredOption]_registered_optionsdict[str, Any]_global_configall list[str]_reserved_keysc@seZdZdZdS) OptionErrorz^ Exception raised for pandas.options. Backwards compatible with KeyError checks. N)rrr__doc__rrrrr,hsr,rbool)patsilentreturncCsft|}t|dkr2|s t|tdt|t|dkrFtd|d}|sZt|t|}|S)NrzNo such keys(s): zPattern matched multiple keys)_select_optionslen_warn_if_deprecatedr,repr_translate_key)r/r0keysrrrr_get_single_keyts  r9FrcCst||}t|\}}||SN)r9 _get_root)r/r0rrootkrrr _get_options  r>Noner1c Ost|}|r|ddkr td|dd}|rPt|d}td|dt|ddd|dddD]\}}t||}t|}|r|j r| |t |\} }|| |<|j rn|rt j d d | |Wdq1s0Yqn| |qndS) Nrz4Must provide an even number of non-keyword argumentsr0Fz2_set_option() got an unexpected keyword argument ""r2T)record)r4 ValueErrorpoplistr8 TypeErrorzipr9_get_registered_optionr"r;r$warningscatch_warnings) argskwargsnargsr0kwargr=vror<rrr _set_options& &    *rRTr)r/ _print_descr1cCsDt|}t|dkrtdddd|D}|r@t|dS|S)NrNo such keys(s) cSsg|] }t|qSr)_build_option_description.0r=rrr z$_describe_option..)r3r4r,joinprint)r/rTr8srrr_describe_options r_cCsft|}t|dkrtdt|dkrDt|dkrD|dkrDtd|D]}t|t|j|dqHdS)NrrUr2r)zYou must specify at least 4 characters when resetting multiple keys, use the special keyword "all" to reset all the options to their default valuer0)r3r4r,rDrRr&r)r/r0r8r=rrr _reset_options  rbr/cCst|dd}t|jSNTra)r9rIr)r/rrrrget_default_vals rec@sReZdZdZdddddddZdd dd d d Zdd ddZddddZdS) DictWrapperz/provide attribute-style access to a nested dictrSr'rr?)dprefixr1cCs t|d|t|d|dS)Nrgrh)r __setattr__)selfrgrhrrr__init__szDictWrapper.__init__r)rvalr1cCsRt|d}|r|d7}||7}||jvrFt|j|tsFt||ntddS)Nrh.z.You can only set the value of existing options)r__getattribute__rg isinstancedictrRr,)rjrrlrhrrrris  zDictWrapper.__setattr__rc Cst|d}|r|d7}||7}zt|d|}Wn.tyb}ztd|WYd}~n d}~00t|trxt||St|SdS)NrhrmrgzNo such option)rrnKeyErrorr,rorprfr>)rjrrhrPerrrrr __getattr__s    zDictWrapper.__getattr__ Iterable[str]r@cCst|jSr:)rFrgr8)rjrrr__dir__szDictWrapper.__dir__N)rS)rrrr-rkrirtrvrrrrrfs  rfc@s>eZdZddddddZddd d Zeddd d Zd S)CallableDynamicDoczCallable[..., T]rr?)funcdoc_tmplr1cCs||_||_dSr:) __doc_tmpl____func__)rjrxryrrrrkszCallableDynamicDoc.__init__r r@cOs|j|i|Sr:)r{)rjrLkwdsrrr__call__szCallableDynamicDoc.__call__cCs,tddd}ttt}|jj||dS)Nr)F)rT) opts_desc opts_list)r_pp_options_listrFr&r8rzformat)rjr~rrrrr- s zCallableDynamicDoc.__doc__N)rrrrkr}propertyr-rrrrrwsrwa 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@s:eZdZdZddddZddddZdddd Zd S) 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 r?r@cGsLt|ddkst|dkr$tdtt|ddd|ddd|_dS)NrArz>Need to invoke as option_context(pat, val, [(pat, val), ...]).r2)r4rDrFrHops)rjrLrrrrks zoption_context.__init__cCs4dd|jD|_|jD]\}}t||ddqdS)NcSs g|]\}}|t|ddfqS)Tra)r>)rYr/rlrrrrZr[z,option_context.__enter__..Tra)rundorR)rjr/rlrrr __enter__szoption_context.__enter__cGs(|jr$|jD]\}}t||ddq dSrd)rrR)rjrLr/rlrrr__exit__szoption_context.__exit__N)rrrr-rkrrrrrrrs rrr!r#)rrr r"r$r1c CsVddl}ddl}|}|tvr0td|d|tvrHtd|d|rT|||d}|D]@}td|j d|st |d | |rbt |d qbt } d } t |dd D]H\} } t| tst| jd|d| d | | vri| | <| | } qt| ts0t| jd|dd d || |d <t|||||dt|<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 keyrm^$z is not a valid identifierz is a python keywordz5Path prefix to option '{option}' is already an option)option)rrr r"r$)keywordtokenizelowerr&r,r+splitrematchNamerD iskeywordr( enumeraterorprr\r) rrr r"r$rrpathr=cursorriprrrregister_options:       r)rrrrr1cCs6|}|tvr td|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%r,r)rrrrrrrdeprecate_options'r)r/r1cs8tvrgStt}dkr&|Sfdd|DS)zb returns a list of keys matching `pat` if pat=="all", returns all registered options r)cs g|]}t|tjr|qSr)rsearchIrXrcrrrZRr[z#_select_options..)r&sortedr8)r/r8rrcrr3Cs  r3ztuple[dict[str, Any], str])rr1cCs4|d}t}|ddD] }||}q||dfS)Nrmr)rr()rrrrrrrr;Us   r;cCs|}|tvS)z4Returns True if the given option has been deprecated)rr%rqrrr_is_deprecated]srrqcCs*z t|}Wnty YdS0|SdS)z Retrieves the metadata for a deprecated option, if `key` is deprecated. Returns ------- DeprecatedOption (namedtuple) if key is deprecated, None otherwise N)r%rrrrgrrr_get_deprecated_optioncs   rcCs t|S)z Retrieves the option metadata if `key` is a registered option. Returns ------- RegisteredOption (namedtuple) if key is deprecated, None otherwise )r&getrqrrrrIssrIcCst|}|r|jp|S|SdS)z if key id deprecated and a replacement key defined, will return the replacement key, otherwise returns `key` as - is N)rrrrrrr7~s r7cCst|}|r|jr(tj|jttdnVd|d}|jrJ|d|j7}|jrd|d|jd7}n|d7}tj|ttddSd 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)rrrJwarn FutureWarningrrr)rrgrrrrr5s" r5)r=r1cCst|}t|}|d}|jr<|d|jd7}n|d7}|rf|d|jdt|dd7}|r|jprd}|d 7}|d |d 7}|d 7}|S) zCBuilds a formatted description of a registered option and prints it rVzNo description available.z [default: z] [currently: T]rSz (Deprecatedz, use `z ` instead.)) rIrr r\striprrr>r)r=rQrgr^rrrrrWs  rWPru)r8_printc sddlm}ddlmddddfdd }g}d d t|D}|rX||d |7}d d |D}|t|ddD],\}fdd t|D}|||7}qxd|} |rt| n| SdS)z@Builds a concise listing of available options, grouped by prefixr)groupby)wraprrur*)nameksr1csP|rd|dnd}d||ddd}|rL|drL|rL|dd |d<|S) Nz- z.[rSz, z F)initial_indentsubsequent_indentbreak_long_wordsrr)r\)rrpfxls)widthrrrppszpp_options_list..ppcSsg|]}|ddkr|qSrmrfindrYxrrrrZr[z#pp_options_list..rScSsg|]}|ddkr|qSrrrrrrrZr[cSs|d|dSNrm)rfindrrrrr[z!pp_options_list..cs g|]}|tddqS)r2N)r4r)r=rrrZr[rVN) itertoolsrtextwraprrrFr\r]) r8rrrrrZsinglesgrr^r)r=rrrrs     rzIterator[None]c#sbdddfdd }t}t}t}|ta|ta|tazdVW|a|a|an|a|a|a0dS)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. r )rxr1csddfdd }tt|S)Nrrqcs$d|}|g|Ri|Srr)rrLr|Zpkey)rxrhrrinnersz*config_prefix..wrap..inner)r r )rxrrh)rxrrszconfig_prefix..wrapN)r get_option set_option)rhrZ_register_optionr>rRrrr config_prefixsrz type[Any]zCallable[[Any], None])_typer1csddfdd }|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` r?r@cs t|krtdddS)NzValue must have type 'r)typerDrrrrr+s zis_type_factory..innerrrrrrris_type_factorysrcsLtttfr(tdttn ddddfdd }|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` |rr?r@cst|stddS)NzValue must be an instance of )rorDrrZ type_reprrrrEs z"is_instance_factory..inner)rotuplerFr\maprrrrris_instance_factory2s  rcs4ddDddDddfdd }|S)NcSsg|]}t|r|qSrcallablerYcrrrrZNr[z%is_one_of_factory..cSsg|]}t|s|qSrrrrrrrZOr[r?r@cs\vrXtfddDsXddD}d|}d|}trP|d7}t|dS)Nc3s|]}|VqdSr:rrrrr Tr[z3is_one_of_factory..inner..cSsg|] }t|qSr)r)rYlvalrrrrZUr[z4is_one_of_factory..inner..rzValue must be one of z or a callable)anyr\r4rD)rZuvalsZ pp_valuesr callables legal_valuesrrrQs  z is_one_of_factory..innerr)rrrrris_one_of_factoryLs r)valuer1cCs2|dur dSt|tr"|dkr"dSd}t|dS)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)rointrD)rrrrris_nonnegative_int_s rcCst|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)rrD)objrrr is_callables r)F)rST)F)rSNN)NNN)rF)Lr- __future__r contextlibrrrtypingrrrrr r r rJpandas._typingr r pandas.util._exceptionsrrrr%rr&r(r+AttributeErrorrrr,r9r>rRr_rbrerfrwZ_get_option_tmplZ_set_option_tmplZ_describe_option_tmplZ_reset_option_tmplrr reset_optiondescribe_optionoptionsrrrr3r;rrrIr7r5rWrrrrrrrZis_intr.is_boolfloatis_floatrZis_strbytesZis_textrrrrrsz2 $       ."$""    #M3  &6