Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

More Time! Time as a vector space, the way it was meant to be.

Project description

Date class

A simplified date and time class for time manipulation. This library is intended for personal and business applications where assuming every solar day has 24 * 60 * 60 seconds is considered accurate. See GMT vs UTC below.


  • All time is in GMT - Timezone math is left to be resolved at the human endpoints: Machines should only be dealing with one type of time; without holes, without overlap, and with minimal context.
  • Single time type - There is no distinction between dates, datetime and times; all measurements in the time dimension are handled by one type called Date. This is important for treating time as a vector space.
  • Standard range comparision - All time range comparisons have been standardized to min <= value < max. The minimum is inclusive (<=), and the maximum is exclusive (<).

Date properties

Date() constructor

The Date() method will convert unix timestamps, millisecond timestamps, various string formats and simple time formulas to create a GMT time

now() staticmethod

Return Date instance with millisecond resolution (in GMT).

eod() staticmethod

Return end-of-day: Smallest Date which is greater than all time points in today. Think of it as tomorrow. Same as now().ceiling(DAY)

today() staticmethod

The beginning of today. Same as now().floor(DAY)

range(min, max, interval) staticmethod

Return an explicit list of Dates starting with min, each interval more than the last, but now including max. Used in defining partitions in time domains.

floor(duration=None) method

This method is usually used to perform date comparisons at the given resolution (aka duration). Round down to the nearest whole duration. duration as assumed to be DAY if not provided.

format(format="%Y-%m-%d %H:%M:%S") method

Just like strftime

milli property

Number of milliseconds since epoch

unix property

Number of seconds since epoch

add(duration) method

Add a duration to the time to get a new Date instance. The self is not modified.

addDay() method

Convenience method for self.add(DAY)

Duration class

Represents the difference between two Dates. There are two scales:

  • DAY scale - includes seconds, minutes, hours, days and weeks.
  • YEAR scale - includes months, quarters, years, and centuries.

Duration() constructor

Create a new Duration by name, by formula, by timespan, or (more rarely) number of milliseconds.

floor(interval=None) method

Round down to nearest interval size.

seconds property

return total number of seconds (including partial) in this duration (estimate given for YEAR scale)

total_seconds() method

Same as the seconds property

round(interval, decimal=0) method

Return number of given interval rounded to given decimal places

format(interval, decimal=0) method

Return a string representing self using given interval and decimal rounding

Time Vector Space

The Date and Duration objects are the point and vectors in a one dimensional vector space. As such, the + and - operators are allowed. Comparisons with (>, >=, <=, <) are also supported.


The solar day is he most popular timekeeping unit. This library chose GMT (UT1) for its base clock because of its consistent seconds in a solar day. UTC suffers from inconsistent leap seconds and makes time-math difficult, even while forcing us to make pedantic conclusions like some minutes do not have 60 seconds. Lucky for us Python's implementation of UTC (datetime.utcnow()) is wrong, and implements GMT: Which is what we use.

Error Analysis

Assuming we need a generous leap second each 6 months (the past decade saw only 4 leap seconds), then GMT deviates from UTC by up to 1 seconds over 181 days (December to June, 15,638,400 seconds) which is an error rate error = 1/15,638,400 = 0.000006395%. If we want to call the error "noise", we have a 70dB signal/noise ratio. All applications that can tolerate this level of error should use GMT as their time basis.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mo-times, version 4.23.21108
Filename, size File type Python version Upload date Hashes
Filename, size mo-times-4.23.21108.tar.gz (41.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page