U
    c$                     @  s<  d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dl	m
Z
mZmZmZmZmZmZmZmZ d dlZd dlZd dlmZ d d	lmZmZmZmZmZmZmZ d d
l m!Z!m"Z"m#Z# d dl$m%Z% d dl&m'Z'm(Z(m)Z)m*Z*m+Z+ d dl,m-Z- d dl.m/Z/m0Z0m1Z1m2Z2m3Z3m4Z4m5Z5m6Z6m7Z7m8Z8 d dl9m:Z:m;Z; d dl<m=Z= d dl>m?Z?m@Z@ d dlAmBZB d dlCmDZD d dlEmFZF d dlGmHZHmIZImJZJ d dlKmLZL d dlMmNZN d dlOmPZP e
rd dlQmRZR d dlSmTZT d dlUmVZVmWZW eeee'f ZXeeYeZf Z[ee[ef Z\ee\eXf Z]eee[ ee[df e'f Z^G dd dedd Z_G d!d" d"e_d#d Z`ee`d$f Zad%Zbd|d&d'd(d)Zcd}d+d,d-d.d/d0d1Zdd+d2d.d3d4d5d6d7Zed~d8d&d9d:d;d<d=Zfdd>d4d?d:d@dAdBZgdCd:dDdEdFZhdd2d9dHd2dId.d&d&d.dJ	dKdLZidId.dId.dMdNdOdPZjdId.dId.dMdNdQdRZkdId:dSdTdUZldVdW ZmeddXdYd.d.d&d2d.d2d.d.dZd[d\d]Znedd^dYd.d.d&d2d.d2d.d.d4d[d_d]Znedd`dYd.d.d&d2d.d2d.d.dad[dbd]ZnddddYd.d.d&d2d.d2d.d.ded[dfd]ZndgdgdhdhdididjdjdkdkdldldmdmdmdndndndodododpZodYdqdrdsZpdtdIdudvdwdxZqddydzZrd{d1d]dzgZsdS )    )annotations)abc)datetime)partial)islice)	TYPE_CHECKINGCallableHashableListTuple	TypedDictUnioncastoverloadN)tslib)OutOfBoundsDatetime	Timedelta	TimestampiNaTnat_stringsparsing	timezones)DateParseErrorformat_is_isoguess_datetime_format)array_strptime)AnyArrayLike	ArrayLikeDateTimeErrorChoicesTimezonenpt)find_stack_level)
ensure_objectis_datetime64_dtypeis_datetime64_ns_dtypeis_datetime64tz_dtypeis_float
is_integeris_integer_dtypeis_list_likeis_numeric_dtype	is_scalar)ABCDataFrame	ABCSeries)notna)DatetimeArrayIntegerArray)
algorithms)unique)ExtensionArray)maybe_convert_dtypeobjects_to_datetime64nstz_to_dtype)extract_array)Index)DatetimeIndex)NaTType)UnitChoices)	DataFrameSeries.c                   @  s&   e Zd ZU ded< ded< ded< dS )YearMonthDayDictDatetimeDictArgyearmonthdayN__name__
__module____qualname____annotations__ rH   rH   ?/tmp/pip-unpacked-wheel-g7fro6k3/pandas/core/tools/datetimes.pyr>   f   s   
r>   T)totalc                   @  sV   e Zd ZU ded< ded< ded< ded< ded< ded< ded< ded	< ded
< dS )FulldatetimeDictr?   hourhoursminuteminutessecondsecondsmsusnsNrC   rH   rH   rH   rI   rK   l   s   
rK   Fr<   2   zbool | Nonedayfirstc                 C  s0   t |  d }t|r,t| |d  |dS d S )Nr   rV   )r.   Znonzerolenr   )arrrW   Znon_nan_elementsrH   rH   rI    _guess_datetime_format_for_array   s    rZ   ffffff?ArrayConvertiblefloatz
int | Nonebool)argunique_sharecheck_countreturnc                 C  s   d}|dkr<t | tkrdS t | dkr6t | d }qjd}n.d|  krTt | ks^n td|dkrjdS d|  k r~d	k sn td
ztt| |}W n tk
r   Y dS X t ||| krd}|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)]   z+unique_share must be in next bounds: (0; 1))rX   start_caching_atAssertionErrorsetr   	TypeError)r_   r`   ra   Z
do_cachingZunique_elementsrH   rH   rI   should_cache   s0     
ri   z
str | Noner   r=   )r_   formatcacheconvert_listlikerb   c                 C  s   ddl m} |td}|rt| s&|S t| }t|t| k r|||}z|||d}W n tk
rp   | Y S X |jjs||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=   dtype)index)
pandasr=   objectri   r2   rX   r   rp   	is_uniqueZ
duplicated)r_   rj   rk   rl   r=   cache_arrayZunique_datesZcache_datesrH   rH   rI   _maybe_cache   s    


ru   r   r	   r8   )dt_arrayutcnamerb   c                 C  s2   t | r"|rdnd}t| ||dS t| || jdS )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.
    tz : object
        None or '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
    rw   Ntzrx   )rx   ro   )r#   r9   r8   ro   )rv   rw   rx   rz   rH   rH   rI   _box_as_indexlike   s    r{    DatetimeScalarOrArrayConvertiblezHashable | None)r_   rt   rx   rb   c                 C  s*   ddl m} || |}t|jd|dS )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   rm   Nrw   rx   )rq   r=   mapr{   _values)r_   rt   rx   r=   resultrH   rH   rI   _convert_and_box_cache  s    r   z
np.ndarray)r   rb   c                   sF   t dd t| |D } dk	r:t  fdd|D }t||dS )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
    tz : object
        None or pytz timezone object
    name : string, default None
        Name for a DatetimeIndex

    Returns
    -------
    tz_result : Index-like of parsed dates with timezone
    c                 S  s   g | ]\}}t ||qS rH   )r   tz_localize).0reszonerH   rH   rI   
<listcomp><  s     z3_return_parsed_timezone_results.<locals>.<listcomp>Nc                   s   g | ]}|  qS rH   )
tz_convert)r   Z	tz_resultrz   rH   rI   r   @  s     rx   )nparrayzipr8   )r   r   rz   rx   Z
tz_resultsrH   r   rI   _return_parsed_timezone_results(  s    r   raisezTimezone | Nonestr)	rj   rx   rz   uniterrorsinfer_datetime_formatrW   	yearfirstexactc
              	   C  sr  t | ttfrtj| dd} t| dd}
t|
rht | ttfsLt| ||dS |dkrd| 	d
|} | S t|
rt | ttfszt| ||dW S  tk
r   Y qX n|r| 
|S | S |dk	r|dk	rtdt| ||||S t| dd	d	k rtd
| }zt| dt|d\} }W nj tk
r   |dkr`tjdgddt| }t||d Y S |dkr~t| |d}| Y S  Y nX t| } d}|r|dkrt| |d}|dk	rt|}|r| }d}|dk	rt| |||||	||}|dk	r|S |dks|st|dk}t| |||||dd\}}|dk	r\t|t|d}tj||dS |dk}t|||dS )aS  
    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
    tz : object
        None or 'utc'
    unit : str
        None or string of the frequency of the passed data
    errors : str
        error handing behaviors from to_datetime, 'raise', 'coerce', 'ignore'
    infer_datetime_format : bool, default False
        inferring format behavior from to_datetime
    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
    Orn   ro   Nry   rw   z#cannot specify both format and unitndimrd   zAarg must be a string, datetime, list, tuple, 1-d array, or SeriesF)copyrz   coerceZNaTzdatetime64[ns]r   ignorerV   T)rW   r   rw   r   require_iso8601Zallow_objectr}   )
