Repository: pandas-dev/pandas
Pull request: ERR: FutureWarning difficult to identify source
- [x] closes #26329
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [n/a ] whatsnew entry


Problem statement:
FutureWarning difficult to identify source
This is a suggestion, not a bug. The following resulted in a `FutureWarning`

    df = df.assign(block=(df.index.to_series().diff() != pd.Timedelta(15,'m')).cumsum())

> FutureWarning: The default of the 'keep_tz' keyword will change to True in a future release. You can set 'keep_tz=True' to obtain the future behaviour and silence this warning.

It wasn't in any way obvious why since the warning doesn't mention the method name and there's no stack trace (and futures warnings are only printed once). I had to search the source (which was also difficult as the message was split to maintain a character limit per line).

It would be nice if future warnings were more explicit, i.e. name the class and method as well as the argument. 

(In this case it's the `to_series()` method, which ideally wouldn't be required but `DateTimeIndex` doesn't yet implement diff())

Hints from issue discussion:
FYI, you can use the warnings module to elevate warnings to errors so that you get a traceback:

```pytb
In [14]: warnings.simplefilter('error', FutureWarning)

In [15]: pd.date_range(2000, periods=4, tz='utc').to_series()
---------------------------------------------------------------------------
FutureWarning                             Traceback (most recent call last)
<ipython-input-15-0d004c39654b> in <module>
----> 1 pd.date_range(2000, periods=4, tz='utc').to_series()

~/Envs/dask-dev/lib/python3.7/site-packages/pandas/core/indexes/datetimes.py in to_series(self, keep_tz, index, name)
    725                           "to True in a future release. You can set "
    726                           "'keep_tz=True' to obtain the future behaviour and "
--> 727                           "silence this warning.", FutureWarning, stacklevel=2)
    728             keep_tz = False
    729         elif keep_tz is False:

FutureWarning: The default of the 'keep_tz' keyword will change to True in a future release. You can set 'keep_tz=True' to obtain the future behaviour and silence this warning.
```

Changing the message to note something like

    The default of the 'keep_tz' keyword in DatetimeIndex.to_series ...

seems OK. Are you likely to work on this?

Commit message: FutureWarning difficult to identify source

Patch to review:
diff --git a/doc/source/whatsnew/v0.25.0.rst b/doc/source/whatsnew/v0.25.0.rst
index d38ee7b8b589a..a980d2238750f 100644
--- a/doc/source/whatsnew/v0.25.0.rst
+++ b/doc/source/whatsnew/v0.25.0.rst
@@ -332,6 +332,7 @@ Timezones
 - Bug in :func:`to_datetime` where an uninformative ``RuntimeError`` was raised when passing a naive :class:`Timestamp` with datetime strings with mixed UTC offsets (:issue:`25978`)
 - Bug in :func:`to_datetime` with ``unit='ns'`` would drop timezone information from the parsed argument (:issue:`26168`)
 - Bug in :func:`DataFrame.join` where joining a timezone aware index with a timezone aware column would result in a column of ``NaN`` (:issue:`26335`)
+- FutureWarning message raised by :func:`DatetimeIndex.to_series` updated to identify source of warning (:issue:`26329`)
 
 Numeric
 ^^^^^^^
diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py
index 6b9806f4d32f5..9c735a5598f4a 100644
--- a/pandas/core/indexes/datetimes.py
+++ b/pandas/core/indexes/datetimes.py
@@ -689,7 +689,8 @@ def to_series(self, keep_tz=None, index=None, name=None):
             name = self.name
 
         if keep_tz is None and self.tz is not None:
-            warnings.warn("The default of the 'keep_tz' keyword will change "
+            warnings.warn("The default of the 'keep_tz' keyword in "
+                          "DatetimeIndex.to_series will change "
                           "to True in a future release. You can set "
                           "'keep_tz=True' to obtain the future behaviour and "
                           "silence this warning.", FutureWarning, stacklevel=2)
diff --git a/pandas/tests/frame/test_alter_axes.py b/pandas/tests/frame/test_alter_axes.py
index fe347d36d88e7..ab0f17fb4ff13 100644
--- a/pandas/tests/frame/test_alter_axes.py
+++ b/pandas/tests/frame/test_alter_axes.py
@@ -460,9 +460,13 @@ def test_convert_dti_to_series(self):
                       name='B')
         tm.assert_series_equal(result, comp)
 
-        with tm.assert_produces_warning(FutureWarning):
+        with tm.assert_produces_warning(FutureWarning) as m:
             result = idx.to_series(index=[0, 1])
         tm.assert_series_equal(result, expected.dt.tz_convert(None))
+        msg = ("The default of the 'keep_tz' keyword in "
+               "DatetimeIndex.to_series will change to True in a future "
+               "release.")
+        assert msg in str(m[0].message)
 
         with tm.assert_produces_warning(FutureWarning):
             result = idx.to_series(keep_tz=False, index=[0, 1])


Code review comments:
diff_hunk: @@ -332,6 +332,7 @@ Timezones
 - Bug in :func:`to_datetime` where an uninformative ``RuntimeError`` was raised when passing a naive :class:`Timestamp` with datetime strings with mixed UTC offsets (:issue:`25978`)
 - Bug in :func:`to_datetime` with ``unit='ns'`` would drop timezone information from the parsed argument (:issue:`26168`)
 - Bug in :func:`DataFrame.join` where joining a timezone aware index with a timezone aware column would result in a column of ``NaN`` (:issue:`26335`)
+- FutureWarning message raised by :func:`DatetimeIndex.to_series` updated to identify source of warning (:issue:`26329`)
path: doc/source/whatsnew/v0.25.0.rst
text: @user1:
don't need a note for this

@user2:
Meta-question: with review requests like this, is it better to just merge? I also thought that the note was unnecessary, but the "harm" of this note is small. Maybe better to just merge, and reduce CI burden / risk of a merge conflict coming up?

@user1:
i don’t think the ci burden is relevant here
we are pretty fast now adays
and better to fix things even small typos on the first go
as once things are merged it is almost impossible to see that something is amiss