API: rename _prop_attributes to __finalize__ (in NDFrame)

[jreback]

• rename _propogate_attributes to _metadata (in NDFrame)
• change methods which directly pass metadata to use finalize

These provide a simple mechanism for meta data propagation, which
can be overriden in subclasses if desired. Currently these only do non-ambiguous
propagation.

makes #60, #2485 easier

[jreback]

@jtratner

I was actually toying with the idea of having __finalize__ have a signature like this:

def __finalize__(self, other, method=None):
.....

then a sub-class (or even in the current implementation of ``finalize`) you could dispatch on the method (which would be the name of the calling method) and do something interesting

[jtratner]

that's similar to what numpy does. Let's be clear about lifecycle for NDFrame:

__new__ --> not used (just object's __new__)
__init__ --> called to reconstruct object, no access to metadata of previous
__finalize__ --> called after __init__ is done initializing after things like arithmetic, sorting, and slicing that generate either same type or constructorsliced?

So if you do df["A"], would that call __finalize__? what about df.loc or other structures like that? (or the methods that promote upwards)?

__init__ doesn't return anything, should __finalize__ return self?

[jtratner]

also which __finalize__ gets called on df["A"]? I'm assuming it's whatever is on the sliced constructor?

[jtratner]

I'm a fan of having it return self, looks nicer in the code too.

[jtratner]

btw - to keep in mind, from the Python docs on magic methods:

__*__
System-defined names. These names are defined by the interpreter and its implementation (including the standard library). Current system names are discussed in the Special method names section and elsewhere. More will likely be defined in future versions of Python. Any use of __*__ names, in any context, that does not follow explicitly documented use, is subject to breakage without warning.

http://docs.python.org/2/reference/lexical_analysis.html#reserved-classes-of-identifiers

I'm guessing that numpy is popular enough for them not to worry about it 😄

I still like __finalize__ though.

[jtratner]

Does this have a performance hit? I'd guess that it would be minimal.

[jreback]

it's already in there (and minimal)
just per construction