3 pd#] @sFUdZddlmZddlmZmZddlZddlmZm Z m Z m Z m Z m Z mZmZmZddlZddlmZeddZed d ZiZe eefiZe eefiZe eefd gZe eGd d d eeZeeedddZdXeedddZ ddddZ!dYeedddZ"dZeeddddZ#edd d!Z$Gd"d#d#Z%Gd$d%d%Z&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+d+eZ0d[ee1ee e egefe e egefdd,d-d.a2d\ee ee edd/d0d1Z3ee ed2d3d4Z4eee eefefd5d6d7Z5eed5d8d9Z6ed:d;d<Z7ed:d=d>Z8eed5d?d@Z9eed5dAdBZ:eedCdDdEZ;d]e eedGdHdIZe egdfddOdPZ?e egdfddQdRZ@e eAddSdTdUZBe>eAZCe>eZDe>eEZFe>eZGe?eeHfZIeddVdWZJdS)^a 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. ) namedtuple)ContextDecoratorcontextmanagerN) AnyCallableDictIterableListOptionalTupleTypecast)FDeprecatedOptionzkey msg rkey removal_verRegisteredOptionzkey defval doc validator cballc@seZdZdZdS) OptionErrorzU Exception for pandas.options, backwards compatible with KeyError checks N)__name__ __module__ __qualname____doc__rr7/tmp/pip-build-7vycvbft/pandas/pandas/_config/config.pyrKsr)patsilentreturncCsft|}t|dkr2|s t|tdt|t|dkrFtd|d}|sZt|t|}|S)NrzNo such keys(s): zPattern matched multiple keys)_select_optionslen_warn_if_deprecatedrrepr_translate_key)rrkeyskeyrrr_get_single_keyVs  r$F)rrcCst||}t|\}}||S)N)r$ _get_root)rrr#rootkrrr _get_optionhs  r()rc Ost|}| s|ddkr"td|jdd}|rRt|jd}td|dxt|ddd|dddD]z\}}t||}t|}|r|j r|j |t |\} }|| |<|j rr|rt j d d |j |WdQRXqr|j |qrWdS) Nrz4Must provide an even number of non-keyword argumentsrFz2_set_option() got an unexpected keyword argument ""rT)record)r ValueErrorpoplistr" TypeErrorzipr$_get_registered_option validatorr%cbwarningscatch_warnings) argskwargsnargsrkwargr'vr#or&rrr _set_optionps& (    r<T)r _print_desccCsFt|}t|dkrtddjdd|D}|r>t|n|SdS)NrzNo such keys(s) cSsg|] }t|qSr)_build_option_description).0r'rrr sz$_describe_option..)rrrjoinprint)rr>r"srrr_describe_options  rFcCsjt|}t|dkrtdt|dkrDt|dkrD|dkrDtdx |D]}t|t|j|dqJWdS)NrzNo such keys(s)rrzYou must specify at least 4 characters when resetting multiple keys, use the special keyword "all" to reset all the options to their default value)r)rrrr,r<_registered_optionsdefval)rrr"r'rrr _reset_options   rJ)rcCst|dd}t|jS)NT)r)r$r1rI)rr#rrrget_default_vals rKc@s\eZdZdZdeeefedddZeedddd Zed d d Z e ed ddZ dS) DictWrapperz0 provide attribute-style access to a nested dictr=)dprefixcCs tj|d|tj|d|dS)NrMrN)object __setattr__)selfrMrNrrr__init__szDictWrapper.__init__N)r#valrcCsTtj|d}|r|d7}||7}||jkrHt|j|t rHt||ntddS)NrN.z.You can only set the value of existing options)rO__getattribute__rM isinstancedictr<r)rQr#rSrNrrrrPs  zDictWrapper.__setattr__)r#cCstj|d}|r|d7}||7}ytj|d|}Wn,tk r`}ztd|WYdd}~XnXt|trvt||St|SdS)NrNrTrMzNo such option)rOrUKeyErrorrrVrWrLr()rQr#rNr:errrrr __getattr__s   zDictWrapper.__getattr__)rcCst|jjS)N)r.rMr")rQrrr__dir__szDictWrapper.__dir__)r=) rrrrrstrrrRrPrZrr[rrrrrLs  rLc@s(eZdZddZddZeddZdS)CallableDynamicDoccCs||_||_dS)N) __doc_tmpl____func__)rQfuncZdoc_tmplrrrrRszCallableDynamicDoc.__init__cOs |j||S)N)r_)rQr6kwdsrrr__call__szCallableDynamicDoc.__call__cCs,tddd}tttj}|jj||dS)NrF)r>) opts_desc opts_list)rFpp_options_listr.rHr"r^format)rQrcrdrrrrs zCallableDynamicDoc.__doc__N)rrrrRrbpropertyrrrrrr]sr]a; 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 ----- The available options with its descriptions: {opts_desc} aG 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 ----- 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 not 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 ----- The available options with its descriptions: {opts_desc} a5 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 ----- The available options with its descriptions: {opts_desc} c@s(eZdZdZddZddZddZdS) 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): ... ... cGsLt|ddkot|dks$tdtt|ddd|ddd|_dS)Nr)rz>Need to invoke as option_context(pat, val, [(pat, val), ...]).r)rr,r.r0ops)rQr6rrrrRszoption_context.__init__cCs8dd|jD|_x |jD]\}}t||ddqWdS)NcSs g|]\}}|t|ddfqS)T)r)r()rArrSrrrrBsz,option_context.__enter__..T)r)riundor<)rQrrSrrr __enter__szoption_context.__enter__cGs,|jr(x |jD]\}}t||ddqWdS)NT)r)rjr<)rQr6rrSrrr__exit__szoption_context.__exit__N)rrrrrRrkrlrrrrrh~s rh)r#rIdocr2r3rc Cs`ddl}ddl}|j}|tkr0td|d|tkrHtd|d|rT|||jd}xH|D]@}tjd|j d|st |d |j |rdt |d qdWt } d } x^t |ddD]J\} } t| tst| jdj|d| d | | kri| | <| | } qWt| ts:t| jdj|ddd || |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. rNzOption 'z' has already been registeredz' is a reserved keyrT^$z is not a valid identifierz is a python keywordz5Path prefix to option '{option}' is already an optionr)option)r#rIrmr2r3rqrq)keywordtokenizelowerrHr_reserved_keyssplitrematchNamer, iskeyword_global_config enumeraterVrWrfrCr) r#rIrmr2r3rrrspathr'cursormsgiprrrregister_options8        r)r#rrkeyrcCs6|j}|tkr 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 : 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. zOption 'z)' has already been defined as deprecated.N)rt_deprecated_optionsrr)r#rr removal_verrrrdeprecate_options$r)rrcs8tkrgSttj}dkr&|Sfdd|DS)zb returns a list of keys matching `pat` if pat=="all", returns all registered options rcs g|]}tj|tjr|qSr)rwsearchI)rAr')rrrrB*sz#_select_options..)rHsortedr")rr"r)rrrs  r)r#rcCs8|jd}t}x|ddD] }||}qW||dfS)NrTrrqrq)rvr{)r#r}r~rrrrr%-s   r%cCs|j}|tkS)z6 Returns True if the given option has been deprecated )rtr)r#rrr_is_deprecated5sr)r#c Cs*y t|}Wntk r dSX|SdS)z Retrieves the metadata for a deprecated option, if `key` is deprecated. Returns ------- DeprecatedOption (namedtuple) if key is deprecated, None otherwise N)rrX)r#rMrrr_get_deprecated_option;s  rcCs tj|S)z Retrieves the option metadata if `key` is a registered option. Returns ------- RegisteredOption (namedtuple) if key is deprecated, None otherwise )rHget)r#rrrr1Ksr1cCst|}|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)rr)r#rMrrrr!Vs r!cCst|}|r|jr,t|jtj|jtnPd|d}|jrN|d|j7}|jrh|d|jd7}n|d7}tj|tdSdS) z Checks if `key` is a deprecated option and if so, prints a warning. Returns ------- bool - True if `key` is deprecated, False otherwise. 'z' is deprecatedz and will be removed in z, please use 'z ' instead.z, please refrain from using it.TF)rrrDr4warn FutureWarningrr)r#rMrrrrrbs   r)r'rcCst|}t|}|d}|jr<|dj|jjjd7}n|d7}|rf|d|jdt|dd7}|r|jrv|jnd}|d 7}|d |d 7}|d 7}|S) zE Builds a formatted description of a registered option and prints it  r?zNo description available.z [default: z] [currently: T]r=z (Deprecatedz, use `z ` instead.)) r1rrmrCstriprvrIr(r)r'r;rMrErrrrr@}s r@P)r"_printc sddlm}ddlmtttttdfdd }g}ddt|D}|r`||d |7}d d|D}xB|t|d d D],\}fd dt|D}|||7}qWdj |} |rt | n| SdS)zB Builds a concise listing of available options, grouped by prefix r)groupby)wrap)nameksrcsP|rd|dnd}dj||ddd}|rL|d rL|rL|d d |d <|S) Nz- z.[r=z, z F)initial_indentsubsequent_indentbreak_long_wordsrrrqrqrq)rC)rrpfxls)widthrrrppszpp_options_list..ppcSsg|]}|jddkr|qS)rTr)find)rAxrrrrBsz#pp_options_list..r=cSsg|]}|jddkr|qS)rTr)r)rArrrrrBscSs|d|jdS)NrT)rfind)rrrrsz!pp_options_list..cs g|]}|tddqS)rN)r)rAr)r'rrrBsr?N) itertoolsrtextwraprr\rr rr.rCrD) r"rrrrrZsinglesgrrEr)r'rrrres     rec#sNttdfdd }t}t}t}|ta|ta|tadV|a|a|adS)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`rcstdfdd }tt|S)N)r#csd|}|f||S)NrTr)r#r6raZpkey)r`rNrrinnersz*config_prefix..wrap..inner)r\r r)r`r)rN)r`rrszconfig_prefix..wrapN)rr get_option set_option)rNrZ_register_optionr(r<r)rNr config_prefixsr)_typercsddfdd }|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` N)rcs t|krtdddS)NzValue must have type 'r)typer,)r)rrrrs zis_type_factory..innerr)rrr)rris_type_factorysrcsLtttfr(tdjttn 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` |rN)rcst|stddS)NzValue must be an instance of )rVr,)r)r type_reprrrrs z"is_instance_factory..inner)rVtupler.rCmapr\)rrr)rrris_instance_factorys  rcs4ddDddDddfdd }|S)NcSsg|]}t|r|qSr)callable)rAcrrrrB!sz%is_one_of_factory..cSsg|]}t|s|qSr)r)rArrrrrB"s)rcs\krXtfddDsXddD}dj|}d|}trP|d7}t|dS)Nc3s|]}|VqdS)Nr)rAr)rrr 'sz3is_one_of_factory..inner..cSsg|] }t|qSr)r\)rAZlvalrrrrB(sz4is_one_of_factory..inner..rzValue must be one of z or a callable)anyrCrr,)rZuvalsZ pp_valuesr) callables legal_values)rrr$s  z is_one_of_factory..innerr)rrr)rrris_one_of_factorys r)valuercCs2|dkr 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)rVintr,)rrrrris_nonnegative_int2s 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)rr,)objrrr is_callableTs r)F)r=T)F)r=NN)NNN)rF)Kr collectionsr contextlibrrrwtypingrrrrr r r r r r4Zpandas._typingrrrrr\rHr{ruAttributeErrorrXrboolr$r(r<rFrJrKrLr]Z_get_option_tmplZ_set_option_tmplZ_describe_option_tmplZ_reset_option_tmplrrZ reset_optionZdescribe_optionoptionsrhrOrrrr%rrr1r!rr@rerrrrrrZis_intZis_boolfloatZis_floatZis_strbytesZis_textrrrrr1sr ,     .-"     #(H.   & 5