isinstancelisttupler   r   getattrr%   r/   r9   r   r   r$   
ValueError_to_datetime_with_unitrh   r4   r   Zmaybe_get_tzrepeatrX   r8   r"   rZ   r   _to_datetime_with_formatrf   r5   r6   Z_simple_newr{   )r_   rj   rx   rz   r   r   r   rW   r   r   Z	arg_dtypeorig_arg_Znpvaluesidxr   Zformat_is_iso8601r   rw   r   	tz_parsedZdtarH   rH   rI   _convert_listlike_datetimesE  s    )




       



r   zIndex | None)fmtr   r   r   rb   c                 C  s   |dk}zt | |||d\}}	W n tk
rr   |dkr< n2|dkrjtj| jdd}|d}
|
t n| }Y n| tk
r   |s|dkr q|dkrtj| jdd}|d}
|
t q| }nY dS Y n X d	|ksd
|krt	||	||S t
|||dS )zL
    Call array_strptime, with fallback behavior depending on 'errors'.
    rw   )r   r   r   r   M8[ns]rn   i8Nz%Zz%zr}   )r   r   r   emptyshapeviewfillr   r   r   r{   )r_   rx   rz   r   r   r   r   rw   r   r   iresultrH   rH   rI   _array_strptime_with_fallback  s0    

