PR: adding a core.config module to hold package-wide configurables

[ghost]

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

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

[ghost]

should describe_option print the description, rather then return it as a string?

[ghost]

rebased to clear merge conflicts from PEP8 tsunami.

[ghost]

The equiv. of f2ded9a should be considered for cherry-pick whether this goes in or not.
IPython finally fixed the corresponding issue on their end: ipython/ipython#2500

[wesm]

This definitely will be going in in the next major release

[ghost]

groovy.

[changhiskhan]

Putting a note here to remind myself to move the plot options into this module after 0.9.1

[ghost]

• cleared merge conflicts against git master
• changed describe_option to describe_options :
  • when invoked with no argument , will print help on all registered options.
  • when given an argument, print description of exact key if it exists, otherwise
    print descriptions for all option keys that match.
  • added optional argument to return description as string rather then printing it. mostly for testing.
• nicer formatting
• some cleanups

[ghost]

removed 2.5 support

[wesm]

Am I correct that this should be backwards-compatible change?

[ghost]

I think so.
set_printoptions still works, even though it now relies on core.config behind the scenes.

[wesm]

Do you think this should be mentioned in the "what's new?" page (docs/source/v0.10.0.txt)?

[ghost]

Better mention the new API functions I think, that matters to users.

Will sphinx pick up the doctsrings automatically, or do I need to add docs myself? I neglected
that part of things.

[wesm]

You can add entries to the API page. But it might make sense to write some brief exposition on config options-- printoptions might be in the docs already but I don't remember adding them myself.

[ghost]

updated docs/source/v0.10.0.txt

[ghost]

@wesm, I think having both reset_option and reset_options is silly in retrospect,
when is 0.10.0 coming out? I'd like to mend this before the API becomes part of a stable release.