
    Owg              
      L   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 d dlZd dlZd dlmZmZ d d	l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) d dl*m+Z+ d dl,m-Z-m.Z.m/Z/m0Z0m1Z1m2Z2 d dl3m4Z4m5Z5 d dl6m7Z7m8Z8 d dl9m:Z:m;Z;m<Z< d dl=m>Z> d dl?m@Z@ d dlAmBZB d dlCmDZDmEZEmFZF d dlGmHZH d dlImJZJ d dlKmLZL erd dlMmNZN d dlOmPZP d dlQmRZR d dlSmTZTmUZU eeVeWe'f   ZXeeYeZf   Z[ee[eej                  f   Z]ee]eXf   Z^eeVe[   eWe[df   e'f   Z_ G d d ed!"      Z` G d# d$e`d%"      Zaeead&f   Zbd'ZcdOdPd(Zd	 dQ	 	 	 	 	 	 	 dRd)Ze	 	 	 	 	 	 	 	 	 	 dSd*Zf	 dT	 	 	 	 	 	 	 dUd+Zg	 dV	 	 	 	 	 	 	 dWd,Zh	 	 	 	 	 	 	 dX	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 dYd.Zi	 	 	 	 	 	 	 	 	 	 dZd/Zjd[d0Zkd1 Zle	 	 	 	 	 	 	 	 	 	 d\	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 d]d2       Zme	 	 	 	 	 	 	 	 	 	 d\	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 d^d3       Zme	 	 	 	 	 	 	 	 	 	 d\	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 d_d4       Zmd-d%d%d%dej                  dej                  d5d!f
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 d`d6Zmi d7d7d8d7d9d9d:d9d;d;d<d;d=d>d?d>d@dAdBdAdCdDdEdDdFdFdGdFdHdFdIdIdJdIdIdKdKdKdLZodadMZpg dNZqy)b    )annotations)abc)date)partial)islice)TYPE_CHECKINGCallable	TypedDictUnioncastoverloadN)libtslib)OutOfBoundsDatetime	Timedelta	Timestampastype_overflowsafeis_supported_dtype	timezones)cast_from_unit_vectorized)DateParseErrorguess_datetime_format)array_strptime)AnyArrayLike	ArrayLikeDateTimeErrorChoices)find_stack_level)ensure_objectis_float
is_integeris_integer_dtypeis_list_likeis_numeric_dtype)
ArrowDtypeDatetimeTZDtype)ABCDataFrame	ABCSeries)DatetimeArrayIntegerArrayNumpyExtensionArray)unique)ArrowExtensionArray)ExtensionArray)maybe_convert_dtypeobjects_to_datetime64tz_to_dtype)extract_array)Index)DatetimeIndex)Hashable)NaTType)UnitChoices)	DataFrameSeries.c                  ,    e Zd ZU ded<   ded<   ded<   y)YearMonthDayDictDatetimeDictArgyearmonthdayN__name__
__module____qualname____annotations__     R/var/www/horilla/myenv/lib/python3.12/site-packages/pandas/core/tools/datetimes.pyr:   r:   e   s    
	rE   r:   T)totalc                  h    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
<   y)FulldatetimeDictr;   hourhoursminuteminutessecondsecondsmsusnsNr?   rD   rE   rF   rI   rI   k   s8    
rE   rI   Fr7   2   c                
   t        j                  |       x}dk7  rit        | |   x}      t        u rSt	        ||      }||S t        j                  | |dz   d        dk7  r$t        j                  dt        t                      y )Ndayfirst   zCould 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   )arrrW   r[   first_non_nan_elementguessed_formats        rF    _guess_datetime_format_for_arrayrd   ~   s    ..s33:^)<<%=D2%N )%% ##C(:(<$=>"DK  /1 rE   c                j   d}|3t        |       t        k  ryt        |       dk  rt        |       dz  }n,d}n)d|cxk  rt        |       k  sJ d        J d       |dk(  ryd|cxk  rdk  sJ d	        J d	       	 t        t        | |            }t        |      ||z  kD  rd}|S # t        $ r Y yw xY w)
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.
    TFi  
   i  r   z1check_count must be in next bounds: [0; len(arg)]rX   z+unique_share must be in next bounds: (0; 1))lenstart_caching_atsetr   	TypeError)argunique_sharecheck_count
do_cachingunique_elementss        rF   should_cacherp      s    : J s8''s8tc(b.KK (C(	?>	?(	?>	?(!|aN!NNN!NNfS+67 ?kL88
	  s   <B& &	B21B2c                   ddl m}  |t              }|rt        |       s|S t	        | t
        j                  t        t        t        f      st        j                  |       } t        |       }t        |      t        |       k  rI |||      }	  |||d      }|j                  j                  s||j                  j!                             }|S # t        $ r |cY S w xY w)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   r8   dtypeF)indexcopy)pandasr8   objectrp   
isinstancenpndarrayr-   r2   r'   arrayr+   rg   r   ru   	is_unique
duplicated)rk   formatcacheconvert_listliker8   cache_arrayunique_datescache_datess           rF   _maybe_cacher      s    0 v&KC #

NE9MN((3-Cc{|s3x'*<@K#$[5Q $$..);+<+<+G+G+I*IJ ' #""#s   C CCc                    t        j                  | j                  d      r|rdnd}t        | ||      S t	        | || j                        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.
    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
    MutcNtzname)r   rt   )r   is_np_dtypert   r3   r2   )dt_arrayr   r   r   s       rF   _box_as_indexliker     sA    . x~~s+UtX"488HNN;;rE   c                    ddl m}  || |j                  j                        j	                  |      }t        |j                  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   rr   rs   Fr   r   )rw   r8   ru   rt   mapr   _values)rk   r   r   r8   results        rF   _convert_and_box_cacher      s=    ( C{00667;;KHFV^^TBBrE   raisec	                   t        | t        t        f      rt        j                  | d      } n%t        | t
              rt        j                  |       } t        | dd      }	|rdnd}
t        |	t              rHt        | t        t        f      st        | |
|      S |r | j                  d      j                  d      } | S t        |	t              r|	j                  t        u r|rt        | t              r`t!        t"        | j                        }|	j$                  j&                  |j)                  d      }n|j+                  d      }t        |      } | S |	j$                  j&                  | j)                  d      } | S | j+                  d      } | S t-        j.                  |	d      r{t1        |	      s7t3        t        j4                  |       t        j6                  d	      |d
k(        } t        | t        t        f      st        | |
|      S |r| j                  d      S | S ||t9        d      t;        | ||||      S t        | dd      dkD  rt=        d      	 t?        | dtA        jB                  |
            \  } }tI        |       } |tK        | |      }||dk7  rtM        | |||||      S tO        | ||||d      \  }}|t        jP                  |j6                        d   }t!        t        tS        ||            }|jU                  d|jV                   d      }t        jX                  ||      }t        jX                  ||      S t[        |||      S # t<        $ r\ |d
k(  r?t        j                  dgd      jE                  tG        |             }t        ||      cY S |dk(  rt        | |      }|cY S  w xY w)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
    Ors   rt   Nr   r   UTCr   zM8[s]coerce)	is_coercez#cannot specify both format and unitndimrX   zAarg must be a string, datetime, list, tuple, 1-d array, or SeriesF)rv   r   NaTzdatetime64[ns]r   ignorerV   mixedT)rW   	yearfirstr   errorsallow_objectr   M8[]r   ).ry   listtuplerz   r|   r*   getattrr%   r(   r3   
