sact.epoch 1.0.2

Time object subclassing datetime allowing diverting local clock mecanism

Get timestamp from a datetime

Let's say you have some code using datetime.datetime.now():

>>> import datetime
>>> now = datetime.datetime.now()

First issue: if this variable is meant to represent a time stored as UTC in a database.

How do you get UTC timestamp from datetime ? (cf: http://bugs.python.org/issue1457227)

This is a common question. (cf: http://stackoverflow.com/questions/5067218/get-utc-timestamp-in-python-with-datetime/5499906#5499906)

The answer is datetime.datetime objects can be naive, which means unaware of the timezone. Thus, it is impossible to get UTC timestamp from this form of datetime unless you can guess the timezone yourself.

Hopefully, the timezone of your system didn't change between the datetime object creation and the moment you want to get a timestamp, if this is the case you can safely use:

>>> import sact.epoch.utils
>>> utc_timestamp = sact.epoch.utils.datetime_to_timestamp(now)

datetime_to_timestamp will ask your system for the number of seconds between EPOCH in the current timezone and the provided datetime. This is why you must ensure that datetime object was created when the same TimeZone on the system than when you run this function.

No doctest is given to your eyes on the content of the variable utc_timestamp because the output depends on the current time. And this can be often an issue you'll encounter: having complex code that depends on the current date, how do you test it ? This is the purpose of sact.epoch.Time.

Forcing to use only aware datetime

Quite quickly, you'll ask yourself: but what use have I of naive datetime.datetime objects if they can't be used in lots of cases ?

The answer is: there are no use of naive datetime.datetime.

Aware datetime objects as sact.epoch.Time contains all additional information allowing to:

• get an UTC timestamp
• compare two Time object whatever there timezone is.

Using naive datetime might even be concidered harmfull. sact.epoch.Time will ensure that all your objects are aware. By default, TimeZone won't even be dependent of your system local time, but will be stored in UTC timezone.

datetime objects:

>>> print repr(datetime.datetime.now().tzinfo)

None >>> print repr(datetime.datetime(1970, 1, 1, 1, 1).tzinfo) None

In comparison, sact.epoch.Time object will always set a timezone:

>>> print repr(sact.epoch.Time.now().tzinfo)

<TimeZone: UTC> >>> print repr(sact.epoch.Time(1970, 1, 1, 1, 1).tzinfo) <TimeZone: UTC>

Of course, as Time object is aware, a simple timestamp property is available:

>>> epoch = sact.epoch.Time(1970, 1, 1, 0, 0)
>>> epoch.timestamp

0

Diverting time

If you use sact.epoch.Time.now() in place of datetime.datetime.now(), your code will have seams to divert real time reference without touching the system clock.

Say your code is:

>>> db_timestamp = epoch.timestamp
>>> def is_it_ok():

... now = sact.epoch.Time.now().timestamp ... print 0 == ((now - db_timestamp) % 2)

is_it_ok function code should print True if number of seconds between now and epoch is odd.

This is the type of function which is quite difficult to test if you are using datetime.datetime.now(). Whole application will make extensive usage of the system clock, and will eventually be difficult to test unless you used sact.epoch.Time.now() in place of datetime.

Here's the test of the function:

>>> clock = sact.epoch.clock.ManageableClock()

By default, the clock is following the system clock. Let's stop it and set it to epoch (more on manageable clock in the docstring of the class ManageableClock):

>>> clock.stop()
>>> clock.ts = 0

Now let's use ZCA to declare this clock as new reference clock:

>>> from zope.component import globalSiteManager as gsm
>>> gsm.registerUtility(clock)

We are ready to test the function:

>>> sact.epoch.Time.now().timestamp

0 >>> is_it_ok() True

>>> clock.ts = 1
>>> sact.epoch.Time.now().timestamp
1
>>> is_it_ok()
False

Please note that ManageableClock have a wait method:

>>> clock.wait(minutes=1)
>>> sact.epoch.Time.now().timestamp

61 >>> is_it_ok() False

Of course, the execution of clock.wait is immediate. You can use a datetime.timedelta as argument of wait or any keyword args you would send to datetime.timedelta constructor (this includes days, seconds, microseconds, milliseconds, minutes, hours, weeks as of python version 2.7.1, cf: http://docs.python.org/library/datetime.html#datetime.timedelta)

Diverting timezone of system

When displaying times to the user, it is appreciated to show the time in local timezone:

>>> def what_time_is_it():

... print sact.epoch.Time.now().iso_local

Notice the shortcut iso_local property which will be of some help.

This property uses sact.epoch.TzLocal() which is responsible of giving the system local timezone:

>>> sact.epoch.TzLocal()
<TimeZone: System>

Let use the ZCA to divert the TzLocal mechanism to get the system local:

>>> from sact.epoch import testTimeZone
>>> from sact.epoch.interfaces import ITimeZone

>>> gsm.registerUtility(testTimeZone, ITimeZone, name='local')

Now we can test our function:

>>> clock.ts = 0
>>> what_time_is_it()

1970-01-01 00:05:00+00:05

The testTimeZone used is very special and recognizable on purpose: it has a constant +5 minute offset on UTC.

Internally, call to TzLocal() has been diverted:

>>> sact.epoch.TzLocal()

<TimeZone: Test>

Changes

• Update Buildout to 1.5.2. [Sébastien Douche]
• Updated buildout part doc so our docs directory layout

remains compatible with collective.sphinx.recipe 1.0.7. [Valentin Lab]

Fix

• Some date and time methods failed on already instancied datetime.

[Guillaume Savary]

Other

• Pkg: dev: minor and fixup to autogen.sh script. [Valentin Lab]

Changes

• Some minor rephrasing in the documentation. [Valentin Lab]

Fix

• Minor packaging fixups, filled the description field for PyPI,

corrected the licence, and remove a utf-8 char in the doc that was crashing python setup.py commands. [Valentin Lab]

New

• New .aslocal and .strftime_local() shortcuts in Time

object. [Valentin Lab]

Changes

• Renamed INSTALL and README to <name>.rst for github.

[Valentin Lab]

• buildout.cfg and bootstrap.py is cleaned from local

configuration. [Valentin Lab]

• Prepare for autogen.sh pre-release script. [Valentin Lab]
• Added a small doc on the Clock.wait() method. [Valentin Lab]
• Moved all docs into docs/source, written a full overview, updated conf

and changelog. [Valentin Lab]

• Prepared setup.py for release on github and pypi. [Valentin Lab]
• More doc, better doc. [Valentin Lab]
• Added a default repr for System and Test TimeZone objects.

[Valentin Lab]

• Removed dependency towards sact.test. [Valentin Lab]

Fix

• Make tests about time more stable. [Jonathan Ballet]

This test was asserting that two consecutives calls of the ts property return different result, the first call being lower than the second call. But the value returned by ts is a floating point number expressed in seconds, and it seems that, sometimes, Python's so fast that the assertion fails. Using the test command with --repeat 1000, it seems that I have 2% runs which are failing with this test on my computer. The fix should be sufficient, since each doctest lines are reinterpreted by Doctest, and I guess it should have a sufficient cost so that it now passes at 100%.

Fix

• Round_date now rounds microseconds as well as seconds. [Pascal Varet]
• Updated package repository URL. [Pascal Varet]