ENH/DOC: reimplement Series delegates/accessors using descriptors

This PR implements `Series.str`, `Series.dt` and `Series.cat` as descriptors
instead of properties. This means that the API docs can refer to methods like
`Series.str.lower` instead of `StringMethods.lower` and tab-completion like
`Series.str.<tab>` also works, even on the base class.

CC jorisvandenbossche jreback

Author: shoyer

doc/source/whatsnew/v0.16.0.txt

@@ -107,6 +107,8 @@ Enhancements
 
 - ``Timedelta`` will now accept nanoseconds keyword in constructor (:issue:`9273`)
 
+- Added auto-complete for ``Series.str.<tab>``, ``Series.dt.<tab>`` and ``Series.cat.<tab>`` (:issue:`9322`)
+
 Performance
 ~~~~~~~~~~~
 

pandas/core/base.py

@@ -166,6 +166,28 @@ def f(self, *args, **kwargs):
             if not hasattr(cls, name):
                 setattr(cls,name,f)
 
+
+class AccessorProperty(object):
+    """Descriptor for implementing accessor properties like Series.str
+    """
+    def __init__(self, accessor_cls, construct_accessor):
+        self.accessor_cls = accessor_cls
+        self.construct_accessor = construct_accessor
+        self.__doc__ = accessor_cls.__doc__
+
+    def __get__(self, instance, owner=None):
+        if instance is None:
+            # this ensures that Series.str.<method> is well defined
+            return self.accessor_cls
+        return self.construct_accessor(instance)
+
+    def __set__(self, instance, value):
+        raise AttributeError("can't set attribute")
+
+    def __delete__(self, instance):
+        raise AttributeError("can't delete attribute")
+
+
 class FrozenList(PandasObject, list):
 
     """

pandas/core/categorical.py

@@ -829,7 +829,7 @@ def searchsorted(self, v, side='left', sorter=None):
         array([3, 4])	    # eggs before milk
         >>> x = pd.Categorical(['apple', 'bread', 'bread', 'cheese', 'milk', 'donuts' ])
         >>> x.searchsorted(['bread', 'eggs'], side='right', sorter=[0, 1, 2, 3, 5, 4])
-        array([3, 5])       # eggs after donuts, after switching milk and donuts 
+        array([3, 5])       # eggs after donuts, after switching milk and donuts
         """
         if not self.ordered:
             raise ValueError("searchsorted requires an ordered Categorical.")

pandas/core/series.py

@@ -27,7 +27,10 @@
 from pandas.core.indexing import _check_bool_indexer, _maybe_convert_indices
 from pandas.core import generic, base
 from pandas.core.internals import SingleBlockManager
-from pandas.core.categorical import Categorical
+from pandas.core.categorical import Categorical, CategoricalAccessor
+from pandas.core.strings import StringMethods
+from pandas.tseries.common import (maybe_to_datetimelike,
+                                   CombinedDatetimelikeProperties)
 from pandas.tseries.index import DatetimeIndex
 from pandas.tseries.tdi import TimedeltaIndex
 from pandas.tseries.period import PeriodIndex, Period
@@ -2452,11 +2455,6 @@ def asof(self, where):
         new_values = com.take_1d(values, locs)
         return self._constructor(new_values, index=where).__finalize__(self)
 
