diff options
Diffstat (limited to 'docs/tutorial/1-serialization.md')
| -rw-r--r-- | docs/tutorial/1-serialization.md | 94 |
1 files changed, 50 insertions, 44 deletions
diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index 96214f5b..a3c19858 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -41,20 +41,7 @@ Once that's done we can create an app that we'll use to create a simple Web API. python manage.py startapp snippets -The simplest way to get up and running will probably be to use an `sqlite3` database for the tutorial. Edit the `tutorial/settings.py` file, and set the default database `"ENGINE"` to `"sqlite3"`, and `"NAME"` to `"tmp.db"`. - - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.sqlite3', - 'NAME': 'tmp.db', - 'USER': '', - 'PASSWORD': '', - 'HOST': '', - 'PORT': '', - } - } - -We'll also need to add our new `snippets` app and the `rest_framework` app to `INSTALLED_APPS`. +We'll need to add our new `snippets` app and the `rest_framework` app to `INSTALLED_APPS`. Let's edit the `tutorial/settings.py` file: INSTALLED_APPS = ( ... @@ -64,15 +51,15 @@ We'll also need to add our new `snippets` app and the `rest_framework` app to `I We also need to wire up the root urlconf, in the `tutorial/urls.py` file, to include our snippet app's URLs. - urlpatterns = patterns('', + urlpatterns = [ url(r'^', include('snippets.urls')), - ) + ] Okay, we're ready to roll. ## Creating a model to work with -For the purposes of this tutorial we're going to start by creating a simple `Snippet` model that is used to store code snippets. Go ahead and edit the `snippets` app's `models.py` file. Note: Good programming practices include comments. Although you will find them in our repository version of this tutorial code, we have omitted them here to focus on the code itself. +For the purposes of this tutorial we're going to start by creating a simple `Snippet` model that is used to store code snippets. Go ahead and edit the `snippets/models.py` file. Note: Good programming practices include comments. Although you will find them in our repository version of this tutorial code, we have omitted them here to focus on the code itself. from django.db import models from pygments.lexers import get_all_lexers @@ -98,9 +85,10 @@ For the purposes of this tutorial we're going to start by creating a simple `Sni class Meta: ordering = ('created',) -Don't forget to sync the database for the first time. +We'll also need to create an initial migration for our snippet model, and sync the database for the first time. - python manage.py syncdb + python manage.py makemigrations snippets + python manage.py migrate ## Creating a Serializer class @@ -112,42 +100,41 @@ The first thing we need to get started on our Web API is to provide a way of ser class SnippetSerializer(serializers.Serializer): - pk = serializers.Field() # Note: `Field` is an untyped read-only field. + pk = serializers.IntegerField(read_only=True) title = serializers.CharField(required=False, max_length=100) - code = serializers.CharField(widget=widgets.Textarea, - max_length=100000) + code = serializers.CharField(style={'type': 'textarea'}) linenos = serializers.BooleanField(required=False) language = serializers.ChoiceField(choices=LANGUAGE_CHOICES, default='python') style = serializers.ChoiceField(choices=STYLE_CHOICES, default='friendly') - def restore_object(self, attrs, instance=None): + def create(self, validated_attrs): """ - Create or update a new snippet instance, given a dictionary - of deserialized field values. + Create and return a new `Snippet` instance, given the validated data. + """ + return Snippet.objects.create(**validated_attrs) - Note that if we don't define this method, then deserializing - data will simply return a dictionary of items. + def update(self, instance, validated_attrs): + """ + Update and return an existing `Snippet` instance, given the validated data. """ - if instance: - # Update existing instance - instance.title = attrs.get('title', instance.title) - instance.code = attrs.get('code', instance.code) - instance.linenos = attrs.get('linenos', instance.linenos) - instance.language = attrs.get('language', instance.language) - instance.style = attrs.get('style', instance.style) - return instance + instance.title = validated_attrs.get('title', instance.title) + instance.code = validated_attrs.get('code', instance.code) + instance.linenos = validated_attrs.get('linenos', instance.linenos) + instance.language = validated_attrs.get('language', instance.language) + instance.style = validated_attrs.get('style', instance.style) + instance.save() + return instance - # Create new instance - return Snippet(**attrs) +The first part of the serializer class defines the fields that get serialized/deserialized. The `create()` and `update()` methods define how fully fledged instances are created or modified when calling `serializer.save()` -The first part of the serializer class defines the fields that get serialized/deserialized. The `restore_object` method defines how fully fledged instances get created when deserializing data. +A serializer class is very similar to a Django `Form` class, and includes similar validation flags on the various fields, such as `required`, `max_length` and `default`. -Notice that we can also use various attributes that would typically be used on form fields, such as `widget=widgets.Textarea`. These can be used to control how the serializer should render when displayed as an HTML form. This is particularly useful for controlling how the browsable API should be displayed, as we'll see later in the tutorial. +The field flags can also control how the serializer should be displayed in certain circumstances, such as when rendering to HTML. The `style={'type': 'textarea'}` flag above is equivelent to using `widget=widgets.Textarea` on a Django `Form` class. This is particularly useful for controlling how the browsable API should be displayed, as we'll see later in the tutorial. -We can actually also save ourselves some time by using the `ModelSerializer` class, as we'll see later, but for now we'll keep our serializer definition explicit. +We can actually also save ourselves some time by using the `ModelSerializer` class, as we'll see later, but for now we'll keep our serializer definition explicit. ## Working with Serializers @@ -219,6 +206,24 @@ Open the file `snippets/serializers.py` again, and edit the `SnippetSerializer` model = Snippet fields = ('id', 'title', 'code', 'linenos', 'language', 'style') +One nice property that serializers have is that you can inspect all the fields in a serializer instance, by printing it's representation. Open the Django shell with `python manange.py shell`, then try the following: + + >>> from snippets.serializers import SnippetSerializer + >>> serializer = SnippetSerializer() + >>> print repr(serializer) # In python 3 use `print(repr(serializer))` + SnippetSerializer(): + id = IntegerField(label='ID', read_only=True) + title = CharField(allow_blank=True, max_length=100, required=False) + code = CharField(style={'type': 'textarea'}) + linenos = BooleanField(required=False) + language = ChoiceField(choices=[('Clipper', 'FoxPro'), ('Cucumber', 'Gherkin'), ('RobotFramework', 'RobotFramework'), ('abap', 'ABAP'), ('ada', 'Ada')... + style = ChoiceField(choices=[('autumn', 'autumn'), ('borland', 'borland'), ('bw', 'bw'), ('colorful', 'colorful')... + +It's important to remember that `ModelSerializer` classes don't do anything particularly magical, they are simply a shortcut for creating serializer classes: + +* An automatically determined set of fields. +* Simple default implementations for the `create()` and `update()` methods. + ## Writing regular Django views using our Serializer Let's see how we can write some API views using our new Serializer class. @@ -297,11 +302,12 @@ We'll also need a view which corresponds to an individual snippet, and can be us Finally we need to wire these views up. Create the `snippets/urls.py` file: from django.conf.urls import patterns, url + from snippets import views - urlpatterns = patterns('snippets.views', - url(r'^snippets/$', 'snippet_list'), - url(r'^snippets/(?P<pk>[0-9]+)/$', 'snippet_detail'), - ) + urlpatterns = [ + url(r'^snippets/$', views.snippet_list), + url(r'^snippets/(?P<pk>[0-9]+)/$', views.snippet_detail), + ] It's worth noting that there are a couple of edge cases we're not dealing with properly at the moment. If we send malformed `json`, or if a request is made with a method that the view doesn't handle, then we'll end up with a 500 "server error" response. Still, this'll do for now. |