Consumers

@action(atomic=None, **kwargs)[source]

Mark a method as an action.

Note

Should be used as a method decorator eg: @action()

It can be used on both async and sync methods.

from djangochannelsrestframework.decorators import action

class MyConsumer(AsyncAPIConsumer):
    queryset = User.objects.all()
    serializer_class = UserSerializer

    @action()
    async def delete_user(self, request_id, user_pk, **kwargs):
        ...

Methods decorated with @action() will be called when a json message arrives from the client with a matching action name.

The default way of sending a message to call an action is:

{
 action: "delete_user",
 request_id: 42,
 user_pk: 82
}

You can alter how AsyncAPIConsumer matches the action using the get_action_name() method.

When using on sync methods you can provide an additional option atomic=True to forcefully wrap the method in a transaction. The default value for atomic is determined by django’s default db ATOMIC_REQUESTS setting.

Parameters

atomic (Optional[bool]) –

class AsyncAPIConsumer(*args, **kwargs)

This provides an async API consumer that is very inspired by DjangoRestFrameworks ViewSets.

permission_classes     An array for Permission classes
async add_group(name)

Add a group to the set of groups this consumer is subscribed to.

Parameters

name (str) –

async check_permissions(action, **kwargs)

Check if the action should be permitted. Raises an appropriate exception if the request is not permitted.

Parameters

action (str) –

async get_action_name(content, **kwargs)

Retrieves the action name from the json message.

Returns a tuple of the action name and the argumetns that is passed to the action.

Override this method if you do not want to use {“action”: “action_name”} as the way to describe actions.

Parameters

content (Dict) –

Return type

Tuple[Optional[str], Dict]

async get_permissions(action, **kwargs)

Instantiates and returns the list of permissions that this view requires.

Parameters

action (str) –

async handle_action(action, request_id, **kwargs)

Handle a call for a given action.

This method checks permissions and handles exceptions sending them back over the ws connection to the client.

If there is no action listed on the consumer for this action name a MethodNotAllowed error is sent back over the ws connection.

Parameters
  • action (str) –

  • request_id (str) –

async handle_exception(exc, action, request_id)

Handle any exception that occurs, by sending an appropriate message

Parameters
  • exc (Exception) –

  • action (str) –

async receive_json(content, **kwargs)

Called with decoded JSON content.

Parameters

content (Dict) –

async remove_group(name)

Remove a group to the set of groups this consumer is subscribed to.

Parameters

name (str) –

async reply(action, data=None, errors=None, status=200, request_id=None)

Send a json response back to the client.

You should aim to include the request_id if possible as this helps clients link messages they have sent to responses.

Parameters

action (str) –

async websocket_connect(message)

Called when a WebSocket connection is opened.

class GenericAsyncAPIConsumer(*args, **kwargs)[source]

Base class for all other generic views, this subclasses AsyncAPIConsumer.

queryset

will be accesed when the method get_queryset is called.

serializer_class

it should correspond with the queryset model, it will be useded for the return response.

lookup_field

field used in the get_object method. Optional.

lookup_url_kwarg

url parameter used it for the lookup.

filter_queryset(queryset, **kwargs)[source]

Given a queryset, filter it with whichever filter backend is in use.

You are unlikely to want to override this method, although you may need to call it either from a list view, or from a custom get_object method if you want to apply the configured filtering backend to the default queryset.

Parameters
  • queryset (QuerySet) – cached queryset to filter.

  • kwargs – keyworded dictionary arguments.

Returns

Filtered queryset.

Return type

QuerySet

Todos:

Implement

get_object(**kwargs)[source]

Returns the object the view is displaying.

You may want to override this if you need to provide non-standard queryset lookups. Eg if objects are referenced using multiple keyword arguments in the url conf.

Parameters

kwargs – keyworded dictionary, it can be use it for filtering the queryset.

Returns

Model object class.

Return type

Model

Examples

>>> filtered_queryset = self.get_object(**{"field__gte": value})  # this way you could filter from the frontend.
get_queryset(**kwargs)[source]

Get the list of items for this view. This must be an iterable, and may be a queryset. Defaults to using self.queryset.

This method should always be used rather than accessing self.queryset directly, as self.queryset gets evaluated only once, and those results are cached for all subsequent requests.

You may want to override this if you need to provide different querysets depending on the incoming request.

(Eg. return a list of items that is specific to the user)

Parameters

kwargs – keyworded dictionary.

Returns

Queryset attribute.

Return type

QuerySet

get_serializer(action_kwargs=None, *args, **kwargs)[source]

Return the serializer instance that should be used for validating and deserializing input, and for serializing output.

Parameters
  • action_kwargs (Optional[Dict]) – keyworded dictionary from the action.

  • args – listed arguments.

  • kwargs – keyworded dictionary arguments.

Returns

Model serializer.

Return type

Serializer

get_serializer_class(**kwargs)[source]

Return the class to use for the serializer. Defaults to using self.serializer_class.

You may want to override this if you need to provide different serializations depending on the incoming request.

(Eg. admins get full serialization, others get basic serialization)

Parameters

kwargs – keyworded dictionary arguments.

Returns

Model serializer class.

Return type

Type[Serializer]

get_serializer_context(**kwargs)[source]

Extra context provided to the serializer class.

Parameters

kwargs – keyworded dictionary arguments.

Returns

Context dictionary, containing the scope and the consumer instance.

Return type

Dict[str, Any]

view_as_consumer(wrapped_view, mapped_actions=None)

Wrap a django View to be used over a json ws connection.

websocket_urlpatterns = [
    re_path(r"^user/$", view_as_consumer(UserViewSet.as_view()))
]

This exposes the django view to your websocket connection so that you can send messages:

{
 action: "retrieve",
 request_id: 42,
 query: {pk: 92}
}

The default mapping for actions is:

  • create - PUT

  • update - PATCH

  • list - GET

  • retrieve - GET

Providing a query dict in the websocket messages results in the values of this dict being writen to the GET property of the request within your django view.

Providing a parameters dict within the websocket messages results in these values being passed as kwargs to the view method (in the same way that url parameters would normally be extracted).

Parameters
  • wrapped_view (Callable[[HttpRequest], HttpResponse]) –

  • mapped_actions (Optional[Dict[str, str]]) –

Return type

DjangoViewAsConsumer