U
|
¬ý°d¶® ã @ sN d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dl m
|
Z
|
m Z m Z m Z mZmZmZmZmZ d dlZd dlZd dlmZmZ d d lmZmZm Z m Z m Z m Z m Z m!Z!m"Z"m#Z$ d d
|
l%m&Z& d d l'm(Z(m)Z) d d l*m+Z+ d d l,m-Z-m.Z.m/Z/m0Z0 d dl1m2Z2 d dl3m4Z4m5Z5m6Z6m7Z7m8Z8m9Z9m:Z:m;Z;m<Z< d dl=m>Z>m?Z? d dl@mAZA d dlBmCZCmDZDmEZE d dlFmGZG d dlHmIZI d dlJmKZK d dlLmMZMmNZNmOZO d dlPmQZQ d dlRmSZS d dlTmUZU e
|
rêd dlVmWZW d dlXmYZY d d lZm[Z[m\Z\ ee ee-f Z]ee^e_f Z`ee`ef Zaeeae]f Zbee e` ee`d f e-f ZcG d d d ed d!ZdG d"d# d#edd$d!Zeeeed%f Zfd&Zgdzd'd(d)d*d+Zhd{d-d.d/d0d1d2d3Zid-d(d0d4d5d6d7d8Zjd|d9d0d:d;d<d=d>Zkd}d?d5d@d;dAdBdCZldDd0d;dEdFdGZmd~d(d:d0d(dId'd'd0dJdKdLZnd0dMd0dMd;dNdOdPZod0dMd;dQdRdSZpdTdU ZqeddVdId0d0d0d(d0d(d0d0dWdX dYdZZredd[dId0d0d0d(d0d(d0d0d5dX d\dZZredd]dId0d0d0d(d0d(d0d0d^dX d_dZZrdHd$d$d$dejsdejsd`d f
|
dadId0d0d0d(dbd(dcdMd0ddde dfdZZrdgdgdhdhdididjdjdkdkdldldmdmdmdndndndodododpZtdId0dqdrdsZudtdMdudvdwdxZvdyd3dZgZwdS )é )Ú annotations)Úabc)Údatetime)Úpartial)Úislice) Ú TYPE_CHECKINGÚCallableÚHashableÚListÚTupleÚ TypedDictÚUnionÚcastÚoverloadN)ÚlibÚtslib)
|
ÚOutOfBoundsDatetimeÚ TimedeltaÚ TimestampÚastype_overflowsafeÚget_unit_from_dtypeÚiNaTÚis_supported_unitÚ nat_stringsÚparsingÚ timezones)Úprecision_from_unit)ÚDateParseErrorÚguess_datetime_format)Úarray_strptime)Ú AnyArrayLikeÚ ArrayLikeÚDateTimeErrorChoicesÚnpt)Úfind_stack_level) Ú ensure_objectÚis_datetime64_dtypeÚis_datetime64tz_dtypeÚis_floatÚ
|
is_integerÚis_integer_dtypeÚ is_list_likeÚis_numeric_dtypeÚ is_scalar)Ú ABCDataFrameÚ ABCSeries)Únotna)Ú DatetimeArrayÚ IntegerArrayÚ PandasArray)Ú
|
algorithms)Úunique)ÚExtensionArray)Úmaybe_convert_dtypeÚobjects_to_datetime64nsÚ tz_to_dtype)Ú extract_array)ÚIndex)Ú DatetimeIndex)ÚNaTType)Ú UnitChoices)Ú DataFrameÚSeries.c @ s& e Zd ZU ded< ded< ded< dS )ÚYearMonthDayDictÚDatetimeDictArgÚyearÚmonthÚdayN©Ú__name__Ú
|
__module__Ú __qualname__Ú__annotations__© rK rK úRd:\z\workplace\vscode\pyvenv\venv\Lib\site-packages\pandas/core/tools/datetimes.pyrA k s
|
rA T)Útotalc @ sV e Zd ZU ded< ded< ded< ded< ded< ded< ded< ded < ded
|
< d S ) ÚFulldatetimeDictrB ÚhourÚhoursÚminuteÚminutesÚsecondÚsecondsÚmsÚusÚnsNrF rK rK rK rL rN q s
|
rN Fr? é2 z bool | Nonez
|
str | None)ÚdayfirstÚreturnc C sn t | ¡ }dkrjt| | }tkrjt||d}|d k r>|S t | |d d
¡dkrjtjdtt d d S )Néÿÿÿÿ©rY é zªCould not infer format, so each element will be parsed individually, falling back to `dateutil`. To ensure parsing is consistent and as-expected, please specify a format.©Ú
|
stacklevel) r Úfirst_non_nullÚtypeÚstrr ÚwarningsÚwarnÚ UserWarningr$ )ÚarrrY r` Zfirst_non_nan_elementZguessed_formatrK rK rL Ú _guess_datetime_format_for_array s ÿûrg çffffffæ?ÚArrayConvertibleÚfloatz
|
int | NoneÚbool)ÚargÚ unique_shareÚ check_countrZ c C sÊ d}|dkr<t | tkr dS t | dkr6t | d }qjd}n.d| krTt | ks^n td|dkrjdS d| k r~d k sn td
|
ztt| |}W n tk
|
r° Y dS X t ||| krÆd}|S ) a
|
Decides whether to do caching.
|
|
If the percent of unique elements among `check_count` elements less
|
than `unique_share * 100` then we can do caching.
|
|
Parameters
|
----------
|
arg: listlike, tuple, 1-d array, Series
|
unique_share: float, default=0.7, optional
|
0 < unique_share < 1
|
check_count: int, optional
|
0 <= check_count <= len(arg)
|
|
Returns
|
-------
|
do_caching: bool
|
|
Notes
|
-----
|
By default for a sequence of less than 50 items in size, we don't do
|
caching; for the number of elements less than 5000, we take ten percent of
|
all elements to check for a uniqueness share; if the sequence size is more
|
than 5000, then we check only the first 500 elements.
|
All constants were chosen empirically by.
|
TNFi é
|
iô r z1check_count must be in next bounds: [0; len(arg)]r] z+unique_share must be in next bounds: (0; 1))ÚlenÚstart_caching_atÚAssertionErrorÚsetr Ú TypeError)rl rm rn Z
|
do_cachingZunique_elementsrK rK rL Ú should_cache s0 ÿÿ
|
þ ru r r@ )rl ÚformatÚcacheÚconvert_listlikerZ c C s ddl m} |td}|rt| s&|S t| }t|t| k r|||}z|||dd}W n tk
|
rr | Y S X |jjs||j ¡ }|S )aÉ
|
Create a cache of unique dates from an array of dates
|
|
Parameters
|
----------
|
arg : listlike, tuple, 1-d array, Series
|
format : string
|
Strftime format to parse time
|
cache : bool
|
True attempts to create a cache of converted values
|
convert_listlike : function
|
Conversion function to apply on dates
|
|
Returns
|
-------
|
cache_array : Series
|
Cache of converted, unique dates. Can be empty
|
r ©r@ ©ÚdtypeF)ÚindexÚcopy)
|
Úpandasr@ Úobjectru r5 rp r r| Ú is_uniqueZ
|
duplicated)rl rv rw rx r@ Ú cache_arrayZ unique_datesZ cache_datesrK rK rL Ú _maybe_cache× s
|
|
|
r r! r r; )Údt_arrayÚutcÚnamerZ c C s2 t | r"|rdnd}t| ||dS t| || jdS )a
|
Properly boxes the ndarray of datetimes to DatetimeIndex
|
if it is possible or to generic Index instead
|
|
Parameters
|
----------
|
dt_array: 1-d array
|
Array of datetimes to be wrapped in an Index.
|
utc : bool
|
Whether to convert/localize timestamps to UTC.
|
name : string, default None
|
Name for a resulting index
|
|
Returns
|
-------
|
result : datetime of converted dates
|
- DatetimeIndex if convertible to sole datetime64 type
|
- general Index otherwise
|
r N©Útzr
)r
r{ )r& r< r; r{ )r r r
r rK rK rL Ú_box_as_indexlike s r Ú DatetimeScalarOrArrayConvertiblezHashable | None)rl r r
rZ c C s2 ddl m} || |jjd |¡}t|jd|dS )a
|
Convert array of dates with a cache and wrap the result in an Index.
|
|
Parameters
|
----------
|
arg : integer, float, string, datetime, list, tuple, 1-d array, Series
|
cache_array : Series
|
Cache of converted, unique dates
|
name : string, default None
|
Name for a DatetimeIndex
|
|
Returns
|
-------
|
result : Index-like of converted dates
|
r ry rz F©r r
)r~ r@ r| r{ Úmapr Ú_values)rl r r
r@ ÚresultrK rK rL Ú_convert_and_box_cache# s r z
|
np.ndarray)r r rZ c C sr t jt| td}t|D ]J}||k}t| | |¡}|r\|jdkrR| d¡}n
|
| d¡}|||< qt ||dS )aÊ
|
Return results from array_strptime if a %z or %Z directive was passed.
|
|
Parameters
|
----------
|
result : ndarray[int64]
|
int64 date representations of the dates
|
timezones : ndarray
|
pytz timezone objects
|
utc : bool
|
Whether to convert/localize timestamps to UTC.
|
name : string, default None
|
Name for a DatetimeIndex
|
|
Returns
|
-------
|
tz_result : Index-like of parsed dates with timezone
|
rz Nr ©r
)
|
ÚnpÚemptyrp r r5 r1 Ú tz_localizeÚtzinfoÚ
|
tz_convertr; )r r r r
Z
|
tz_resultsÚzoneÚmaskÚdtarK rK rL Ú _return_parsed_timezone_results= s
|
|
|
r Úraiser" )rv r
r ÚunitÚerrorsrY Ú yearfirstÚexactc C sR t | ttfr tj| dd} nt | tr2t | ¡} t| dd} |rFdnd}
|
t| rt | tt fsnt | |
|
|dS |r|
|
d¡ d¡} | S t | ròt tj| } tt| sÄtt | ¡t d¡|dkd } t | tt fsàt | |
|
|dS |rî| d¡S | S |dk r |dk rtd
|
t| ||||S t| d d d kr8td z t| dt |
|
¡d\} } W nj tk
|
r¾ |dkrtjdgdd t| ¡} t | |d Y S |dkr¸t| |d} | Y S Y nX t | } |dkrÞt | |d}|dk r|dkrt | |||||S t | ||||dd\}}|dk rDt|t |d}t j!||dS t"|||dS )a
|
Helper function for to_datetime. Performs the conversions of 1D listlike
|
of dates
|
|
Parameters
|
----------
|
arg : list, tuple, ndarray, Series, Index
|
date to be parsed
|
name : object
|
None or string for the Index name
|
utc : bool
|
Whether to convert/localize timestamps to UTC.
|
unit : str
|
None or string of the frequency of the passed data
|
errors : str
|
error handing behaviors from to_datetime, 'raise', 'coerce', 'ignore'
|
dayfirst : bool
|
dayfirst parsing behavior from to_datetime
|
yearfirst : bool
|
yearfirst parsing behavior from to_datetime
|
exact : bool, default True
|
exact format matching behavior from to_datetime
|
|
Returns
|
-------
|
Index-like of parsed dates
|
ÚOrz r{ Nr r zM8[s]Úcoerce)Z is_coercez#cannot specify both format and unitÚndimr] zAarg must be a string, datetime, list, tuple, 1-d array, or SeriesF)r} r ÚNaTzdatetime64[ns]r Úignorer\ ÚmixedT)rY r r r Z allow_objectr )#Ú
|
isinstanceÚlistÚtupler Úarrayr3 Úgetattrr' r1 r< r r r& r r{ r r r ÚasarrayÚ
|
ValueErrorÚ_to_datetime_with_unitrt r7 Ú libtimezonesZ maybe_get_tzÚrepeatrp r; r% rg Ú _array_strptime_with_fallbackr8 r9 Z _simple_newr )rl rv r
r r r rY r r Z arg_dtyper Ú_ZnpvaluesÚidxr Ú tz_parsedr rK rK rL Ú_convert_listlike_datetimes` sx &
|
|
ü
|
|
|
ÿ
|
|
|
ú
|
|
r² rb )r Úfmtr r rZ c C sD t | ||||d\}}tdd |D r6t||||S t|||dS )zL
|
Call array_strptime, with fallback behavior depending on 'errors'.
|
)r r r c s s | ]}|d k V qd S ©NrK )Ú.0r rK rK rL Ú <genexpr>å s z0_array_strptime_with_fallback.<locals>.<genexpr>r )r Úanyr r )rl r
r r³ r r r r rK rK rL r® Ù s r® )r r rZ c C s
|
t | dd} t| tr0| d| d¡}d}nht | ¡} | jjdkr´| jd| ddd}zt|t d ¡dd}W n8 t k
|
r¬ |d
|
kr | t
|
¡} t | |||| Y S X d}nä| jjd krvt |\}}t | ¡| tkB } | | jd dd}
|
d |
|
| < |
|
tjjk ¡ s |
|
tjjk ¡ rR|d
|
krB| t
|
¡} t | ||||S t d| d|
|
jd dd}t dd¡|| < d}n"| jt
|
dd} tj| ||d\}}|dkr²tj||d} n t||d} t| tsÎ| S | d¡ |¡} |r| j dkrü| d¡} n
|
| d¡} | S )zF
|
to_datetime specalized to the case where a 'unit' is passed.
|
T)Z extract_numpyz datetime64[ú]N)ÚiÚuF©r} úM8[ns]r ÚfZf8r z cannot convert input with unit 'ú'r¡ rW ©r r¢ r ÚUTCr ) r: r¤ r2 Úastyper r© r{ Úkindr r r r« r Úisnanr r ÚminÚ_valuer· ÚmaxZ
|
datetime64r Zarray_with_unit_to_datetimer; Z _with_inferr< r r r ) rl r r
r r rf r± Zmultr¯ r Zfvaluesr rK rK rL r« ë sV
|
|
|
|
ÿ
|
|
|
|
r« c
|
C sÐ |dkr¬| }t d ¡ }|dkr(tdz | | } W n, tk
|
r` } ztd|W 5 d}~X Y nX t j ¡ | }t j ¡ | }t | |k¡st | |k ¡r¨t| dn t | rÄt
|
| sèt | sèt t | ¡sètd| d | d
|
zt ||d }W nj tk
|
r. } ztd | d |W 5 d}~X Y n6 tk
|
rb } ztd | d|W 5 d}~X Y nX |jdk rtd| d|t d } | td|d }
|
t| rÄt| tttjfsÄt | ¡} | |
|
} | S )a
|
Helper function for to_datetime.
|
Adjust input argument to the specified origin
|
|
Parameters
|
----------
|
arg : list, tuple, ndarray, Series, Index
|
date to be adjusted
|
origin : 'julian' or Timestamp
|
origin offset for the arg
|
unit : str
|
passed unit from to_datetime, must be 'D'
|
|
Returns
|
-------
|
ndarray or scalar of adjusted date(s)
|
Zjulianr ÚDz$unit must be 'D' for origin='julian'z3incompatible 'arg' type for given 'origin'='julian'Nz% is Out of Bounds for origin='julian'r¾ z!' is not compatible with origin='z+'; it must be numeric with a unit specified)r zorigin z is Out of Boundsz# cannot be converted to a Timestampzorigin offset z must be tz-naiver] )r Zto_julian_daterª rt rÆ rÄ r r· r r- r) r( r, r© r r r+ r¤ r/ r; Úndarray) rl Úoriginr ÚoriginalZj0ÚerrZj_maxZj_minÚoffsetZ td_offsetZioffsetrK rK rL Ú_adjust_to_origin3 s` ÿþ ÿÿÿÿ þÿ"
|
ÿþ
|
rÍ ÚDatetimeScalarr ) rl r rY r r rv r r Úinfer_datetime_formatrw rZ c C s d S r´ rK © rl r rY r r rv r r rÏ rÉ rw rK rK rL Ú to_datetime| s rÑ zSeries | DictConvertiblec C s d S r´ rK rÐ rK rK rL rÑ s z list | tuple | Index | ArrayLiker< c C s d S r´ rK rÐ rK rK rL rÑ s Úunixz2DatetimeScalarOrArrayConvertible | DictConvertiblezbool | lib.NoDefaultzlib.NoDefault | boolz8DatetimeIndex | Series | DatetimeScalar | NaTType | None) rl r rY r r rv r r rÏ rÉ rw rZ c C s& |t jk r|dkrtd|t jk r4tjdt d | dkr@dS | dkrTt| | |} tt||||||d} t | t
|
r | } |r| j dk r| d¡} n
|
| d¡} nt | trît| ||
|
| } | jsÊ| | ¡} n | | j|}| j|| j| jd } n4t | ttjfrt| ||} nt | trVt| ||
|
| } | jsDt| | | jd
|
} n| | || jd
|
} nÌt | rêz.t t t t t!t"j#d tf | }t|||
|
| } W n: t$k
|
rÈ |d kr¬ d dl%m&} |g t'd} Y nX | jsÞt|| } n
|
| ||} n8| t" (| g¡|d } t | t)r"t | t"j*r"t)| } | S )uÙ5
|
Convert argument to datetime.
|
|
This function converts a scalar, array-like, :class:`Series` or
|
:class:`DataFrame`/dict-like to a pandas datetime object.
|
|
Parameters
|
----------
|
arg : int, float, str, datetime, list, tuple, 1-d array, Series, DataFrame/dict-like
|
The object to convert to a datetime. If a :class:`DataFrame` is provided, the
|
method expects minimally the following columns: :const:`"year"`,
|
:const:`"month"`, :const:`"day"`.
|
errors : {'ignore', 'raise', 'coerce'}, default 'raise'
|
- If :const:`'raise'`, then invalid parsing will raise an exception.
|
- If :const:`'coerce'`, then invalid parsing will be set as :const:`NaT`.
|
- If :const:`'ignore'`, then invalid parsing will return the input.
|
dayfirst : bool, default False
|
Specify a date parse order if `arg` is str or is list-like.
|
If :const:`True`, parses dates with the day first, e.g. :const:`"10/11/12"`
|
is parsed as :const:`2012-11-10`.
|
|
.. warning::
|
|
``dayfirst=True`` is not strict, but will prefer to parse
|
with day first.
|
|
yearfirst : bool, default False
|
Specify a date parse order if `arg` is str or is list-like.
|
|
- If :const:`True` parses dates with the year first, e.g.
|
:const:`"10/11/12"` is parsed as :const:`2010-11-12`.
|
- If both `dayfirst` and `yearfirst` are :const:`True`, `yearfirst` is
|
preceded (same as :mod:`dateutil`).
|
|
.. warning::
|
|
``yearfirst=True`` is not strict, but will prefer to parse
|
with year first.
|
|
utc : bool, default False
|
Control timezone-related parsing, localization and conversion.
|
|
- If :const:`True`, the function *always* returns a timezone-aware
|
UTC-localized :class:`Timestamp`, :class:`Series` or
|
:class:`DatetimeIndex`. To do this, timezone-naive inputs are
|
*localized* as UTC, while timezone-aware inputs are *converted* to UTC.
|
|
- If :const:`False` (default), inputs will not be coerced to UTC.
|
Timezone-naive inputs will remain naive, while timezone-aware ones
|
will keep their time offsets. Limitations exist for mixed
|
offsets (typically, daylight savings), see :ref:`Examples
|
<to_datetime_tz_examples>` section for details.
|
|
See also: pandas general documentation about `timezone conversion and
|
localization
|
<https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html
|
#time-zone-handling>`_.
|
|
format : str, default None
|
The strftime to parse time, e.g. :const:`"%d/%m/%Y"`. See
|
`strftime documentation
|
<https://docs.python.org/3/library/datetime.html
|
#strftime-and-strptime-behavior>`_ for more information on choices, though
|
note that :const:`"%f"` will parse all the way up to nanoseconds.
|
You can also pass:
|
|
- "ISO8601", to parse any `ISO8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
|
time string (not necessarily in exactly the same format);
|
- "mixed", to infer the format for each element individually. This is risky,
|
and you should probably use it along with `dayfirst`.
|
exact : bool, default True
|
Control how `format` is used:
|
|
- If :const:`True`, require an exact `format` match.
|
- If :const:`False`, allow the `format` to match anywhere in the target
|
string.
|
|
Cannot be used alongside ``format='ISO8601'`` or ``format='mixed'``.
|
unit : str, default 'ns'
|
The unit of the arg (D,s,ms,us,ns) denote the unit, which is an
|
integer or float number. This will be based off the origin.
|
Example, with ``unit='ms'`` and ``origin='unix'``, this would calculate
|
the number of milliseconds to the unix epoch start.
|
infer_datetime_format : bool, default False
|
If :const:`True` and no `format` is given, attempt to infer the format
|
of the datetime strings based on the first non-NaN element,
|
and if it can be inferred, switch to a faster method of parsing them.
|
In some cases this can increase the parsing speed by ~5-10x.
|
|
.. deprecated:: 2.0.0
|
A strict version of this argument is now the default, passing it has
|
no effect.
|
|
origin : scalar, default 'unix'
|
Define the reference date. The numeric values would be parsed as number
|
of units (defined by `unit`) since this reference date.
|
|
- If :const:`'unix'` (or POSIX) time; origin is set to 1970-01-01.
|
- If :const:`'julian'`, unit must be :const:`'D'`, and origin is set to
|
beginning of Julian Calendar. Julian day number :const:`0` is assigned
|
to the day starting at noon on January 1, 4713 BC.
|
- If Timestamp convertible (Timestamp, dt.datetime, np.datetimt64 or date
|
string), origin is set to Timestamp identified by origin.
|
- If a float or integer, origin is the millisecond difference
|
relative to 1970-01-01.
|
cache : bool, default True
|
If :const:`True`, use a cache of unique, converted dates to apply the
|
datetime conversion. May produce significant speed-up when parsing
|
duplicate date strings, especially ones with timezone offsets. The cache
|
is only used when there are at least 50 values. The presence of
|
out-of-bounds values will render the cache unusable and may slow down
|
parsing.
|
|
Returns
|
-------
|
datetime
|
If parsing succeeded.
|
Return type depends on input (types in parenthesis correspond to
|
fallback in case of unsuccessful timezone or out-of-range timestamp
|
parsing):
|
|
- scalar: :class:`Timestamp` (or :class:`datetime.datetime`)
|
- array-like: :class:`DatetimeIndex` (or :class:`Series` with
|
:class:`object` dtype containing :class:`datetime.datetime`)
|
- Series: :class:`Series` of :class:`datetime64` dtype (or
|
:class:`Series` of :class:`object` dtype containing
|
:class:`datetime.datetime`)
|
- DataFrame: :class:`Series` of :class:`datetime64` dtype (or
|
:class:`Series` of :class:`object` dtype containing
|
:class:`datetime.datetime`)
|
|
Raises
|
------
|
ParserError
|
When parsing a date from string fails.
|
ValueError
|
When another datetime conversion error happens. For example when one
|
of 'year', 'month', day' columns is missing in a :class:`DataFrame`, or
|
when a Timezone-aware :class:`datetime.datetime` is found in an array-like
|
of mixed time offsets, and ``utc=False``.
|
|
See Also
|
--------
|
DataFrame.astype : Cast argument to a specified dtype.
|
to_timedelta : Convert argument to timedelta.
|
convert_dtypes : Convert dtypes.
|
|
Notes
|
-----
|
|
Many input types are supported, and lead to different output types:
|
|
- **scalars** can be int, float, str, datetime object (from stdlib :mod:`datetime`
|
module or :mod:`numpy`). They are converted to :class:`Timestamp` when
|
possible, otherwise they are converted to :class:`datetime.datetime`.
|
None/NaN/null scalars are converted to :const:`NaT`.
|
|
- **array-like** can contain int, float, str, datetime objects. They are
|
converted to :class:`DatetimeIndex` when possible, otherwise they are
|
converted to :class:`Index` with :class:`object` dtype, containing
|
:class:`datetime.datetime`. None/NaN/null entries are converted to
|
:const:`NaT` in both cases.
|
|
- **Series** are converted to :class:`Series` with :class:`datetime64`
|
dtype when possible, otherwise they are converted to :class:`Series` with
|
:class:`object` dtype, containing :class:`datetime.datetime`. None/NaN/null
|
entries are converted to :const:`NaT` in both cases.
|
|
- **DataFrame/dict-like** are converted to :class:`Series` with
|
:class:`datetime64` dtype. For each row a datetime is created from assembling
|
the various dataframe columns. Column keys can be common abbreviations
|
like [âyearâ, âmonthâ, âdayâ, âminuteâ, âsecondâ, âmsâ, âusâ, ânsâ]) or
|
plurals of the same.
|
|
The following causes are responsible for :class:`datetime.datetime` objects
|
being returned (possibly inside an :class:`Index` or a :class:`Series` with
|
:class:`object` dtype) instead of a proper pandas designated type
|
(:class:`Timestamp`, :class:`DatetimeIndex` or :class:`Series`
|
with :class:`datetime64` dtype):
|
|
- when any input element is before :const:`Timestamp.min` or after
|
:const:`Timestamp.max`, see `timestamp limitations
|
<https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html
|
#timeseries-timestamp-limits>`_.
|
|
- when ``utc=False`` (default) and the input is an array-like or
|
:class:`Series` containing mixed naive/aware datetime, or aware with mixed
|
time offsets. Note that this happens in the (quite frequent) situation when
|
the timezone has a daylight savings policy. In that case you may wish to
|
use ``utc=True``.
|
|
Examples
|
--------
|
|
**Handling various input formats**
|
|
Assembling a datetime from multiple columns of a :class:`DataFrame`. The keys
|
can be common abbreviations like ['year', 'month', 'day', 'minute', 'second',
|
'ms', 'us', 'ns']) or plurals of the same
|
|
>>> df = pd.DataFrame({'year': [2015, 2016],
|
... 'month': [2, 3],
|
... 'day': [4, 5]})
|
>>> pd.to_datetime(df)
|
0 2015-02-04
|
1 2016-03-05
|
dtype: datetime64[ns]
|
|
Using a unix epoch time
|
|
>>> pd.to_datetime(1490195805, unit='s')
|
Timestamp('2017-03-22 15:16:45')
|
>>> pd.to_datetime(1490195805433502912, unit='ns')
|
Timestamp('2017-03-22 15:16:45.433502912')
|
|
.. warning:: For float arg, precision rounding might happen. To prevent
|
unexpected behavior use a fixed-width exact type.
|
|
Using a non-unix epoch origin
|
|
>>> pd.to_datetime([1, 2, 3], unit='D',
|
... origin=pd.Timestamp('1960-01-01'))
|
DatetimeIndex(['1960-01-02', '1960-01-03', '1960-01-04'],
|
dtype='datetime64[ns]', freq=None)
|
|
**Differences with strptime behavior**
|
|
:const:`"%f"` will parse all the way up to nanoseconds.
|
|
>>> pd.to_datetime('2018-10-26 12:00:00.0000000011',
|
... format='%Y-%m-%d %H:%M:%S.%f')
|
Timestamp('2018-10-26 12:00:00.000000001')
|
|
**Non-convertible date/times**
|
|
If a date does not meet the `timestamp limitations
|
<https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html
|
#timeseries-timestamp-limits>`_, passing ``errors='ignore'``
|
will return the original input instead of raising any exception.
|
|
Passing ``errors='coerce'`` will force an out-of-bounds date to :const:`NaT`,
|
in addition to forcing non-dates (or non-parseable dates) to :const:`NaT`.
|
|
>>> pd.to_datetime('13000101', format='%Y%m%d', errors='ignore')
|
'13000101'
|
>>> pd.to_datetime('13000101', format='%Y%m%d', errors='coerce')
|
NaT
|
|
.. _to_datetime_tz_examples:
|
|
**Timezones and time offsets**
|
|
The default behaviour (``utc=False``) is as follows:
|
|
- Timezone-naive inputs are converted to timezone-naive :class:`DatetimeIndex`:
|
|
>>> pd.to_datetime(['2018-10-26 12:00:00', '2018-10-26 13:00:15'])
|
DatetimeIndex(['2018-10-26 12:00:00', '2018-10-26 13:00:15'],
|
dtype='datetime64[ns]', freq=None)
|
|
- Timezone-aware inputs *with constant time offset* are converted to
|
timezone-aware :class:`DatetimeIndex`:
|
|
>>> pd.to_datetime(['2018-10-26 12:00 -0500', '2018-10-26 13:00 -0500'])
|
DatetimeIndex(['2018-10-26 12:00:00-05:00', '2018-10-26 13:00:00-05:00'],
|
dtype='datetime64[ns, UTC-05:00]', freq=None)
|
|
- However, timezone-aware inputs *with mixed time offsets* (for example
|
issued from a timezone with daylight savings, such as Europe/Paris)
|
are **not successfully converted** to a :class:`DatetimeIndex`. Instead a
|
simple :class:`Index` containing :class:`datetime.datetime` objects is
|
returned:
|
|
>>> pd.to_datetime(['2020-10-25 02:00 +0200', '2020-10-25 04:00 +0100'])
|
Index([2020-10-25 02:00:00+02:00, 2020-10-25 04:00:00+01:00],
|
dtype='object')
|
|
- A mix of timezone-aware and timezone-naive inputs is also converted to
|
a simple :class:`Index` containing :class:`datetime.datetime` objects:
|
|
>>> from datetime import datetime
|
>>> pd.to_datetime(["2020-01-01 01:00:00-01:00", datetime(2020, 1, 1, 3, 0)])
|
Index([2020-01-01 01:00:00-01:00, 2020-01-01 03:00:00], dtype='object')
|
|
|
|
|
Setting ``utc=True`` solves most of the above issues:
|
|
- Timezone-naive inputs are *localized* as UTC
|
|
>>> pd.to_datetime(['2018-10-26 12:00', '2018-10-26 13:00'], utc=True)
|
DatetimeIndex(['2018-10-26 12:00:00+00:00', '2018-10-26 13:00:00+00:00'],
|
dtype='datetime64[ns, UTC]', freq=None)
|
|
- Timezone-aware inputs are *converted* to UTC (the output represents the
|
exact same datetime, but viewed from the UTC time offset `+00:00`).
|
|
>>> pd.to_datetime(['2018-10-26 12:00 -0530', '2018-10-26 12:00 -0500'],
|
... utc=True)
|
DatetimeIndex(['2018-10-26 17:30:00+00:00', '2018-10-26 17:00:00+00:00'],
|
dtype='datetime64[ns, UTC]', freq=None)
|
|
- Inputs can contain both string or datetime, the above
|
rules still apply
|
|
>>> pd.to_datetime(['2018-10-26 12:00', datetime(2020, 1, 1, 18)], utc=True)
|
DatetimeIndex(['2018-10-26 12:00:00+00:00', '2020-01-01 18:00:00+00:00'],
|
dtype='datetime64[ns, UTC]', freq=None)
|
> r£ ÚISO8601z8Cannot use 'exact' when 'format' is 'mixed' or 'ISO8601'zùThe argument 'infer_datetime_format' is deprecated and will be removed in a future version. A strict version of it is now the default, see https://pandas.pydata.org/pdeps/0004-consistent-to-datetime-parsing.html. You can safely remove this argument.r^ NrÒ )r r rY r r r r )r| r
r r@ r r ry rz )+r Ú
|
no_defaultrª rc rd r$ rÍ r r² r¤ r r r r r/ r r r r Z _constructorr| r
r. r ÚMutableMappingÚ _assemble_from_unit_mappingsr; r r+ r r r¥ r¦ r6 r rÈ r r~ r@ r r§ rk Zbool_)rl r rY r r rv r r rÏ rÉ rw rx r r ÚvaluesZargcr@ rK rK rL rÑ ¯ sx D
|
ú ù
|
|
|
|
ÿ
|
rC rD rE ÚhÚmÚsrU rV rW )rC ZyearsrD ÚmonthsrE ÚdaysrO rP rQ rR rS rT rU Z millisecondZ millisecondsrV Ú microsecondÚ microsecondsrW Z
|
nanosecondÚ nanoseconds)r r c s ddl m}mm} || } | jjs,tddd fdd| ¡ D }dd | ¡ D }d d
|
d g}t t
|
|t
|
| ¡ }t |r d |¡} td | dt t
|
| ¡ t
|
t ¡ }
|
t |
|
rÞd |
|
¡} td| d fdd} | | |d d | | |d
|
d | | |d } zt| d |d} W n8 ttfk
|
rp } ztd| |W 5 d}~X Y nX dddd d d g}|D ]}| |¡}|dk r|| krz | || | | | d 7 } W n> ttfk
|
r } ztd | d!| |W 5 d}~X Y nX q| S )"a.
|
assemble the unit specified fields from the arg (DataFrame)
|
Return a Series for actual parsing
|
|
Parameters
|
----------
|
arg : DataFrame
|
errors : {'ignore', 'raise', 'coerce'}, default 'raise'
|
|
- If :const:`'raise'`, then invalid parsing will raise an exception
|
- If :const:`'coerce'`, then invalid parsing will be set as :const:`NaT`
|
- If :const:`'ignore'`, then invalid parsing will return the input
|
utc : bool
|
Whether to convert/localize timestamps to UTC.
|
|
Returns
|
-------
|
Series
|
r )r? Ú
|
to_numericÚ to_timedeltaz#cannot assemble with duplicate keysc S s, | t krt | S | ¡ t kr(t | ¡ S | S r´ )Ú _unit_mapÚlower)ÚvaluerK rK rL r½ s
|
z'_assemble_from_unit_mappings.<locals>.fc s i | ]}| |qS rK rK )rµ Úk)r½ rK rL Ú
|
<dictcomp> s z0_assemble_from_unit_mappings.<locals>.<dictcomp>c S s i | ]\}}||qS rK rK )rµ rå ÚvrK rK rL ræ s rC rD rE ú,zNto assemble mappings requires at least that [year, month, day] be specified: [z ] is missingz9extra keys have been passed to the datetime assemblage: [r¸ c s& | d} t | r"| jddd} | S )Nr¿ Úint64Fr» )r* rÁ )r× )r rà rK rL r s z,_assemble_from_unit_mappings.<locals>.coerceé' éd z%Y%m%d)rv r r z cannot assemble the datetimes: NrØ rÙ rÚ rU rV rW )r r z cannot assemble the datetimes [z]: )r~ r? rà rá Úcolumnsr rª ÚkeysÚitemsÚsortedrs rp Újoinrâ r× rÑ rt Úget)rl r r r? rá r Zunit_revÚrequiredÚreqZ _requiredZexcessZ_excessr r× rË Zunitsrº rä rK )r r½ rà rL rÖ ` sX
|
|
|
|
ÿ
|
|
ÿ
|
ÿþÿ"
|
ÿþrÖ znpt.NDArray[np.object_]znp.ndarray | None)rl r rZ c
|
s¼ fdd fdd}z | tj¡W S tttfk
|
rD Y nX z | tj¡}||t|W S tttfk
|
r| Y nX z t | t
|
t ¡ }|| |W S tttfk
|
r¶ Y nX dS )a*
|
try to parse the YYYYMMDD/%Y%m%d format, try to deal with NaT-like,
|
arg is a passed in as an object dtype, but could really be ints/strings
|
with nan-like/or floats (e.g. with nan)
|
|
Parameters
|
----------
|
arg : np.ndarray[object]
|
errors : {'raise','ignore','coerce'}
|
c s> | j tdd} t | d | d d | d ¡}tj| dd S )NFr» rê rë r¿ r )rÁ r r Ztry_parse_year_month_dayr Zarray_to_datetime)ÚcargÚparsedr¿ rK rL ÚcalcÊ s
|
ÿz _attempt_YYYYMMDD.<locals>.calcc sR t j| jdd}| d¡}t|| < | | t j¡ t j¡}| d¡||< |S )Nr¼ rz Úi8)r r ÚshapeÚviewr rÁ Úfloat64ré )rô r r ZiresultZ masked_result)rö rK rL Úcalc_with_maskÒ s
|
|
z)_attempt_YYYYMMDD.<locals>.calc_with_maskN) rÁ r ré rª Ú OverflowErrorrt rú r0 r4 Úisinr¥ r )rl r rû rô r rK )rö r rL Ú_attempt_YYYYMMDD¾ s"
|
rþ r )F)rh N)FN)N)NFNr NNT)
|
..........)
|
..........)
|
..........)xÚ
|
__future__r Ú collectionsr r Ú functoolsr Ú itertoolsr Útypingr r r r
|
r r r r r rc Únumpyr Z pandas._libsr r Zpandas._libs.tslibsr r r r r r r r r r r¬ Z pandas._libs.tslibs.conversionr Zpandas._libs.tslibs.parsingr r Z pandas._libs.tslibs.strptimer Zpandas._typingr r! r" r# Zpandas.util._exceptionsr$ Zpandas.core.dtypes.commonr% r& r' r( r) r* r+ r, r- Zpandas.core.dtypes.genericr. r/ Zpandas.core.dtypes.missingr0 Z pandas.arraysr1 r2 r3 Z pandas.corer4 Zpandas.core.algorithmsr5 Zpandas.core.arrays.baser6 Z pandas.core.arrays.datetimesr7 r8 r9 Zpandas.core.constructionr: Zpandas.core.indexes.baser; Z pandas.core.indexes.datetimesr< Zpandas._libs.tslibs.nattyper= Z pandas._libs.tslibs.timedeltasr> r~ r? r@ ri rj rb ZScalarrÎ r rB rA rN ZDictConvertiblerq rg ru r r r r r² r® r« rÍ rÑ rÔ râ rÖ rþ Ú__all__rK rK rK rL Ú<module> s , 0 , ÿ<0 ÿ ý& ÷ yHI õ& õ& õ&õ& ë^7ý
|
