pandas.Timestamp.tz_localize#

Timestamp.tz_localize(tz, ambiguous='raise', nonexistent='raise')#

Attach or detach a time zone on a Timestamp.

This method does not shift the date/time values. It attaches a time zone to a tz-naive Timestamp, or detaches the time zone from a tz-aware Timestamp. In both cases the wall time is preserved.

Parameters:
tzstr, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None

Time zone to attach to the tz-naive Timestamp; the wall time is preserved. None detaches the time zone from a tz-aware Timestamp, returning a tz-naive Timestamp with the same wall time.

ambiguousbool, ‘NaT’, default ‘raise’

When clocks moved backward due to DST, ambiguous times may arise. For example in Central European Time (UTC+01), when going from 03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the ambiguous parameter dictates how ambiguous times should be handled.

The behavior is as follows:

  • bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates).

  • ‘NaT’ will return NaT for an ambiguous time.

  • ‘raise’ will raise a ValueError for an ambiguous time.

nonexistent‘shift_forward’, ‘shift_backward’, ‘NaT’, timedelta, default ‘raise’

A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST.

The behavior is as follows:

  • ‘shift_forward’ will shift the nonexistent time forward to the closest existing time.

  • ‘shift_backward’ will shift the nonexistent time backward to the closest existing time.

  • ‘NaT’ will return NaT where there are nonexistent times.

  • timedelta objects will shift nonexistent times by the timedelta.

  • ‘raise’ will raise a ValueError if there are nonexistent times.

Returns:
localizedTimestamp
Raises:
TypeError

If the Timestamp is tz-aware and tz is not None.

See also

Timestamp.tzinfo

Returns the timezone information of the Timestamp.

Timestamp.tz_convert

Convert timezone-aware Timestamp to another time zone.

DatetimeIndex.tz_localize

Localize a DatetimeIndex to a specific time zone.

datetime.datetime.astimezone

Convert a datetime object to another time zone.

Examples

Create a naive timestamp object:

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651')
>>> ts
Timestamp('2020-03-14 15:32:52.192548651')

Add ‘Europe/Stockholm’ as timezone:

>>> ts.tz_localize(tz='Europe/Stockholm')
Timestamp('2020-03-14 15:32:52.192548651+0100', tz='Europe/Stockholm')

Analogous for pd.NaT:

>>> pd.NaT.tz_localize()
NaT