Merge branch 'master' of https://github.com/pandas-dev/pandas into tslibs-offsets-years

Author: jbrockmendel

doc/source/whatsnew/v0.21.1.txt

@@ -73,6 +73,7 @@ Conversion
 Indexing
 ^^^^^^^^
 
+- Bug in a boolean comparison of a ``datetime.datetime`` and a ``datetime64[ns]`` dtype Series (:issue:`17965`)
 - Bug where a ``MultiIndex`` with more than a million records was not raising ``AttributeError`` when trying to access a missing attribute (:issue:`18165`)
 -
 -

pandas/_libs/index.pyx

@@ -19,7 +19,7 @@ from hashtable cimport HashTable
 
 from pandas._libs import algos, period as periodlib, hashtable as _hash
 from pandas._libs.tslib import Timestamp, Timedelta
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, date
 
 from cpython cimport PyTuple_Check, PyList_Check
 
@@ -549,7 +549,7 @@ cpdef convert_scalar(ndarray arr, object value):
     if arr.descr.type_num == NPY_DATETIME:
         if isinstance(value, np.ndarray):
             pass
-        elif isinstance(value, datetime):
+        elif isinstance(value, (datetime, np.datetime64, date)):
             return Timestamp(value).value
         elif value is None or value != value:
             return iNaT

pandas/core/frame.py

@@ -4029,15 +4029,30 @@ def combine(self, other, func, fill_value=None, overwrite=True):
         ----------
         other : DataFrame
         func : function
+            Function that takes two series as inputs and return a Series or a
+            scalar
         fill_value : scalar value
         overwrite : boolean, default True
             If True then overwrite values for common keys in the calling frame
 
         Returns
         -------
         result : DataFrame
-        """
 
+        Examples
+        --------
+        >>> df1 = DataFrame({'A': [0, 0], 'B': [4, 4]})
+        >>> df2 = DataFrame({'A': [1, 1], 'B': [3, 3]})
+        >>> df1.combine(df2, lambda s1, s2: s1 if s1.sum() < s2.sum() else s2)
+           A  B
+        0  0  3
+        1  0  3
+
+        See Also
+        --------
+        DataFrame.combine_first : Combine two DataFrame objects and default to
+            non-null values in frame calling the method
+        """
         other_idxlen = len(other.index)  # save for compare
 
         this, other = self.align(other, copy=False)
@@ -4125,16 +4140,24 @@ def combine_first(self, other):
         ----------
         other : DataFrame
 
+        Returns
+        -------
+        combined : DataFrame
+
         Examples
         --------
-        a's values prioritized, use values from b to fill holes:
+        df1's values prioritized, use values from df2 to fill holes:
 
-        >>> a.combine_first(b)
+        >>> df1 = pd.DataFrame([[1, np.nan]])
+        >>> df2 = pd.DataFrame([[3, 4]])
+        >>> df1.combine_first(df2)
+           0    1
+        0  1  4.0
 
-
-        Returns
-        -------
-        combined : DataFrame
+        See Also
+        --------
+        DataFrame.combine : Perform series-wise operation on two DataFrames
+            using a given function
         """
         import pandas.core.computation.expressions as expressions
 

pandas/core/series.py

@@ -1361,13 +1361,13 @@ def idxmax(self, axis=None, skipna=True, *args, **kwargs):
 
     # ndarray compat
     argmin = deprecate('argmin', idxmin,
-                       msg="'argmin' is deprecated. Use 'idxmin' instead. "
+                       msg="'argmin' is deprecated, use 'idxmin' instead. "
                            "The behavior of 'argmin' will be corrected to "
                            "return the positional minimum in the future. "
                            "Use 'series.values.argmin' to get the position of "
                            "the minimum now.")
     argmax = deprecate('argmax', idxmax,
-                       msg="'argmax' is deprecated. Use 'idxmax' instead. "
+                       msg="'argmax' is deprecated, use 'idxmax' instead. "
                            "The behavior of 'argmax' will be corrected to "
                            "return the positional maximum in the future. "
                            "Use 'series.values.argmax' to get the position of "
@@ -1731,11 +1731,26 @@ def combine(self, other, func, fill_value=np.nan):
         ----------
         other : Series or scalar value
         func : function
+            Function that takes two scalars as inputs and return a scalar
         fill_value : scalar value
 
         Returns
         -------
         result : Series
+
+        Examples
+        --------
+        >>> s1 = Series([1, 2])
+        >>> s2 = Series([0, 3])
+        >>> s1.combine(s2, lambda x1, x2: x1 if x1 < x2 else x2)
+        0    0
+        1    2
+        dtype: int64
+
+        See Also
+        --------
+        Series.combine_first : Combine Series values, choosing the calling
+            Series's values first
         """
         if isinstance(other, Series):
             new_index = self.index.union(other.index)