r   c              
   C  s   d}|dkrvt |}zt||d}W n2 tttfk
rV }	 ztd|	W 5 d}	~	X Y nX |dk	rv|dk}
t||
|dS t| ||||||}|S )zG
    Try parsing with the given format, returning None on failure.
    N%Y%m%dr   z0cannot convert the input to '%Y%m%d' date formatrw   r}   )r"   _attempt_YYYYMMDDr   rh   r   r{   r   )r_   r   rx   rz   r   r   r   r   r   errrw   r   rH   rH   rI   r     s0          r   )r   rb   c                 C  s   t | dd} t| tr.| d| d}d}nt| } tj| ||d\}}|dkrdtj	||d}nt
||d}t|t
s~|S |d	|}|dk	r|jdkr||}n
||}|S )
zF
    to_datetime specalized to the case where a 'unit' is passed.
    T)Zextract_numpyzdatetime64[]Nr   r   r   UTC)r7   r   r0   astyper   asarrayr   Zarray_with_unit_to_datetimer8   Z_with_inferr9   r   r   rz   )r_   r   rx   rz   r   rY   r   r   rH   rH   rI   r      s"    




r   c              
   C  s  |dkr| }t d }|dkr(tdz| | } W n, tk
r` } ztd|W 5 d}~X Y nX t j | }t j | }t| |kst| |k rt| dnt	| rt
| st| stt| std|  d	| d
zt |}W nj tk
r* } ztd| d|W 5 d}~X Y n6 tk
r^ } ztd| d|W 5 d}~X Y nX |jdk	r|td| d|t d }	|	td|d }
t| rt| tttjfst| } | |
 } | 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)
    Zjulianr   Dz$unit must be 'D' for origin='julian'z3incompatible 'arg' type for given 'origin'='julian'Nz% is Out of Bounds for origin='julian''z!' is not compatible with origin='z+'; it must be numeric with a unit specifiedzorigin z is Out of Boundsz# cannot be converted to a Timestampzorigin offset z must be tz-naiverd   )r   )r   Zto_julian_dater   rh   maxminr   anyr   r+   r'   r&   r*   r   rz   r   r)   r   r-   r8   ndarray)r_   originr   originalZj0r   Zj_maxZj_minoffsetZ	td_offsetZioffsetrH   rH   rI   _adjust_to_originE  s`    "

r   DatetimeScalarr   r   )r_   r   rW   r   rw   rj   r   r   r   rk   rb   c                 C  s   d S NrH   r_   r   rW   r   rw   rj   r   r   r   r   rk   rH   rH   rI   to_datetime  s    r   zSeries | DictConvertiblec                 C  s   d S r   rH   r   rH   rH   rI   r     s    z list | tuple | Index | ArrayLiker9   c                 C  s   d S r   rH   r   rH   rH   rI   r     s    unixz2DatetimeScalarOrArrayConvertible | DictConvertiblez8DatetimeIndex | Series | DatetimeScalar | NaTType | Nonec              
   C  s  | dkrdS |	dkr t | |	|} |r(dnd}tt|||||||d}t| tr~| }|dk	rz| jdk	rp| |}n
