o ۭjnc@sUdZddlmZddlmZmZddlZddlmZm Z m Z m Z m Z m Z ddlZddlmZmZddlmZerAddlmZmZGd d d e ZGd d d e ZiZd ed<iZded<iZded<dgZded<GdddeeZ duddZ!dvdwd!d"Z"dxd$d%Z#dydzd*d+Z$dvd{d,d-Z%d|d.d/Z&Gd0d1d1Z'Gd2d3d3e eZ(d4Z)d5Z*d6Z+d7Z,e(e"e)a-e(e#e*a.e(e%e,Z/e(e$e+Z0e'eZ1Gd8d9d9eZ2 &  d}d~dBdCa3   dddGdHZ4ddIdJZ5ddLdMZ6ddNdOZ7ddPdQZ8ddRdSZ9ddTdUZ:ddVdWZ;ddYdZZddjdkZ?ddldmZ@ddndoZAddqdrZBe?eCZDe?eEZFe?eGZHe?eIZJe@eIeKfZLddsdtZMdS)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. ) annotations)ContextDecoratorcontextmanagerN) TYPE_CHECKINGAnyCallableGeneric NamedTuplecast)FT)find_stack_level) GeneratorIterablec@s.eZdZUded<ded<ded<ded<dS)DeprecatedOptionstrkey str | Nonemsgrkey removal_verN__name__ __module__ __qualname____annotations__rrR/var/www/html/CropPilot/venv/lib/python3.10/site-packages/pandas/_config/config.pyrQs  rc@s6eZdZUded<ded<ded<ded<ded <d S) RegisteredOptionrrobjectdefvaldocCallable[[object], Any] | None validatorCallable[[str], Any] | NonecbNrrrrrrXs  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. Examples -------- >>> pd.options.context Traceback (most recent call last): OptionError: No such option N)rrr__doc__rrrrr-msr-patrsilentboolreturncCsft|}t|dkr|st|tdt|t|dkr#td|d}|s-t|t|}|S)NrzNo such keys(s): zPattern matched multiple keys)_select_optionslen_warn_if_deprecatedr-repr_translate_key)r/r0keysrrrr_get_single_keys  r:FrcCst||}t|\}}||SN)r: _get_root)r/r0rrootkrrr _get_options  r?Nonec Ost|}|r |ddkrtd|dd}|r(tt|}td|dt|ddd|dddD]G\}}t||}t |}|rN|j rN| |t |\} } || | <|j r~|ryt jd d  | |Wdn1sswYq7| |q7dS) Nrz4Must provide an even number of non-keyword argumentsr0Fz2_set_option() got an unexpected keyword argument ""r3T)record)r5 ValueErrorpopnextiterr9 TypeErrorzipr:_get_registered_optionr#r<r%warningscatch_warnings) argskwargsnargsr0kwargr>vror=k_rootrrr _set_options. &      rTT _print_descrcCsDt|}t|dkrtdddd|D}|r t|dS|S)NrNo such keys(s) cSg|]}t|qSr)_build_option_description.0r>rrr z$_describe_option..)r4r5r-joinprint)r/rVr9srrr_describe_options rbcCsft|}t|dkrtdt|dkr"t|dkr"|dkr"td|D] }t|t|j|dq$dS)NrrWr3r*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)r4r5r-rDrTr'r )r/r0r9r>rrr _reset_options  recCst|dd}t|jSNTrd)r:rJr )r/rrrrget_default_vals  rgc@sDeZdZUdZded<ddd d ZdddZdddZdddZdS) DictWrapperz/provide attribute-style access to a nested dictr(drUprefixrr2r@cCs t|d|t|d|dS)Nrirj)r __setattr__)selfrirjrrr__init__szDictWrapper.__init__rvalrcCsPt|d}|r |d7}||7}||jvr$t|j|ts$t||dStd)Nrj.z.You can only set the value of existing options)r__getattribute__ri isinstancedictrTr-)rlrrnrjrrrrks zDictWrapper.__setattr__c Cstt|d}|r |d7}||7}z t|d|}Wnty+}ztd|d}~wwt|tr6t||St|S)NrjrorizNo such option)rrpKeyErrorr-rqrrrhr?)rlrrjrQerrrrr __getattr__s    zDictWrapper.__getattr__r+cCst|jSr;)listrir9)rlrrr__dir__szDictWrapper.__dir__N)rU)rir(rjrr2r@)rrrnrr2r@rr)r2r+) rrrr.rrmrkrurwrrrrrhs    rhc@s.eZdZdddZdd d Zedd d ZdS)CallableDynamicDocfuncCallable[..., T]doc_tmplrr2r@cCs||_||_dSr;) __doc_tmpl____func__)rlrzr|rrrrm s zCallableDynamicDoc.__init__r cOs|j|i|Sr;)r~)rlrMkwdsrrr__call__szCallableDynamicDoc.__call__cCs,tddd}ttt}|jj||dS)Nr*F)rV) opts_desc opts_list)rbpp_options_listrvr'r9r}format)rlrrrrrr.s zCallableDynamicDoc.__doc__N)rzr{r|rr2r@)r2r )r2r)rrrrmrpropertyr.rrrrry s   rya 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@s.eZdZdZd ddZd ddZd dd Zd S) 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 r2r@cGsLt|ddkst|dkrtdtt|ddd|ddd|_dS)NrArz>Need to invoke as option_context(pat, val, [(pat, val), ...]).r3)r5rDrvrIops)rlrMrrrrms (zoption_context.__init__cCs4dd|jD|_|jD] \}}t||ddq dS)NcSsg|] \}}|t|fqSr)r?)r\r/rnrrrr]sz,option_context.__enter__..Trd)rundorT)rlr/rnrrr __enter__szoption_context.__enter__cGs,|jr|jD] \}}t||ddqdSdSrf)rrT)rlrMr/rnrrr__exit__s zoption_context.__exit__Nr2r@)rrrr.rmrrrrrrrs  rrr rr!r#r"r%r$c CsTddl}ddl}|}|tvrtd|d|tvr$td|d|r*|||d}|D] }td|j d|sEt |d | |rQt |d q1t } d } t |dd D]$\} } t| tsvt| jd|d| d | | vr~i| | <| | } q^t| tst| 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 keyro^$z is not a valid identifierz is a python keywordz5Path prefix to option '{option}' is already an option)option)rr r!r#r%)keywordtokenizelowerr'r-r,splitrematchNamerD iskeywordr) enumeraterqrrrr_r) rr r!r#r%rrpathr>cursorriprrrregister_options<       rrrrcCs6|}|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&r-r)rrrrrrrdeprecate_option6s'rcs8tvrgStt}dkr|Sfdd|DS)zb returns a list of keys matching `pat` if pat=="all", returns all registered options r*cs g|] }t|tjr|qSr)rsearchIr[r/rrr]x z#_select_options..)r'sortedr9)r/r9rrrr4is  r4tuple[dict[str, Any], str]cCs4|d}t}|ddD]}||}q ||dfS)Nror)rr))rrrrrrrr<{s   r<cCs|}|tvS)z4Returns True if the given option has been deprecated)rr&rrrr_is_deprecatedsrcCs$zt|}W|StyYdSw)z Retrieves the metadata for a deprecated option, if `key` is deprecated. Returns ------- DeprecatedOption (namedtuple) if key is deprecated, None otherwise N)r&rsrrirrr_get_deprecated_options   rcCs t|S)z Retrieves the option metadata if `key` is a registered option. Returns ------- RegisteredOption (namedtuple) if key is deprecated, None otherwise )r'getrrrrrJs rJcCst|}|r |jp |S|S)z if key id deprecated and a replacement key defined, will return the replacement key, otherwise returns `key` as - is )rrrrrrr8s r8cCst|}|rB|jrtj|jttddSd|d}|jr&|d|j7}|jr3|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)rrrKwarn FutureWarningr rr)rrirrrrr6s$ r6r>cCst|}t|}|d}|jr|d|jd7}n|d7}|r3|d|jdt|dd7}|rJ|jp9d}|d 7}|d |d 7}|d 7}|S) zCBuilds a formatted description of a registered option and prints it rXzNo description available.z [default: z] [currently: T]rUz (Deprecatedz, use `z ` instead.)) rJrr!r_striprr r?r)r>rRrirarrrrrZs  rZPr9 Iterable[str]widthint_printc sddlm}ddlmdfd d }g}d d t|D}|r(||d|7}dd |D}|t|ddD]\}fdd t|D}|||7}q8d|} |r\t| dS| S)z@Builds a concise listing of available options, grouped by prefixr)groupby)wrapnamerksrr2r+csP|rd|dnd}d||ddd}|r&|dr&|r&|dd |d<|S) Nz- z.[rUz, z F)initial_indentsubsequent_indentbreak_long_wordsrr)r_)rrpfxls)rrrrppszpp_options_list..ppcSsg|] }|ddkr|qSrorfindr\xrrrr]z#pp_options_list..rUcSsg|] }|ddkr|qSrrrrrrr]rcSs|d|dSNro)rfindrrrrsz!pp_options_list..cs g|] }|tddqS)r3N)r5r)r>rrr]rrXN)rrrrr2r+) itertoolsrtextwraprrrvr_r`) r9rrrrrsinglesgrrar)r>rrrrs     rrjGenerator[None, None, None]c#s\dfdd }t}t}t}|ta|ta|taz dVW|a|a|adS|a|a|aw)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. rzr r2csdfdd }tt|S)Nrrcs$d|}|g|Ri|Srr)rrMrpkey)rzrjrrinner+sz*config_prefix..wrap..innerrx)r r )rzrrj)rzrr*s zconfig_prefix..wrapN)rzr r2r )r get_option set_option)rjr_register_optionr?rTrrr config_prefix s r_type type[Any]Callable[[Any], None]csdfdd }|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` r2r@cs t|krtdddS)NzValue must have type 'r)typerDrrrrrQs zis_type_factory..innerNrrrrrrris_type_factoryCsrcsHtttfrtdttndddfdd }|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` |rr2r@cst|s tddS)NzValue must be an instance of )rqrDrr type_reprrrrks z"is_instance_factory..innerNr)rqtuplervr_maprrrrris_instance_factoryXs   rcs0ddDddDdfdd }|S) NcSsg|]}t|r|qSrcallabler\crrrr]sz%is_one_of_factory..cSsg|]}t|s|qSrrrrrrr]trr2r@cs`vr,tfddDs.ddD}d|}d|}tr(|d7}t|dSdS)Nc3s|]}|VqdSr;rrrrr xsz3is_one_of_factory..inner..cSrYr)r)r\lvalrrrr]yr^z4is_one_of_factory..inner..rzValue must be one of z or a callable)anyr_r5rD)ruvals pp_valuesr callables legal_valuesrrrvs  z is_one_of_factory..innerrr)rrrrris_one_of_factoryrs rvaluecCs.|durdSt|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)rqrrD)rrrrris_nonnegative_ints 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)r/rr0r1r2r)F)r/rr0r1r2rr)rUT)r/rrVr1r2r)r/rr0r1r2r@)r/r)rUNN) rrr rr!rr#r"r%r$r2r@)NNN) rrrrrrrrr2r@)r/rr2r+)rrr2r)rrr2r1rx)rrr2r)r>rr2r)rF)r9rrrrr1)rjrr2r)rrr2r)r2r)rrr2r@)r2r1)Nr. __future__r contextlibrrrtypingrrrrr r rKpandas._typingr r pandas.util._exceptionsr collections.abcrrrrr&rr'r)r,AttributeErrorrsr-r:r?rTrbrergrhry_get_option_tmpl_set_option_tmpl_describe_option_tmpl_reset_option_tmplrr reset_optiondescribe_optionoptionsrrrr4r<rrrJr8r6rZrrrrrrris_intr1is_boolfloatis_floatris_strbytesis_textrrrrrs 2        0'/( &   $ M 3      &  6