Skip to content

Commit f5a2b35

Browse files
committed
Merge pull request #3859 from hayd/DOC_add_to_datetime
DOC add to_datetime to api.rst
2 parents e9a5e01 + e5078a6 commit f5a2b35

File tree

2 files changed

+74
-1
lines changed

2 files changed

+74
-1
lines changed

doc/source/api.rst

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ Data manipulations
126126
merge
127127
concat
128128

129-
Top-level Missing Data
129+
Top-level missing data
130130
~~~~~~~~~~~~~~~~~~~~~~
131131

132132
.. currentmodule:: pandas.core.common
@@ -137,6 +137,17 @@ Top-level Missing Data
137137
isnull
138138
notnull
139139

140+
Top-level dealing with datetimes
141+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142+
143+
.. currentmodule:: pandas.tseries.tools
144+
145+
.. autosummary::
146+
:toctree: generated/
147+
148+
to_datetime
149+
150+
140151
Standard moving window functions
141152
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142153

doc/source/timeseries.rst

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,68 @@ scalar values and ``PeriodIndex`` for sequences of spans. Better support for
110110
irregular intervals with arbitrary start and end points are forth-coming in
111111
future releases.
112112

113+
114+
.. _timeseries.converting:
115+
116+
Converting to Timestamps
117+
------------------------
118+
119+
To convert a Series or list-like object of date-like objects e.g. strings,
120+
epochs, or a mixture, you can use the ``to_datetime`` function. When passed
121+
a Series, this returns a Series (with the same index), while a list-like
122+
is converted to a DatetimeIndex:
123+
124+
.. ipython:: python
125+
126+
to_datetime(Series(['Jul 31, 2009', '2010-01-10', None]))
127+
128+
to_datetime(['2005/11/23', '2010.12.31'])
129+
130+
If you use dates which start with the day first (i.e. European style),
131+
you can pass the ``dayfirst`` flag:
132+
133+
.. ipython:: python
134+
135+
to_datetime(['04-01-2012 10:00'], dayfirst=True)
136+
137+
to_datetime(['14-01-2012', '01-14-2012'], dayfirst=True)
138+
139+
.. warning::
140+
141+
You see in the above example that ``dayfirst`` isn't strict, so if a date
142+
can't be parsed with the day being first it will be parsed as if
143+
``dayfirst`` were False.
144+
145+
146+
Pass ``coerce=True`` to convert bad data to ``NaT`` (not a time):
147+
148+
.. ipython:: python
149+
150+
to_datetime(['2009-07-31', 'asd'])
151+
152+
to_datetime(['2009-07-31', 'asd'], coerce=True)
153+
154+
It's also possible to convert integer or float epoch times. The default unit
155+
for these is nanoseconds (since these are how Timestamps are stored). However,
156+
often epochs are stored in another ``unit`` which can be specified:
157+
158+
159+
.. ipython:: python
160+
161+
to_datetime([1])
162+
163+
to_datetime([1, 3.14], unit='s')
164+
165+
.. note::
166+
167+
Epoch times will be rounded to the nearest nanosecond.
168+
169+
Take care, ``to_datetime`` may not act as you expect on mixed data:
170+
171+
.. ipython:: python
172+
173+
pd.to_datetime([1, '1'])
174+
113175
.. _timeseries.daterange:
114176

115177
Generating Ranges of Timestamps

0 commit comments

Comments
 (0)