Metadata-Version: 1.0
Name: ago
Version: 0.0.6
Summary: ago: Human readable timedeltas
Home-page: https://bitbucket.org/russellballestrini/ago/src
Author: Russell Ballestrini
Author-email: russell@ballestrini.net
License: Public Domain
Description: What are human readable timedeltas? 
        ===============================================
        
        ago.py makes customizable human readable timedeltas, for example:
        
        Testing past tense::
        
         Russell commented 1 year, 127 days, 16 hours ago
         You replied 1 year, 127 days ago
        
        Testing future tense::
        
         Program will shutdown in 2 days, 3 hours, 27 minutes
         Job will run 2 days, 3 hours from now
        
        
        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 *setup.py* file.
        
        
        How to use
        ==================
        
        The ago module comes with two functions: 
        
        #. human
        #. delta2dict
        
        You really only need to worry about *human*.
        
        Here are all the available arguments and defaults::
        
         human(dt, precision=2, past_tense='{} ago', future_tense='in {}'):
        
        dt
         either a datetime or timedelta object to become human readable, required
        
        precision
         control how verbose the output should look, optional
        
        past_tense
         format string used when dt is a past datetime, optional
        
        future_tense
         format string used when dt is a future datetime, optional
        
        
        Here is an example on how to use *human*::
        
         from ago import human
         from ago import delta2dict
         
         from datetime import datetime
         from datetime import timedelta
        
         # pretend this was stored in database
         db_date = datetime( 
           year = 2010, 
           month=5, 
           day=4, 
           hour=6, 
           minute=54, 
           second=33, 
           microsecond=4000
          )
        
         # to find out how long ago, use the human function
         print 'Created ' + human( db_date )
         
         # optionally pass a precision
         print 'Created ' + human( db_date, 3 )
         print 'Created ' + human( db_date, 6 )
        
        We also support future dates and times::
        
         PRESENT = datetime.now()
         PAST = PRESENT - timedelta( 492, 58711, 45 ) # days, secs, ms
         FUTURE = PRESENT + timedelta( 2, 12447, 963 ) # days, secs, ms
        
         print human( FUTURE )
        
        Example past_tense and future_tense keyword arguments::
        
         output1 = human( PAST,
           past_tense = 'titanic sunk {0} ago',
           future_tense = 'titanic will sink in {0} from now'
         )
        
         output2 = human( FUTURE,
           past_tense = 'titanic sunk {0} ago',
           future_tense = 'titanic will sink in {0} from now'
         )
        
         print output1
         # titanic sunk 1 year, 127 days ago
         print output2
         # titanic will sink in 2 days, 3 hours from now
        
        Now we will document how to use delta2dict::
        
         # subtract two datetime objects for a timedelta object
         delta = PRESENT - db_date
        
         # create a dictionary of units out of the timedelta
         print delta2dict( delta )
        
        
        Need more examples?
        ==========================
        
        You should look at test_ago.py
        
        
        How do I thank you?
        ==========================
        
        You should follow me on twitter http://twitter.com/russellbal
        
        
        License
        =========================
        
        Public Domain
        
        
        Public Revision Control
        ==============================
        
        https://bitbucket.org/russellballestrini/ago
        
Keywords: ago human readable time deltas timedelta datetime
Platform: All
