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.
==============
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)
Built Distribution
mo_times-1.0.17085-py2.7.egg
(43.5 kB
view hashes)