Skip to content

DOC: Improved the docstring of str.extract() (Delhi) #20141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jul 7, 2018
Merged

DOC: Improved the docstring of str.extract() (Delhi) #20141

Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
effaede
Modified docstring of str.extract
arjunsharma97 Mar 10, 2018
c9f4ac8
Updated docstring of str.extract
arjunsharma97 Mar 10, 2018
3f7aadf
Updated docstring of str.extract
arjunsharma97 Mar 10, 2018
b0ead62
Merge remote-tracking branch 'upstream/master' into strextract
arjunsharma97 Mar 15, 2018
3900c1a
Minor changes to str.extract
arjunsharma97 Mar 15, 2018
2977c41
Merge remote-tracking branch 'upstream/master' into strextract
Jul 7, 2018
ec8bd44
small cleanup
Jul 7, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions pandas/core/strings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -693,21 +693,21 @@ def _str_extract_frame(arr, pat, flags=0):

def str_extract(arr, pat, flags=0, expand=True):
r"""
Return the match object corresponding to regex `pat`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this r before the doc string right?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it is to ensure correct rendering for used \ in the examples

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This description isn't quite right, is it? We aren't returning a Match object.

Maybe

Extract capture groups in the regex `pat` as columns in a DataFrame.


For each subject string in the Series, extract groups from the
first match of regular expression pat.
first match of regular expression `pat`.

Parameters
----------
pat : string
Regular expression pattern with capturing groups
Regular expression pattern with capturing groups.
flags : int, default 0 (no flags)
re module flags, e.g. re.IGNORECASE

``re`` module flags, e.g. ``re.IGNORECASE``.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a llink to https://docs.python.org/3/library/re.html#contents-of-module-re ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this can be done by using :mod:`re`

expand : bool, default True
* If True, return DataFrame.
* If False, return Series/Index/DataFrame.
If True, return DataFrame, else return Series/Index/DataFrame.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When is a DataFrame returned if expand=False?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It still returns a DataFrame when you have multiple groups (only if there is only one group, it gives a Series). Probably good to explain this a bit more.

(I find this a bit strange behaviour, but that's what it currently is. In other case we then return a Series with lists I think)


.. versionadded:: 0.18.0
.. versionadded:: 0.18.0.

Returns
-------
Expand All @@ -728,7 +728,7 @@ def str_extract(arr, pat, flags=0, expand=True):
A pattern with two groups will return a DataFrame with two columns.
Non-matches will be NaN.

>>> s = Series(['a1', 'b2', 'c3'])
>>> s = pd.Series(['a1', 'b2', 'c3'])
>>> s.str.extract(r'([ab])(\d)')
0 1
0 a 1
Expand Down Expand Up @@ -767,7 +767,6 @@ def str_extract(arr, pat, flags=0, expand=True):
1 2
2 NaN
dtype: object

"""
if not isinstance(expand, bool):
raise ValueError("expand must be True or False")
Expand Down