Misc cleanups

* docstring on PeriodArray * examples for period_array * remove _box_values_as_index * names * object_dtype * use __sub__
pandas-dev · jreback · Oct 25, 2018 · Sep 26, 2018 · Sep 27, 2018 · Sep 27, 2018
commit a094b3df8307855c8ecefae2f12822a41c5919e0
diff --git a/pandas/core/arrays/period.py b/pandas/core/arrays/period.py
@@ -114,12 +114,27 @@ class PeriodArray(dtl.DatetimeLikeArrayMixin, ExtensionArray):
 
     Users should use :func:`period_array` to create new instances.
 
+    Parameters
+    ----------
+    values : Union[PeriodArray, Series[period], ndarary[int], PeriodIndex
+        The data to store. These should be arrays that can be directly
+        converted to ordinals without inference or copy (PeriodArray,
+        ndarray[int64]), or a box around such an array (Series[period],
+        PeriodIndex).
+    freq : str or DateOffset
+        The `freq` to use for the array. Mostly applicable when `values`
+        is an ndarray of integers, when `freq` is required. When `values`
+        is a PeriodArray (or box around), it's checked that ``values.freq``
+        matches `freq`.
+    copy : bool, default False
+        Whether to copy the ordinals before storing.
+
     Notes
     -----
     There are two components to a PeriodArray
 
     - ordinals : integer ndarray
-    - freq : pd.tseries.offsets.Tick
+    - freq : pd.tseries.offsets.Offset
 
     The values are physically stored as a 1-D ndarray of integers. These are
     called "ordinals" and represent some kind of offset from a base.
@@ -149,7 +164,6 @@ class PeriodArray(dtl.DatetimeLikeArrayMixin, ExtensionArray):
     # --------------------------------------------------------------------
     # Constructors
     def __init__(self, values, freq=None, copy=False):
-        # type: (Union[PeriodArray, np.ndarray], Union[str, Tick]) -> None
         if isinstance(values, ABCSeries):
             values = values._values
             if not isinstance(values, type(self)):
@@ -317,6 +331,11 @@ def __setitem__(
             value  # type: Union[NaTType, Period, Sequence[Period]]
         ):
         # type: (...) -> None
+        # n.b. the type on `value` is a bit too restrictive.
+        # we also accept a sequence of stuff coercible to a PeriodArray
+        # by period_array, which includes things like ndarray[object],
+        # ndarray[datetime64ns]. I think ndarray[int] / ndarray[str] won't
+        # work, since the freq can't be inferred.
         if is_list_like(value):
             if len(key) != len(value) and not com.is_bool_indexer(key):
                 msg = ("shape mismatch: value array of length '{}' does not "
@@ -903,6 +922,19 @@ def period_array(data, freq=None, ordinal=None, copy=False):
     <PeriodArray>
     ['2017', '2018', 'NaT']
     Length: 3, dtype: period[A-DEC]
+
+    Integers that look like years are handled
+
+    >>> period_array([2000, 2001, 2002], freq='D')
+    ['2000-01-01', '2001-01-01', '2002-01-01']
+    Length: 3, dtype: period[D]
+
+    Datetime-like strings may also be passed
+
+    >>> period_array(['2000-Q1', '2000-Q2', '2000-Q3', '2000-Q4'], freq='Q')
+    <PeriodArray>
+    ['2000Q1', '2000Q2', '2000Q3', '2000Q4']
+    Length: 4, dtype: period[Q-DEC]
     """
 
     if data is None and ordinal is None:

diff --git a/pandas/core/indexes/period.py b/pandas/core/indexes/period.py
@@ -64,8 +64,8 @@ def _new_PeriodIndex(cls, **d):
     values = d.pop('data')
     if values.dtype == 'int64':
         freq = d.pop('freq', None)
-        data = PeriodArray(values, freq=freq)
-        return cls._simple_new(data, **d)
+        values = PeriodArray(values, freq=freq)
+        return cls._simple_new(values, **d)
     else:
         return cls(values, **d)
 
@@ -537,14 +537,6 @@ def asof_locs(self, where, mask):
 
         return result
 
-    def _box_values_as_index(self):
-        """
-        return object Index which contains boxed values
-        """
-        # TODO(DatetimeArray): remove
-        # Have to add our name.
-        return Index(self.values, name=self.name)
-
     @Appender(_index_shared_docs['astype'])
     def astype(self, dtype, copy=True, how='start'):
         dtype = pandas_dtype(dtype)

diff --git a/pandas/core/series.py b/pandas/core/series.py
@@ -4358,7 +4358,7 @@ def _try_cast(arr, take_fast_path):
                 data = np.array(data, dtype=dtype, copy=False)
             subarr = np.array(data, dtype=object, copy=copy)
 
-    if subarr.dtype == 'object' and dtype != 'object':
+    if is_object_dtype(subarr.dtype) and dtype != 'object':
         inferred = lib.infer_dtype(subarr)
         if inferred == 'period':
             try:

diff --git a/pandas/tests/extension/test_period.py b/pandas/tests/extension/test_period.py
@@ -120,6 +120,12 @@ def test_add_series_with_extension_array(self, data):
     def test_error(self):
         pass
 
+    def test_direct_arith_with_series_returns_not_implemented(self, data):
+        # Override to use __sub__ instead of __add__
+        other = pd.Series(data)
+        result = data.__sub__(other)
+        assert result is NotImplemented
+
 
 class TestCasting(BasePeriodTests, base.BaseCastingTests):
     pass