ago /

The default branch has multiple heads

Filename Size Date modified Message
72 B
2.5 KB
2.1 KB
713 B

How to install

There are a number of ways to install this package:

easy_install ago

pip install ago

or specify ago under the setup_requires list within your setuptools-compatible project's file.

How to use

The ago module comes with three functions:

  1. human
  2. delta2human
  3. delta2dict

You really only need to worry about human:

from ago import human, delta2human, delta2dict

from datetime import datetime

# pretend this was stored in database
d1 = datetime(
  year = 2010,

# to find out how long ago, use the human function
print 'Created ' + human( d1 ) + ' ago.'

# optionally pass a precision
print 'Created ' + human( d1, 3 ) + ' ago.'
print 'Created ' + human( d1, 6 ) + ' ago.'

Future dates and times are also handled as well:

future_delta = timedelta(-365, -1, -1)
future = + -future_delta

#Default formatting for future date
print 'To be completed ' + human(future)

#Custom formatting for future date
print 'To be completed ' + human(future, future_str="%s from now")

By default, datetime objects in the future are formatted like in %s (which produces output like in 1 year, 2 days. You can customise the formatting of future dates and time differences using the future_str keyword. The %s in future_str will be replaced with the given human-readable timedelta and must be present.

Now we will document how to use delta2human and delta2dict:

# pretend we already have a timedelta object

# subtract two datetime objects for a timedelta object
d2 =
delta = d2 - d1

# display a human readable timedelta from a timedelta
print 'Created ' + delta2human( delta ) + ' ago.'

#  create a dictionary out of the timedelta
delta_dict = delta2dict( delta )
print delta_dict

These methods also work with future datetime objects and delta2human accepts customization of future string formatting like human does:

print 'To be completed ' + delta2human( future_delta )
print 'To be completed ' + delta2human( future_delta, future_str="%s later" )
future_delta_dict = delta2dict( future_delta )
print future_delta_dict

How do I thank you?

You should follow me on twitter


Public Domain

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.