tz_converttz_localizer$   r\   r   r2   r   r,   pyarrow_dtyper   _dt_tz_convert_dt_tz_localizer   r   r   r   asarrayrt   
ValueError_to_datetime_with_unitrj   r.   libtimezonesmaybe_get_tzrepeatrg   r   rd   _array_strptime_with_fallbackr/   datetime_datar0   viewunit_simple_newr   )rk   r   r   r   r   r   rW   r   exact	arg_dtyper   	arg_array_npvaluesidxr   	tz_parsedout_unitrt   dt64_valuesdtas                        rF   _convert_listlike_datetimesr   :  s   L #e}%hhs#&	C,	-hhsmWd+I4B)_-#}=> $77..&2259C
	Iz	*y~~/J#u% !4cii@	**--9 ) 8 8 ?I ) 9 9% @II& 
	 **--9,,U3C 
 --e4C
	C	(!),%

3! H,	C #}=> $77??5))
		BCC%c4sFCC	fa	 1	$O
 	
	$Su9R9RSU9VWQ 
C~1#I f/,S$VUFSS-FI  ##FLL1!4_k)X&FGkkC

|1"56''5A((488V488I  Xxx/?@GGCQH 55x$'CJs   $M AO)O?Oc                   t        | ||||      \  }}|ft        j                  |j                        d   }t	        ||      }	t        j                  ||	      }
|r|
j                  d      }
t        |
|      S |j                  t        k7  r8|r6t        j                  |j                        d   }t        |d| d|	      }|S t        ||j                  |	      S )
zL
    Call array_strptime, with fallback behavior depending on 'errors'.
    )r   r   r   r   )r   r   rs   r   r   r   z, UTC])rt   r   )
