Action Streams

Listings of actions are available for several points of view. All streams return a QuerySet of Action items sorted by -timestamp.

Using Builtin Streams

There are several builtin streams which cover the basics, but you are never limited to them. They are available as simple functions you can import from actstream.models. Some are also available on any instance of a registered model using a GenericRelatedObjectManager behind the scenes. The examples below show you all ways of accessing them.

User Streams

User streams are the most important, like your News Feed on github. Basically you follow anyone (or anything) on your site and their actions show up here. These streams take one argument which is a User instance which is the one doing the following (usually request.user).

If optional parameter with_user_activity is passed as True, the stream will include user’s own activity like Twitter. Default is False

from actstream.models import user_stream

user_stream(request.user, with_user_activity=True)

Generates a stream of Actions from objects that request.user follows

Actor Streams

Actor streams show you what a particular actor object has done. Helpful for viewing “My Activities”.

from actstream.models import actor_stream

actor_stream(request.user)
# OR
request.user.actor_actions.all()

Generates a stream of Actions where the request.user was the actor

Action Object Streams

Action object streams show you what actions a particular instance was used as the action_object

from actstream.models import action_object_stream

action_object_stream(comment)
# OR
comment.action_object_actions.all()

Generates a stream of Actions where the comment was generated as the action_object

Target Streams

Target streams show you what actions a particular instance was used as the target

from actstream.models import target_stream

target_stream(group)
# OR
group.target_actions.all()

Generates a stream of Actions where the group was generated as the target

Model Streams

Model streams offer a much broader scope showing ALL Actions from any particular model. Argument may be a class or instance of the model.

from actstream.models import model_stream

model_stream(request.user)

Generates a stream of Actions from all User instances.

Any Streams

Any streams shows you what actions a particular object was involved in either acting as the actor, target or action_object.

from actstream.models import any_stream

any_stream(request.user)

Generates a stream of Actions where request.user was involved in any part.

Writing Custom Streams

You can override and extend the Action manager Action.objects to add your own streams. The setting ACTSTREAM_SETTINGS['MANAGER'] tells the app which manager to import and use. The builtin streams are defined in actstream/managers.py and you should check out how they are written. Streams must use the @stream decorator. They must take at least one argument which is a model instance to be used for reference when creating streams. Streams may return:

• dict - Action queryset parameters to be AND’d together

• tuple of dicts - tuple of Action queryset parameter dicts to be OR’d together

• QuerySet - raw queryset of Action objects

When returning a queryset, you do NOT need to call fetch_generic_relations() or select_related(..).

Example

To start writing your custom stream module, create a file in your app called myapp/managers.py

# myapp/managers.py
from datetime import datetime

from django.contrib.contenttypes.models import ContentType

from actstream.managers import ActionManager, stream

class MyActionManager(ActionManager):

    @stream
    def mystream(self, obj, verb='posted', time=None):
        if time is None:
            time = datetime.now()
        return obj.actor_actions.filter(verb = verb, timestamp__lte = time)

If you haven’t done so already, configure this manager to be your default Action manager by setting the MANAGER setting.

This example defines a manager with one custom stream which filters for ‘posted’ actions by verb and timestamp.

Now that stream is available directly on the Action manager through Action.objects.mystream or from the GenericRelation on any actionable model instance.

from django.contrib.auth.models import User
from actstream.models import Action

user_instance = User.objects.all()[0]
Action.objects.mystream(user_instance, 'commented')
# OR
user_instance.actor_actions.mystream('commented')