pydata/pandas — pull request #2097 by y-p (2012-10-21 11:28:51+00:00)
Title: PR: adding a core.config module to hold package-wide configurables

PR for #2081

Summary
----
- core.config is a new module which serves as a general mechanism for working with configurables,
- superceds fmt.print_config, while remaining backward-compatible (set_printoptions(), reset_printoptions() are still working).
- adds the following user API's: `get_option()`, `set_option`, `reset_option()`, `reset_options()` and `describe_option()` (all under the pandas top level module).
- adds the following for developer use: `register_option()` and `deprecate_option()` for developers.

TL;DR description
---
ENH: Add core.config module for managing package-wide configurables

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

Implementation
==============

- Data is stored using nested dictionaries, and should be accessed
through the provided API.

- "Registered options" and "Deprecated options" have metadata associcated
with them, which are stored in auxilary dictionaries keyed on the
fully-qualified key, e.g. "x.y.option - z".

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