lair.clock.UTC2#

lair.clock.UTC2(x, totz, *, localize=False, driver=None, ambiguous='raise', nonexistent='raise')[source]#

Convert times from UTC to the time zone totz.

A time without a time zone is taken as UTC (the rule on the clock example), and a time with one is converted from its own. UTC2MST() and UTC2MTN() are the two common cases.

Parameters:
  • x (dt.datetime | pd.Timestamp | list[dt.datetime] | pd.DataFrame | pd.Series) – The times: a single time, a list of them, or with driver='pandas' the index of a DataFrame or the values of a Series.

  • totz (str) – The time zone to convert to, such as 'America/Denver'.

  • localize (bool, optional) – If True, drop the time zone from the result and keep the clock time of totz. Default False.

  • driver (None | 'pandas', optional) – 'pandas' for a DataFrame or Series; None for a single time or a list.

  • ambiguous (optional) – As in convert_timezones(). UTC has no repeated or skipped hours, so they never apply; every shortcut takes them.

  • nonexistent (optional) – As in convert_timezones(). UTC has no repeated or skipped hours, so they never apply; every shortcut takes them.

Returns:

dt.datetime | pd.Timestamp | list[dt.datetime] | pd.DataFrame | pd.Series – The converted times, in the shape of x: a single time gives a single time, a datetime a datetime and a pd.Timestamp a pd.Timestamp.

See also

convert_timezones

The general conversion, from any zone to any zone.

UTC2MTN

UTC to Salt Lake City time.

UTC2MST

UTC to Mountain Standard Time.

Examples

18:00 UTC in Pacific time, in July:

>>> import datetime as dt
>>> from lair.clock import UTC2
>>> UTC2(dt.datetime(2024, 7, 15, 18), "America/Los_Angeles")
datetime.datetime(2024, 7, 15, 11, 0, tzinfo=zoneinfo.ZoneInfo(key='America/Los_Angeles'))