-    @cache_readonly
-    def str(self):
-        from pandas.core.strings import StringMethods
-        return StringMethods(self)
-
     def to_timestamp(self, freq=None, how='start', copy=True):
         """
         Cast to datetimeindex of timestamps, at *beginning* of period
@@ -2502,27 +2500,35 @@ def to_period(self, freq=None, copy=True):
         return self._constructor(new_values,
                                  index=new_index).__finalize__(self)
 
+    #------------------------------------------------------------------------------
+    # string methods
+
+    def _make_str_accessor(self):
+        return StringMethods(self)
+
+    str = base.AccessorProperty(StringMethods, _make_str_accessor)
+
     #------------------------------------------------------------------------------
     # Datetimelike delegation methods
 
-    @cache_readonly
-    def dt(self):
-        from pandas.tseries.common import maybe_to_datetimelike
+    def _make_dt_accessor(self):
         try:
             return maybe_to_datetimelike(self)
         except (Exception):
             raise TypeError("Can only use .dt accessor with datetimelike values")
 
+    dt = base.AccessorProperty(CombinedDatetimelikeProperties, _make_dt_accessor)
+
     #------------------------------------------------------------------------------
     # Categorical methods
 
-    @cache_readonly
-    def cat(self):
-        from pandas.core.categorical import CategoricalAccessor
+    def _make_cat_accessor(self):
         if not com.is_categorical_dtype(self.dtype):
             raise TypeError("Can only use .cat accessor with a 'category' dtype")
         return CategoricalAccessor(self.values, self.index)
 
+    cat = base.AccessorProperty(CategoricalAccessor, _make_cat_accessor)
+
 Series._setup_axes(['index'], info_axis=0, stat_axis=0,
                    aliases={'rows': 0})
 Series._add_numeric_operations()

pandas/core/strings.py

@@ -2,8 +2,6 @@
 
 from pandas.compat import zip
 from pandas.core.common import isnull, _values_from_object
-from pandas.core.series import Series
-from pandas.core.frame import DataFrame
 import pandas.compat as compat
 import re
 import pandas.lib as lib
@@ -12,6 +10,8 @@
 
 
 def _get_array_list(arr, others):
+    from pandas.core.series import Series
+
     if len(others) and isinstance(_values_from_object(others)[0],
                                   (list, np.ndarray, Series)):
         arrays = [arr] + list(others)
@@ -95,6 +95,8 @@ def _na_map(f, arr, na_result=np.nan, dtype=object):
 
 
 def _map(f, arr, na_mask=False, na_value=np.nan, dtype=object):
+    from pandas.core.series import Series
+
     if not len(arr):
         return np.ndarray(0, dtype=dtype)
 
@@ -459,6 +461,9 @@ def str_extract(arr, pat, flags=0):
     2    NaN   NaN
 
     """
+    from pandas.core.series import Series
+    from pandas.core.frame import DataFrame
+
     regex = re.compile(pat, flags=flags)
     # just to be safe, check this
     if regex.groups == 0:
@@ -510,6 +515,8 @@ def str_get_dummies(arr, sep='|'):
     See also ``pd.get_dummies``.
 
     """
+    from pandas.core.frame import DataFrame
+
     # TODO remove this hack?
     arr = arr.fillna('')
     try:
@@ -643,6 +650,9 @@ def str_split(arr, pat=None, n=None, return_type='series'):
     -------
     split : array
     """
+    from pandas.core.series import Series
+    from pandas.core.frame import DataFrame
+
     if return_type not in ('series', 'frame'):
         raise ValueError("return_type must be {'series', 'frame'}")
     if pat is None:
@@ -949,6 +959,9 @@ def __iter__(self):
             g = self.get(i)
 
     def _wrap_result(self, result):
+        from pandas.core.series import Series
+        from pandas.core.frame import DataFrame
+
         if not hasattr(result, 'ndim'):
             return result
         elif result.ndim == 1:

pandas/tests/test_categorical.py

@@ -909,8 +909,8 @@ def test_searchsorted(self):
         exp = np.array([1])
         self.assert_numpy_array_equal(res, exp)
         self.assert_numpy_array_equal(res, chk)
-       
-        # Searching for a value that is not present in the Categorical 
+
+        # Searching for a value that is not present in the Categorical
         res = c1.searchsorted(['bread', 'eggs'])
         chk = s1.searchsorted(['bread', 'eggs'])
         exp = np.array([1, 4])
@@ -927,7 +927,7 @@ def test_searchsorted(self):
         # As above, but with a sorter array to reorder an unsorted array
         res = c2.searchsorted(['bread', 'eggs'], side='right', sorter=[0, 1, 2, 3, 5, 4])
         chk = s2.searchsorted(['bread', 'eggs'], side='right', sorter=[0, 1, 2, 3, 5, 4])
