Repository: pandas-dev/pandas
Pull request: DOC: Test doctests in pandas/core/tools/datetimes.py 
- [x] closes #26401
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Problem statement:
Test doctests in pandas/core/tools/datetimes.py
#### Code Sample, a copy-pastable example if possible

Doctests in `to_datetime()`.

#### Problem description

It is being failed as below:

```
Failed example:
    df = pd.DataFrame({'year': [2015, 2016],
Exception raised:
    Traceback (most recent call last):
      File "/Applications/PyCharm.app/Contents/helpers/pycharm/docrunner.py", line 140, in __run
        compileflags, 1), test.globs)
      File "<doctest to_datetime[0]>", line 1
        df = pd.DataFrame({'year': [2015, 2016],
                                               ^
    SyntaxError: unexpected EOF while parsing
```

```
Failed example:
    pd.to_datetime([1, 2, 3], unit='D',
                   origin=pd.Timestamp('1960-01-01'))
Expected:
    0    1960-01-02
    1    1960-01-03
    2    1960-01-04
Got:
    DatetimeIndex(['1960-01-02', '1960-01-03', '1960-01-04'], dtype='datetime64[ns]', freq=None)
```

```
Failed example:
    %timeit pd.to_datetime(s,infer_datetime_format=False)
Exception raised:
    Traceback (most recent call last):
      File "/Applications/PyCharm.app/Contents/helpers/pycharm/docrunner.py", line 140, in __run
        compileflags, 1), test.globs)
      File "<doctest to_datetime[7]>", line 1
        %timeit pd.to_datetime(s,infer_datetime_format=False)
        ^
    SyntaxError: invalid syntax
```

#### Expected Output

#### Output of ``pd.show_versions()``

<details>

INSTALLED VERSIONS
------------------
commit: None
python: 3.7.3.final.0
python-bits: 64
OS: Darwin
OS-release: 18.5.0
machine: x86_64
processor: i386
byteorder: little
LC_ALL: None
LANG: en_US.UTF-8
LOCALE: en_US.UTF-8

pandas: 0.24.2
pytest: 4.4.1
pip: 19.0.3
setuptools: 40.8.0
Cython: None
numpy: 1.16.2
scipy: None
pyarrow: 0.13.0
xarray: None
IPython: None
sphinx: 2.0.1
patsy: None
dateutil: 2.8.0
pytz: 2019.1
blosc: None
bottleneck: None
tables: None
numexpr: None
feather: None
matplotlib: None
openpyxl: None
xlrd: None
xlwt: None
xlsxwriter: None
lxml.etree: None
bs4: None
html5lib: None
sqlalchemy: None
pymysql: None
psycopg2: None
jinja2: 2.10.1
s3fs: None
fastparquet: None
pandas_gbq: None
pandas_datareader: None
gcsfs: None

</details>

Hints from issue discussion:

Commit message: Test doctests in pandas/core/tools/datetimes.py

Patch to review:
diff --git a/ci/code_checks.sh b/ci/code_checks.sh
index 6d8e03d0896ae..3d1ec637ae202 100755
--- a/ci/code_checks.sh
+++ b/ci/code_checks.sh
@@ -239,6 +239,10 @@ if [[ -z "$CHECK" || "$CHECK" == "doctests" ]]; then
     pytest -q --doctest-modules pandas/core/groupby/groupby.py -k"-cumcount -describe -pipe"
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
+    MSG='Doctests datetimes.py' ; echo $MSG
+    pytest -q --doctest-modules pandas/core/tools/datetimes.py
+    RET=$(($RET + $?)) ; echo $MSG "DONE"
+
     MSG='Doctests top-level reshaping functions' ; echo $MSG
     pytest -q --doctest-modules \
         pandas/core/reshape/concat.py \
diff --git a/pandas/core/tools/datetimes.py b/pandas/core/tools/datetimes.py
index 0b0916026cd30..375e27ee0b461 100644
--- a/pandas/core/tools/datetimes.py
+++ b/pandas/core/tools/datetimes.py
@@ -525,8 +525,8 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     'ms', 'us', 'ns']) or plurals of the same
 
     >>> df = pd.DataFrame({'year': [2015, 2016],
-                           'month': [2, 3],
-                           'day': [4, 5]})
+    ...                    'month': [2, 3],
+    ...                    'day': [4, 5]})
     >>> pd.to_datetime(df)
     0   2015-02-04
     1   2016-03-05
@@ -548,8 +548,7 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     Passing infer_datetime_format=True can often-times speedup a parsing
     if its not an ISO8601 format exactly, but in a regular format.
 
-    >>> s = pd.Series(['3/11/2000', '3/12/2000', '3/13/2000']*1000)
-
+    >>> s = pd.Series(['3/11/2000', '3/12/2000', '3/13/2000'] * 1000)
     >>> s.head()
     0    3/11/2000
     1    3/12/2000
@@ -558,11 +557,16 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     4    3/12/2000
     dtype: object
 
-    >>> %timeit pd.to_datetime(s,infer_datetime_format=True)
-    100 loops, best of 3: 10.4 ms per loop
+    >>> import timeit
+    >>> timeit.timeit(
+    ...    lambda: pd.to_datetime(s, infer_datetime_format=True),
+    ...    number = 1)  # doctest: +SKIP
+    0.007785393000000029
 
-    >>> %timeit pd.to_datetime(s,infer_datetime_format=False)
-    1 loop, best of 3: 471 ms per loop
+    >>> timeit.timeit(
+    ...    lambda: pd.to_datetime(s, infer_datetime_format=False),
+    ...    number = 1)  # doctest: +SKIP
+    0.21016200499999993
 
     Using a unix epoch time
 
@@ -577,10 +581,9 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     Using a non-unix epoch origin
 
     >>> pd.to_datetime([1, 2, 3], unit='D',
-                       origin=pd.Timestamp('1960-01-01'))
-    0    1960-01-02
-    1    1960-01-03
-    2    1960-01-04
+    ...                origin=pd.Timestamp('1960-01-01'))
+    DatetimeIndex(['1960-01-02', '1960-01-03', '1960-01-04'], \
+dtype='datetime64[ns]', freq=None)
     """
     if arg is None:
         return None


Code review comments:
diff_hunk: @@ -558,11 +557,16 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     4    3/12/2000
     dtype: object
 
-    >>> %timeit pd.to_datetime(s,infer_datetime_format=True)
-    100 loops, best of 3: 10.4 ms per loop
+    >>> import timeit
+    >>> timeit.timeit(
+    ...    lambda: pd.to_datetime(s, infer_datetime_format=True),
+    ...    number = 1)  # doctest: +SKIP
+    0.007785393000000029
 
-    >>> %timeit pd.to_datetime(s,infer_datetime_format=False)
-    1 loop, best of 3: 471 ms per loop
+    >>> timeit.timeit(
path: pandas/core/tools/datetimes.py
text: @user1:
I think I personally prefer to keep the `%timeit` (which is easier to use / better practice IMO). 
Another option is to add a `# doctest: +SKIP` flag for those two

@author:
Yea .. I prefer that too but `%timeit` is specific to IPython ....

@user1:
Yes, but I think we can be opinionated about that. Maybe add a note between brackets before the example that the following only works in IPython?)

@author:
okie!

@author:
Actually, let me just don't add the note and revert it back with `# doctest: +SKIP`. I am sure people would know `%timeit` is for IPython ..