add tests and doc changes for 'pk' #350,

modify get_fields to allow excluding using 'pk' shorctut as well

**Ammend**: remove un-intended change in setup.py

docs/api-guide/serializers.md

@@ -236,6 +236,8 @@ For example:
             model = Account
             exclude = ('id',)
 
+**Note**: All fields names in either `fields` or `exclude` must already be defined in the model or set explicitly, with the exception of `pk` which is a shortcut field to the actual primary key field of the model (by default Django sets this to `id` but can be overidden).
+
 ## Specifiying nested serialization
 
 The default `ModelSerializer` uses primary keys for relationships, but you can also easily generate nested representations using the `depth` option:

docs/tutorial/1-serialization.md

@@ -201,7 +201,7 @@ Open the file `snippets/serializers.py` again, and edit the `SnippetSerializer`
     class SnippetSerializer(serializers.ModelSerializer):
         class Meta:
             model = Snippet
-            fields = ('id', 'title', 'code', 'linenos', 'language', 'style')
+            fields = ('pk', 'title', 'code', 'linenos', 'language', 'style')
 
 
 

docs/tutorial/4-authentication-and-permissions.md

@@ -59,7 +59,7 @@ Now that we've got some users to work with, we'd better add representations of t
 
         class Meta:
             model = User
-            fields = ('id', 'username', 'snippets')
+            fields = ('pk', 'username', 'snippets')
 
 Because `'snippets'` is a *reverse* relationship on the User model, it will not be included by default when using the `ModelSerializer` class, so we've needed to add an explicit field for it.
 

rest_framework/serializers.py

@@ -130,6 +130,8 @@ class BaseSerializer(Field):
             # Set up the field
             field.initialize(parent=self, field_name=key)
 
+        pk_field = None
+
         # Add in the default fields
         fields = self.default_fields(nested)
         for key, val in fields.items():
@@ -147,7 +149,7 @@ class BaseSerializer(Field):
             new = SortedDict()
             for key in self.opts.fields:
                 if key == 'pk':
-                    # User requested the 'pk', use the primary key found
+                    # 'pk' shortcut: use the primary key found
                     new[key] = ret[pk_field]
                     continue
                 new[key] = ret[key]
@@ -156,6 +158,9 @@ class BaseSerializer(Field):
         # Remove anything in 'exclude'
         if self.opts.exclude:
             for key in self.opts.exclude:
+                if key == 'pk':
+                    # 'pk' shortcut: remove the primary key found
+                    ret.pop(pk_field)
                 ret.pop(key, None)
 
         return ret

rest_framework/tests/serializer.py

@@ -50,7 +50,7 @@ class PersonSerializer(serializers.ModelSerializer):
 
     class Meta:
         model = Person
-        fields = ('name', 'age', 'info')
+        fields = ('pk', 'name', 'age', 'info')
 
 
 class BasicTests(TestCase):
@@ -112,7 +112,7 @@ class BasicTests(TestCase):
         """
         serializer = PersonSerializer(self.person)
         self.assertEquals(set(serializer.data.keys()),
-                          set(['name', 'age', 'info']))
+                          set(['pk', 'name', 'age', 'info']))
 
     def test_field_with_dictionary(self):
         """ Make sure that dictionaries from fields are left intact
@@ -121,6 +121,14 @@ class BasicTests(TestCase):
         expected = self.person_data
         self.assertEquals(serializer.data['info'], expected)
 
+    def test_pk_field_exists(self):
+        """
+        Verify the `pk` shortcut for primary key (by default: `id`)
+        """
+
+        serializer = PersonSerializer(self.person)
+        self.assertEquals(serializer.data['pk'], self.person.id)
+
 
 class ValidationTests(TestCase):
     def setUp(self):