r   rz   r   rt   r%   r(   r   r   r2   rx   )rk   r   r   fmtr   r   r   tz_outr   rt   r   ress               rF   r   r     s     $CE&cRNFF-a065''e<..'CSt$$		C-a0FCvV"44@
v||$77rE   c           	        t        | d      } t        | t              r| j                  d| d      }d}nt	        j
                  |       } | j                  j                  dv r<| j                  d| dd      }	 t        |t	        j                  d	      d      }d}n| j                  j                  dk(  rBt	        j                  d
      5  	 t        | |      }	 ddd       j                  d	      }d}n2| j                  t        d      } t        j                   | ||      \  }}|dk(  rt#        j$                  ||      }nt'        ||      }t        |t&              s|S |j)                  d      j+                  |      }|r0|j,                  |j)                  d      }|S |j+                  d      }|S # t        $ r- |d
k(  r | j                  t              } t        | ||||      cY S w xY w# t        $ rB |d
k7  r-t        | j                  t              ||||      cY cddd       S t        d| d      w xY w# 1 sw Y   gxY w)zF
    to_datetime specalized to the case where a 'unit' is passed.
    T)extract_numpyzdatetime64[r   NiuFrv   zM8[ns]r   f)overr   z cannot convert input with unit ''r   r   r   r   r   )r1   ry   r)   astyperz   r   rt   kindr   r   rx   r   errstater   r   r   array_with_unit_to_datetimer2   _with_inferr3   r   r   r   )rk   r   r   r   r   ra   r   r   s           rF   r   r     sC    4
0C #|$jj;tfA./	jjo99>>T! **{4&2*?CL)#rxx/AN IYY^^s"'* 
	3CdCC
 ((8$CI**V%*0C">>sDQWXNC""3T2s.fm,
 &11)<F
99''.F M &&u-FM[ ' LW$jj(-c4sFKK	L + (5JJv.dC  
 
 .:4&B 
 
s<   ;!F< IG5<3G21G250I %I0I  IIc                   |dk(  r| }t        d      j                         }|dk7  rt        d      	 | |z
  } t         j                  j                         |z
  }t         j
                  j                         |z
  }t        j                  | |kD        st        j                  | |k        rt        | d      | S t        |       s;t        |       s0t        t        j                  |             st        d|  d	| d
      	 t        ||      }|j                  t        d| d      |t        d      z
  }	|	t        d|      z  }
t        |       r:t!        | t"        t$        t        j&                  f      st        j                  |       } | |
z   } | S # t        $ r}t        d      |d}~ww xY w# t        $ r}t        d| d      |d}~wt        $ r}t        d| d      |d}~ww xY w)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)
    julianr   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 specifiedr   zorigin z is Out of Boundsz# cannot be converted to a Timestampzorigin offset z must be tz-naiverX   )r   to_julian_dater   rj   maxminrz   anyr   r    r   r#   r   r   r   r"   ry   r'   r2   r{   )rk   originr   originalj0errj_maxj_minoffset	td_offsetioffsets              rF   _adjust_to_originr   &  s   $ q\((*3;CDD	(C ,,.3,,.366#+"&&u"5%*AB F J; _2B2::c?2SC59& B; ; 	vD1F 99 ~fX5FGHHYq\)	 y66 Zi

5S%T**S/CGmJY  	E	2 # 	T%x7H&IJPSS 	&!DE	s;   F  F/ 	F,F''F,/	G)8GG)G$$G)c                     y NrD   rk   r   rW   r   r   r   r   r   infer_datetime_formatr   r   s              rF   to_datetimer   n       rE   c                     y r   rD   r   s              rF   r   r     r   rE   c                     y r   rD   r   s              rF   r   r     r   rE   unixc           	        |t         j                  ur|dv rt        d      |t         j                  urt        j                  dt                      |dk(  r$t        j                  dt        t                      | y|	dk7  rt        | |	|      } t        t        ||||||	      }t        | t              r6| }|r0| j                  | j                  d
      }|S | j                  d
      }|S t        | t              rjt!        | ||
