Times

Warnings

• deprecated The `times` library itself recommends using the 'Arrow' library directly. Version 0.7 was rewritten on top of Arrow, and the project has been inactive since 2015. It is advisable to use 'Arrow' (or the standard 'datetime' module with 'zoneinfo' or 'pytz') for new projects.
  Fix: Migrate to `arrow` (recommended by `times` itself) or `datetime` with `zoneinfo` (Python 3.9+) / `pytz` for active maintenance and modern features. For example, `arrow.get(local_time_str_naive, 'Europe/Amsterdam').to('utc')`.
• gotcha When accepting local time input, `times.to_universal()` requires you to explicitly specify the source timezone if the input is a naive datetime (without timezone information). If the input string already contains a timezone offset, you must *not* provide a separate timezone argument, as it will auto-detect from the string.
  Fix: Carefully manage whether your input datetime or string includes timezone information and adjust your `times.to_universal()` call accordingly. If `local_time` has `tzinfo`, omit the timezone argument. If a string has an offset, omit the timezone argument. Otherwise, provide it explicitly, e.g., `times.to_universal(naive_dt, 'Europe/Berlin')`.
• gotcha While `times.to_local()` converts a universal time to a local datetime object, the documentation advises using `times.format()` directly for presentation. This is because `to_local()` may inherit complexities of `pytz` regarding ambiguous or non-existent times during DST transitions, especially if further date arithmetic is performed on the resulting local datetime.
  Fix: For display purposes, prefer `times.format(universal_time, timezone, format_string)`. If you need a local datetime object for other operations, be aware of `pytz`'s limitations and consider working primarily in UTC until the final presentation or conversion step.

Install

• pip install times Install stable version

Imports

• times

  import times

  The library is imported directly as 'times' to access its functions.

Quickstart

This quickstart demonstrates how to convert local times to universal (UTC) and vice-versa, using string inputs or datetime objects, and how to format times for presentation in a specific timezone.

import times
import datetime

# Example 1: Accepting local time and converting to universal time
# The second argument can be a pytz.timezone instance or a timezone string.
# If local_time already has timezone info, omit the source timezone argument.
local_time_str_naive = '2012-02-01 11:31:45'
universal_time = times.to_universal(local_time_str_naive, 'Europe/Amsterdam')
print(f"Local (naive) to Universal: {universal_time}")

# Example 2: Accepting datetime string with offset (auto-detects timezone)
universal_time_offset = times.to_universal('2012-02-03 11:59:03-0500')
print(f"String with offset to Universal: {universal_time_offset}")

# Example 3: Presenting universal time to a local timezone
# (using the universal_time from above)
formatted_local_time = times.format(universal_time, 'America/New_York', '%Y-%m-%d %H:%M:%S %Z%z')
print(f"Universal to formatted local: {formatted_local_time}")

# Example 4: Converting universal datetime to local representation (less recommended for direct formatting)
local_dt_obj = times.to_local(universal_time, 'Asia/Tokyo')
print(f"Universal to local datetime object: {local_dt_obj}")