This document describes the current stable version of Celery (5.6). For development docs, go here.

# `celery.utils.time`

Utilities related to dates, times, intervals, and timezones.

class celery.utils.time.LocalTimezone

  Local time implementation. Provided in _Zone to the app when enable_utc is disabled. Otherwise, _Zone provides a UTC ZoneInfo instance as the timezone implementation for the application.

  Note

  Used only when the `enable_utc` setting is disabled.

  dst(dt: datetime) → timedelta

    datetime -> DST offset as timedelta positive east of UTC.

  fromutc(dt: datetime) → datetime

    datetime in UTC -> datetime in local time.

  tzname(dt: datetime) → str

    datetime -> string name of time zone.

  utcoffset(dt: datetime) → timedelta

    datetime -> timedelta showing offset from UTC, negative values indicating West of UTC

celery.utils.time.adjust_timestamp(ts: float, offset: int, here: ~typing.Callable[[...], float] = <function utcoffset>) → float

  Adjust timestamp based on provided utcoffset.

celery.utils.time.delta_resolution(dt: datetime, delta: timedelta) → datetime

  Round a `datetime` to the resolution of timedelta.

  If the `timedelta` is in days, the `datetime` will be rounded to the nearest days, if the `timedelta` is in hours the `datetime` will be rounded to the nearest hour, and so on until seconds, which will just return the original `datetime`.

class celery.utils.time.ffwd(year=None, month=None, weeks=0, weekday=None, day=None, hour=None, minute=None, second=None, microsecond=None, **kwargs: Any)

  Version of `dateutil.relativedelta` that only supports addition.

celery.utils.time.get_exponential_backoff_interval(factor: int, retries: int, maximum: int, full_jitter: bool = False) → int

  Calculate the exponential backoff wait time.

celery.utils.time.humanize_seconds(secs: int, prefix: str = '', sep: str = '', now: str = 'now', microseconds: bool = False) → str

  Show seconds in human form.

  For example, 60 becomes “1 minute”, and 7200 becomes “2 hours”.

  Parameters:

    - prefix (str) – can be used to add a preposition to the output (e.g., ‘in’ will give ‘in 1 second’, but add nothing to ‘now’).

    - now (str) – Literal ‘now’.

    - microseconds (bool) – Include microseconds.

celery.utils.time.is_naive(dt: datetime) → bool

  Return True if `datetime` is naive, meaning it doesn’t have timezone info set.

celery.utils.time.localize(dt: datetime, tz: tzinfo) → datetime

  Convert aware `datetime` to another timezone.

  Using a ZoneInfo timezone will give the most flexibility in terms of ambiguous DST handling.

celery.utils.time.make_aware(dt: datetime, tz: tzinfo) → datetime

  Set timezone for a `datetime` object.

celery.utils.time.maybe_iso8601(dt: datetime | str | None) → None | datetime

  Either `datetime | str -> datetime` or `None -> None`.

celery.utils.time.maybe_make_aware(dt: datetime, tz: tzinfo | None = None, naive_as_utc: bool = True) → datetime

  Convert dt to aware datetime, do nothing if dt is already aware.

celery.utils.time.maybe_timedelta(delta: int) → timedelta

  Convert integer to timedelta, if argument is an integer.

celery.utils.time.rate(r: str) → float

  Convert rate string (“100/m”, “2/h” or “0.5/s”) to seconds.

celery.utils.time.remaining(start: datetime, ends_in: timedelta, now: datetime | None = None, relative: bool = False) → timedelta

  Calculate the real remaining time for a start date and a timedelta.

  For example, “how many seconds left for 30 seconds after start?”

  Parameters:

    - start (datetime) – Starting date.

    - ends_in (timedelta) – The end delta.

    - relative (bool) – If enabled the end time will be calculated using `delta_resolution()` (i.e., rounded to the resolution of ends_in).

    - now (datetime) – Current time and date. Defaults to `datetime.now(timezone.utc)()`.

  Returns:

    Remaining time.

  Return type:

    timedelta

celery.utils.time.to_utc(dt: datetime) → datetime

  Convert naive `datetime` to UTC.

celery.utils.time.utcoffset(time: ~types.ModuleType = <module 'time' (built-in)>, localtime: ~typing.Callable[[...], ~time.struct_time] = <built-in function localtime>) → float

  Return the current offset to UTC in hours.

celery.utils.time.weekday(name: str) → int

  Return the position of a weekday: 0 - 7, where 0 is Sunday.

  Example

      >>> weekday('sunday'), weekday('sun'), weekday('mon')
      (0, 0, 1)