Stream Django

stream-django is a Django client for Stream, it supports Django from 1.11 up to and including 4.0 using Python 2.7 and 3.4, 3.5, 3.6+.

You can sign up for a Stream account at https://getstream.io/get_started.

Note there is also a lower level Python - Stream integration library which is suitable for all Python applications.

💡 This is a library for the Feeds product. The Chat SDKs can be found here.

Build activity streams & news feeds

You can build:

• Activity streams such as seen on Github
• A twitter style newsfeed
• A feed like instagram/ pinterest
• Facebook style newsfeeds
• A notification system

Example apps

You can check out our example apps built using this library (you can deploy them directly to Heroku with 1 click):

• Pinterest-like example app
• Twitter for scientists example app

Table of Contents

• Build activity streams & news feeds
• Example apps
• Table of Contents
• Installation
• Model integration
• Activity fields
• Activity extra data
• Feed manager
• Feeds bundled with feed_manager
  • User feed:
  • News feeds:
  • Notification feed:
• Follow a feed
• Showing the newsfeed
• Activity enrichment
• Templating
• Settings
• Temporarily disabling the signals
• Customizing enrichment
• Enrich extra fields
• Change how models are retrieved
• Preload related data
• Full documentation and Low level APIs access
• Copyright and License Information

Installation

Install stream_django package with pip:

pip install stream_django

add stream_django to your INSTALLED_APPS

INSTALLED_APPS = [
    ...
    'stream_django'
]

STREAM_API_KEY = 'my_api_key'
STREAM_API_SECRET = 'my_api_secret_key'

Login with Github on getstream.io and add STREAM_API_KEY and STREAM_API_SECRET to your Django settings module (you can find them in the dashboard).

Model integration

Stream Django can automatically publish new activities to your feed. Simple mixin the Activity class on the models you want to publish.

from stream_django.activity import Activity

class Tweet(models.Model, Activity):
    ...

class Like(models.Model, Activity):
    ...

Every time a Tweet is created it will be added to the user's feed. Users which follow the given user will also automatically get the new tweet in their feeds.

Activity fields

Models are stored in feeds as activities. An activity is composed of at least the following fields: actor, verb, object, time. You can also add more custom data if needed. The Activity mixin will try to set things up automatically:

object is a reference to the model instance actor is a reference to the user attribute of the instance verb is a string representation of the class name

By default the actor field will look for an attribute called user or actor and a field called created_at to track creation time. If you're user field is called differently you'll need to tell us where to look for it. Below shows an example how to set things up if your user field is called author.

class Tweet(models.Model, Activity):
    created_at = models.DateTimeField(auto_now_add=True)
    author = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)

    @property
    def activity_actor_attr(self):
        return self.author

Activity extra data

Often you'll want to store more data than just the basic fields. You achieve this by implementing the extra_activity_data method in the model.

NOTE: you should only return data that json.dumps can handle (datetime instances are supported too).

class Tweet(models.Model, Activity):

    @property
    def extra_activity_data(self):
        return {'is_retweet': self.is_retweet }

Feed manager

Django Stream comes with a feed_manager class that helps with all common feed operations.

Feeds bundled with feed_manager

To get you started the manager has 4 feeds pre configured. You can add more feeds if your application needs it. The three feeds are divided in three categories.

User feed:

The user feed stores all activities for a user. Think of it as your personal Facebook page. You can easily get this feed from the manager.

from stream_django.feed_manager import feed_manager

feed_manager.get_user_feed(user_id)

News feeds:

The news feeds (or timelines) store the activities from the people you follow. There is both a simple timeline newsfeed (similar to twitter) and an aggregated version (like facebook).

timeline = feed_manager.get_news_feeds(user_id)['timeline']
timeline_aggregated = feed_manager.get_news_feeds(user_id)['timeline_aggregated']

Notification feed:

The notification feed can be used to build notification functionality.

Below we show an example of how you can read the notification feed.

notification_feed = feed_manager.get_notification_feed(user_id)

class Tweet(models.Model, Activity):

    @property
    def activity_notify(self):
        if self.is_retweet and self.parent_tweet.author != self.author:
            target_feed = feed_manager.get_notification_feed(self.parent_tweet.author_id)
            return [target_feed]

class Follow(models.Model, Activity):

    @property
    def activity_notify(self):
        return [feed_manager.get_notification_feed(self.target_user.id)]

feed_manager.follow_user(request.user.id, target_user)

{'actor': 'core.User:1', 'verb': 'like', 'object': 'core.Like:42'}

from stream_django.enrich import Enrich

enricher = Enrich()
feed = feed_manager.get_feed('timeline', request.user.id)
activities = feed.get(limit=25)['results']
enriched_activities = enricher.enrich_activities(activities)

{% load activity_tags %}

{% for activity in activities %}
    {% render_activity activity %}
{% endfor %}

{{ activity.actor.username }} said "{{ activity.object.body }} {{ activity.created_at|timesince }} ago"

{{ activity.actor_count }} user{{ activity.actor_count|pluralize }} liked {% render_activity activity.activities.0 %}

{% render_activity activity 'homepage' %}

from stream_django.activity import create_model_reference

class Tweet(models.Model, Activity):

    @property
    def extra_activity_data(self):
        ref = create_model_reference(self.parent_tweet)
        return {'parent_tweet': ref }


# instruct the enricher to enrich actor, object and parent_tweet fields
enricher = Enrich(fields=['actor', 'object', 'parent_tweet'])
feed = feed_manager.get_feed('timeline', request.user.id)
activities = feed.get(limit=25)['results']
enriched_activities = enricher.enrich_activities(activities)

class MyEnrich(Enrich):
    '''
    Overwrites how model instances are fetched from the database
    '''

    def fetch_model_instances(self, modelClass, pks):
        '''
        returns a dict {id:modelInstance} with instances of model modelClass
        and pk in pks
        '''
        ...

class AnotherEnrich(Enrich):
    '''
    Overwrites how Likes instances are fetched from the database
    '''

    def fetch_like_instances(self, pks):
        return {l.id: l for l in Like.objects.cached_likes(ids)}

class Tweet(models.Model, Activity):

    @classmethod
    def activity_related_models(cls):
        return ['user']

from stream_django.client import stream_client

special_feed = stream_client.feed('special:42')
special_feed.follow('timeline:60')