soluto/shisell-python

Shisell is a service agnostic abstraction for analytic dispatchers.

Shisell is a service agnostic abstraction for analytic dispatchers.

It helps you dispatch analytic events which are scoped to a component or module. It allows providing extra data (properties), identities, and metadata to the dispatched events. Shisell's analytic dispatchers are immutable and can be composed by passing a dispatcher object to a child module. Shisell can be used as an abstraction for sending analytic events so you can easily switch or add analytic services without rewriting the event dispatching code.

Install

$ pip install shisell

Usage

At the initialization code of your app, you should create a root dispatcher object. This root dispatcher is the "parent" of all dispatchers, and it is where you would set up common properties which needs to be attached to all the dispatched events.
In order to create the root dispatcher, shisell needs to receive a writer function. The writer function is just a function that accepts an object of type AnalyticsEventModel, and usually writes it to an analytics service (e.g. Mixpanel, Google Analytics etc.). Out of the box Shisell comes with a writer function which outputs the event to the logger.

Use the following code to use the built in dispatcher:

from shisell import create_root_dispatcher
from shisell.writers import log_writer

root_dispatcher = create_root_dispatcher(log_writer)

Once the root dispatcher is created you can compose dispatchers by extending with one of the extender methods. Finally, call dispatch on one of the dispatchers with an event name.

from shisell.extenders import create_scoped, with_extra, with_identity
# Composing dispatchers
login_view_dispatcher = root_dispatcher.extend(create_scoped('LoginView'))
registration_box_dispatcher = login_view_dispatcher.extend(with_extra('type', 'registration'))
# ...
registration_box_dispatcher.extend(with_identity('email', user_email), with_extra('btn','register')).dispatch('click')

# logger output:
# {  
#    "Scope":"LoginView",
#    "Name":"click",
#    "MetaData":{},
#    "ExtraData":{  
#       "type":"registration",
#       "btn":"register"
#    },
#    "Identities":{  
#       "email":"[email protected]"
#    }
# }

Using Filters

Filters are functions which are executed by the root dispatcher when dispatching events. Filters can be used to add dynamic values to the dispatched event.
Here's an example adding a Timestamp propery:

def add_timestamp(model):
    model.ExtraData["timestamp"] = time.time()

root_dispatcher = create_root_dispatcher(log_writer).extend(with_filter(add_timestamp))

home_page_dispatcher = root_dispatcher.extend(create_scoped('HomePage'))
# ...
home_page_dispatcher.dispatch('PageView')

# console output:
# {  
#    "Scope":"HomePage",
#    "Name":"PageView",
#    "MetaData":{  
#
#    },
#    "ExtraData":{  
#       "timestamp":1537108727.4074192
#    },
#    "Identities":{  
#
#    }
# }

Extending the Dispatcher

We use several different extension methods for composing dispatchers, and you can easily add a custom one. For example, let's say that we frequently create dispatchers with several extra data properties that are part of our user model. So we have this sort of code often:

home_view_dispatcher = root_dispatcher.extend(
  with_extra('firstName', user.first_name),
  with_extra('lastName', user.last_name),
  with_extra('email', user.email),
  with_extra('age', user.age),
);

Instead of writing this code every time you can add a method that does this for you:

def with_user(user):
  new_context = AnalyticsContext()
  new_context.ExtraData['firstName'] = user.first_name
  new_context.ExtraData['lastName'] = user.last_name
  new_context.ExtraData['email'] = user.email
  new_context.ExtraData['age'] = user.age
  
  return with_context(new_context)

# Usage
home_view_dispatcher = root_dispatcher.extend(with_user(user))

Creating a Custom Root Dispatcher

When you call 'dispatch' on a dispatcher, it creates a union of the AnalyticsContext of each dispatcher along the way until reaching the root dispatcher. The default root dispatcher that is generated by calling create_root_dispatcher simply converts the unified context to an AnalyticsEventModel and passes it on to the writer function.

If you would like to use a different model than the AnalyticsEventModel you can create your own custom dispatcher by creating a new AnalyticsDispatcher and passing it a function that receives two parameters - the eventName and the context.

Note: it is the root dispatcher's responsibility to run the filters.

Contributing

Thanks for thinking about contributing! We are looking for contributions of any sort and size - features, bug fixes, documentation or anything else that you think will make shisell better.

• Fork and clone locally
• Create a topic specific branch
• Add a cool feature or fix a bug
• Add tests
• Send a Pull Request

Running Tests

$ python3 -m unittest

Running with coverage:

$ coverage run --source=shisell -m unittest
$ coverage report -m