|      }|j"                  s| j%                  |      }|S  || j&                  |      }| j)                  || j*                  | j,                        }|S t        | t.        t0        j2                  f      rt5        | ||      }|S t        | t6              rKt!        | ||
|      }|j"                  st9        | || j,                        }|S  || || j,                        }|S t;        |       rk	 t=        t>        t@        tB        tD        tF        jH                  dt6        f   |       }t!        |||
|      }|j"                  st9        |      }|S  ||      }|S  |tG        jR                  | g      |      d   }t        | tT              r%t        |tF        jV                        rtU        |      }|S # tJ        $ r |dk(  r ddl&m'}  |g tP              }Y w xY w)a7:  
    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"`. The column "year"
        must be specified in 4-digit format.
    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.

        .. warning::

            In a future version of pandas, parsing datetimes with mixed time
            zones will raise an error unless `utc=True`.
            Please specify `utc=True` to opt in to the new behaviour
            and silence this warning. To create a `Series` with mixed offsets and
            `object` dtype, please use `apply` and `datetime.datetime.strptime`.

        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`.

        .. note::

            If a :class:`DataFrame` is passed, then `format` has no effect.

    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 difference
          (in units determined by the ``unit`` argument) 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**

    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='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`.
      Parsing datetimes with mixed time zones will show a warning unless
      `utc=True`. If you specify `utc=False` the warning below will be shown
      and a simple :class:`Index` containing :class:`datetime.datetime`
      objects will be returned:

    >>> pd.to_datetime(['2020-10-25 02:00 +0200',
    ...                 '2020-10-25 04:00 +0100'])  # doctest: +SKIP
    FutureWarning: In a future version of pandas, parsing datetimes with mixed
    time zones will raise an error unless `utc=True`. Please specify `utc=True`
    to opt in to the new behaviour and silence this warning. To create a `Series`
    with mixed offsets and `object` dtype, please use `apply` and
    `datetime.datetime.strptime`.
    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)])  # doctest: +SKIP
    FutureWarning: In a future version of pandas, parsing datetimes with mixed
    time zones will raise an error unless `utc=True`. Please specify `utc=True`
    to opt in to the new behaviour and silence this warning. To create a `Series`
    with mixed offsets and `object` dtype, please use `apply` and
    `datetime.datetime.strptime`.
    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'zThe 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.rY   r   zerrors='ignore' is deprecated and will raise in a future version. Use to_datetime without passing `errors` and catch exceptions explicitly insteadNr   )r   r   rW   r   r   r   r   )ru   r   r   r8   r   r   rr   rs   ),r   
no_defaultr   r^   r_   r   FutureWarningr   r   r   ry   r   r   r   r   r'   r   emptyr   r   _constructorru   r   r&   r   MutableMapping_assemble_from_unit_mappingsr2   r   r"   r   r   r   r   r-   rz   r{   r   rw   r8   rx   r|   boolbool_)rk   r   rW   r   r   r   r   r   r   r   r   r   r   r   valuesargcr8   s                    rF   r   r     s   n
 CNN"v1E'ESTTCNN23
 ()	
 ! ')	
 {VT2# #y!vv!.b M_ /^ M] 
C	#"37GH  WW[)FV MS &ckk6:F%%fCIICHH%MFP MO 
C,(:(:;	<-c63?L MK 
C	"37GH  +C388LFD MA &c6AF@ M? 
c		3
 dE>2::xNOQTD 'tVU<LMK   +D+>F M &dF3F M ""((C5/6:1=c4 Z%A&\F
 M+ # 	3  % 62K	3s   =AJ> >#K$#K$r<   yearsr=   monthsr>   daysrJ   hrK   rL   mrM   rN   srO   rP   millisecondmillisecondsrQ   microsecondrR   )microsecondsrR   
nanosecondnanosecondsc                P   ddl m}mm}  ||       } | j                  j
                  st        d      d }| j                         D ci c]  }| ||       }}|j                         D ci c]  \  }}||
 }	}}g d}
t        t        |
      t        |	j                               z
        }t        |      r dj                  |      }t        d| d      t        t        |	j                               t        t        j                               z
        }t        |      r dj                  |      }t        d	| d
      fd} || |	d            dz   || |	d            dz  z    || |	d            z   }	 t        |d|      }g d}|D ]3  }|	j#                  |      }||| v s	 | | || |         |      z  }5 |S c c}w c c}}w # t         t        f$ r}t        d|       |d}~ww xY w# t         t        f$ r}t        d| d|       |d}~ww xY w)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   )r7   