| |}nt| trt	| ||
|}|j
s| |}n || j|}| j|| j| jd}n2t| ttjfrt| ||}nt| tr2t	| ||
|}|j
s t| || jd}n|| || jd}nt| rz.ttttttjdtf | }t	|||
|}W n: tk
r   |dkr d	d
lm } |g t!d}Y nX |j
st||}n
|||}n8|t"| g|d	 }t| t#rt|tj$rt#|}|S )uF7  
    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. If a delimited date string cannot be parsed in
            accordance with the given `dayfirst` option, e.g.
            ``to_datetime(['31-12-2021'])``, then a warning will be shown.

    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 None
        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"`. Note that
        :const:`"%f"` will parse all the way up to nanoseconds. See
        `strftime documentation
        <https://docs.python.org/3/library/datetime.html
        #strftime-and-strptime-behavior>`_ for more information on choices.
    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.

    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.
    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, origin is set to Timestamp identified by
          origin.
    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.

        .. versionchanged:: 0.25.0
            changed default value from :const:`False` to :const:`True`.

    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]

    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.head()
    0    3/11/2000
    1    3/12/2000
    2    3/13/2000
    3    3/11/2000
    4    3/12/2000
    dtype: object

    >>> %timeit pd.to_datetime(s, infer_datetime_format=True)  # doctest: +SKIP
    100 loops, best of 3: 10.4 ms per loop

    >>> %timeit pd.to_datetime(s, infer_datetime_format=False)  # doctest: +SKIP
    1 loop, best of 3: 471 ms per loop

    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)

    **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')
    datetime.datetime(1300, 1, 1, 0, 0)
    >>> 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', '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, pytz.FixedOffset(-300)]', 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 converted to
      a timezone-aware :class:`DatetimeIndex` if the offsets of the timezone-aware
      are constant:

    >>> from datetime import datetime
    >>> pd.to_datetime(["2020-01-01 01:00 -01:00", datetime(2020, 1, 1, 3, 0)])
    DatetimeIndex(['2020-01-01 01:00:00-01:00', '2020-01-01 02:00:00-01:00'],
                  dtype='datetime64[ns, pytz.FixedOffset(-60)]', freq=None)

    |

    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 naive and aware, string or datetime, the above
      rules still apply

    >>> from datetime import timezone, timedelta
    >>> pd.to_datetime(['2018-10-26 12:00', '2018-10-26 12:00 -0530',
    ...                datetime(2020, 1, 1, 18),
    ...                datetime(2020, 1, 1, 18,
    ...                tzinfo=timezone(-timedelta(hours=1)))],
    ...                utc=True)
    DatetimeIndex(['2018-10-26 12:00:00+00:00', '2018-10-26 17:30:00+00:00',
                   '2020-01-01 18:00:00+00:00', '2020-01-01 19:00:00+00:00'],
                  dtype='datetime64[ns, UTC]', freq=None)
    Nr   rw   )rz   r   rW   r   r   r   r   )rp   rx   r   r=   r   r   rm   rn   )%r   r   r   r   r   rz   r   r   r-   ru   r   r~   r   Z_constructorrp   rx   r,   r   MutableMapping_assemble_from_unit_mappingsr8   r   r)   r   r   r   r   r3   r   r   r   rq   r=   rr   r   r^   Zbool_)r_   r   rW   r   rw   rj   r   r   r   r   rk   rz   rl   r   rt   valuesZargcr=   rH   rH   rI   r     sn      M



 
r@   rA   rB   hmsrR   rS   rT   )r@   ZyearsrA   monthsrB   daysrL   rM   rN   rO   rP   rQ   rR   ZmillisecondZmillisecondsrS   microsecondmicrosecondsrT   Z
nanosecondZnanosecondsr   c                   s  ddl m}mm} || } | jjs,tddd fdd|  D }dd | D }d	d
dg}t	t
|t
|  }t|rd|}	td|	 dt	t
| t
t  }
t|
rd|
}td| d fdd}|| |d	  d || |d
  d  || |d   }zt|d |d}W n8 ttfk
rp } ztd| |W 5 d}~X Y nX ddddddg}|D ]}||}|dk	r|| krz|||| | | d7 }W n> ttfk
r } ztd | d!| |W 5 d}~X Y nX 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
    tz : None or 'utc'

    Returns
    -------
    Series
    r   )r<   
