Hide keyboard shortcuts

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. 

7 

8If you need to make sure options are available even before a certain 

9module is imported, register them here rather then in the module. 

10 

11""" 

12import warnings 

13 

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) 

24 

25# compute 

26 

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""" 

33 

34 

35def use_bottleneck_cb(key): 

36 from pandas.core import nanops 

37 

38 nanops.set_use_bottleneck(cf.get_option(key)) 

39 

40 

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""" 

47 

48 

49def use_numexpr_cb(key): 

50 from pandas.core.computation import expressions 

51 

52 expressions.set_use_numexpr(cf.get_option(key)) 

53 

54 

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 

68 

69pc_precision_doc = """ 

70: int 

71 Floating point output precision (number of significant digits). This is 

72 only a suggestion 

73""" 

74 

75pc_colspace_doc = """ 

76: int 

77 Default space for DataFrame columns. 

78""" 

79 

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. 

85 

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""" 

93 

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""" 

100 

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. 

106 

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""" 

114 

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""" 

120 

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""" 

126 

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""" 

132 

133pc_pprint_nest_depth = """ 

134: int 

135 Controls the number of nested levels to process when pretty-printing 

136""" 

137 

138pc_multi_sparse_doc = """ 

139: boolean 

140 "sparsify" MultiIndex display (don't display repeated 

141 elements in outer levels within groups) 

142""" 

143 

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""" 

151 

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""" 

158 

159colheader_justify_doc = """ 

160: 'left'/'right' 

161 Controls the justification of column headers. used by DataFrameFormatter. 

162""" 

163 

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""" 

170 

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""" 

177 

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""" 

184 

185pc_ambiguous_as_wide_doc = """ 

186: boolean 

187 Whether to handle Unicode characters belong to Ambiguous as Wide (width=2) 

188 (default: False) 

189""" 

190 

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""" 

197 

198pc_table_schema_doc = """ 

199: boolean 

200 Whether to publish a Table Schema representation for frontends 

201 that support it. 

202 (default: False) 

203""" 

204 

205pc_html_border_doc = """ 

206: int 

207 A ``border=value`` attribute is inserted in the ``<table>`` tag 

208 for the DataFrame HTML repr. 

209""" 

210 

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""" 

217 

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""" 

226 

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""" 

232 

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. 

238 

239 If set to None, the number of items to be printed is unlimited. 

240""" 

241 

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""" 

249 

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""" 

256 

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""" 

262 

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""" 

269 

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""" 

276 

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""" 

283 

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""" 

290 

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""" 

297 

298 

299def table_schema_cb(key): 

300 from pandas.io.formats.printing import _enable_data_resource_formatter 

301 

302 _enable_data_resource_formatter(cf.get_option(key)) 

303 

304 

305def is_terminal() -> bool: 

306 """ 

307 Detect if Python is running in a terminal. 

308 

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 

321 

322 

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) 

346 

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 ) 

357 

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 ) 

432 

433tc_sim_interactive_doc = """ 

434: boolean 

435 Whether to simulate interactive mode for purposes of testing 

436""" 

437 

438with cf.config_prefix("mode"): 

439 cf.register_option("sim_interactive", False, tc_sim_interactive_doc) 

440 

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""" 

446 

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""" 

453 

454# We don't want to start importing everything at the global context level 

455# or we'll hit circular deps. 

456 

457 

458def use_inf_as_na_cb(key): 

459 from pandas.core.dtypes.missing import _use_inf_as_na 

460 

461 _use_inf_as_na(key) 

462 

463 

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 ) 

469 

470cf.deprecate_option( 

471 "mode.use_inf_as_null", msg=use_inf_as_null_doc, rkey="mode.use_inf_as_na" 

472) 

473 

474 

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""" 

481 

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 ) 

489 

490 

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""" 

497 

498_xls_options = ["xlrd"] 

499_xlsm_options = ["xlrd", "openpyxl"] 

500_xlsx_options = ["xlrd", "openpyxl"] 

501_ods_options = ["odf"] 

502_xlsb_options = ["pyxlsb"] 

503 

504 

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 ) 

512 

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 ) 

520 

521 

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 ) 

529 

530 

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 ) 

538 

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 ) 

546 

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""" 

553 

554_xls_options = ["xlwt"] 

555_xlsm_options = ["openpyxl"] 

556_xlsx_options = ["openpyxl", "xlsxwriter"] 

557 

558 

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 ) 

566 

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 ) 

574 

575 

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 ) 

583 

584 

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""" 

591 

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 ) 

599 

600# -------- 

601# Plotting 

602# --------- 

603 

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""" 

610 

611 

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 

617 

618 _get_plot_backend(key) 

619 

620 

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 ) 

628 

629 

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""" 

636 

637 

638def register_converter_cb(key): 

639 from pandas.plotting import register_matplotlib_converters 

640 from pandas.plotting import deregister_matplotlib_converters 

641 

642 if cf.get_option(key): 

643 register_matplotlib_converters() 

644 else: 

645 deregister_matplotlib_converters() 

646 

647 

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 )