Python – Taking Time with Delorean

Recently I wrote about the arrow project and one of my readers mentioned that another datetime related project known as Delorean. So in this article, we’ll spend some time going over the delorean project. This will be a high level article as there is no reason to rewrite the delorean’s documentation.

---

Getting Started

To install Delorean, all you need is pip and admin privileges. Here’s the typical method of installing the package:

pip install delorean

When you install it, you will notice that Delorean has a couple of dependencies: pytz and python-dateutil. Fortunately, pip will install those for you as well if you don’t already have them.

---

Using Delorean

Actually using Delorean is quite simple. Let’s look at a few examples. We’ll start by looking at how Delorean handles time zones:

>>> from delorean import Delorean
>>> CST = "US/Central"
>>> d = Delorean(timezone=CST)
>>> d
Delorean(datetime=2014-09-03 08:01:12.112257-05:00, timezone=US/Central)
>>> e = Delorean(timezone=EST)
>>> e
Delorean(datetime=2014-09-03 09:02:00.537070-04:00, timezone=US/Eastern)
>>> d.shift(EST)
Delorean(datetime=2014-09-03 09:01:12.112257-04:00, timezone=US/Eastern)

Here we see how Delorean can use strings to set the timezone and how easy it is create objects with different time zones. We can also see how to shift between time zones. Next we’ll check out offsets:

>>> d.next_day(1)
Delorean(datetime=2014-09-04 08:01:12.112257-05:00, timezone=US/Central)
>>> d.next_day(-2)
Delorean(datetime=2014-09-01 08:01:12.112257-05:00, timezone=US/Central)

As you can see, going forward and backwards in time is extremely easy. All you need to do is call Delorean’s next_day() method. If you need to work with Python’s datetime module and Delorean objects, then you’ll probably want to check out Delorean’s epoch() and naive() methods:

>>> d.epoch()
1409749272.112257
>>> d.naive()
datetime.datetime(2014, 9, 3, 13, 1, 12, 112257)

As you probably guessed, the epoch method returns the number of seconds since the epoch. The naive method on the other hand returns a datetime.datetime object.

One of Delorean’s more interesting features is its ability to use natural language to get certains dates relative to the date object you created:

>>> d.next_tuesday()
Delorean(datetime=2014-09-09 09:01:12.112257-04:00, timezone=US/Eastern)
>>> d.next_friday()
Delorean(datetime=2014-09-05 09:01:12.112257-04:00, timezone=US/Eastern)
>>> d.last_sunday()
Delorean(datetime=2014-08-31 09:01:12.112257-04:00, timezone=US/Eastern)

Isn’t that handy? Another neat feature of Delorean is its stops() function:

>>> from delorean import stops
>>> import delorean
>>> for stop in stops(freq=delorean.HOURLY, count=10):
        print stop
 
Delorean(datetime=2014-09-03 13:18:51+00:00, timezone=UTC)
Delorean(datetime=2014-09-03 14:18:51+00:00, timezone=UTC)
Delorean(datetime=2014-09-03 15:18:51+00:00, timezone=UTC)
Delorean(datetime=2014-09-03 16:18:51+00:00, timezone=UTC)
Delorean(datetime=2014-09-03 17:18:51+00:00, timezone=UTC)
Delorean(datetime=2014-09-03 18:18:51+00:00, timezone=UTC)
Delorean(datetime=2014-09-03 19:18:51+00:00, timezone=UTC)
Delorean(datetime=2014-09-03 20:18:51+00:00, timezone=UTC)
Delorean(datetime=2014-09-03 21:18:51+00:00, timezone=UTC)
Delorean(datetime=2014-09-03 22:18:51+00:00, timezone=UTC)

You can use Delorean to create a group of Delorean objects for different seconds, minutes, hours, days, weeks, months and years. You can also include a timezone.

---

Wrapping Up

Delorean comes with other fun features such as truncation and parsing datetime strings. You should definitely give this project a try and see how much fun it is to use!

---

Related Reading

• Delorean home page
• arrow – a new date / time package for Python