More documentation on source='*' for Serializer fields

[cancan101]

Right now the docs for the special value just say:

The value source='*' has a special meaning, and is used to indicate that the entire object should be passed through to the field. This can be useful for creating nested representations. (See the implementation of the PaginationSerializer class for an example.)

And as far as the PaginationSerializer, the entire implementation is just this.

What exactly does the * do and what would happen in the case of PaginationSerializer if it were omitted?

[tomchristie]

Yup totally agree we should have fuller documentation on source="*".

Not too fussed about that in the particular context of PaginationSerializer as we'll be completely revisiting the pagination API for 3.1.

Here's an example of using the source='*'

Say we have a model like so:

class UserInfoModel(model.Model):
    address_line1 = ...
    address_line2 = ...
    town = ...
    country = ...
    post_code = ...
    phone = ...
    email = ...

Now say that we wanted to split out the 'phone' and 'email' from the rest of the representation and end up with an output that looks like this:

{
    "address": {"address_line1": ..., "address_line2":..., ...}
    "contact_details": {"email": ..., "phone_number": ...}
}

We can do so by using an AddressSerializer and ContactDetailsSerializer, and passing them the complete UserInfoModel instance.

class UserInfoSerializer(serializers.Serializer)
    address = AddressSerializer(source='*')
    contact_details = ContactDetailsSerializer(source='*')

This serializer would also handle reconstructing updates from the split dictionary style, restoring all the attributes into a single dictionary that can be used to create or update a UserInfoModel instance.

And yes, more docs on this.

[ssbrewster]

More examples are always useful but would you then want to add an example for each of the serializer field core arguments (currently there is an example for the style argument only)?

[tomchristie]

@ssbrewster If someone wants to take it on, then yes. Otherwise, not a huge priority.