to_numericto_timedeltaz#cannot assemble with duplicate keysc                 S  s,   | t krt |  S |  t kr(t |   S | S r   )	_unit_maplower)valuerH   rH   rI   f  s
    z'_assemble_from_unit_mappings.<locals>.fc                   s   i | ]}| |qS rH   rH   )r   k)r   rH   rI   
<dictcomp>  s      z0_assemble_from_unit_mappings.<locals>.<dictcomp>c                 S  s   i | ]\}}||qS rH   rH   )r   r   vrH   rH   rI   r     s      r@   rA   rB   ,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"| jddd} | S )Nr   int64Fr   )r(   r   )r   )r   r   rH   rI   r     s    z,_assemble_from_unit_mappings.<locals>.coerce'  d   r   )rj   r   rw   zcannot assemble the datetimes: Nr   r   r   rR   rS   rT   )r   r   zcannot assemble the datetimes [z]: )rq   r<   r   r   columnsrs   r   keysitemssortedrg   rX   joinr   r   r   rh   get)r_   r   rz   r<   r   r   Zunit_revrequiredreqZ	_requiredZexcessZ_excessr   r   r   Zunitsur   rH   )r   r   r   rI   r   r  sX    






"
r   znpt.NDArray[np.object_]znp.ndarray | None)r_   r   rb   c              
     s   fdd  fdd}z |  tjW S  tttfk
rD   Y nX z|  tj}||t|W S  tttfk
r|   Y nX zt	| t
t }|| |W S  tttfk
r   Y nX dS )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 tdd} t| d | d d | d }tj| dd S )NFr   r   r   r   r   )r   rr   r   Ztry_parse_year_month_dayr   Zarray_to_datetime)cargparsedr   rH   rI   calc  s     
 z_attempt_YYYYMMDD.<locals>.calcc                   sR   t j| jdd}|d}t|| <  | | t jt j}|d||< |S )Nr   rn   r   )r   r   r   r   r   r   float64r   )r   maskr   r   Zmasked_result)r   rH   rI   calc_with_mask  s    

z)_attempt_YYYYMMDD.<locals>.calc_with_maskN)r   r   r   r   OverflowErrorrh   r   r.   r1   isinr   r   )r_   r   r   r   r   rH   )r   r   rI   r     s"    
r   c                 C  s,   t jdtt d ddlm} || |||S )Nzz`to_time` has been moved, should be imported from pandas.core.tools.times. This alias will be removed in a future version.)
stacklevelr   )to_time)warningswarnFutureWarningr!   Zpandas.core.tools.timesr   )r_   rj   Zinfer_time_formatr   r   rH   rH   rI   r     s    r   r   )F)r[   N)NN)N)NNNr   FNNT)
..........)
..........)
..........)
r   FFNNTNFr   T)NFr   )t
__future__r   collectionsr   r   	functoolsr   	itertoolsr   typingr   r   r	   r
   r   r   r   r   r   r   Znumpyr   Zpandas._libsr   Zpandas._libs.tslibsr   r   r   r   r   r   r   Zpandas._libs.tslibs.parsingr   r   r   Zpandas._libs.tslibs.strptimer   Zpandas._typingr   r   r   r   r    Zpandas.util._exceptionsr!   Zpandas.core.dtypes.commonr"   r#   r$   r%   r&   r'   r(   r)   r*   r+   Zpandas.core.dtypes.genericr,   r-   Zpandas.core.dtypes.missingr.   Zpandas.arraysr/   r0   Zpandas.corer1   Zpandas.core.algorithmsr2   Zpandas.core.arrays.baser3   Zpandas.core.arrays.datetimesr4   r5   r6   Zpandas.core.constructionr7   Zpandas.core.indexes.baser8   Zpandas.core.indexes.datetimesr9   Zpandas._libs.tslibs.nattyper:   Zpandas._libs.tslibs.timedeltasr;   rq   r<   r=   r\   r]   r   ZScalarr   r|   r?   r>   rK   ZDictConvertiblere   rZ   ri   ru   r{   r   r   r   r   r   r   r   r   r   r   r   r   __all__rH   rH   rH   rI   <module>   s  ,$	0   <0                0&%I          &          &          &          $   ]6
