Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/pandas/core/config_init.py : 86%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2This module is imported from the pandas package __init__.py file
3in order to ensure that the core.config options registered here will
4be available as soon as the user loads the package. if register_option
5is invoked inside specific modules, they will not be registered until that
6module is imported, which may or may not be a problem.
8If you need to make sure options are available even before a certain
9module is imported, register them here rather then in the module.
11"""
12import warnings
14import pandas._config.config as cf
15from pandas._config.config import (
16 is_bool,
17 is_callable,
18 is_instance_factory,
19 is_int,
20 is_nonnegative_int,
21 is_one_of_factory,
22 is_text,
23)
25# compute
27use_bottleneck_doc = """
28: bool
29 Use the bottleneck library to accelerate if it is installed,
30 the default is True
31 Valid values: False,True
32"""
35def use_bottleneck_cb(key):
36 from pandas.core import nanops
38 nanops.set_use_bottleneck(cf.get_option(key))
41use_numexpr_doc = """
42: bool
43 Use the numexpr library to accelerate computation if it is installed,
44 the default is True
45 Valid values: False,True
46"""
49def use_numexpr_cb(key):
50 from pandas.core.computation import expressions
52 expressions.set_use_numexpr(cf.get_option(key))
55with cf.config_prefix("compute"):
56 cf.register_option(
57 "use_bottleneck",
58 True,
59 use_bottleneck_doc,
60 validator=is_bool,
61 cb=use_bottleneck_cb,
62 )
63 cf.register_option(
64 "use_numexpr", True, use_numexpr_doc, validator=is_bool, cb=use_numexpr_cb
65 )
66#
67# options from the "display" namespace
69pc_precision_doc = """
70: int
71 Floating point output precision (number of significant digits). This is
72 only a suggestion
73"""
75pc_colspace_doc = """
76: int
77 Default space for DataFrame columns.
78"""
80pc_max_rows_doc = """
81: int
82 If max_rows is exceeded, switch to truncate view. Depending on
83 `large_repr`, objects are either centrally truncated or printed as
84 a summary view. 'None' value means unlimited.
86 In case python/IPython is running in a terminal and `large_repr`
87 equals 'truncate' this can be set to 0 and pandas will auto-detect
88 the height of the terminal and print a truncated object which fits
89 the screen height. The IPython notebook, IPython qtconsole, or
90 IDLE do not run in a terminal and hence it is not possible to do
91 correct auto-detection.
92"""
94pc_min_rows_doc = """
95: int
96 The numbers of rows to show in a truncated view (when `max_rows` is
97 exceeded). Ignored when `max_rows` is set to None or 0. When set to
98 None, follows the value of `max_rows`.
99"""
101pc_max_cols_doc = """
102: int
103 If max_cols is exceeded, switch to truncate view. Depending on
104 `large_repr`, objects are either centrally truncated or printed as
105 a summary view. 'None' value means unlimited.
107 In case python/IPython is running in a terminal and `large_repr`
108 equals 'truncate' this can be set to 0 and pandas will auto-detect
109 the width of the terminal and print a truncated object which fits
110 the screen width. The IPython notebook, IPython qtconsole, or IDLE
111 do not run in a terminal and hence it is not possible to do
112 correct auto-detection.
113"""
115pc_max_categories_doc = """
116: int
117 This sets the maximum number of categories pandas should output when
118 printing out a `Categorical` or a Series of dtype "category".
119"""
121pc_max_info_cols_doc = """
122: int
123 max_info_columns is used in DataFrame.info method to decide if
124 per column information will be printed.
125"""
127pc_nb_repr_h_doc = """
128: boolean
129 When True, IPython notebook will use html representation for
130 pandas objects (if it is available).
131"""
133pc_pprint_nest_depth = """
134: int
135 Controls the number of nested levels to process when pretty-printing
136"""
138pc_multi_sparse_doc = """
139: boolean
140 "sparsify" MultiIndex display (don't display repeated
141 elements in outer levels within groups)
142"""
144float_format_doc = """
145: callable
146 The callable should accept a floating point number and return
147 a string with the desired format of the number. This is used
148 in some places like SeriesFormatter.
149 See formats.format.EngFormatter for an example.
150"""
152max_colwidth_doc = """
153: int or None
154 The maximum width in characters of a column in the repr of
155 a pandas data structure. When the column overflows, a "..."
156 placeholder is embedded in the output. A 'None' value means unlimited.
157"""
159colheader_justify_doc = """
160: 'left'/'right'
161 Controls the justification of column headers. used by DataFrameFormatter.
162"""
164pc_expand_repr_doc = """
165: boolean
166 Whether to print out the full DataFrame repr for wide DataFrames across
167 multiple lines, `max_columns` is still respected, but the output will
168 wrap-around across multiple "pages" if its width exceeds `display.width`.
169"""
171pc_show_dimensions_doc = """
172: boolean or 'truncate'
173 Whether to print out dimensions at the end of DataFrame repr.
174 If 'truncate' is specified, only print out the dimensions if the
175 frame is truncated (e.g. not display all rows and/or columns)
176"""
178pc_east_asian_width_doc = """
179: boolean
180 Whether to use the Unicode East Asian Width to calculate the display text
181 width.
182 Enabling this may affect to the performance (default: False)
183"""
185pc_ambiguous_as_wide_doc = """
186: boolean
187 Whether to handle Unicode characters belong to Ambiguous as Wide (width=2)
188 (default: False)
189"""
191pc_latex_repr_doc = """
192: boolean
193 Whether to produce a latex DataFrame representation for jupyter
194 environments that support it.
195 (default: False)
196"""
198pc_table_schema_doc = """
199: boolean
200 Whether to publish a Table Schema representation for frontends
201 that support it.
202 (default: False)
203"""
205pc_html_border_doc = """
206: int
207 A ``border=value`` attribute is inserted in the ``<table>`` tag
208 for the DataFrame HTML repr.
209"""
211pc_html_use_mathjax_doc = """\
212: boolean
213 When True, Jupyter notebook will process table contents using MathJax,
214 rendering mathematical expressions enclosed by the dollar symbol.
215 (default: True)
216"""
218pc_width_doc = """
219: int
220 Width of the display in characters. In case python/IPython is running in
221 a terminal this can be set to None and pandas will correctly auto-detect
222 the width.
223 Note that the IPython notebook, IPython qtconsole, or IDLE do not run in a
224 terminal and hence it is not possible to correctly detect the width.
225"""
227pc_chop_threshold_doc = """
228: float or None
229 if set to a float value, all float values smaller then the given threshold
230 will be displayed as exactly 0 by repr and friends.
231"""
233pc_max_seq_items = """
234: int or None
235 when pretty-printing a long sequence, no more then `max_seq_items`
236 will be printed. If items are omitted, they will be denoted by the
237 addition of "..." to the resulting string.
239 If set to None, the number of items to be printed is unlimited.
240"""
242pc_max_info_rows_doc = """
243: int or None
244 df.info() will usually show null-counts for each column.
245 For large frames this can be quite slow. max_info_rows and max_info_cols
246 limit this null check only to frames with smaller dimensions than
247 specified.
248"""
250pc_large_repr_doc = """
251: 'truncate'/'info'
252 For DataFrames exceeding max_rows/max_cols, the repr (and HTML repr) can
253 show a truncated table (the default from 0.13), or switch to the view from
254 df.info() (the behaviour in earlier versions of pandas).
255"""
257pc_memory_usage_doc = """
258: bool, string or None
259 This specifies if the memory usage of a DataFrame should be displayed when
260 df.info() is called. Valid values True,False,'deep'
261"""
263pc_latex_escape = """
264: bool
265 This specifies if the to_latex method of a Dataframe uses escapes special
266 characters.
267 Valid values: False,True
268"""
270pc_latex_longtable = """
271:bool
272 This specifies if the to_latex method of a Dataframe uses the longtable
273 format.
274 Valid values: False,True
275"""
277pc_latex_multicolumn = """
278: bool
279 This specifies if the to_latex method of a Dataframe uses multicolumns
280 to pretty-print MultiIndex columns.
281 Valid values: False,True
282"""
284pc_latex_multicolumn_format = """
285: string
286 This specifies the format for multicolumn headers.
287 Can be surrounded with '|'.
288 Valid values: 'l', 'c', 'r', 'p{<width>}'
289"""
291pc_latex_multirow = """
292: bool
293 This specifies if the to_latex method of a Dataframe uses multirows
294 to pretty-print MultiIndex rows.
295 Valid values: False,True
296"""
299def table_schema_cb(key):
300 from pandas.io.formats.printing import _enable_data_resource_formatter
302 _enable_data_resource_formatter(cf.get_option(key))
305def is_terminal() -> bool:
306 """
307 Detect if Python is running in a terminal.
309 Returns True if Python is running in a terminal or False if not.
310 """
311 try:
312 # error: Name 'get_ipython' is not defined
313 ip = get_ipython() # type: ignore
314 except NameError: # assume standard Python interpreter in a terminal
315 return True
316 else:
317 if hasattr(ip, "kernel"): # IPython as a Jupyter kernel
318 return False
319 else: # IPython in a terminal
320 return True
323with cf.config_prefix("display"):
324 cf.register_option("precision", 6, pc_precision_doc, validator=is_nonnegative_int)
325 cf.register_option(
326 "float_format",
327 None,
328 float_format_doc,
329 validator=is_one_of_factory([None, is_callable]),
330 )
331 cf.register_option("column_space", 12, validator=is_int)
332 cf.register_option(
333 "max_info_rows",
334 1690785,
335 pc_max_info_rows_doc,
336 validator=is_instance_factory((int, type(None))),
337 )
338 cf.register_option("max_rows", 60, pc_max_rows_doc, validator=is_nonnegative_int)
339 cf.register_option(
340 "min_rows",
341 10,
342 pc_min_rows_doc,
343 validator=is_instance_factory([type(None), int]),
344 )
345 cf.register_option("max_categories", 8, pc_max_categories_doc, validator=is_int)
347 def _deprecate_negative_int_max_colwidth(key):
348 value = cf.get_option(key)
349 if value is not None and value < 0:
350 warnings.warn(
351 "Passing a negative integer is deprecated in version 1.0 and "
352 "will not be supported in future version. Instead, use None "
353 "to not limit the column width.",
354 FutureWarning,
355 stacklevel=4,
356 )
358 cf.register_option(
359 # FIXME: change `validator=is_nonnegative_int`
360 # in version 1.2
361 "max_colwidth",
362 50,
363 max_colwidth_doc,
364 validator=is_instance_factory([type(None), int]),
365 cb=_deprecate_negative_int_max_colwidth,
366 )
367 if is_terminal():
368 max_cols = 0 # automatically determine optimal number of columns
369 else:
370 max_cols = 20 # cannot determine optimal number of columns
371 cf.register_option(
372 "max_columns", max_cols, pc_max_cols_doc, validator=is_nonnegative_int
373 )
374 cf.register_option(
375 "large_repr",
376 "truncate",
377 pc_large_repr_doc,
378 validator=is_one_of_factory(["truncate", "info"]),
379 )
380 cf.register_option("max_info_columns", 100, pc_max_info_cols_doc, validator=is_int)
381 cf.register_option(
382 "colheader_justify", "right", colheader_justify_doc, validator=is_text
383 )
384 cf.register_option("notebook_repr_html", True, pc_nb_repr_h_doc, validator=is_bool)
385 cf.register_option("pprint_nest_depth", 3, pc_pprint_nest_depth, validator=is_int)
386 cf.register_option("multi_sparse", True, pc_multi_sparse_doc, validator=is_bool)
387 cf.register_option("expand_frame_repr", True, pc_expand_repr_doc)
388 cf.register_option(
389 "show_dimensions",
390 "truncate",
391 pc_show_dimensions_doc,
392 validator=is_one_of_factory([True, False, "truncate"]),
393 )
394 cf.register_option("chop_threshold", None, pc_chop_threshold_doc)
395 cf.register_option("max_seq_items", 100, pc_max_seq_items)
396 cf.register_option(
397 "width", 80, pc_width_doc, validator=is_instance_factory([type(None), int])
398 )
399 cf.register_option(
400 "memory_usage",
401 True,
402 pc_memory_usage_doc,
403 validator=is_one_of_factory([None, True, False, "deep"]),
404 )
405 cf.register_option(
406 "unicode.east_asian_width", False, pc_east_asian_width_doc, validator=is_bool
407 )
408 cf.register_option(
409 "unicode.ambiguous_as_wide", False, pc_east_asian_width_doc, validator=is_bool
410 )
411 cf.register_option("latex.repr", False, pc_latex_repr_doc, validator=is_bool)
412 cf.register_option("latex.escape", True, pc_latex_escape, validator=is_bool)
413 cf.register_option("latex.longtable", False, pc_latex_longtable, validator=is_bool)
414 cf.register_option(
415 "latex.multicolumn", True, pc_latex_multicolumn, validator=is_bool
416 )
417 cf.register_option(
418 "latex.multicolumn_format", "l", pc_latex_multicolumn, validator=is_text
419 )
420 cf.register_option("latex.multirow", False, pc_latex_multirow, validator=is_bool)
421 cf.register_option(
422 "html.table_schema",
423 False,
424 pc_table_schema_doc,
425 validator=is_bool,
426 cb=table_schema_cb,
427 )
428 cf.register_option("html.border", 1, pc_html_border_doc, validator=is_int)
429 cf.register_option(
430 "html.use_mathjax", True, pc_html_use_mathjax_doc, validator=is_bool
431 )
433tc_sim_interactive_doc = """
434: boolean
435 Whether to simulate interactive mode for purposes of testing
436"""
438with cf.config_prefix("mode"):
439 cf.register_option("sim_interactive", False, tc_sim_interactive_doc)
441use_inf_as_null_doc = """
442: boolean
443 use_inf_as_null had been deprecated and will be removed in a future
444 version. Use `use_inf_as_na` instead.
445"""
447use_inf_as_na_doc = """
448: boolean
449 True means treat None, NaN, INF, -INF as NA (old way),
450 False means None and NaN are null, but INF, -INF are not NA
451 (new way).
452"""
454# We don't want to start importing everything at the global context level
455# or we'll hit circular deps.
458def use_inf_as_na_cb(key):
459 from pandas.core.dtypes.missing import _use_inf_as_na
461 _use_inf_as_na(key)
464with cf.config_prefix("mode"):
465 cf.register_option("use_inf_as_na", False, use_inf_as_na_doc, cb=use_inf_as_na_cb)
466 cf.register_option(
467 "use_inf_as_null", False, use_inf_as_null_doc, cb=use_inf_as_na_cb
468 )
470cf.deprecate_option(
471 "mode.use_inf_as_null", msg=use_inf_as_null_doc, rkey="mode.use_inf_as_na"
472)
475# user warnings
476chained_assignment = """
477: string
478 Raise an exception, warn, or no action if trying to use chained assignment,
479 The default is warn
480"""
482with cf.config_prefix("mode"):
483 cf.register_option(
484 "chained_assignment",
485 "warn",
486 chained_assignment,
487 validator=is_one_of_factory([None, "warn", "raise"]),
488 )
491# Set up the io.excel specific reader configuration.
492reader_engine_doc = """
493: string
494 The default Excel reader engine for '{ext}' files. Available options:
495 auto, {others}.
496"""
498_xls_options = ["xlrd"]
499_xlsm_options = ["xlrd", "openpyxl"]
500_xlsx_options = ["xlrd", "openpyxl"]
501_ods_options = ["odf"]
502_xlsb_options = ["pyxlsb"]
505with cf.config_prefix("io.excel.xls"):
506 cf.register_option(
507 "reader",
508 "auto",
509 reader_engine_doc.format(ext="xls", others=", ".join(_xls_options)),
510 validator=str,
511 )
513with cf.config_prefix("io.excel.xlsm"):
514 cf.register_option(
515 "reader",
516 "auto",
517 reader_engine_doc.format(ext="xlsm", others=", ".join(_xlsm_options)),
518 validator=str,
519 )
522with cf.config_prefix("io.excel.xlsx"):
523 cf.register_option(
524 "reader",
525 "auto",
526 reader_engine_doc.format(ext="xlsx", others=", ".join(_xlsx_options)),
527 validator=str,
528 )
531with cf.config_prefix("io.excel.ods"):
532 cf.register_option(
533 "reader",
534 "auto",
535 reader_engine_doc.format(ext="ods", others=", ".join(_ods_options)),
536 validator=str,
537 )
539with cf.config_prefix("io.excel.xlsb"):
540 cf.register_option(
541 "reader",
542 "auto",
543 reader_engine_doc.format(ext="xlsb", others=", ".join(_xlsb_options)),
544 validator=str,
545 )
547# Set up the io.excel specific writer configuration.
548writer_engine_doc = """
549: string
550 The default Excel writer engine for '{ext}' files. Available options:
551 auto, {others}.
552"""
554_xls_options = ["xlwt"]
555_xlsm_options = ["openpyxl"]
556_xlsx_options = ["openpyxl", "xlsxwriter"]
559with cf.config_prefix("io.excel.xls"):
560 cf.register_option(
561 "writer",
562 "auto",
563 writer_engine_doc.format(ext="xls", others=", ".join(_xls_options)),
564 validator=str,
565 )
567with cf.config_prefix("io.excel.xlsm"):
568 cf.register_option(
569 "writer",
570 "auto",
571 writer_engine_doc.format(ext="xlsm", others=", ".join(_xlsm_options)),
572 validator=str,
573 )
576with cf.config_prefix("io.excel.xlsx"):
577 cf.register_option(
578 "writer",
579 "auto",
580 writer_engine_doc.format(ext="xlsx", others=", ".join(_xlsx_options)),
581 validator=str,
582 )
585# Set up the io.parquet specific configuration.
586parquet_engine_doc = """
587: string
588 The default parquet reader/writer engine. Available options:
589 'auto', 'pyarrow', 'fastparquet', the default is 'auto'
590"""
592with cf.config_prefix("io.parquet"):
593 cf.register_option(
594 "engine",
595 "auto",
596 parquet_engine_doc,
597 validator=is_one_of_factory(["auto", "pyarrow", "fastparquet"]),
598 )
600# --------
601# Plotting
602# ---------
604plotting_backend_doc = """
605: str
606 The plotting backend to use. The default value is "matplotlib", the
607 backend provided with pandas. Other backends can be specified by
608 prodiving the name of the module that implements the backend.
609"""
612def register_plotting_backend_cb(key):
613 if key == "matplotlib":
614 # We defer matplotlib validation, since it's the default
615 return
616 from pandas.plotting._core import _get_plot_backend
618 _get_plot_backend(key)
621with cf.config_prefix("plotting"):
622 cf.register_option(
623 "backend",
624 defval="matplotlib",
625 doc=plotting_backend_doc,
626 validator=register_plotting_backend_cb,
627 )
630register_converter_doc = """
631: bool or 'auto'.
632 Whether to register converters with matplotlib's units registry for
633 dates, times, datetimes, and Periods. Toggling to False will remove
634 the converters, restoring any converters that pandas overwrote.
635"""
638def register_converter_cb(key):
639 from pandas.plotting import register_matplotlib_converters
640 from pandas.plotting import deregister_matplotlib_converters
642 if cf.get_option(key):
643 register_matplotlib_converters()
644 else:
645 deregister_matplotlib_converters()
648with cf.config_prefix("plotting.matplotlib"):
649 cf.register_option(
650 "register_converters",
651 "auto",
652 register_converter_doc,
653 validator=is_one_of_factory(["auto", True, False]),
654 cb=register_converter_cb,
655 )