as an aside can u put a small doc that shows how to subclass DataFrame now that it is reasonably supportered - maybe put it in the FAQ

Sure, will do. By the way, is there any difference between FAQ and Gotcha? Otherwise, it may better to merge them to be more searchable.

@jorisvandenbossche what about merging faq and gotchas? I would say yes

Added subclassing documentation. Pls review.

@sinhrks This documentation on subclassing is great

I don't have much feedback on the particulars because I have not done much subclassing of dataframe myself.

However, we should clarify two things:

1. Is this subclassing API officially supported? My impression was that up until now, this has not been the case. We should think carefully about what we can guarantee this and in any case include a warning against using other internal methods. Perhaps we should explicitly label this subclassing API as "experimental" (we reserve the right to break it in the future if necessary).
2. We should encourage using composition instead of inheritance when possible. This is a good opportunity to point out that the Index class, in particular, has a well defined API. For example of using composition with the pandas.Index to enable label based indexing, you could point users to xray.

Nice docs! I agree with the questions raised by @shoyer, although I cannot say much about it myself as I never did some subclassing of dataframes.

But one remark: I don't think this belongs in a FAQ, but that we should start with some 'advanced' section in the docs (together with internals or so)

@sinhrks pls add a mention to try using monkey-patching first if you just want to add a function http://pandas.pydata.org/pandas-docs/stable/faq.html#adding-features-to-your-pandas-installation
maybe put this as the first warning box! (2nd would be the composition/inheritance)

@sinhrks ok as @jorisvandenbossche just mentioned, let's move this to the internals.rst section.

Fixed @jreback 's points, and moved it to internals.rst. And preparing a composition example in separate PR.

@sinhrks lgtm, some minor comments.

I think you can add a release note in enhancements. Trying not to 'advertise' this too much :)

@jreback Thanks, fixed your points, and added a release note.

@sinhrks awesome.

I sent you an invite to change the pandas push permissions. As soon as you accept, pls make this your first PR to merged!

Thanks, let me merge this once after rebased.

@sinhrks awesome!

Did we ever resolve the question of whether the subclassing API is officially guaranteed or not? I suppose the reality is that people are going to subclass whether we tell them it's OK or not.

@shoyer well enough warnings to not encourage it
but u r right people will do it anyways

it's pretty doable nowadays (though imho composition is much more useful)