3
���h#] � @ sF U d Z ddlmZ ddlmZmZ ddlZddlmZm Z m
Z
m Z m Z m
Z
mZmZmZ ddlZddlmZ edd�Zed d
�Zi Ze
eef i Ze
eef i Ze
eef d gZe e G d d
� d
ee �Z ee ed�dd�Z dXee d�dd�Z dd�dd�Z!dYee d�dd �Z"dZee dd�d d �Z#ed �d d!�Z$G d"d#� d#�Z%G d$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%e�Z/G d*d+� d+e�Z0d[ee1ee
e egef e
e egef dd,�d-d.�a2d\ee
e e
e dd/�d0d1�Z3ee e d2�d3d4�Z4eee
eef ef d5�d6d7�Z5ee d5�d8d9�Z6ed:�d;d<�Z7ed:�d=d>�Z8eed5�d?d@�Z9ee d5�dAdB�Z:eedC�dDdE�Z;d]e e e dG�dHdI�Z<edJdK� �Z=ee e egdf dL�dMdN�Z>e egdf d�dOdP�Z?e egdf d�dQdR�Z@e
eA ddS�dTdU�ZBe>eA�ZCe>e �ZDe>eE�ZFe>e�ZGe?eeHf�ZIe d�dVdW�ZJdS )^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)�ContextDecorator�contextmanagerN) �Any�Callable�Dict�Iterable�List�Optional�Tuple�Type�cast)�F�DeprecatedOptionzkey msg rkey removal_ver�RegisteredOptionzkey defval doc validator cb�allc @ s e Zd ZdZdS )� OptionErrorzU
Exception for pandas.options, backwards compatible with KeyError
checks
N)�__name__�
__module__� __qualname__�__doc__� r r �7/tmp/pip-build-5_djhm0z/pandas/pandas/_config/config.pyr K s r )�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 r �keys�keyr r r �_get_single_keyV s r$ F)r r c C s t | |�}t|�\}}|| S )N)r$ � _get_root)r r r# �root�kr r r � _get_optionh s
r( )r c
O s� t | �}| s|d dkr"td��|jdd�}|rRt|j� �d }td|� d���x�t| d d d� | dd d� �D ]z\}}t||�}t|�}|r�|j r�|j |� t
|�\} }|| |< |j rr|r�t j
d d
�� |j |� W d Q R X qr|j |� qrW d S ) N� r z4Must provide an even number of non-keyword argumentsr Fz2_set_option() got an unexpected keyword argument "�"r T)�record)r �
ValueError�pop�listr" � TypeError�zipr$ �_get_registered_option� validatorr% �cb�warnings�catch_warnings)
�args�kwargs�nargsr Zkwargr' �vr# �or& r r r � _set_optionp s& (
r; � T)r � _print_descc C sF t | �}t|�dkr td��djdd� |D ��}|r>t|� n|S d S )Nr zNo such keys(s)�
c S s g | ] }t |��qS r )�_build_option_description)�.0r' r r r �
<listcomp>� s z$_describe_option.<locals>.<listcomp>)r r r �join�print)r r= r" �sr r r �_describe_option� s
rE c C sj t | �}t|�dkr td��t|�dkrDt| �dk rD| dkrDtd��x |D ]}t|t| j|d� qJW d S )Nr zNo such keys(s)r � r z�You 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 )r r r r, r; �_registered_options�defval)r r r" r' r r r �
_reset_option� s
rI )r c C s t | dd�}t|�jS )NT)r )r$ r1 rH )r r# r r r �get_default_val� s rJ c @ s\ e Zd ZdZdeeef ed�dd�Zeedd�dd �Zed
�d d �Z e
e d
�dd�Z dS )� DictWrapperz0 provide attribute-style access to a nested dictr< )�d�prefixc C s t j| d|� t j| d|� d S )NrL rM )�object� __setattr__)�selfrL rM r r r �__init__� s zDictWrapper.__init__N)r# �valr c C sT t j| d�}|r|d7 }||7 }|| jkrHt| j| t� rHt||� ntd��d S )NrM �.z.You can only set the value of existing options)rN �__getattribute__rL �
isinstance�dictr; r )rP r# rR rM r r r rO � s zDictWrapper.__setattr__)r# c C s� t j| d�}|r|d7 }||7 }yt j| d�| }W n, tk
r` } ztd�|�W Y d d }~X nX t|t�rvt||�S t|�S d S )NrM rS rL zNo such option)rN rT �KeyErrorr rU rV rK r( )rP r# rM r9 �errr r r � __getattr__� s
zDictWrapper.__getattr__)r c C s t | jj� �S )N)r. rL r" )rP r r r �__dir__� s zDictWrapper.__dir__)r< ) r r r r r �strr rQ rO rY r rZ r r r r rK � s
rK c @ s( e Zd Zdd� Zdd� Zedd� �ZdS )�CallableDynamicDocc C s || _ || _d S )N)� __doc_tmpl__�__func__)rP �funcZdoc_tmplr r r rQ � s zCallableDynamicDoc.__init__c O s | j ||�S )N)r^ )rP r6 �kwdsr r r �__call__� s zCallableDynamicDoc.__call__c C s, t ddd�}tttj� ��}| jj||d�S )Nr F)r= )� opts_desc� opts_list)rE �pp_options_listr. rG r" r] �format)rP rb rc r r r r � s zCallableDynamicDoc.__doc__N)r r r rQ ra �propertyr r r r r r\ � s r\ 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( e Zd ZdZdd� Zdd� Zdd� ZdS ) �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):
... ...
c G sL t |�d dkot |�dks$td��tt|d d d� |dd d� ��| _d S )Nr) r z>Need to invoke as option_context(pat, val, [(pat, val), ...]).r )r r, r. r0 �ops)rP r6 r r r rQ � s zoption_context.__init__c C s8 dd� | j D �| _x | j D ]\}}t||dd� qW d S )Nc S s g | ]\}}|t |d d�f�qS )T)r )r( )r@ r rR r r r rA � s z,option_context.__enter__.<locals>.<listcomp>T)r )rh �undor; )rP r rR r r r � __enter__� s zoption_context.__enter__c G s, | j r(x | j D ]\}}t||dd� qW d S )NT)r )ri r; )rP r6 r rR r r r �__exit__� s zoption_context.__exit__N)r r r r rQ rj rk r r r r rg ~ s
rg )r# rH �docr2 r3 r c
C s` ddl }ddl}| j� } | tkr0td| � d���| tkrHtd| � d���|rT||� | jd�}xH|D ]@}tjd|j d |�s�t
|� d ���|j |�rdt
|� d
���qdW t } d }
x^t
|dd� �D ]J\} } t| t�s�t|
jdj|d| � �d
���| | k�ri | | < | | } q�W t| t��s:t|
jdj|dd� �d
���|| |d < t| ||||d�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.
r NzOption 'z ' has already been registeredz' is a reserved keyrS �^�$z is not a valid identifierz is a python keywordz5Path prefix to option '{option}' is already an optionr )�option)r# rH rl r2 r3 ���rp rp )�keyword�tokenize�lowerrG r �_reserved_keys�split�re�match�Namer, � iskeyword�_global_config� enumeraterU rV re rB r )
r# rH rl r2 r3 rq rr �pathr' �cursor�msg�i�pr r r �register_option� s8
r� )r# r~ �rkeyr c C s6 | j � } | tkr td| � d���t| |||�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)rs �_deprecated_optionsr r )r# r~ r� � removal_verr r r �deprecate_option� s $r� )r r c s8 � t kr� gS tt j� �}� 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 j� |t j�r|�qS r )rv �search�I)r@ r' )r r r rA * s z#_select_options.<locals>.<listcomp>)rG �sortedr" )r r" r )r r r s r )r# r c C s8 | j d�}t}x |d d� D ] }|| }q W ||d fS )NrS r rp rp )ru rz )r# r| r} r� r r r r% - s
r% c C s | j � } | tkS )z6 Returns True if the given option has been deprecated )rs r� )r# r r r �_is_deprecated5 s r� )r# c C s* y t | }W n tk
r 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� rW )r# rL r r r �_get_deprecated_option; s
r� c C s
t j| �S )z�
Retrieves the option metadata if `key` is a registered option.
Returns
-------
RegisteredOption (namedtuple) if key is deprecated, None otherwise
)rG �get)r# r r r r1 K s r1 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# rL r r r r! V s
r! c C s� t | �}|r�|jr,t|j� tj|jt� nPd| � d�}|jrN|d|j� �7 }|jrh|d|j� d�7 }n|d7 }tj|t� dS dS ) 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)r� r~ rC r4 �warn�
FutureWarningr� r� )r# rL r~ r r r r b s
r )r' r c C s� t | �}t| �}| � d�}|jr<|dj|jj� jd��7 }n|d7 }|rf|d|j� dt| d�� d�7 }|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.�)) r1 r� rl rB �stripru rH r( r� )r' r: rL rD r� r r r r? } s
r? �P )r" �_printc
s� ddl m} ddlm� ttt tt d���fdd� }g }dd� t| �D �}|r`||d |�7 }d
d� | D �} xB|t| �d d � �D ],\� }� fd
d�t|�D �}||� |�7 }q�W dj |�} |r�t
| � n| S dS )zB Builds a concise listing of available options, grouped by prefix r )�groupby)�wrap)�name�ksr c sP | rd| d nd}�dj |�� |ddd�}|rL|d
rL| rL|d d |d < |S )
Nz- z.[r< z, z F)�initial_indent�subsequent_indent�break_long_wordsr r� rp rp rp )rB )r� r� �pfx�ls)�widthr� r r �pp� s zpp_options_list.<locals>.ppc S s g | ]}|j d �dk r|�qS )rS r )�find)r@ �xr r r rA � s z#pp_options_list.<locals>.<listcomp>r< c S s g | ]}|j d �dkr|�qS )rS r )r� )r@ r� r r r rA � s c S s | d | j d�� S )NrS )�rfind)r� r r r �<lambda>� s z!pp_options_list.<locals>.<lambda>c s g | ]}|t � �d d� �qS )r N)r )r@ r� )r' r r rA � s r> N) � itertoolsr� �textwrapr� r[ r r r� r. rB rC )
r" r� r� r� r� r� Zsingles�gr� rD r )r' r� r� r rd � s
rd c # sN t t d�� fdd� }t}t}t}|t�a|t�a|t�adV |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_ r c s t d�� �fdd� }tt|�S )N)r# c s �� d| � �}� |f|�|�S )NrS r )r# r6 r` Zpkey)r_ rM r r �inner� s z*config_prefix.<locals>.wrap.<locals>.inner)r[ r
r )r_ r� )rM )r_ r r� � s zconfig_prefix.<locals>.wrapN)r r� �
get_option�
set_option)rM r� Z_register_optionr( r; r )rM r �
config_prefix� s r� )�_typer 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`
N)r c s t | �� kr td� � d���d S )NzValue must have type 'r� )�typer, )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 � ttf�r(t� �� djtt� ���n d� � d��dd�� �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� N)r c s t | � �std�� ���d S )Nz Value must be an instance of )rU r, )r� )r� � type_reprr r r� s
z"is_instance_factory.<locals>.inner)rU �tupler. rB �mapr[ )r� r� r )r� r� r �is_instance_factory s
r� c s4 dd� �D �� dd� �D ��d d�� �fdd� }|S )Nc S s g | ]}t |�r|�qS r )�callable)r@ �cr r r rA ! s z%is_one_of_factory.<locals>.<listcomp>c S s g | ]}t |�s|�qS r )r� )r@ r� r r r rA " s )r c s\ � �krXt � fdd��D ��sXdd� �D �}dj|�}d|� �}t��rP|d7 }t|��d S )Nc 3 s | ]}|� �V qd S )Nr )r@ r� )r� r r � <genexpr>' s z3is_one_of_factory.<locals>.inner.<locals>.<genexpr>c S s g | ] }t |��qS r )r[ )r@ Zlvalr r r rA ( s z4is_one_of_factory.<locals>.inner.<locals>.<listcomp>r� zValue must be one of z or a callable)�anyrB r r, )r� ZuvalsZ pp_valuesr~ )� callables� legal_values)r� r r� $ s
z is_one_of_factory.<locals>.innerr )r� r� r )r� r� r �is_one_of_factory s r� )�valuer c C s2 | dkr dS t | t�r"| 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)rU �intr, )r� r~ r r r �is_nonnegative_int2 s
r� c C s t | �std��dS )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� r, )�objr r r � is_callableT s
r� )F)r< T)F)r< NN)NNN)r� F)Kr � collectionsr �
contextlibr r rv Ztypingr r r r r r
r r r
r4 Zpandas._typingr r r r� r[ rG rz rt �AttributeErrorrW r �boolr$ r( r; rE rI rJ rK r\ Z_get_option_tmplZ_set_option_tmplZ_describe_option_tmplZ_reset_option_tmplr� r� Z reset_optionZdescribe_option�optionsrg rN r� r� r r% r� r� r1 r! r r? rd r� r� r� r� r� r� Zis_intZis_bool�floatZis_floatZis_str�bytesZis_textr� r r r r �<module>1 sr ,
.-"
# (H. & 5 |