Snowplow Python Tracker 0.9.0 released

We are pleased to announce a new release of the Snowplow Python Tracker. We detail the new features, along with examples, below.

Version 0.9.0 includes a community contribution (many thanks @vicrep), which allows for a custom JSON encoder to be passed as a Tracker initialization parameter.

It also introduces a new way to track multiple subjects, by making event_subject an optional parameter supported by all track methods.

Additionally it allows the optional timestamp argument to only set the true_tstamp of the event, in accordance with the Snowplow Tracker Protocol.

Similar to the on_failure callback, the argument being passed to the on_success callback is now the array of successfully sent events, in order to allow users to inspect it if required.

Redis and Celery are now extras, so that users who don’t use the related functionality do not need to install them as dependencies. 

Finally, this release adds support for Unicode, publishes a Python 3 wheel in PyPI and increases the test coverage. 

Read on below for:

1. Customizing JSON encoder
2. Tracking multiple subjects
3. Setting the true_tstamp
4. On_success callback
5. Installation – Redis, Celery as extras
6. Upgrading
7. Documentation and help

1.Customizing the JSON encoder

It is now possible to customize the JSON encoder used to serialize objects added to the payload. This happens through an additional optional parameter for Tracker initialization.

For example:

from datetime import date
from json.encoder import JSONEncoder
def date_encoder(o):
    if isinstance(o,date):
        return o.isoformat()
    return JSONEncoder.default(o)

t = Tracker(my_emitter, json_encoder=date_encoder)

2. Tracking multiple subjects

With Version 0.9.0, it is now possible to set the subject per event. This allows you to track multiple subjects with a fine-grained control over the information you may want to add as your users’ journeys evolve. Prior to v0.9.0 this was only possible by mutating the Tracker-level subject, which made it problematic for multi-threaded applications (GitHub issue #158). 

Now, the Tracker-level subject will only be used for events that don’t specify an event subject as an optional argument.

You can specify an event_subject in all track methods. For example:

evSubject = Subject().set_platform("srv").set_user_id("tester")
t.track_page_view("www.example.com", event_subject=evSubject)

3. Setting the true_tstamp

The true_tstamp is the exact timestamp of when the event occurred that is set by the user using the optional timestamp argument in all track methods. If this timestamp is set, it will be the one used for determining the derived_tstamp of an event.

As described in GitHub issue #251, prior to v0.9.0:

1. Setting the true_tstamp resulted in the dvce_created_tstamp not being set
2. The user could also set the dvce_created_timestamp

With this release:

1. The user can only set the true_tstamp of an event.
2. The dvce_created_timestamp is set in all cases independently.

You can set the true_tstamp of an event by providing the optional timestamp argument in the track methods. This should be the Unix timestamp in milliseconds, for example:

import time
time_in_millis = time.time() * 1000
t.track_page_view("example.com", tstamp=time_in_millis)

If you migrate from the previous version, make sure to replace any references to Timestamp objects, since the Timestamp class (along with the TrueTimestamp and DeviceTimestamp subclasses) have been removed.

4. on_success callback argument

on_success is an optional callback that will execute on successfully sent events. Prior to v0.9.0, this callback function would receive the number of successfully sent events. With this release (GitHub issue #228), the on_success callback function will be passed the array of successfully sent events themselves, in order to augment this functionality.

For example:

def success_callback(arr):
    for event_dict in arr:
        print(event_dict)

e = Emitter("my.collector.endpoint”, on_success=success_callback)

5. Installation – Redis, Celery as extras

Through pip, you can install the Snowplow Python Tracker v0.9.0 as:

$ pip install snowplow-tracker==0.9.0

The above will not install the Redis and Celery extras. If you want to use the functionality of the RedisEmitter or RedisWorker or the CeleryEmitter, you need to install the tracker as:

$ pip install snowplow-tracker[redis]

$ pip install snowplow-tracker[celery]

6. Upgrading

As described in the corresponding sections above, in order to upgrade from the previous version, you only need to take special care if you:

1. require the extras [redis,celery] as dependencies 
2. set the optional timestamp argument in the track methods
3. use the on_success callback

7. Documentation and help

For help on integrating the tracker please have a look at the Setup guide. Information about how to use the tracker can be found in the Python Tracker Documentation. If you have any questions or run into any problems, please visit our Discourse forum.

If you are interested in the full release notes, you can find them here. Please raise any bugs in the Python Tracker’s issues on GitHub.