Skip to main content

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 <//#GMT%20vs%20UTC>`__.

Assumptions
-----------

- **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.
- **Exclusive ceiling time ranges** - All time comparisons have been
standardized to ``min <= value < max``. The minimum is inclusive, and
the maximum is excluded. (please word this better)

``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.

GMT vs UTC
----------

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


Release history Release notifications | RSS feed

Download files

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

Source Distribution

mo-times-1.0.17085.zip (50.4 kB view hashes)

Uploaded Source

Built Distribution

mo_times-1.0.17085-py2.7.egg (43.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page