ENH: Add StringMethods.partition and rpartition

[sinhrks]

Derived from #9111.

[jorisvandenbossche]

What do you think of having return_type defaults to 'frame'? (I know in str.split the default is 'series', but that is for back compatibility)

[shoyer]

+1 for defaulting to return a frame.

[sinhrks]

OK, changed default to 'frame'.

[jreback]

lgtm, but not sure when would use partition over split

[jorisvandenbossche]

partition will always give three items back (only split on first or last occurence of separator) I think?

@sinhrks maybe add some examples to the docstring, and put a 'see also' to split explaining the difference. (+ a see also the the other (r)partition)

[sinhrks]

Added docstrings (examples and see also). partition is more specific than split, may useful when want to retain separators.

[jorisvandenbossche]

Small detail, but can you put a point . at the end of this sentence (as in html, the line breaks are not preserved, so the following If series, ... comes directly behind this, so without punctuation it looks strange

[sinhrks]

@jorisvandenbossche Thanks, fixed your points.

About return type, I'll prepare separate PR for existing funcs which is also incorrect.

[sinhrks]

Hmm, StringMethods docstrings are mostly derived from corresponding module level functions, and there are 2 policies:

1. Describe the return type when called via StringMethods (describe what user will see)
   • https://github.com/pydata/pandas/blob/master/pandas/core/strings.py#L396
2. Describe the return type of the module level function (what the module level function returns)
   • https://github.com/pydata/pandas/blob/master/pandas/core/strings.py#L541

First policy looks preferable, so OK to change all the descriptions like first one? I understand that these module level functions are not public.

[jorisvandenbossche]

Yes, there is no real good solution to have it correct for both (unless starting with templating, but then the purpose of having a visual docstring you can correctly see in the source code for the module level functions is a bit lost). So I would say: most important that user sees the correct info, so I would indeed go with the first one.

[jorisvandenbossche]

@sinhrks or, maybe what we could also do is this: replace the array with Series, and leave the module level function docstrings as is.
Eg for the example of str_findall: have a .replace('matches : array', 'matches : Series') on the docstring

BTW: it is not that there is a different policy in the docstrings apparently. Eg the str_extract you linked to is really returning already a Series/DataFrame. So it is just that the str_ functions have different return types.

[sinhrks]

Separate docstring issue to #9843 as we have to fix other methods, and also consider #9667.

[jorisvandenbossche]

@sinhrks can you update this with expand=True/false instead of return_type? (see discussion in #9870)

[sinhrks]

OK, fixed this. And posting the behavior of expand in #9870.

[jreback]

looks fine. needs a rebase.

[jorisvandenbossche]

Can you add a . at the end of the sentence.

Or make it a list:

* If true ..
* If false ..

[sinhrks]

@jreback @jorisvandenbossche Thanks, fixed your points. Pls check again.

[jorisvandenbossche]

Looks good!