to_numericto_timedeltaz#cannot assemble with duplicate keysc                    | t         v r	t         |    S | j                         t         v rt         | j                            S | S r   )	_unit_maplower)values    rF   r   z'_assemble_from_unit_mappings.<locals>.f  s;    IU## ;;=I%U[[]++rE   )r<   r=   r>   ,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                l     |       } t        | j                        r| j                  dd      } | S )Nr   int64Fr   )r!   rt   r   )r   r   r  s    rF   r   z,_assemble_from_unit_mappings.<locals>.coerce  s4    F62 FLL)]]7]7FrE   r<   i'  r=   d   r>   z%Y%m%d)r   r   r   zcannot assemble the datetimes: N)r   r   r   rP   rQ   rR   )r   r   zcannot assemble the datetimes [z]: )rw   r7   r  r	  columnsr}   r   keysitemssortedri   rg   joinr  r   r   rj   get)rk   r   r   r7   r	  r   kr   vunit_revrequiredreq	_requiredexcess_excessr   r   r   unitsur  r  s    `                   @rF   r   r   q  s\   (  C.C;;  >?? !XXZ(AqtG(D(!%.A1.H. (H
XX]]_!55
6C
3xHHSM	11:<I
 	
 C(3y/?/?/A+BBCF
6{((6"GyPQR
 	
 	s8F#$%-
Xg&'
(3
.	/
Xe_%
&	' 
KVHVM  AE Q#,vc%j'9&QQ	 Me ).H z" K:3%@AsJK z*  5eWCuEs<   G0GG 3G?G<(G77G<?H%H  H%)r   rp   r   )F)rW   bool | Nonereturn
str | None)gffffff?N)rk   ArrayConvertiblerl   floatrm   z
int | Noner#  r   )
rk   r%  r   r$  r   r   r   r	   r#  r8   )FN)r   r   r   r   r   Hashable | Noner#  r2   r   )rk    DatetimeScalarOrArrayConvertibler   r8   r   r'  r#  r2   )NFNr   NNT)r   r$  r   r'  r   r   r   r$  r   r   rW   r"  r   r"  r   r   )
r   r   r   r]   r   r   r   r]   r#  r2   )r   r   r   r]   r#  r2   )
..........)rk   DatetimeScalarr   r   rW   r   r   r   r   r   r   r$  r   r   r   r$  r   r   r   r   r#  r   )rk   zSeries | DictConvertibler   r   rW   r   r   r   r   r   r   r$  r   r   r   r$  r   r   r   r   r#  r8   )rk   z list | tuple | Index | ArrayLiker   r   rW   r   r   r   r   r   r   r$  r   r   r   r$  r   r   r   r   r#  r3   )rk   z2DatetimeScalarOrArrayConvertible | DictConvertibler   r   rW   r   r   r   r   r   r   r$  r   zbool | lib.NoDefaultr   r$  r   zlib.NoDefault | boolr   r]   r   r   r#  z8DatetimeIndex | Series | DatetimeScalar | NaTType | None)r   r   r   r   )r
__future__r   collectionsr   datetimer   	functoolsr   	itertoolsr   typingr   r	   r
   r   r   r   r^   numpyrz   pandas._libsr   r   pandas._libs.tslibsr   r   r   r   r   r   r   pandas._libs.tslibs.conversionr   pandas._libs.tslibs.parsingr   r   pandas._libs.tslibs.strptimer   pandas._typingr   r   r   pandas.util._exceptionsr   pandas.core.dtypes.commonr   r   r    r!   r"   r#   pandas.core.dtypes.dtypesr$   r%   pandas.core.dtypes.genericr&   r'   pandas.arraysr(   r)   r*   pandas.core.algorithmsr+   pandas.core.arraysr,   pandas.core.arrays.baser-   pandas.core.arrays.datetimesr.   r/   r0   pandas.core.constructionr1   pandas.core.indexes.baser2   pandas.core.indexes.datetimesr3   collections.abcr4   pandas._libs.tslibs.nattyper5   pandas._libs.tslibs.timedeltasr6   rw   r7   r8   r   r   r%  r&  r]   Scalar
datetime64r)  r(  r;   r:   rI   DictConvertiblerh   rd   rp   r   r   r   r   r   r   r   r   r   r  r   __all__rD   rE   rF   <module>rJ     s6   "         E 8 
 5 
 
 * 2 2 
 3 * 7(3: ul23 	ucz	vtR]]23#(9I)I#J  VeFCK&8,FGy 	'u 	 (+56 0 QU9	9).9CM9	9x/	// / 	/
 /f EI<<"<2A<
<@ !C	)CC C 	C: !#* !K9K9 K9 
	K9
 K9 !K9 K9 K9 K9\8 
8 
	8
 8 8 84AHEP 
 $'"%	   	
 
        
  
 $'"%	!   	
 
        
  
 $'"%	)   	
 
        
$ $+"%..25..s	;s s s 	s
 
s s  s s 0s s s >sn
FV W g	
 
5 E C S c s c s 	$ 4 D  	$!" 4#$ 
+	2[|rE   