The timestamp Module

*2010.10.24 11:49:23 much of this functionality exists in the dateutil included with python http://labix.org/python-dateutil I didn’t know about that module at the time Its parse function is really nice.

*2010.03.16 10:56:36 todo would be nice if format was more generalized it is difficult when there are different versions of a string depending on the degree of accuracy. (seconds, no seconds, etc)

*2009.07.17 07:36:52 considering that timestamps have different formats might be nice to associate that format with the object instance and make it settable/configurable.

depending on format could have different output for date, time, accuracies, etc.

*2010.03.16 10:20:38 some time ago... moved time to be the first keyword argument that way Timestamp objects can be initialized from a standard python datetime object, without specifying the time keyword

*2009.03.14 18:23:13 subclass datetime why_not would be nice if this were a subclass of datetime with special formatters built in tried this last week with ill effects, because...

datetime objects in python are immutable class attributes like year, month, and day are read-only

subclassing requires overriding __new__, not __init___ http://stackoverflow.com/questions/399022/why-cant-i-subclass-datetime-date http://www.python.org/doc/current/reference/datamodel.html#object.__new__

due to multiple ways of initializing, we don’t want to require that year, month, day be passed in, like datetime does

could add those arguments to the init function if that was needed by those using Timestamp objects in place of datetime objects

class moments.timestamp.Day(tstamp=None, **kwargs)

days are a 24 hour period starting at midnight (00:00) and ending at 23:59... have a number within a month and a name and number within a week have a number within a year

These are a time range too

class moments.timestamp.Month(tstamp=None, **kwargs)

using this to hold a collection of days (or weeks?) to ultimately render those days, and their content (summary) to some other representation (HTML, areaui, etc)

class moments.timestamp.Timerange(start, end=None, name='', end_is_now=False)

Timerange holds a start and end python datetime

trange can either be a string representing two timestamps separated by a ‘-‘ or just a simple tstamp string in which case it will be evaluated as a range based on accuracy

*2011.07.06 19:21:53 start can be either a text based string range “start-end” or a timestamp object representing the start of the range

*2011.07.06 22:15:06 merging in RelativeRange functions

Relative range was a class to quickly get ranges relative to ‘now’ (or start) sometimes these are more complex than just ‘future’ and ‘past’ on Timestamp

results in timeranges from specific functions

biggest_cycle()

determine what the biggest cycle is in our range... i.e. year, month, day

day(timestamp=None)

return a range for the day that timestamp falls in

days(overlap_edges=True)

return a list of all days contained in self (this could also be an iterator)

if overlap_edges is set, may extend beyond the current range rounding to the nearest full day on each end

default()

checks the accuracy of the start timestamp calls correct method automatically to generate a range based on that accuracy

from_text(trange)

will work with either a simple timestamp string or a string with a - separating two timestamp strings

check the tstamp for a range of times split if found return the range start and end

has(timestamp)

return true if timestamp is in our range

see also Timestamp.is_in(Timerange)

hour(timestamp=None)

return a range for the day that timestamp falls in

minute(timestamp=None)

return a range for the minute that timestamp falls in

month(timestamp=None)

return a range for the month that timestamp falls in

months(overlap_edges=True)

return a list of all months contained in self (this could also be an iterator)

if overlap_edges is set, may extend beyond the current range rounding to the nearest full month on each end

week(timestamp=None, week_start=0)

uses date.weekday() to determine position in the week Monday is 0, (default week_start) if another day should be used, specify in week_start

year(timestamp=None)

return a range for the year that timestamp falls in

year_past(timestamp=None)

the last 12 months

class moments.timestamp.Timestamp(auto=None, tstamp=None, cstamp=None, compact=None, now=True, format=None, accuracy=None)

Timestamps have different ways of being formatted, and this object is a common place to store these.

compact and cstamp are the same thing.

apple_compact(accuracy=None)

take a python datetime object return a string representation of that time YYYYMMDDTHHMMSS

compact(accuracy=None)

return a string representation of our internal datetime object with a format like: YYYYMMDDHHMMSS controlled by ‘accuracy’

epoch()

convert Timestamps to a ‘seconds since epoc’ format

return the current timestamp object as the number of seconds since the epoch. aka POSIX timestamp aka utime (?) *2009.11.04 13:57:55 http://stackoverflow.com/questions/255035/converting-datetime-to-posix-time

filename(suffix='.txt')

often need to generate a filename from a timestamp this makes it easy!

from_apple_compact(text_time)

take a string of the format: YYYYMMDDTHHMMSS (where T is the character ‘T’) return a python datetime object

from_compact(text_time)

take a string of the format: YYYYMMDDHHMMSS return a python datetime object

from_epoch(posix_time)

accept a posix time and convert it to a local datetime (in current Timestamp) http://docs.python.org/library/datetime.html#datetime.datetime.fromtimestamp see also datetime.utcfromtimestamp()

from_google_calendar(text_time)

take a string of the format: YYYY-MM-DDTHH:MM:SS.000-04:00 (where T is the character ‘T’) return a python datetime object

Note that timezone feature is not yet working

from_gps(text_time, offset=-4)

take a string of the gps format: apply a delta for local time zone return a python datetime object

from_text(text_time)

take a string of the format: YYYY.MM.DD HH:MM return a python datetime object

from_text2(text_time)

Month DD, YYYY

future(years=0, weeks=0, days=0, hours=0, minutes=0, seconds=0)

return a new Timestamp object that is in the future according to parameters

months are not included since it is tricky to convert those into days (months are not consistent in length) and days are what we need to boil the distance down to.

could revisit that in the future (hehe) the tricky cases will be when the function is called on the 31st of a month, and told to go into the future to a month that does not have 31 days. Should it roll back to the 30th of that future month? (or 28th in Feb?) or should it go forward?

future_month(months=1)

because future and past does not handle months, handle this separately

google_calendar(accuracy=None)

take a python datetime object return a string representation of that time YYYYMMDDTHHMMSS

is_in(timerange)

check if we are contained in the given timerange

this should be equivalent to: timerange.has(timestamp)

now()

update the timestamp to be the current time (when now() is called)

parse(text_time)

Attempt to automatically determine the time format in use

similar to dateutil.parser parse

but no timezones

note: TypeError: can’t compare offset-naive and offset-aware datetimes from dateutil.parser import parse self.dt = parse(text_time)

past(years=0, weeks=0, days=0, hours=0, minutes=0, seconds=0)

return a new Timestamp object that is in the past according to parameters

round(accuracy=None)

return a new timestamp object with the desired accuracy

text(accuracy=None)

return a string representation of our internal datetime object with a format like: YYYYMMDDHHMMSS controlled by ‘accuracy’

moments.timestamp.parse_line_for_time(line)

look at the line, determine if there is a timestamp return the timestamp, and the remainder if so