o Zzj. @sdZddlZddlZddlZddlZddlZddlmZddl m Z ddl m Z er0ddl mZejjZzddlZWn eyEdZYnwdejdejd ejfd d Z  d#d eejBejBejBd edBdejdBd efddZ  d#deejBejBejBdBd edBdejdBd edBfddZ d$dedBdejdBd ejdBfddZddd ejdBfddZdejd efddZded ejfddZ dejdBd ed eejBdBfd!d"Z!dS)%aThis module contains helper functions related to datetime and timestamp conversations. .. versionchanged:: 20.0 Previously, the contents of this module were available through the (no longer existing) module ``telegram._utils.helpers``. Warning: Contents of this module are intended to be used internally by the library and *not* by the user. Changes to this module are not considered breaking changes and may not be documented in the changelog. N) TYPE_CHECKING)warn)PTBDeprecationWarning)BotdatetimetzinforeturncCs|tur |jtdSttt|tjr"||WdSWdn1s,wY|j dur<|j|dS| |S)z|d}| }| }tj||}|j durZt||}|| krh|tjdd7}t|St|tjr|j dur|t||}t|Stdt|jd)a Converts a given time object to a float POSIX timestamp. Used to convert different time specifications to a common format. The time object can be relative (i.e. indicate a time increment, or a time of day) or absolute. Objects from the :class:`datetime` module that are timezone-naive will be assumed to be in UTC, if ``bot`` is not passed or ``bot.defaults`` is :obj:`None`. Args: time_object (:obj:`float` | :obj:`datetime.timedelta` | :obj:`datetime.datetime` | :obj:`datetime.time`): Time value to convert. The semantics of this parameter will depend on its type: * :obj:`float` will be interpreted as "seconds from :paramref:`reference_t`" * :obj:`datetime.timedelta` will be interpreted as "time increment from :paramref:`reference_timestamp`" * :obj:`datetime.datetime` will be interpreted as an absolute date/time value * :obj:`datetime.time` will be interpreted as a specific time of day reference_timestamp (:obj:`float`, optional): POSIX timestamp that indicates the absolute time from which relative calculations are to be performed (e.g. when :paramref:`time_object` is given as an :obj:`int`, indicating "seconds from :paramref:`reference_time`"). Defaults to now (the time at which this function is called). If :paramref:`time_object` is given as an absolute representation of date & time (i.e. a :obj:`datetime.datetime` object), :paramref:`reference_timestamp` is not relevant and so its value should be :obj:`None`. If this is not the case, a :exc:`ValueError` will be raised. tzinfo (:class:`datetime.tzinfo`, optional): If :paramref:`time_object` is a naive object from the :mod:`datetime` module, it will be interpreted as this timezone. Defaults to :attr:`datetime.timezone.utc` otherwise. Note: Only to be used by ``telegram.ext``. Returns: :obj:`float` | :obj:`None`: The return value depends on the type of argument :paramref:`time_object`. If :paramref:`time_object` is given as a time increment (i.e. as a :obj:`int`, :obj:`float` or :obj:`datetime.timedelta`), then the return value will be :paramref:`reference_timestamp` + :paramref:`time_object`. Else if it is given as an absolute date/time value (i.e. a :obj:`datetime.datetime` object), the equivalent value as a POSIX timestamp will be returned. Finally, if it is a time of the day without date (i.e. a :obj:`datetime.time` object), the return value is the nearest future occurrence of that time of day. Raises: TypeError: If :paramref:`time_object` s type is not one of those described above. ValueError: If :paramref:`time_object` is a :obj:`datetime.datetime` and :paramref:`reference_timestamp` is not :obj:`None`. NzAt is an (absolute) datetime while reference_timestamp is not Nonetz)dayszUnable to convert z object to timestamp)timerdtmr ValueError timedelta total_secondsintfloatr fromtimestamprdatetimetzcombiner_datetime_to_float_timestamp TypeErrortype__name__)rrr reference_dtreference_datereference_timeaware_datetimerrrto_float_timestampBs6:            r/dt_objcCs|dur tt|||SdS)z Wrapper over :func:`to_float_timestamp` which returns an integer (the float value truncated down to the nearest integer). See the documentation for :func:`to_float_timestamp` for more details. N)r!r/)r0rrrrr to_timestamps  r1unixtimecCs,|durdStjj||durtdS|dS)ai Converts an (integer) unix timestamp to a timezone aware datetime object. :obj:`None` s are left alone (i.e. ``from_timestamp(None)`` is :obj:`None`). Args: unixtime (:obj:`int`): Integer POSIX timestamp. tzinfo (:obj:`datetime.tzinfo`, optional): The timezone to which the timestamp is to be converted to. Defaults to :obj:`None`, in which case the returned datetime object will be timezone aware and in UTC. Returns: Timezone aware equivalent :obj:`datetime.datetime` value if :paramref:`unixtime` is not :obj:`None`; else :obj:`None`. Nr)rrr#r )r2rrrrfrom_timestamps r3botz Bot | NonecCs(|durdSt|dr|jr|jjSdS)z Extracts the timezone info from the default values of the bot. If the bot has no default values, :obj:`None` is returned. Ndefaults)hasattrr5r)r4rrrextract_tzinfo_from_defaultss r7cCs"|jdur |jtjjd}|S)z Converts a datetime object to a float timestamp (with sub-second precision). If the datetime object is timezone-naive, it is assumed to be in UTC. Nr )rr rtimezoneutc timestamp)r0rrrr's r'rc Cs<zt|WStjy}z td|d|d}~ww)z|Wrapper around the `ZoneInfo` constructor with slightly more helpful error message in case tzdata is not installed. zNo time zone found with key z. Make sure to use a valid time zone name and correctly install the tzdata (https://pypi.org/project/tzdata/) package if your system does not provide the time zone data.N)zoneinfoZoneInfoZoneInfoNotFoundError)rerrrrr get_zone_infos  r?value attributecCs^|durdStdddvr|Sttdd|ddd |}r-t|S|S) aP Convert a `datetime.timedelta` to seconds or return it as-is, based on environment config. This utility is part of the migration process from integer-based time representations to using `datetime.timedelta`. The behavior is controlled by the `PTB_TIMEDELTA` environment variable. Note: When `PTB_TIMEDELTA` is not enabled, the function will issue a deprecation warning. Args: value (:obj:`datetime.timedelta`): The timedelta value to process. attribute (:obj:`str`): The name of the attribute at the caller scope, used for warning messages. Returns: - :obj:`None` if :paramref:`value` is None. - :obj:`datetime.timedelta` if `PTB_TIMEDELTA=true` or ``PTB_TIMEDELTA=1``. - :obj:`int` if the total seconds is a whole number. - float: otherwise. N PTB_TIMEDELTAfalse)true1zv22.2z%In a future major version attribute `z` will be of type `datetime.timedelta`. You can opt-in early by setting `PTB_TIMEDELTA=true` or ``PTB_TIMEDELTA=1`` as an environment variable.) stacklevel) osgetenvlowerstriprrr is_integerr!)r@rAsecondsrrrget_timedelta_values   rN)NN)N)"__doc__r rrrHrr;typingrtelegram._utils.warningsrtelegram.warningsrtelegramrr8r9r r ImportErrorrrr"rr/r!r1r3r7r'strr<r?rNrrrrsh        h   *