DOC: more complete docs on offsets/frequencies needed

[jorisvandenbossche]

Add these to the API docs:

The contents of pd.tseries.offsets.__all__

['Day',
 'BusinessDay',
 'BDay',
 'CustomBusinessDay',
 'CDay',
 'CBMonthEnd',
 'CBMonthBegin',
 'MonthBegin',
 'BMonthBegin',
 'MonthEnd',
 'BMonthEnd',
 'SemiMonthEnd',
 'SemiMonthBegin',
 'BusinessHour',
 'CustomBusinessHour',
 'YearBegin',
 'BYearBegin',
 'YearEnd',
 'BYearEnd',
 'QuarterBegin',
 'BQuarterBegin',
 'QuarterEnd',
 'BQuarterEnd',
 'LastWeekOfMonth',
 'FY5253Quarter',
 'FY5253',
 'Week',
 'WeekOfMonth',
 'Easter',
 'Hour',
 'Minute',
 'Second',
 'Milli',
 'Micro',
 'Nano',
 'DateOffset']

and pd.tseries.api.infer_freq

---

From mailingslist (https://groups.google.com/forum/?fromgroups#!topic/pydata/66lTrtgev7A), eg frequencies.is_super/subperiod are missing in the docs (both in user guide as in api docs)

A lot of the functions/objects in pandas.tseries.offsets and pandas.tseries.frequencies are not included in the API docs, or mentioned in the timeseries.rst docs.
Furthermore, the difference between both submodules is not fully clear to me (eg the offsets objects like BDay are available in both)

[jreback]

frequencies is effectively internal (except to_offset) and deals with freq inference. offsets is public and exposes the actual Offset objects. (the offsets e.g. Day/Second/etc are merely imported into the top-level namespace of frequencies for convinence).

[jorisvandenbossche]

But the is_superperiod function you noted in the mailing list is from frequencies, so not public?

[jreback]

not sure, they could be made public, see https://github.com/pydata/pandas/blob/master/pandas/tseries/api.py but I think they in reality should prob be methods of the offset objects themselves (easy to do, just add into DateOffset which everything inherits), then Second().is_superperiod(Minute()) -> False

but not really sure what these are actually used

[jorisvandenbossche]

Hmm, never used pandas.tseries.api, and this is also nowhere used in the docs (update: ok, this is used to import in the toplevel namespace, but all offsets are in the docs always imported from the offsets submodule).
Let this then be an issue about: clear out what we see as public api regarding offsets-related things, and then also document this.

[TomAugspurger]

I think most of the public API has been decided.

The TODO here is to add the contents of pd.tseries.offsets.__all__

['Day',
 'BusinessDay',
 'BDay',
 'CustomBusinessDay',
 'CDay',
 'CBMonthEnd',
 'CBMonthBegin',
 'MonthBegin',
 'BMonthBegin',
 'MonthEnd',
 'BMonthEnd',
 'SemiMonthEnd',
 'SemiMonthBegin',
 'BusinessHour',
 'CustomBusinessHour',
 'YearBegin',
 'BYearBegin',
 'YearEnd',
 'BYearEnd',
 'QuarterBegin',
 'BQuarterBegin',
 'QuarterEnd',
 'BQuarterEnd',
 'LastWeekOfMonth',
 'FY5253Quarter',
 'FY5253',
 'Week',
 'WeekOfMonth',
 'Easter',
 'Hour',
 'Minute',
 'Second',
 'Milli',
 'Micro',
 'Nano',
 'DateOffset']

and pd.tseries.api.infer_freq