diff --git a/pandas/core/strings.py b/pandas/core/strings.py index 669b19fc35430..ecc8c266b136d 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -2340,47 +2340,82 @@ def rsplit(self, pat=None, n=-1, expand=False): return self._wrap_result(result, expand=expand) _shared_docs['str_partition'] = (""" - Split the string at the %(side)s occurrence of `sep`, and return 3 elements - containing the part before the separator, the separator itself, - and the part after the separator. + Split the string at the %(side)s occurrence of `sep`. + + This method splits the string at the %(side)s occurrence of `sep`, + and returns 3 elements containing the part before the separator, + the separator itself, and the part after the separator. If the separator is not found, return %(return)s. Parameters ---------- - pat : string, default whitespace + pat : str, default whitespace String to split on. expand : bool, default True - * If True, return DataFrame/MultiIndex expanding dimensionality. - * If False, return Series/Index. + If True, return DataFrame/MultiIndex expanding dimensionality. + If False, return Series/Index. Returns ------- - split : DataFrame/MultiIndex or Series/Index of objects + DataFrame/MultiIndex or Series/Index of objects See Also -------- %(also)s + Series.str.split : Split strings around given separators. + str.partition : Standard library version. Examples -------- - >>> s = Series(['A_B_C', 'D_E_F', 'X']) - 0 A_B_C - 1 D_E_F - 2 X + >>> s = pd.Series(['Linda van der Berg', 'George Pitt-Rivers']) + >>> s + 0 Linda van der Berg + 1 George Pitt-Rivers dtype: object - >>> s.str.partition('_') - 0 1 2 - 0 A _ B_C - 1 D _ E_F - 2 X - - >>> s.str.rpartition('_') - 0 1 2 - 0 A_B _ C - 1 D_E _ F - 2 X + >>> s.str.partition() + 0 1 2 + 0 Linda van der Berg + 1 George Pitt-Rivers + + To partition by the last space instead of the first one: + + >>> s.str.rpartition() + 0 1 2 + 0 Linda van der Berg + 1 George Pitt-Rivers + + To partition by something different than a space: + + >>> s.str.partition('-') + 0 1 2 + 0 Linda van der Berg + 1 George Pitt - Rivers + + To return a Series containining tuples instead of a DataFrame: + + >>> s.str.partition('-', expand=False) + 0 (Linda van der Berg, , ) + 1 (George Pitt, -, Rivers) + dtype: object + + Also available on indices: + + >>> idx = pd.Index(['X 123', 'Y 999']) + >>> idx + Index(['X 123', 'Y 999'], dtype='object') + + Which will create a MultiIndex: + + >>> idx.str.partition() + MultiIndex(levels=[['X', 'Y'], [' '], ['123', '999']], + labels=[[0, 1], [0, 0], [0, 1]]) + + Or an index with tuples with ``expand=False``: + + >>> idx.str.partition(expand=False) + Index([('X', ' ', '123'), ('Y', ' ', '999')], dtype='object') """) @Appender(_shared_docs['str_partition'] % {