DOC: Clarify 'public-ish' API for packages using pandas. (original) (raw)

I've been contributing a little bit to GeoPandas / working on some of my own custom code using pandas that I want to share with others and I realized that I wasn't sure what is and is not part of the public API for pandas.

Here's what I have in my head:

Definitely public:

• anything in pandas toplevel namespace (except for modules imported into that namespace)
• non-_ classmethods on NDFrame
• DateOffsets (in that they have a set interface), but not necessarily direct use of get_offset and friends

Somewhat public:

• Subset of Index methods:
  • Definitely union, intersection, difference, levels, labels, names (and the set methods for them)
  • Somewhat: get_indexer, get_indexer_non_unique, groupby, get_loc, slice_locs, equals, identical, values property
  • Not public: is_, is_unique, lexsort properties on MI
• get_offset and DateOffset subclasses

Nice to make public right now:

• compat module (useful to provide this for modules that depend on pandas...at least in terms of guaranteeing that whatever's in the namespace now will go through a deprecation period).
• test utils (otherwise have to reinvent the wheel)
• cache_readonly decorator

Internal methods/properties that subclasses may rely on/manipulate:

• __finalize__
• _metadata property
• _constructor, _constructor_sliced
• _internal_names (maybe - weird behavior with __setattr__ if you don't do this)
• _reset_cache, _update_inplace, possibly _maybe_update_cacher

Things we could consider making public in the future:

• many of the is_* methods in core/common.

Am I missing anything here? Does this make sense?