-        exp = np.array([3, 5])       # eggs after donuts, after switching milk and donuts 
+        exp = np.array([3, 5])       # eggs after donuts, after switching milk and donuts
         self.assert_numpy_array_equal(res, exp)
         self.assert_numpy_array_equal(res, chk)
 
@@ -2516,6 +2516,13 @@ def get_dir(s):
         results = get_dir(s)
         tm.assert_almost_equal(results,list(sorted(set(ok_for_cat))))
 
+    def test_cat_accessor_api(self):
+        # GH 9322
+        from pandas.core.categorical import CategoricalAccessor
+        self.assertIs(Series.cat, CategoricalAccessor)
+        s = Series(list('aabbcde')).astype('category')
+        self.assertIsInstance(s.cat, CategoricalAccessor)
+
     def test_pickle_v0_14_1(self):
         cat = pd.Categorical(values=['a', 'b', 'c'],
                              categories=['a', 'b', 'c', 'd'],

pandas/tests/test_series.py

@@ -231,6 +231,15 @@ def test_valid_dt_with_missing_values(self):
         expected = Series([time(0),time(0),np.nan,time(0),time(0)],dtype='object')
         tm.assert_series_equal(result, expected)
 
+    def test_dt_accessor_api(self):
+        # GH 9322
+        from pandas.tseries.common import (CombinedDatetimelikeProperties,
+                                           DatetimeProperties)
+        self.assertIs(Series.dt, CombinedDatetimelikeProperties)
+
+        s = Series(date_range('2000-01-01', periods=3))
+        self.assertIsInstance(s.dt, DatetimeProperties)
+
     def test_binop_maybe_preserve_name(self):
 
         # names match, preserve

pandas/tests/test_strings.py

@@ -32,8 +32,9 @@ class TestStringMethods(tm.TestCase):
 
     def test_api(self):
 
-        # GH 6106
-        self.assertIsNone(Series.str)
+        # GH 6106, GH 9322
+        self.assertIs(Series.str, strings.StringMethods)
+        self.assertIsInstance(Series(['']).str, strings.StringMethods)
 
     def test_iter(self):
         # GH3638

pandas/tseries/common.py

@@ -3,7 +3,9 @@
 import numpy as np
 from pandas.core.base import PandasDelegate
 from pandas.core import common as com
-from pandas import Series, DatetimeIndex, PeriodIndex, TimedeltaIndex
+from pandas.tseries.index import DatetimeIndex
+from pandas.tseries.period import PeriodIndex
+from pandas.tseries.tdi import TimedeltaIndex
 from pandas import lib, tslib
 from pandas.core.common import (_NS_DTYPE, _TD_DTYPE, is_period_arraylike,
                                 is_datetime_arraylike, is_integer_dtype, is_list_like,
@@ -35,6 +37,7 @@ def maybe_to_datetimelike(data, copy=False):
     DelegatedClass
 
     """
+    from pandas import Series
 
     if not isinstance(data, Series):
         raise TypeError("cannot convert an object of type {0} to a datetimelike index".format(type(data)))
@@ -59,6 +62,8 @@ def __init__(self, values, index):
         self.index = index
 
     def _delegate_property_get(self, name):
+        from pandas import Series
+
         result = getattr(self.values,name)
 
         # maybe need to upcast (ints)
@@ -82,6 +87,8 @@ def _delegate_property_set(self, name, value, *args, **kwargs):
                          "supported. Change values on the original.")
 
     def _delegate_method(self, name, *args, **kwargs):
+        from pandas import Series
+
         method = getattr(self.values, name)
         result = method(*args, **kwargs)
 
@@ -175,6 +182,14 @@ class PeriodProperties(Properties):
                                          accessors=PeriodIndex._datetimelike_ops,
                                          typ='property')
 
+
+class CombinedDatetimelikeProperties(DatetimeProperties, TimedeltaProperties):
+    # This class is never instantiated, and exists solely for the benefit of
+    # the Series.dt class property. For Series objects, .dt will always be one
+    # of the more specific classes above.
+    __doc__ = DatetimeProperties.__doc__
+
+
 def _concat_compat(to_concat, axis=0):
     """
     provide concatenation of an datetimelike array of arrays each of which is a single