diff --git a/pandas/core/strings/accessor.py b/pandas/core/strings/accessor.py index 935b124ca446a..abd380299ba02 100644 --- a/pandas/core/strings/accessor.py +++ b/pandas/core/strings/accessor.py @@ -659,8 +659,8 @@ def cat( Parameters ---------- - pat : str or compiled regex, optional - String or regular expression to split on. + pat : str%(pat_regex)s, optional + %(pat_description)s. If not specified, split on whitespace. n : int, default -1 (all) Limit number of splits in output. @@ -670,28 +670,12 @@ def cat( - If ``True``, return DataFrame/MultiIndex expanding dimensionality. - If ``False``, return Series/Index, containing lists of strings. - - regex : bool, default None - Determines if the passed-in pattern is a regular expression: - - - If ``True``, assumes the passed-in pattern is a regular expression - - If ``False``, treats the pattern as a literal string. - - If ``None`` and `pat` length is 1, treats `pat` as a literal string. - - If ``None`` and `pat` length is not 1, treats `pat` as a regular expression. - - Cannot be set to False if `pat` is a compiled regex - - .. versionadded:: 1.4.0 - + %(regex_argument)s Returns ------- Series, Index, DataFrame or MultiIndex Type matches caller unless ``expand=True`` (see Notes). - - Raises - ------ - ValueError - * if `regex` is False and `pat` is a compiled regex - + %(raises_split)s See Also -------- Series.str.split : Split strings around given separator/delimiter. @@ -713,10 +697,7 @@ def cat( If using ``expand=True``, Series and Index callers return DataFrame and MultiIndex objects, respectively. - - Use of `regex=False` with a `pat` as a compiled regex will raise - an error. - + %(regex_pat_note)s Examples -------- >>> s = pd.Series( @@ -790,7 +771,37 @@ def cat( 0 this is a regular sentence None 1 https://docs.python.org/3/tutorial index.html 2 NaN NaN + %(regex_examples)s""" + + @Appender( + _shared_docs["str_split"] + % { + "side": "beginning", + "pat_regex": " or compiled regex", + "pat_description": "String or regular expression to split on", + "regex_argument": """ + regex : bool, default None + Determines if the passed-in pattern is a regular expression: + + - If ``True``, assumes the passed-in pattern is a regular expression + - If ``False``, treats the pattern as a literal string. + - If ``None`` and `pat` length is 1, treats `pat` as a literal string. + - If ``None`` and `pat` length is not 1, treats `pat` as a regular expression. + - Cannot be set to False if `pat` is a compiled regex + .. versionadded:: 1.4.0 + """, + "raises_split": """ + Raises + ------ + ValueError + * if `regex` is False and `pat` is a compiled regex + """, + "regex_pat_note": """ + Use of `regex =False` with a `pat` as a compiled regex will raise an error. + """, + "method": "split", + "regex_examples": r""" Remember to escape special characters when explicitly using regular expressions. >>> s = pd.Series(["foo and bar plus baz"]) @@ -829,9 +840,9 @@ def cat( >>> s.str.split(r"\.jpg", regex=False, expand=True) 0 0 foojpgbar.jpg - """ - - @Appender(_shared_docs["str_split"] % {"side": "beginning", "method": "split"}) + """, + } + ) @forbid_nonstring_types(["bytes"]) def split( self, @@ -850,7 +861,19 @@ def split( result = self._data.array._str_split(pat, n, expand, regex) return self._wrap_result(result, returns_string=expand, expand=expand) - @Appender(_shared_docs["str_split"] % {"side": "end", "method": "rsplit"}) + @Appender( + _shared_docs["str_split"] + % { + "side": "end", + "pat_regex": "", + "pat_description": "String to split on", + "regex_argument": "", + "raises_split": "", + "regex_pat_note": "", + "method": "rsplit", + "regex_examples": "", + } + ) @forbid_nonstring_types(["bytes"]) def rsplit(self, pat=None, n=-1, expand=False): result = self._data.array._str_rsplit(pat, n=n)