DOC: add doc-strings to tz_convert/tz_localize in tslib.pyx

TST: more tests, xref pandas-dev#15823, xref pandas-dev#11708

pandas/_libs/tslib.pyx

@@ -1570,7 +1570,7 @@ cpdef convert_str_to_tsobject(object ts, object tz, object unit,
                 if tz is not None:
                     # shift for _localize_tso
                     ts = tz_localize_to_utc(np.array([ts], dtype='i8'), tz,
-                                            ambiguous='raise', 
+                                            ambiguous='raise',
                                             errors='raise')[0]
         except ValueError:
             try:
@@ -4075,7 +4075,23 @@ except:
     have_pytz = False
 
 
+@cython.boundscheck(False)
+@cython.wraparound(False)
 def tz_convert(ndarray[int64_t] vals, object tz1, object tz2):
+    """
+    Convert the values (in i8) from timezone1 to timezone2
+
+    Parameters
+    ----------
+    vals : int64 ndarray
+    tz1 : string / timezone object
+    tz2 : string / timezone object
+
+    Returns
+    -------
+    int64 ndarray of converted
+    """
+
     cdef:
         ndarray[int64_t] utc_dates, tt, result, trans, deltas
         Py_ssize_t i, j, pos, n = len(vals)
@@ -4177,6 +4193,23 @@ def tz_convert(ndarray[int64_t] vals, object tz1, object tz2):
 
 
 def tz_convert_single(int64_t val, object tz1, object tz2):
+    """
+    Convert the val (in i8) from timezone1 to timezone2
+
+    This is a single timezone versoin of tz_convert
+
+    Parameters
+    ----------
+    val : int64
+    tz1 : string / timezone object
+    tz2 : string / timezone object
+
+    Returns
+    -------
+    int64 converted
+
+    """
+
     cdef:
         ndarray[int64_t] trans, deltas
         Py_ssize_t pos
@@ -4376,7 +4409,7 @@ cpdef ndarray _unbox_utcoffsets(object transinfo):
 def tz_localize_to_utc(ndarray[int64_t] vals, object tz, object ambiguous=None,
                        object errors='raise'):
     """
-    Localize tzinfo-naive DateRange to given time zone (using pytz). If
+    Localize tzinfo-naive i8 to given time zone (using pytz). If
     there are ambiguities in the values, raise AmbiguousTimeError.
 
     Returns
@@ -4548,6 +4581,7 @@ def tz_localize_to_utc(ndarray[int64_t] vals, object tz, object ambiguous=None,
 
     return result
 
+
 cdef inline bisect_right_i8(int64_t *data, int64_t val, Py_ssize_t n):
     cdef Py_ssize_t pivot, left = 0, right = n
 

pandas/tests/tseries/test_timezones.py

@@ -1,4 +1,5 @@
 # pylint: disable-msg=E1101,W0612
+import pytest
 import pytz
 import numpy as np
 from distutils.version import LooseVersion
@@ -167,17 +168,43 @@ def test_timestamp_constructor_near_dst_boundary(self):
         for tz in ['Europe/Brussels', 'Europe/Prague']:
             result = Timestamp('2015-10-25 01:00', tz=tz)
             expected = Timestamp('2015-10-25 01:00').tz_localize(tz)
-            self.assertEqual(result, expected)
+            assert result == expected
 
-            with tm.assertRaises(pytz.AmbiguousTimeError):
+            with pytest.raises(pytz.AmbiguousTimeError):
                 Timestamp('2015-10-25 02:00', tz=tz)
 
         result = Timestamp('2017-03-26 01:00', tz='Europe/Paris')
         expected = Timestamp('2017-03-26 01:00').tz_localize('Europe/Paris')
-        self.assertEqual(result, expected)
+        assert result == expected
+
+        with pytest.raises(pytz.NonExistentTimeError):
+            Timestamp('2017-03-26 02:00', tz='Europe/Paris')
+
+        # GH 11708
+        result = to_datetime("2015-11-18 15:30:00+05:30").tz_localize(
+            'UTC').tz_convert('Asia/Kolkata')
+        expected = Timestamp('2015-11-18 15:30:00+0530', tz='Asia/Kolkata')
+        assert result == expected
+
+        # GH 15823
+        result = Timestamp('2017-03-26 00:00', tz='Europe/Paris')
+        expected = Timestamp('2017-03-26 00:00:00+0100', tz='Europe/Paris')
+        assert result == expected
+
+        result = Timestamp('2017-03-26 01:00', tz='Europe/Paris')
+        expected = Timestamp('2017-03-26 01:00:00+0100', tz='Europe/Paris')
+        assert result == expected
 
-        with tm.assertRaises(pytz.NonExistentTimeError):
+        with pytest.raises(pytz.NonExistentTimeError):
             Timestamp('2017-03-26 02:00', tz='Europe/Paris')
+        result = Timestamp('2017-03-26 02:00:00+0100', tz='Europe/Paris')
+        expected = Timestamp(result.value).tz_localize(
+            'UTC').tz_convert('Europe/Paris')
+        assert result == expected
+
+        result = Timestamp('2017-03-26 03:00', tz='Europe/Paris')
+        expected = Timestamp('2017-03-26 03:00:00+0200', tz='Europe/Paris')
+        assert result == expected
 
     def test_timestamp_to_datetime_tzoffset(self):
         # tzoffset