@@ -1764,7 +1779,21 @@ def combine_first(self, other):
 
         Returns
         -------
-        y : Series
+        combined : Series
+
+        Examples
+        --------
+        >>> s1 = pd.Series([1, np.nan])
+        >>> s2 = pd.Series([3, 4])
+        >>> s1.combine_first(s2)
+        0    1.0
+        1    4.0
+        dtype: float64
+
+        See Also
+        --------
+        Series.combine : Perform elementwise operation on two Series
+            using a given function
         """
         new_index = self.index.union(other.index)
         this = self.reindex(new_index, copy=False)

pandas/tests/indexes/datetimes/test_partial_slicing.py

@@ -2,9 +2,10 @@
 
 import pytest
 
-from datetime import datetime
+from datetime import datetime, date
 import numpy as np
 import pandas as pd
+import operator as op
 
 from pandas import (DatetimeIndex, Series, DataFrame,
                     date_range, Index, Timedelta, Timestamp)
@@ -330,3 +331,21 @@ def test_loc_datetime_length_one(self):
 
         result = df.loc['2016-10-01T00:00:00':]
         tm.assert_frame_equal(result, df)
+
+    @pytest.mark.parametrize('datetimelike', [
+        Timestamp('20130101'), datetime(2013, 1, 1),
+        date(2013, 1, 1), np.datetime64('2013-01-01T00:00', 'ns')])
+    @pytest.mark.parametrize('op,expected', [
+        (op.lt, [True, False, False, False]),
+        (op.le, [True, True, False, False]),
+        (op.eq, [False, True, False, False]),
+        (op.gt, [False, False, False, True])])
+    def test_selection_by_datetimelike(self, datetimelike, op, expected):
+        # GH issue #17965, test for ability to compare datetime64[ns] columns
+        # to datetimelike
+        df = DataFrame({'A': [pd.Timestamp('20120101'),
+                              pd.Timestamp('20130101'),
+                              np.nan, pd.Timestamp('20130103')]})
+        result = op(df.A, datetimelike)
+        expected = Series(expected, name='A')
+        tm.assert_series_equal(result, expected)

pandas/util/_decorators.py

@@ -3,7 +3,7 @@
 import inspect
 import types
 import warnings
-from textwrap import dedent
+from textwrap import dedent, wrap
 from functools import wraps, update_wrapper
 
 
@@ -29,11 +29,16 @@ def deprecate(name, alternative, alt_name=None, klass=None,
 
     alt_name = alt_name or alternative.__name__
     klass = klass or FutureWarning
-    msg = msg or "{} is deprecated. Use {} instead".format(name, alt_name)
+    msg = msg or "{} is deprecated, use {} instead".format(name, alt_name)
 
+    @wraps(alternative)
     def wrapper(*args, **kwargs):
         warnings.warn(msg, klass, stacklevel=stacklevel)
         return alternative(*args, **kwargs)
+
+    if getattr(wrapper, '__doc__', None) is not None:
+        wrapper.__doc__ = ('\n'.join(wrap(msg, 70)) + '\n'
+                           + dedent(wrapper.__doc__))
     return wrapper