Skip to content

DOC: update .str.contains/match/startswith docstring examples for default behaviour #61960

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 1 commit into from
Jul 28, 2025
+15 −45
Merged

DOC: update .str.contains/match/startswith docstring examples for default behaviour #61960

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
60 changes: 15 additions & 45 deletions pandas/core/strings/accessor.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1242,9 +1242,9 @@ def contains(
Flags to pass through to the re module, e.g. re.IGNORECASE.
na : scalar, optional
Fill value for missing values. The default depends on dtype of the
array. For object-dtype, ``numpy.nan`` is used. For the nullable
``StringDtype``, ``pandas.NA`` is used. For the ``"str"`` dtype,
``False`` is used.
array. For the ``"str"`` dtype, ``False`` is used. For object
dtype, ``numpy.nan`` is used. For the nullable ``StringDtype``,
``pandas.NA`` is used.
Comment on lines -1245 to +1247
Copy link
Member Author

Choose a reason for hiding this comment

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

Here I am just changing the order to list the default str dtype first

regex : bool, default True
If True, assumes the pat is a regular expression.
Expand Down Expand Up @@ -1293,18 +1293,6 @@ def contains(
4 False
dtype: bool
Specifying `na` to be `False` instead of `NaN` replaces NaN values
with `False`. If Series or Index does not contain NaN values
the resultant dtype will be `bool`, otherwise, an `object` dtype.
>>> s1.str.contains("og", na=False, regex=True)
0 False
1 True
2 False
3 False
4 False
dtype: bool
Returning 'house' or 'dog' when either expression occurs in a string.
>>> s1.str.contains("house|dog", regex=True)
Expand Down Expand Up @@ -1381,9 +1369,9 @@ def match(self, pat: str, case: bool = True, flags: int = 0, na=lib.no_default):
Regex module flags, e.g. re.IGNORECASE.
na : scalar, optional
Fill value for missing values. The default depends on dtype of the
array. For object-dtype, ``numpy.nan`` is used. For the nullable
``StringDtype``, ``pandas.NA`` is used. For the ``"str"`` dtype,
``False`` is used.
array. For the ``"str"`` dtype, ``False`` is used. For object
dtype, ``numpy.nan`` is used. For the nullable ``StringDtype``,
``pandas.NA`` is used.
Returns
-------
Expand Down Expand Up @@ -1431,9 +1419,9 @@ def fullmatch(self, pat, case: bool = True, flags: int = 0, na=lib.no_default):
Regex module flags, e.g. re.IGNORECASE.
na : scalar, optional
Fill value for missing values. The default depends on dtype of the
array. For object-dtype, ``numpy.nan`` is used. For the nullable
``StringDtype``, ``pandas.NA`` is used. For the ``"str"`` dtype,
``False`` is used.
array. For the ``"str"`` dtype, ``False`` is used. For object
dtype, ``numpy.nan`` is used. For the nullable ``StringDtype``,
``pandas.NA`` is used.
Returns
-------
Expand Down Expand Up @@ -2671,9 +2659,9 @@ def startswith(
accepted.
na : scalar, optional
Object shown if element tested is not a string. The default depends
on dtype of the array. For object-dtype, ``numpy.nan`` is used.
For the nullable ``StringDtype``, ``pandas.NA`` is used.
For the ``"str"`` dtype, ``False`` is used.
on dtype of the array. For the ``"str"`` dtype, ``False`` is used.
For object dtype, ``numpy.nan`` is used. For the nullable
``StringDtype``, ``pandas.NA`` is used.
Returns
-------
Expand Down Expand Up @@ -2710,15 +2698,6 @@ def startswith(
2 False
3 False
dtype: bool
Specifying `na` to be `False` instead of `NaN`.
>>> s.str.startswith("b", na=False)
0 True
1 False
2 False
3 False
dtype: bool
"""
if not isinstance(pat, (str, tuple)):
msg = f"expected a string or tuple, not {type(pat).__name__}"
Expand All @@ -2742,9 +2721,9 @@ def endswith(
accepted.
na : scalar, optional
Object shown if element tested is not a string. The default depends
on dtype of the array. For object-dtype, ``numpy.nan`` is used.
For the nullable ``StringDtype``, ``pandas.NA`` is used.
For the ``"str"`` dtype, ``False`` is used.
on dtype of the array. For the ``"str"`` dtype, ``False`` is used.
For object dtype, ``numpy.nan`` is used. For the nullable
``StringDtype``, ``pandas.NA`` is used.
Returns
-------
Expand Down Expand Up @@ -2781,15 +2760,6 @@ def endswith(
2 True
3 False
dtype: bool
Specifying `na` to be `False` instead of `NaN`.
>>> s.str.endswith("t", na=False)
0 True
1 False
2 False
3 False
dtype: bool
"""
if not isinstance(pat, (str, tuple)):
msg = f"expected a string or tuple, not {type(pat).__name__}"
Expand Down
Loading