django-rest-framework/api-guide/fields.html
2012-10-09 16:45:28 +01:00

297 lines
18 KiB
HTML

<!DOCTYPE html>
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Django REST framework</title>
<link href="http://tomchristie.github.com/django-rest-framework/img/favicon.ico" rel="icon" type="image/x-icon">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content="">
<!-- Le styles -->
<link href="http://tomchristie.github.com/django-rest-framework/css/prettify.css" rel="stylesheet">
<link href="http://tomchristie.github.com/django-rest-framework/css/bootstrap.css" rel="stylesheet">
<link href="http://tomchristie.github.com/django-rest-framework/css/bootstrap-responsive.css" rel="stylesheet">
<link href="http://tomchristie.github.com/django-rest-framework/css/default.css" rel="stylesheet">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<body onload="prettyPrint()" class="fields-page">
<div class="wrapper">
<div class="navbar navbar-inverse navbar-fixed-top">
<div class="navbar-inner">
<div class="container-fluid">
<a class="repo-link btn btn-primary btn-small" href="https://github.com/tomchristie/django-rest-framework/tree/restframework2">GitHub</a>
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="http://tomchristie.github.com/django-rest-framework">Django REST framework</a>
<div class="nav-collapse collapse">
<ul class="nav">
<li><a href="http://tomchristie.github.com/django-rest-framework">Home</a></li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorial <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/quickstart">Quickstart</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/1-serialization">1 - Serialization</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/2-requests-and-responses">2 - Requests and responses</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/3-class-based-views">3 - Class based views</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/4-authentication-permissions-and-throttling">4 - Authentication, permissions and throttling</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/5-relationships-and-hyperlinked-apis">5 - Relationships and hyperlinked APIs</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/6-resource-orientated-projects">6 - Resource orientated projects</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Guide <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/requests">Requests</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/responses">Responses</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/views">Views</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/generic-views">Generic views</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/parsers">Parsers</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/renderers">Renderers</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/serializers">Serializers</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/fields">Serializer fields</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/authentication">Authentication</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/permissions">Permissions</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/throttling">Throttling</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/pagination">Pagination</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/content-negotiation">Content negotiation</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/format-suffixes">Format suffixes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/reverse">Returning URLs</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/exceptions">Exceptions</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/status-codes">Status codes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/settings">Settings</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Topics <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/csrf">Working with AJAX and CSRF</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/browserhacks">Browser hacks</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/browsable-api">Working with the Browsable API</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
</ul>
<ul class="nav pull-right">
<!-- TODO
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Version: 2.0.0 <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="#">Trunk</a></li>
<li><a href="#">2.0.0</a></li>
</ul>
</li>
-->
</ul>
</div><!--/.nav-collapse -->
</div>
</div>
</div>
<div class="body-content">
<div class="container-fluid">
<div class="row-fluid">
<div class="span3">
<!-- TODO
<p style="margin-top: -12px">
<a class="btn btn-mini btn-primary" style="width: 60px">&laquo; previous</a>
<a class="btn btn-mini btn-primary" style="float: right; margin-right: 8px; width: 60px;">next &raquo;</a>
</p>
-->
<div id="table-of-contents">
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
<li class="main"><a href="#serializer-fields">Serializer fields</a></li>
<li class="main"><a href="#generic-fields">Generic Fields</a></li>
<li><a href="#field">Field</a></li>
<li><a href="#writablefield">WritableField</a></li>
<li><a href="#modelfield">ModelField</a></li>
<li class="main"><a href="#typed-fields">Typed Fields</a></li>
<li><a href="#booleanfield">BooleanField</a></li>
<li><a href="#charfield">CharField</a></li>
<li><a href="#emailfield">EmailField</a></li>
<li><a href="#datefield">DateField</a></li>
<li><a href="#datetimefield">DateTimeField</a></li>
<li><a href="#integerfield">IntegerField</a></li>
<li><a href="#floatfield">FloatField</a></li>
<li class="main"><a href="#relational-fields">Relational Fields</a></li>
<li><a href="#relatedfield">RelatedField</a></li>
<li><a href="#manyrelatedfield">ManyRelatedField</a></li>
<li><a href="#primarykeyrelatedfield">PrimaryKeyRelatedField</a></li>
<li><a href="#manyprimarykeyrelatedfield">ManyPrimaryKeyRelatedField</a></li>
<li><a href="#hyperlinkedrelatedfield">HyperlinkedRelatedField</a></li>
<li><a href="#manyhyperlinkedrelatedfield">ManyHyperlinkedRelatedField</a></li>
<li><a href="#hyperlinkedidentityfield">HyperLinkedIdentityField</a></li>
</ul>
</div>
</div>
<div id="main-content" class="span9">
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/fields.py"><span class="label label-info">fields.py</span></a></p>
<h1 id="serializer-fields">Serializer fields</h1>
<blockquote>
<p>Flat is better than nested.</p>
<p>&mdash; <a href="http://www.python.org/dev/peps/pep-0020/">The Zen of Python</a></p>
</blockquote>
<p>Serializer fields handle converting between primative values and internal datatypes. They also deal with validating input values, as well as retrieving and setting the values from their parent objects.</p>
<hr />
<p><strong>Note:</strong> The serializer fields are declared in fields.py, but by convention you should import them using <code>from rest_framework import serializers</code> and refer to fields as <code>serializers.&lt;FieldName&gt;</code>.</p>
<hr />
<h1 id="generic-fields">Generic Fields</h1>
<p>These generic fields are used for representing arbitrary model fields or the output of model methods.</p>
<h2 id="field">Field</h2>
<p>A generic, <strong>read-only</strong> field. You can use this field for any attribute that does not need to support write operations.</p>
<p>For example, using the following model.</p>
<pre class="prettyprint lang-py"><code>class Account(models.Model):
owner = models.ForeignKey('auth.user')
name = models.CharField(max_length=100)
created = models.DateTimeField(auto_now_add=True)
payment_expiry = models.DateTimeField()
def has_expired(self):
now = datetime.datetime.now()
return now &gt; self.payment_expiry
</code></pre>
<p>A serializer definition that looked like this:</p>
<pre class="prettyprint lang-py"><code>class AccountSerializer(serializers.HyperlinkedModelSerializer):
expired = Field(source='has_expired')
class Meta:
fields = ('url', 'owner', 'name', 'expired')
</code></pre>
<p>Would produced output similar to:</p>
<pre class="prettyprint lang-py"><code>{
'url': 'http://example.com/api/accounts/3/',
'owner': 'http://example.com/api/users/12/',
'name': 'FooCorp business account',
'expired': True
}
</code></pre>
<p>Be default, the <code>Field</code> class will perform a basic translation of the source value into primative datatypes, falling back to unicode representations of complex datatypes when neccesary.</p>
<p>You can customize this behaviour by overriding the <code>.to_native(self, value)</code> method.</p>
<h2 id="writablefield">WritableField</h2>
<p>A field that supports both read and write operations. By itself <code>WriteableField</code> does not perform any translation of input values into a given type. You won't typically use this field directly, but you may want to override it and implement the <code>.to_native(self, value)</code> and <code>.from_native(self, value)</code> methods.</p>
<h2 id="modelfield">ModelField</h2>
<p>A generic field that can be tied to any arbitrary model field. The <code>ModelField</code> class delegates the task of serialization/deserialization to it's associated model field. This field can be used to create serializer fields for custom model fields, without having to create a new custom serializer field.</p>
<p><strong>Signature:</strong> <code>ModelField(model_field=&lt;Django ModelField class&gt;)</code></p>
<hr />
<h1 id="typed-fields">Typed Fields</h1>
<p>These fields represent basic datatypes, and support both reading and writing values.</p>
<h2 id="booleanfield">BooleanField</h2>
<h2 id="charfield">CharField</h2>
<h2 id="emailfield">EmailField</h2>
<h2 id="datefield">DateField</h2>
<h2 id="datetimefield">DateTimeField</h2>
<h2 id="integerfield">IntegerField</h2>
<h2 id="floatfield">FloatField</h2>
<hr />
<h1 id="relational-fields">Relational Fields</h1>
<p>Relational fields are used to represent model relationships. They can be applied to <code>ForeignKey</code>, <code>ManyToManyField</code> and <code>OneToOneField</code> relationships, as well as to reverse relationships, and custom relationships such as <code>GenericForeignKey</code>.</p>
<h2 id="relatedfield">RelatedField</h2>
<p>This field can be applied to any of the following:</p>
<ul>
<li>A <code>ForeignKey</code> field.</li>
<li>A <code>OneToOneField</code> field.</li>
<li>A reverse OneToOne relationship</li>
<li>Any other "to-one" relationship.</li>
</ul>
<p>By default <code>RelatedField</code> will represent the target of the field using it's <code>__unicode__</code> method.</p>
<p>You can customise this behaviour by subclassing <code>ManyRelatedField</code>, and overriding the <code>.to_native(self, value)</code> method.</p>
<h2 id="manyrelatedfield">ManyRelatedField</h2>
<p>This field can be applied to any of the following:</p>
<ul>
<li>A <code>ManyToManyField</code> field.</li>
<li>A reverse ManyToMany relationship.</li>
<li>A reverse ForeignKey relationship</li>
<li>Any other "to-many" relationship.</li>
</ul>
<p>By default <code>ManyRelatedField</code> will represent the targets of the field using their <code>__unicode__</code> method.</p>
<p>For example, given the following models:</p>
<pre class="prettyprint lang-py"><code>class TaggedItem(models.Model):
"""
Tags arbitrary model instances using a generic relation.
See: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/
"""
tag = models.SlugField()
content_type = models.ForeignKey(ContentType)
object_id = models.PositiveIntegerField()
content_object = GenericForeignKey('content_type', 'object_id')
def __unicode__(self):
return self.tag
class Bookmark(models.Model):
"""
A bookmark consists of a URL, and 0 or more descriptive tags.
"""
url = models.URLField()
tags = GenericRelation(TaggedItem)
</code></pre>
<p>And a model serializer defined like this:</p>
<pre class="prettyprint lang-py"><code>class BookmarkSerializer(serializers.ModelSerializer):
tags = serializers.ManyRelatedField(source='tags')
class Meta:
model = Bookmark
exclude = ('id',)
</code></pre>
<p>The an example output format for a Bookmark instance would be:</p>
<pre class="prettyprint lang-py"><code>{
'tags': [u'django', u'python'],
'url': u'https://www.djangoproject.com/'
}
</code></pre>
<h2 id="primarykeyrelatedfield">PrimaryKeyRelatedField</h2>
<p>As with <code>RelatedField</code> field can be applied to any "to-one" relationship, such as a <code>ForeignKey</code> field.</p>
<p><code>PrimaryKeyRelatedField</code> will represent the target of the field using it's primary key.</p>
<p>Be default, <code>PrimaryKeyRelatedField</code> is read-write, although you can change this behaviour using the <code>readonly</code> flag.</p>
<h2 id="manyprimarykeyrelatedfield">ManyPrimaryKeyRelatedField</h2>
<p>As with <code>RelatedField</code> field can be applied to any "to-many" relationship, such as a <code>ManyToManyField</code> field, or a reverse <code>ForeignKey</code> relationship.</p>
<p><code>PrimaryKeyRelatedField</code> will represent the target of the field using their primary key.</p>
<p>Be default, <code>ManyPrimaryKeyRelatedField</code> is read-write, although you can change this behaviour using the <code>readonly</code> flag.</p>
<h2 id="hyperlinkedrelatedfield">HyperlinkedRelatedField</h2>
<h2 id="manyhyperlinkedrelatedfield">ManyHyperlinkedRelatedField</h2>
<h2 id="hyperlinkedidentityfield">HyperLinkedIdentityField</h2>
</div><!--/span-->
</div><!--/row-->
</div><!--/.fluid-container-->
</div><!--/.body content-->
<div id="push"></div>
</div><!--/.wrapper -->
<footer class="span12">
<p>Sponsored by <a href="http://dabapps.com/">DabApps</a>.</a></p>
</footer>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="http://tomchristie.github.com/django-rest-framework/js/jquery-1.8.1-min.js"></script>
<script src="http://tomchristie.github.com/django-rest-framework/js/prettify-1.0.js"></script>
<script src="http://tomchristie.github.com/django-rest-framework/js/bootstrap-2.1.1-min.js"></script>
<script>
//$('.side-nav').scrollspy()
var shiftWindow = function() { scrollBy(0, -50) };
if (location.hash) shiftWindow();
window.addEventListener("hashchange", shiftWindow);
$('.dropdown-menu').on('click touchstart', function(event) {
event.stopPropagation();
});
</script>
</body></html>