Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
134 lines (90 sloc) 3.68 KB


Build Status

A Python library for dealing with dates/times. Inspired by both Moment.js and the simplicity of Kenneth Reitz's Requests library. Ideas were also taken from the Times Python module.


I would advise that this is alpha-quality software.

pip install moment


import moment
from datetime import datetime

# Create a moment from a string"12-18-2012", "M-D-YYYY")

# Create a moment with strftime format"12-18-2012", "%m-%d-%Y")

# By default, the "%Y-%m-%d" strftime format is used"2012-12-18")

# Create a moment from the current datetime

# The moment can also be UTC-based

# Create a moment with the UTC time zone
moment.utc("2012-12-18", "YYYY-M-D")

# Create a moment from a Unix timestamp

# Create a moment from a Unix UTC timestamp
moment.unix(1355875153626, utc=True)

# Return a datetime instance, 12, 18).date

# We can do the same thing with the UTC method
moment.utc(2012, 12, 18).date

# Create and format a moment using Moment.js semantics"YYYY-M-D")

# Create and format a moment with strftime semantics, 12, 18).strftime("%Y-%m-%d")

# Update your moment's time zone, 12, 18)).locale("US/Central").date

# Alter the moment's UTC time zone to a different time zone

# Set and update your moment's time zone. For instance, I'm on the
# west coast, but want NYC's current time."US/Pacific").timezone("US/Eastern")

# In order to manipulate time zones, a locale must always be set or
# you must be using UTC.

# You can also clone a moment, so the original stays unaltered
now = moment.utcnow().timezone("US/Pacific")
future = now.clone().add(weeks=2)


Moment allows you to chain commands, which turns out to be super useful.

# Customize your moment by chaining commands, 12, 18).add(days=2).subtract(weeks=3).date

# Imagine trying to do this with datetime, right?
moment.utcnow().add(years=3, months=2).format("YYYY-M-D h:m A")

# You can use multiple keyword arguments, 12, 19).add(hours=1, minutes=2, seconds=3)

# And, a similar subtract example..., 12, 19, 1, 2, 3).subtract(hours=1, minutes=2, seconds=3)

# In addition to adding/subtracting, we can also replace values, minutes=15, seconds=0).epoch()

# And, if you'd prefer to keep the microseconds on your epoch value, minutes=15, seconds=0).epoch(rounding=False)

# Years, months, and days can also be set, months=1, days=1, hours=0, minutes=0, seconds=0)

# Also, datetime properties are available
moment.utc(2012, 12, 19).year == 2012

# Including plural ones (since I'm bad at remembering)

# We can also manipulate to preferred weekdays, such as Monday, 12, 19).replace(weekday=1).strftime("%Y-%m-%d")

# Or, this upcoming Sunday"2012-12-19").replace(weekday=7).date

# We can even go back to two Sundays ago, 12, 19).replace(weekday=-7).format("YYYY-MM-DD")

# It's also available as a property

# And, there's an easy way to zero out the hours, minutes, and seconds