This library will not be maintained any further. You probably want to use the excellent Arrow library.
“There should be one—and preferably only one—obvious way to do it.”
In fact, version 0.7 of times has been rewritten to be implemented on top of Arrow, so it still provides the Times interface, but you'll already be using Arrow. You can probably easily replace your times function calls by Arrow objects.
Times is a small, minimalistic, Python library for dealing with time conversions to and from timezones, for once and for all.
Never work with local times. Whenever you must accept local time input (e.g. from a user), convert it to universal time immediately:
>>> times.to_universal(local_time, 'Europe/Amsterdam') datetime.datetime(2012, 2, 1, 10, 31, 45, 781262)
The second argument can be a
pytz.timezone instance, or a timezone string.
local_time variable already holds timezone info, you must leave out
the source timezone from the call.
To enforce best practices,
times will never implicitly convert times for you,
even if that would technically be possible.
If you want to accepting datetime representations in string form (for example, from JSON APIs), you can convert them to universal datetimes easily:
>>> import time, times >>> print times.to_universal('2012-02-03 11:59:03-0500') # auto-detects source timezone
Times utilizes the string parsing routines available in dateutil. Note
that the source timezone is auto-detected from the string. If the string
contains a timezone offset, you are not allowed to explicitly specify one.
If the string does not contain any timezone offset, you must specify the source timezone explicitly:
>>> print times.to_universal('2012-02-03 11:59:03', 'Europe/Amsterdam')
This is the inverse of
If you prefer working with UNIX (POSIX) timestamps, you can convert them to safe datetime representations easily:
>>> import time, times >>> print times.to_universal(time.time()) 2012-02-03 11:59:03.588419
to_universal auto-detects that you give it a UNIX timestamp.
To get the UNIX timestamp representation of a universal datetime, use:
>>> print times.to_unix(universal_time)
When you want to record the current time, you can use this convenience method:
>>> import times >>> print times.now() datetime.datetime(2012, 2, 1, 11, 51, 27, 621491)
To present times to the end user of your software, you should explicitly format your universal time to your user's local timezone.
>>> import times >>> now = times.now() >>> print times.format(now, 'CET') 2012-02-01 21:32:10+0100
As with the
to_universal function, the second argument may be either
a timezone instance or a timezone string.
Note: It is possible to convert universal times to local times, using
to_local). However, you probably shouldn't do it, unless you want to
strftime() the resulting local date multiple times. In any other case, you
are advised to use
times.format() directly instead.