U
|
¬ý°dÎc ã @ s U d Z ddlmZ ddlmZmZ ddlZddlmZm Z m
|
Z
|
m Z m Z m Z mZ ddlZddlmZmZ ddlmZ G dd d e ZG d
|
d d e Zi Zd ed < i Zded< i Zded< dgZded< G dd de e Z ddddddZ dnddd dd d Z d d!d"d#Z!doddd&d'd(d)Z"dpddd dd*d+Z#dd,d-d.Z$G d/d0 d0Z%G d1d2 d2e e Z&d3Z'd4Z(d5Z)d6Z*e&e e'a+e&e!e(a,e&e#e*Z-e&e"e)Z.e%eZ/G d7d8 d8eZ0dqdd9dd:d;d d<d=d>a1drdd&d&d&d d?d@dAZ2dddBdCdDZ3ddEdFdGdHZ4dddFdIdJZ5ddKdLdMZ6ddKdNdOZ7dddFdPdQZ8dddFdRdSZ9dddTdUdVZ:dsdXdYddZd[d\Z;ed]d!d^d_Z<d`dadbdcddZ=dad!dedfZ>dad!dgdhZ?d9d didjdkZ@e=eAZBe=eCZDe=eEZFe=eGZHe>eGeIfZJdd!dldmZKdS )taò
|
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)ÚContextDecoratorÚcontextmanagerN)ÚAnyÚCallableÚ GeneratorÚGenericÚIterableÚ
|
NamedTupleÚcast)ÚFÚT)Úfind_stack_levelc @ s. e Zd ZU ded< ded< ded< ded< dS )ÚDeprecatedOptionÚstrÚkeyú
|
str | NoneÚmsgÚrkeyÚ removal_verN©Ú__name__Ú
|
__module__Ú __qualname__Ú__annotations__© r r úLd:\z\workplace\vscode\pyvenv\venv\Lib\site-packages\pandas/_config/config.pyr L s
|
r c @ s6 e Zd ZU ded< ded< ded< ded< ded < d
|
S ) ÚRegisteredOptionr r ÚobjectÚdefvalÚdocú Callable[[object], Any] | NoneÚ validatorúCallable[[str], Any] | NoneÚcbNr r r r r r S s
|
|
r zdict[str, DeprecatedOption]Ú_deprecated_optionszdict[str, RegisteredOption]Ú_registered_optionsúdict[str, Any]Ú_global_configÚallú list[str]Ú_reserved_keysc @ s e Zd ZdZdS )Ú OptionErrorz^
|
Exception raised for pandas.options.
|
|
Backwards compatible with KeyError checks.
|
N)r r r Ú__doc__r r r r r, h s r, r Úbool)ÚpatÚsilentÚreturnc C sf t | }t|dkr2|s t| tdt| t|dkrFtd|d }|sZt| t|}|S )Nr zNo such keys(s): é z Pattern matched multiple keys)Ú_select_optionsÚlenÚ_warn_if_deprecatedr, ÚreprÚ_translate_key)r/ r0 Úkeysr r r r Ú_get_single_keyt s r9 Fr c C s t | |}t|\}}|| S ©N)r9 Ú _get_root)r/ r0 r ÚrootÚkr r r Ú _get_option s
|
r> ÚNone©r1 c
|
|
O sî t | }|r|d dkr td| dd¡}|rPt| ¡ d }td| dt| d d d
| dd d
D ]z\}}t||}t|}|r|j r| |¡ t
|
|\} }|| |< |j rn|rÞt j d d
|
| |¡ W 5 Q R X qn| |¡ qnd S ) Né r z4Must provide an even number of non-keyword argumentsr0 Fz2_set_option() got an unexpected keyword argument "ú"r2 T)Úrecord)r4 Ú
|
ValueErrorÚpopÚlistr8 Ú TypeErrorÚzipr9 Ú_get_registered_optionr" r; r$ ÚwarningsÚcatch_warnings)
|
ÚargsÚkwargsÚnargsr0 Úkwargr= Úvr Úor< r r r Ú _set_option s& &
|
|
|
rR Ú Tr )r/ Ú _print_descr1 c C sD t | }t|dkr tdd dd |D ¡}|r@t| d S |S )Nr úNo such keys(s)Ú
|
c S s g | ] }t |qS r )Ú_build_option_description©Ú.0r= r r r Ú
|
<listcomp>³ s z$_describe_option.<locals>.<listcomp>)r3 r4 r, ÚjoinÚprint)r/ rT r8 Úsr r r Ú_describe_option® s r^ c C sf t | }t|dkr tdt|dkrDt| dk rD| dkrDtd|D ]}t|t| j|d qHd S )Nr rU r2 é r) zYou must specify at least 4 characters when resetting multiple keys, use the special keyword "all" to reset all the options to their default value©r0 )r3 r4 r, rD rR r& r )r/ r0 r8 r= r r r Ú _reset_option» s ÿra ©r/ c C s t | dd}t|jS ©NTr` )r9 rI r )r/ r r r r Úget_default_valÌ s rd c @ sR e Zd ZdZdddddddZdd dd
|
d d Zdd ddZddddZdS )Ú DictWrapperz/provide attribute-style access to a nested dictrS r' r r? )ÚdÚprefixr1 c C s t | d|¡ t | d|¡ d S )Nrf rg )r Ú __setattr__)Úselfrf rg r r r Ú__init__Ô s zDictWrapper.__init__r )r Úvalr1 c C sR t | d¡}|r|d7 }||7 }|| jkrFt| j| tsFt|| ntdd S )Nrg Ú.z.You can only set the value of existing options)r Ú__getattribute__rf Ú
|
isinstanceÚdictrR r, )ri r rk rg r r r rh Ø s zDictWrapper.__setattr__©r c
|
C s t | d¡}|r|d7 }||7 }zt | d¡| }W n, tk
|
r` } ztd|W 5 d }~X Y nX t|trvt||S t|S d S )Nrg rl rf zNo such option)r rm ÚKeyErrorr, rn ro re r> )ri r rg rP Úerrr r r Ú __getattr__ä s
|
|
zDictWrapper.__getattr__ú Iterable[str]r@ c C s t | j ¡ S r: )rF rf r8 )ri r r r Ú__dir__ò s zDictWrapper.__dir__N)rS )r r r r- rj rh rs ru r r r r re Ñ s
|
re c @ s> e Zd ZddddddZddd d
|
Zeddd d Zd S )ÚCallableDynamicDoczCallable[..., T]r r? )ÚfuncÚdoc_tmplr1 c C s || _ || _d S r: )Ú __doc_tmpl__Ú__func__)ri rw rx r r r rj s zCallableDynamicDoc.__init__r r@ c O s | j ||S r: )rz )ri rL Úkwdsr r r Ú__call__ s zCallableDynamicDoc.__call__c C s, t ddd}ttt ¡ }| jj||dS )Nr) F)rT )Ú opts_descÚ opts_list)r^ Úpp_options_listrF r& r8 ry Úformat)ri r} r~ r r r r- s zCallableDynamicDoc.__doc__N)r r r rj r| Úpropertyr- r r r r rv ÿ s rv 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
|
-----
|
Please reference the :ref:`User Guide <options>` 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 <options>` 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 <options>` 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 <options>` for more information.
|
|
The available options with its descriptions:
|
|
{opts_desc}
|
c @ s: e Zd ZdZddddZddddZdddd 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
|
r? r@ c G sL t |d dks t |dk r$tdtt|d d d
|dd d
| _d S )NrA r z>Need to invoke as option_context(pat, val, [(pat, val), ...]).r2 )r4 rD rF rH Úops)ri rL r r r rj ° s
|
ÿzoption_context.__init__c C s4 dd | j D | _| j D ]\}}t||dd qd S )Nc S s g | ]\}}|t |d dfqS )Tr` )r> )rY r/ rk r r r rZ ¹ s z,option_context.__enter__.<locals>.<listcomp>Tr` )r ÚundorR )ri r/ rk r r r Ú __enter__¸ s zoption_context.__enter__c G s( | j r$| j D ]\}}t||dd q d S rc )r rR )ri rL r/ rk r r r Ú__exit__¾ s zoption_context.__exit__N)r r r r- rj r
r r r r r r £ s r r r! r# )r r r r" r$ r1 c C sV ddl }ddl}| ¡ } | tkr0td| d| tkrHtd| d|rT|| | d¡}|D ]@}t d|j d |¡st
|
| d | |¡rbt
|
| d
|
qbt } d }
|
t |dd
D ]H\} } t| tsìt|
|
jd |d|
¡d | | krüi | | < | | } q¼t| 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.
|
|
r NúOption 'z ' has already been registeredz' is a reserved keyrl ú^ú$z is not a valid identifierz is a python keywordz5Path prefix to option '{option}' is already an optionéÿÿÿÿ)Úoption)r r r r" r$ )ÚkeywordÚtokenizeÚlowerr& r, r+ ÚsplitÚreÚmatchÚNamerD Ú iskeywordr( Ú enumeratern ro r r[ r ) r r r r" r$ r r Úpathr= Úcursorr ÚiÚpr r r Úregister_optionÄ sB
|
|
|
|
ÿr )r r r r r1 c C s6 | ¡ } | 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 : 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.
|
r z)' has already been defined as deprecated.N)r r% r, r )r r r r r r r Údeprecate_option s 'r )r/ r1 c s8 t kr gS tt ¡ } dkr&|S fdd|D S )zb
|
returns a list of keys matching `pat`
|
|
if pat=="all", returns all registered options
|
r) c s g | ]}t |t j¡r|qS r )r ÚsearchÚIrX rb r r rZ Q s z#_select_options.<locals>.<listcomp>)r& Úsortedr8 )r/ r8 r rb r r3 B s r3 ztuple[dict[str, Any], str])r r1 c C s4 | d¡}t}|d d
D ] }|| }q||d fS )Nrl r )r r( )r r r r r r r r; T s
|
|
|
r; c C s | ¡ } | tkS )z4Returns True if the given option has been deprecated)r r% rp r r r Ú_is_deprecated\ s r rp c C s, z t | }W n tk
|
r" Y dS X |S dS )z±
|
Retrieves the metadata for a deprecated option, if `key` is deprecated.
|
|
Returns
|
-------
|
DeprecatedOption (namedtuple) if key is deprecated, None otherwise
|
N)r% rq ©r rf r r r Ú_get_deprecated_optionb s
|
r c C s
|
t | ¡S )z¨
|
Retrieves the option metadata if `key` is a registered option.
|
|
Returns
|
-------
|
RegisteredOption (namedtuple) if key is deprecated, None otherwise
|
)r& Úgetrp r r r rI r s rI c C s t | }|r|jp| S | S dS )z
|
if key id deprecated and a replacement key defined, will return the
|
replacement key, otherwise returns `key` as - is
|
N)r r r r r r r7 } s
|
r7 c C s t | }|r|jr(tj|jtt d nVd| d}|jrJ|d|j 7 }|jrd|d|j d7 }n|d7 }tj|tt d dS d 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)r r rJ ÚwarnÚ FutureWarningr r r )r rf r r r r r5 s" ý r5 )r= r1 c C s t | }t| }| d}|jr<|d |j ¡ d¡¡7 }n|d7 }|rf|d|j dt| d d7 }|r|jprd}|d 7 }|d
|
| d 7 }|d 7 }|S ) zCBuilds a formatted description of a registered option and prints itú rV zNo description available.z
|
[default: z] [currently: Tú]rS z
|
(Deprecatedz, use `z
|
` instead.ú)) rI r r r[ Ústripr r r> r )r= rQ rf r] r r r r rW § s
|
|
rW éP rt Úint)r8 ÚwidthÚ_printc
|
sÆ ddl m} ddlm ddddfdd }g }d
|
d t| D }|rX||d |7 }d d | D } |t| dd D ],\ } fdd t|D }|| |7 }qxd |¡} |r¾t| n| S dS )z@Builds a concise listing of available options, grouped by prefixr )Úgroupby)Úwrapr rt r* )ÚnameÚksr1 c sP | rd| d nd}d |¡ |ddd}|rL|d rL| rL|d d |d< |S )
|
Nz- z.[rS z, z F)Úinitial_indentÚsubsequent_indentÚbreak_long_wordsr r§ )r[ )r° r± ÚpfxÚls)r¬ r¯ r r ÚppÄ s ûzpp_options_list.<locals>.ppc S s g | ]}| d ¡dk r|qS ©rl r ©Úfind©rY Úxr r r rZ Ò s z#pp_options_list.<locals>.<listcomp>rS c S s g | ]}| d ¡dkr|qS r¸ r¹ r» r r r rZ Õ s c S s | d | d¡
S ©Nrl )Úrfind©r¼ r r r Ú<lambda>× ó z!pp_options_list.<locals>.<lambda>c s g | ]}|t d d
qS )r2 N)r4 r» )r= r r rZ Ø s rV N)Ú itertoolsr® Útextwrapr¯ r rF r[ r\ )
|
r8 r¬ r r® r· r¶ ZsinglesÚgr± r] r )r= r¬ r¯ r r ¿ s
|
|
r z Generator[(None, None, None)]c # sV ddd fdd }t }t}t}|ta|ta|t a z
|
dV W 5 |a|a|a X dS )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 )rw r1 c s dd fdd }t t|S )Nr rp c s d| } |f||S r½ r )r rL r{ Zpkey)rw rg r r Úinner s z*config_prefix.<locals>.wrap.<locals>.inner)r r )rw rÅ ©rg )rw r r¯ s zconfig_prefix.<locals>.wrapN)r Ú
|
get_optionÚ
|
set_option)rg r¯ Z_register_optionr> rR r rÆ r Ú config_prefixå s
|
rÉ z type[Any]zCallable[[Any], None])Ú_typer1 c s dd fdd }|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@ c s t | kr td dd S )NzValue must have type 'r£ )ÚtyperD r¿ ©rÊ r r rÅ * s z is_type_factory.<locals>.innerr ©rÊ rÅ r rÌ r Úis_type_factory s rÎ c sL t ttfr(t d tt ¡n d ddd fdd }|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`
|
|
ú|r£ r? r@ c s t | std d S )Nz Value must be an instance of )rn rD r¿ ©rÊ Z type_reprr r rÅ D s
|
z"is_instance_factory.<locals>.inner)rn ÚtuplerF r[ Úmapr rÍ r rÐ r Úis_instance_factory1 s rÓ c s4 dd D dd D dd fdd }|S )Nc S s g | ]}t |r|qS r ©Úcallable©rY Úcr r r rZ L s z%is_one_of_factory.<locals>.<listcomp>c S s g | ]}t |s|qS r rÔ rÖ r r r rZ M s r? r@ c s\ krXt fddD sXdd D }d |¡}d| }trP|d7 }t|d S )Nc 3 s | ]}| V qd S r: r rÖ r¿ r r Ú <genexpr>Q s z3is_one_of_factory.<locals>.inner.<locals>.<genexpr>c S s g | ] }t |qS r )r )rY Zlvalr r r rZ R s z4is_one_of_factory.<locals>.inner.<locals>.<listcomp>rÏ zValue must be one of z or a callable)Úanyr[ r4 rD )r¼ ZuvalsZ pp_valuesr ©Z callablesÚ legal_valuesr¿ r rÅ O s
|
|
z is_one_of_factory.<locals>.innerr )rÛ rÅ r rÚ r Úis_one_of_factoryK s
|
rÜ )Úvaluer1 c C s2 | dkr dS t | tr"| dkr"dS d}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
|
Nr z+Value must be a nonnegative integer or None)rn r« rD )rÝ r r r r Úis_nonnegative_int\ s
|
rÞ c C s t | 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)rÕ rD )Úobjr r r Ú is_callable~ s rà )F)rS T)F)rS NN)NNN)rª F)Lr- Ú
|
__future__r Ú
|
contextlibr r r Útypingr r r r r r
|
r rJ Zpandas._typingr r Zpandas.util._exceptionsr r r r% r r& r( r+ ÚAttributeErrorrq r, r9 r> rR r^ ra rd re rv Z_get_option_tmplZ_set_option_tmplZ_describe_option_tmplZ_reset_option_tmplrÇ rÈ Z reset_optionZdescribe_optionÚoptionsr r r r3 r; r r rI r7 r5 rW r rÉ rÎ rÓ rÜ rÞ r« Zis_intr. Zis_boolÚfloatZis_floatr Zis_strÚbytesZis_textrà r r r r Ú<module> sz 2 $ ."$""
|
|
|
|
$ ûM ü3 &6
|
