jreback review and misc changes

addressed jreback's review, cleaned up docstrings, added documention, update to interval_range endpoint fix, additional tests

Author: jschendel

doc/source/timeseries.rst

@@ -1705,6 +1705,15 @@ has multiplied span.
 
    pd.PeriodIndex(start='2014-01', freq='3M', periods=4)
 
+If ``start`` or ``end`` are ``Period`` objects, they will be used as anchor
+endpoints for a ``PeriodIndex`` with frequency matching that of the
+``PeriodIndex`` constructor.
+
+.. ipython:: python
+
+   pd.PeriodIndex(start=pd.Period('2017Q1', freq='Q'),
+                  end=pd.Period('2017Q2', freq='Q'), freq='M')
+
 Just like ``DatetimeIndex``, a ``PeriodIndex`` can also be used to index pandas
 objects:
 

pandas/core/indexes/datetimes.py

@@ -292,8 +292,8 @@ def __new__(cls, data=None,
             if is_float(periods):
                 periods = int(periods)
             elif not is_integer(periods):
-                raise ValueError('Periods must be a number, got %s' %
-                                 str(periods))
+                msg = 'periods must be a number, got {periods}'
+                raise ValueError(msg.format(periods=periods))
 
         if data is None and freq is None:
             raise ValueError("Must provide freq argument if no data is "
@@ -412,7 +412,7 @@ def __new__(cls, data=None,
     def _generate(cls, start, end, periods, name, offset,
                   tz=None, normalize=False, ambiguous='raise', closed=None):
         if com._count_not_none(start, end, periods) != 2:
-            raise ValueError('Of the three parameters, start, end, and '
+            raise ValueError('Of the three parameters: start, end, and '
                              'periods, exactly two must be specified')
 
         _normalized = True
@@ -2005,7 +2005,7 @@ def _generate_regular_range(start, end, periods, offset):
 def date_range(start=None, end=None, periods=None, freq='D', tz=None,
                normalize=False, name=None, closed=None, **kwargs):
     """
-    Return a fixed frequency datetime index, with day (calendar) as the default
+    Return a fixed frequency DatetimeIndex, with day (calendar) as the default
     frequency
 
     Parameters
@@ -2014,24 +2014,24 @@ def date_range(start=None, end=None, periods=None, freq='D', tz=None,
         Left bound for generating dates
     end : string or datetime-like, default None
         Right bound for generating dates
-    periods : integer or None, default None
-        If None, must specify start and end
+    periods : integer, default None
+        Number of dates to generate
     freq : string or DateOffset, default 'D' (calendar daily)
         Frequency strings can have multiples, e.g. '5H'
-    tz : string or None
+    tz : string, default None
         Time zone name for returning localized DatetimeIndex, for example
         Asia/Hong_Kong
     normalize : bool, default False
         Normalize start/end dates to midnight before generating date range
-    name : str, default None
-        Name of the resulting index
-    closed : string or None, default None
+    name : string, default None
+        Name of the resulting DatetimeIndex
+    closed : string, default None
         Make the interval closed with respect to the given frequency to
         the 'left', 'right', or both sides (None)
 
     Notes
     -----
-    Of the three parameters, ``start``, ``end``, and ``periods``, exactly two
+    Of the three parameters: ``start``, ``end``, and ``periods``, exactly two
     must be specified.
 
     To learn more about the frequency strings, please see `this link
@@ -2049,7 +2049,7 @@ def date_range(start=None, end=None, periods=None, freq='D', tz=None,
 def bdate_range(start=None, end=None, periods=None, freq='B', tz=None,
                 normalize=True, name=None, closed=None, **kwargs):
     """
-    Return a fixed frequency datetime index, with business day as the default
+    Return a fixed frequency DatetimeIndex, with business day as the default
     frequency
 
     Parameters
@@ -2058,24 +2058,24 @@ def bdate_range(start=None, end=None, periods=None, freq='B', tz=None,
         Left bound for generating dates
     end : string or datetime-like, default None
         Right bound for generating dates
-    periods : integer or None, default None
-        If None, must specify start and end
+    periods : integer, default None
+        Number of dates to generate
     freq : string or DateOffset, default 'B' (business daily)
-        Frequency strings can have multiples, e.g. '5H'
+        Frequency strings can have multiples, e.g. '5, default
     tz : string or None
         Time zone name for returning localized DatetimeIndex, for example
         Asia/Beijing
     normalize : bool, default False
         Normalize start/end dates to midnight before generating date range
-    name : str, default None
-        Name for the resulting index
-    closed : string or None, default None
+    name : string, default None
+        Name of the resulting DatetimeIndex
+    closed : string, default None
         Make the interval closed with respect to the given frequency to
         the 'left', 'right', or both sides (None)
 
     Notes
     -----
-    Of the three parameters, ``start``, ``end``, and ``periods``, exactly two
+    Of the three parameters: ``start``, ``end``, and ``periods``, exactly two
     must be specified.
 
     To learn more about the frequency strings, please see `this link
@@ -2094,7 +2094,7 @@ def bdate_range(start=None, end=None, periods=None, freq='B', tz=None,
 def cdate_range(start=None, end=None, periods=None, freq='C', tz=None,
                 normalize=True, name=None, closed=None, **kwargs):
     """
-    **EXPERIMENTAL** Return a fixed frequency datetime index, with
+    **EXPERIMENTAL** Return a fixed frequency DatetimeIndex, with
     CustomBusinessDay as the default frequency
 
     .. warning:: EXPERIMENTAL
@@ -2108,29 +2108,29 @@ def cdate_range(start=None, end=None, periods=None, freq='C', tz=None,
         Left bound for generating dates
     end : string or datetime-like, default None
         Right bound for generating dates
-    periods : integer or None, default None
-        If None, must specify start and end
+    periods : integer, default None
+        Number of dates to generate
     freq : string or DateOffset, default 'C' (CustomBusinessDay)
         Frequency strings can have multiples, e.g. '5H'
-    tz : string or None
+    tz : string, default None
         Time zone name for returning localized DatetimeIndex, for example
         Asia/Beijing
     normalize : bool, default False
         Normalize start/end dates to midnight before generating date range
-    name : str, default None
-        Name for the resulting index
-    weekmask : str, Default 'Mon Tue Wed Thu Fri'
+    name : string, default None
+        Name of the resulting DatetimeIndex
+    weekmask : string, Default 'Mon Tue Wed Thu Fri'
         weekmask of valid business days, passed to ``numpy.busdaycalendar``
     holidays : list
         list/array of dates to exclude from the set of valid business days,
         passed to ``numpy.busdaycalendar``
-    closed : string or None, default None
+    closed : string, default None
         Make the interval closed with respect to the given frequency to
         the 'left', 'right', or both sides (None)
 
     Notes
     -----
-    Of the three parameters, ``start``, ``end``, and ``periods``, exactly two
+    Of the three parameters: ``start``, ``end``, and ``periods``, exactly two
     must be specified.
 
     To learn more about the frequency strings, please see `this link

pandas/core/indexes/interval.py

@@ -15,6 +15,7 @@
     is_float_dtype,
     is_interval_dtype,
     is_scalar,
+    is_float,
     is_integer)
 from pandas.core.indexes.base import (
     Index, _ensure_index,
@@ -1028,48 +1029,61 @@ def func(self, other):
 IntervalIndex._add_logical_methods_disabled()
 
 
-def interval_range(start=None, end=None, freq=None, periods=None,
+def interval_range(start=None, end=None, periods=None, freq=None,
                    name=None, closed='right', **kwargs):
     """
     Return a fixed frequency IntervalIndex
 
     Parameters
     ----------
-    start : string or datetime-like, default None
-        Left bound for generating data
-    end : string or datetime-like, default None
-        Right bound for generating data
-    freq : integer, string or DateOffset, default 1
+    start : numeric, string, or datetime-like, default None
+        Left bound for generating intervals
+    end : numeric, string, or datetime-like, default None
+        Right bound for generating intervals
     periods : integer, default None
-    name : str, default None
-        Name of the resulting index
+        Number of intervals to generate
+    freq : numeric, string, or DateOffset, default 1
+        The length of each interval. Must be consistent with the
+        type of start and end
+    name : string, default None
+        Name of the resulting IntervalIndex
     closed : string, default 'right'
         options are: 'left', 'right', 'both', 'neither'
 
     Notes
     -----
-    Of the three parameters, ``start``, ``end``, and ``periods``, exactly two
+    Of the three parameters: ``start``, ``end``, and ``periods``, exactly two
     must be specified.
 
     Returns
     -------
     rng : IntervalIndex
     """
     if com._count_not_none(start, end, periods) != 2:
-        raise ValueError('Of the three parameters, start, end, and periods, '
+        raise ValueError('Of the three parameters: start, end, and periods, '
                          'exactly two must be specified')
 
+    # must all be same units or None
+    arr = np.array(list(com._not_none(start, end, freq)))
+    if is_object_dtype(arr):
+        raise ValueError("start, end, freq need to be the same type")
+
     if freq is None:
         freq = 1
+
+    if periods is None:
+        periods = int((end - start) // freq)
+    elif is_float(periods):
+        periods = int(periods)
+    elif not is_integer(periods):
+        msg = 'periods must be a number, got {periods}'
+        raise ValueError(msg.format(periods=periods))
+
     if start is None:
         start = end - periods * freq
-    if end is None:
-        end = start + periods * freq
 
-    # must all be same units or None
-    arr = np.array([start, end, freq])
-    if is_object_dtype(arr):
-        raise ValueError("start, end, freq need to be the same type")
+    # force end to be consistent with freq (truncate if freq skips over end)
+    end = start + periods * freq
 
-    return IntervalIndex.from_breaks(np.arange(start, end + 1, freq),
+    return IntervalIndex.from_breaks(np.arange(start, end + freq, freq),
                                      name=name, closed=closed, **kwargs)

pandas/core/indexes/period.py

@@ -199,8 +199,8 @@ def __new__(cls, data=None, ordinal=None, freq=None, start=None, end=None,
             if is_float(periods):
                 periods = int(periods)
             elif not is_integer(periods):
-                raise ValueError('Periods must be a number, got %s' %
-                                 str(periods))
+                msg = 'periods must be a number, got {periods}'
+                raise ValueError(msg.format(periods=periods))
 
         if name is None and hasattr(data, 'name'):
             name = data.name
@@ -1052,7 +1052,7 @@ def tz_localize(self, tz, infer_dst=False):
 
 def _get_ordinal_range(start, end, periods, freq, mult=1):
     if com._count_not_none(start, end, periods) != 2:
-        raise ValueError('Of the three parameters, start, end, and periods, '
+        raise ValueError('Of the three parameters: start, end, and periods, '
                          'exactly two must be specified')
 
     if freq is not None:
@@ -1067,9 +1067,9 @@ def _get_ordinal_range(start, end, periods, freq, mult=1):
     is_end_per = isinstance(end, Period)
 
     if is_start_per and is_end_per and start.freq != end.freq:
-        raise ValueError('Start and end must have same freq')
+        raise ValueError('start and end must have same freq')
     if (start is tslib.NaT or end is tslib.NaT):
-        raise ValueError('Start and end must not be NaT')
+        raise ValueError('start and end must not be NaT')
 
     if freq is None:
         if is_start_per:
@@ -1158,23 +1158,25 @@ def pnow(freq=None):
 
 def period_range(start=None, end=None, periods=None, freq='D', name=None):
     """
-    Return a fixed frequency datetime index, with day (calendar) as the default
+    Return a fixed frequency PeriodIndex, with day (calendar) as the default
     frequency
 
     Parameters
     ----------
-    start : starting value, period-like, optional
-    end : ending value, period-like, optional
-    periods : int, default None
-        Number of periods in the index
-    freq : str/DateOffset, default 'D'
+    start : string or period-like, default None
+        Left bound for generating periods
+    end : string or period-like, default None
+        Right bound for generating periods
+    periods : integer, default None
+        Number of periods to generate
+    freq : string or DateOffset, default 'D' (calendar daily)
         Frequency alias
-    name : str, default None
-        Name for the resulting PeriodIndex
+    name : string, default None
+        Name of the resulting PeriodIndex
 
     Notes
     -----
-    Of the three parameters, ``start``, ``end``, and ``periods``, exactly two
+    Of the three parameters: ``start``, ``end``, and ``periods``, exactly two
     must be specified.
 
     To learn more about the frequency strings, please see `this link
@@ -1183,9 +1185,27 @@ def period_range(start=None, end=None, periods=None, freq='D', name=None):
     Returns
     -------
     prng : PeriodIndex
+
+    Examples
+    --------
+
+    >>> pd.period_range(start='2017-01-01', end='2018-01-01', freq='M')
+    PeriodIndex(['2017-01', '2017-02', '2017-03', '2017-04', '2017-05',
+                 '2017-06', '2017-06', '2017-07', '2017-08', '2017-09',
+                 '2017-10', '2017-11', '2017-12', '2018-01'],
+                dtype='period[M]', freq='M')
+
+    If ``start`` or ``end`` are ``Period`` objects, they will be used as anchor
+    endpoints for a ``PeriodIndex`` with frequency matching that of the
+    ``period_range`` constructor.
+
+    >>> pd.period_range(start=pd.Period('2017Q1', freq='Q'),
+    ...                 end=pd.Period('2017Q2', freq='Q'), freq='M')
+    PeriodIndex(['2017-03', '2017-04', '2017-05', '2017-06'],
+                dtype='period[M]', freq='M')
     """
     if com._count_not_none(start, end, periods) != 2:
-        raise ValueError('Of the three parameters, start, end, and periods, '
+        raise ValueError('Of the three parameters: start, end, and periods, '
                          'exactly two must be specified')
 
     return PeriodIndex(start=start, end=end, periods=periods,