Latest docs release

api-guide/authentication.html

@@ -206,6 +206,7 @@ a.fusion-poweredby {
 <li><a href="#json-web-token-authentication">JSON Web Token Authentication</a></li>
 <li><a href="#hawk-http-authentication">Hawk HTTP Authentication</a></li>
 <li><a href="#http-signature-authentication">HTTP Signature Authentication</a></li>
+<li><a href="#djoser">Djoser</a></li>
 
               <div class="promo">
               
@@ -337,12 +338,13 @@ print token.key
 <hr />
 <h4 id="generating-tokens">Generating Tokens</h4>
 <p>If you want every user to have an automatically generated Token, you can simply catch the User's <code>post_save</code> signal.</p>
-<pre class="prettyprint lang-py"><code>from django.contrib.auth import get_user_model
+<pre class="prettyprint lang-py"><code>from django.conf import settings
+from django.contrib.auth import get_user_model
 from django.db.models.signals import post_save
 from django.dispatch import receiver
 from rest_framework.authtoken.models import Token
 
-@receiver(post_save, sender=get_user_model())
+@receiver(post_save, sender=settings.AUTH_USER_MODEL)
 def create_auth_token(sender, instance=None, created=False, **kwargs):
     if created:
         Token.objects.create(user=instance)
@@ -356,9 +358,10 @@ for user in User.objects.all():
     Token.objects.get_or_create(user=user)
 </code></pre>
 <p>When using <code>TokenAuthentication</code>, you may want to provide a mechanism for clients to obtain a token given the username and password.  REST framework provides a built-in view to provide this behavior.  To use it, add the <code>obtain_auth_token</code> view to your URLconf:</p>
-<pre class="prettyprint lang-py"><code>urlpatterns += patterns('',
-    url(r'^api-token-auth/', 'rest_framework.authtoken.views.obtain_auth_token')
-)
+<pre class="prettyprint lang-py"><code>from rest_framework.authtoken import views
+urlpatterns += [
+    url(r'^api-token-auth/', views.obtain_auth_token)
+]
 </code></pre>
 <p>Note that the URL part of the pattern can be whatever you want to use.</p>
 <p>The <code>obtain_auth_token</code> view will return a JSON response when valid <code>username</code> and <code>password</code> fields are POSTed to the view using form data or JSON:</p>
@@ -508,6 +511,8 @@ class ExampleAuthentication(authentication.BaseAuthentication):
 <p>The <a href="http://hawkrest.readthedocs.org/en/latest/">HawkREST</a> library builds on the <a href="http://mohawk.readthedocs.org/en/latest/">Mohawk</a> library to let you work with <a href="https://github.com/hueniverse/hawk">Hawk</a> signed requests and responses in your API. <a href="https://github.com/hueniverse/hawk">Hawk</a> lets two parties securely communicate with each other using messages signed by a shared key. It is based on <a href="http://tools.ietf.org/html/draft-hammer-oauth-v2-mac-token-05">HTTP MAC access authentication</a> (which was based on parts of <a href="http://oauth.net/core/1.0a">OAuth 1.0</a>).</p>
 <h2 id="http-signature-authentication">HTTP Signature Authentication</h2>
 <p>HTTP Signature (currently a <a href="https://datatracker.ietf.org/doc/draft-cavage-http-signatures/">IETF draft</a>) provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to <a href="http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html">Amazon's HTTP Signature scheme</a>, used by many of its services, it permits stateless, per-request authentication. <a href="https://github.com/etoccalino/">Elvio Toccalino</a> maintains the <a href="https://github.com/etoccalino/django-rest-framework-httpsignature">djangorestframework-httpsignature</a> package which provides an easy to use HTTP Signature Authentication mechanism.</p>
+<h2 id="djoser">Djoser</h2>
+<p><a href="https://github.com/sunscrapers/djoser">Djoser</a> library provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation. The package works with a custom user model and it uses token based authentication. This is a ready to use REST implementation of Django authentication system.</p>
           </div><!--/span-->
         </div><!--/row-->
       </div><!--/.fluid-container-->

api-guide/format-suffixes.html

@@ -219,12 +219,13 @@ used all the time.</p>
 </ul>
 <p>Example:</p>
 <pre class="prettyprint lang-py"><code>from rest_framework.urlpatterns import format_suffix_patterns
+from blog import views
 
-urlpatterns = patterns('blog.views',
-    url(r'^/$', 'api_root'),
-    url(r'^comments/$', 'comment_list'),
-    url(r'^comments/(?P&lt;pk&gt;[0-9]+)/$', 'comment_detail')
-)
+urlpatterns = [
+    url(r'^/$', views.apt_root),
+    url(r'^comments/$', views.comment_list),
+    url(r'^comments/(?P&lt;pk&gt;[0-9]+)/$', views.comment_detail)
+]
 
 urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
 </code></pre>

index.html

@@ -253,7 +253,7 @@ a.fusion-poweredby {
 <h2 id="requirements">Requirements</h2>
 <p>REST framework requires the following:</p>
 <ul>
-<li>Python (2.6.5+, 2.7, 3.2, 3.3)</li>
+<li>Python (2.6.5+, 2.7, 3.2, 3.3, 3.4)</li>
 <li>Django (1.4.2+, 1.5, 1.6, 1.7)</li>
 </ul>
 <p>The following packages are optional:</p>
@@ -283,10 +283,10 @@ pip install django-filter  # Filtering support
 )
 </code></pre>
 <p>If you're intending to use the browsable API you'll probably also want to add REST framework's login and logout views.  Add the following to your root <code>urls.py</code> file.</p>
-<pre class="prettyprint lang-py"><code>urlpatterns = patterns('',
+<pre class="prettyprint lang-py"><code>urlpatterns = [
     ...
     url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
-)
+]
 </code></pre>
 <p>Note that the URL path can be whatever you want, but you must include <code>'rest_framework.urls'</code> with the <code>'rest_framework'</code> namespace.</p>
 <h2 id="example">Example</h2>

topics/2.3-announcement.html

@@ -223,7 +223,7 @@ a.fusion-poweredby {
 <pre class="prettyprint lang-py"><code>"""
 A REST framework API for viewing and editing users and groups.
 """
-from django.conf.urls.defaults import url, patterns, include
+from django.conf.urls.defaults import url, include
 from django.contrib.auth.models import User, Group
 from rest_framework import viewsets, routers
 
@@ -244,10 +244,10 @@ router.register(r'groups', GroupViewSet)
 
 # Wire up our API using automatic URL routing.
 # Additionally, we include login URLs for the browseable API.
-urlpatterns = patterns('',
+urlpatterns = [
     url(r'^', include(router.urls)),
     url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
-)
+]
 </code></pre>
 <p>The best place to get started with ViewSets and Routers is to take a look at the <a href="../tutorial/6-viewsets-and-routers">newest section in the tutorial</a>, which demonstrates their usage.</p>
 <h2 id="simpler-views">Simpler views</h2>

topics/2.4-announcement.html

@@ -295,8 +295,8 @@ The lowest supported version of Django is now 1.4.2.</p>
 </ul>
 <h2 id="other-features">Other features</h2>
 <p>There are also a number of other features and bugfixes as <a href="release-notes#240">listed in the release notes</a>. In particular these include:</p>
-<p><a href="../api-guide/settings/#view-names-and-descriptions">Customizable view name and description functions</a> for use with the browsable API, by using the <code>VIEW_NAME_FUNCTION</code> and <code>VIEW_DESCRIPTION_FUNCTION</code> settings.</p>
-<p>Smarter <a href="../api-guide/throttling/#how-clients-are-identified">client IP identification for throttling</a>, with the addition of the <code>NUM_PROXIES</code> setting.</p>
+<p><a href="../api-guide/settings#view-names-and-descriptions">Customizable view name and description functions</a> for use with the browsable API, by using the <code>VIEW_NAME_FUNCTION</code> and <code>VIEW_DESCRIPTION_FUNCTION</code> settings.</p>
+<p>Smarter <a href="../api-guide/throttling#how-clients-are-identified">client IP identification for throttling</a>, with the addition of the <code>NUM_PROXIES</code> setting.</p>
 <p>Added the standardized <code>Retry-After</code> header to throttled responses, as per <a href="http://tools.ietf.org/html/rfc6585">RFC 6585</a>. This should now be used in preference to the custom <code>X-Throttle-Wait-Seconds</code> header which will be fully deprecated in 3.0.</p>
 <h2 id="deprecations">Deprecations</h2>
 <p>All API changes in 2.3 that previously raised <code>PendingDeprecationWarning</code> will now raise a <code>DeprecationWarning</code>, which is loud by default.</p>

topics/contributing.html

@@ -356,7 +356,8 @@ More text...
 <p>If you have some functionality that you would like to implement as a third party package it's worth contacting the <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">discussion group</a> as others may be willing to get involved.  We strongly encourage third party package development and will always try to prioritize time spent helping their development, documentation and packaging.</p>
 <p>We recommend the <a href="https://github.com/dabapps/django-reusable-app"><code>django-reusable-app</code></a> template as a good resource for getting up and running with implementing a third party Django package.</p>
 <h2 id="linking-to-your-package">Linking to your package</h2>
-<p>Once your package is decently documented and available on PyPI open a pull request or issue, and we'll add a link to it from the main REST framework documentation.</p>
+<p>Once your package is decently documented and available on PyPI open a pull request or issue, and we'll add a link to it from the main REST framework documentation. You can add your package under <strong>Third party packages</strong> of the API Guide section that best applies, like <a href="../api-guide/authentication">Authentication</a> or <a href="../api-guide/permissions">Permissions</a>. You can also link your package under the <a href="third-party-resources">Third Party Resources</a> section.</p>
+<p>We also suggest adding it to the <a href="https://www.djangopackages.com/grids/g/django-rest-framework/">REST Framework</a> grid on Django Packages.</p>
           </div><!--/span-->
         </div><!--/row-->
       </div><!--/.fluid-container-->

topics/release-notes.html

@@ -242,6 +242,15 @@ a.fusion-poweredby {
 </code></pre>
 <hr />
 <h2 id="24x-series">2.4.x series</h2>
+<h3 id="244">2.4.4</h3>
+<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.4+Release%22+">3rd November 2014</a>.</p>
+<ul>
+<li><strong>Security fix</strong>: Escape URLs when replacing <code>format=</code> query parameter, as used in dropdown on <code>GET</code> button in browsable API to allow explicit selection of JSON vs HTML output.</li>
+<li>Maintain ordering of URLs in API root view for <code>DefaultRouter</code>.</li>
+<li>Fix <code>follow=True</code> in <code>APIRequestFactory</code></li>
+<li>Resolve issue with invalid <code>read_only=True</code>, <code>required=True</code> fields being automatically generated by <code>ModelSerializer</code> in some cases.</li>
+<li>Resolve issue with <code>OPTIONS</code> requests returning incorrect information for views using <code>get_serializer_class</code> to dynamically determine serializer based on request method. </li>
+</ul>
 <h3 id="243">2.4.3</h3>
 <p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.3+Release%22+">19th September 2014</a>.</p>
 <ul>

topics/third-party-resources.html

@@ -214,6 +214,7 @@ a.fusion-poweredby {
 <li><a href="https://github.com/GetBlimp/django-rest-framework-jwt">djangorestframework-jwt</a> - Provides JSON Web Token Authentication support.</li>
 <li><a href="https://github.com/kumar303/hawkrest">hawkrest</a> - Provides Hawk HTTP Authorization.</li>
 <li><a href="https://github.com/etoccalino/django-rest-framework-httpsignature">djangorestframework-httpsignature</a> - Provides an easy to use HTTP Signature Authentication mechanism.</li>
+<li><a href="https://github.com/sunscrapers/djoser">djoser</a> - Provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation.</li>
 </ul>
 <h3 id="permissions">Permissions</h3>
 <ul>

tutorial/1-serialization.html

@@ -256,9 +256,9 @@ cd tutorial
 )
 </code></pre>
 <p>We also need to wire up the root urlconf, in the <code>tutorial/urls.py</code> file, to include our snippet app's URLs.</p>
-<pre class="prettyprint lang-py"><code>urlpatterns = patterns('',
+<pre class="prettyprint lang-py"><code>urlpatterns = [
     url(r'^', include('snippets.urls')),
-)
+]
 </code></pre>
 <p>Okay, we're ready to roll.</p>
 <h2 id="creating-a-model-to-work-with">Creating a model to work with</h2>
@@ -459,11 +459,12 @@ def snippet_detail(request, pk):
 </code></pre>
 <p>Finally we need to wire these views up.  Create the <code>snippets/urls.py</code> file:</p>
 <pre class="prettyprint lang-py"><code>from django.conf.urls import patterns, url
+from snippets import views
 
-urlpatterns = patterns('snippets.views',
-    url(r'^snippets/$', 'snippet_list'),
-    url(r'^snippets/(?P&lt;pk&gt;[0-9]+)/$', 'snippet_detail'),
-)
+urlpatterns = [
+    url(r'^snippets/$', views.snippet_list),
+    url(r'^snippets/(?P&lt;pk&gt;[0-9]+)/$', views.snippet_detail),
+]
 </code></pre>
 <p>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 <code>json</code>, 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.</p>
 <h2 id="testing-our-first-attempt-at-a-web-api">Testing our first attempt at a Web API</h2>

tutorial/2-requests-and-responses.html

@@ -294,11 +294,12 @@ def snippet_detail(request, pk):
 <p>Now update the <code>urls.py</code> file slightly, to append a set of <code>format_suffix_patterns</code> in addition to the existing URLs.</p>
 <pre class="prettyprint lang-py"><code>from django.conf.urls import patterns, url
 from rest_framework.urlpatterns import format_suffix_patterns
+from snippets import views
 
-urlpatterns = patterns('snippets.views',
-    url(r'^snippets/$', 'snippet_list'),
-    url(r'^snippets/(?P&lt;pk&gt;[0-9]+)$', 'snippet_detail'),
-)
+urlpatterns = [
+    url(r'^snippets/$', views.snippet_list),
+    url(r'^snippets/(?P&lt;pk&gt;[0-9]+)$', views.snippet_detail),
+]
 
 urlpatterns = format_suffix_patterns(urlpatterns)
 </code></pre>

tutorial/3-class-based-views.html

@@ -263,10 +263,10 @@ class SnippetList(APIView):
 from rest_framework.urlpatterns import format_suffix_patterns
 from snippets import views
 
-urlpatterns = patterns('',
+urlpatterns = [
     url(r'^snippets/$', views.SnippetList.as_view()),
     url(r'^snippets/(?P<pk>[0-9]+)/$', views.SnippetDetail.as_view()),
-)
+]
 
 urlpatterns = format_suffix_patterns(urlpatterns)
 </code></pre>

tutorial/4-authentication-and-permissions.html

@@ -311,10 +311,10 @@ url(r'^users/(?P<pk>[0-9]+)/$', views.UserDetail.as_view()),
 <pre class="prettyprint lang-py"><code>from django.conf.urls import include
 </code></pre>
 <p>And, at the end of the file, add a pattern to include the login and logout views for the browsable API.</p>
-<pre class="prettyprint lang-py"><code>urlpatterns += patterns('',
+<pre class="prettyprint lang-py"><code>urlpatterns += [
     url(r'^api-auth/', include('rest_framework.urls',
                                namespace='rest_framework')),
-)
+]
 </code></pre>
 <p>The <code>r'^api-auth/'</code> part of pattern can actually be whatever URL you want to use.  The only restriction is that the included urls must use the <code>'rest_framework'</code> namespace.</p>
 <p>Now if you open up the browser again and refresh the page you'll see a 'Login' link in the top right of the page.  If you log in as one of the users you created earlier, you'll be able to create code snippets again.</p>

tutorial/5-relationships-and-hyperlinked-apis.html

@@ -293,8 +293,8 @@ class UserSerializer(serializers.HyperlinkedModelSerializer):
 </ul>
 <p>After adding all those names into our URLconf, our final <code>snippets/urls.py</code> file should look something like this:</p>
 <pre class="prettyprint lang-py"><code># API endpoints
-urlpatterns = format_suffix_patterns(patterns('snippets.views',
-    url(r'^$', 'api_root'),
+urlpatterns = format_suffix_patterns([
+    url(r'^$', views.api_root),
     url(r'^snippets/$',
         views.SnippetList.as_view(),
         name='snippet-list'),
@@ -310,13 +310,13 @@ urlpatterns = format_suffix_patterns(patterns('snippets.views',
     url(r'^users/(?P&lt;pk&gt;[0-9]+)/$',
         views.UserDetail.as_view(),
         name='user-detail')
-))
+])
 
 # Login and logout views for the browsable API
-urlpatterns += patterns('',
+urlpatterns += [
     url(r'^api-auth/', include('rest_framework.urls',
                                namespace='rest_framework')),
-)
+]
 </code></pre>
 <h2 id="adding-pagination">Adding pagination</h2>
 <p>The list views for users and code snippets could end up returning quite a lot of instances, so really we'd like to make sure we paginate the results, and allow the API client to step through each of the individual pages.</p>

tutorial/6-viewsets-and-routers.html

@@ -275,19 +275,19 @@ user_detail = UserViewSet.as_view({
 </code></pre>
 <p>Notice how we're creating multiple views from each <code>ViewSet</code> class, by binding the http methods to the required action for each view.</p>
 <p>Now that we've bound our resources into concrete views, we can register the views with the URL conf as usual.</p>
-<pre class="prettyprint lang-py"><code>urlpatterns = format_suffix_patterns(patterns('snippets.views',
-    url(r'^$', 'api_root'),
+<pre class="prettyprint lang-py"><code>urlpatterns = format_suffix_patterns([
+    url(r'^$', api_root),
     url(r'^snippets/$', snippet_list, name='snippet-list'),
     url(r'^snippets/(?P&lt;pk&gt;[0-9]+)/$', snippet_detail, name='snippet-detail'),
     url(r'^snippets/(?P&lt;pk&gt;[0-9]+)/highlight/$', snippet_highlight, name='snippet-highlight'),
     url(r'^users/$', user_list, name='user-list'),
     url(r'^users/(?P&lt;pk&gt;[0-9]+)/$', user_detail, name='user-detail')
-))
+])
 </code></pre>
 <h2 id="using-routers">Using Routers</h2>
 <p>Because we're using <code>ViewSet</code> classes rather than <code>View</code> classes, we actually don't need to design the URL conf ourselves.  The conventions for wiring up resources into views and urls can be handled automatically, using a <code>Router</code> class.  All we need to do is register the appropriate view sets with a router, and let it do the rest.</p>
 <p>Here's our re-wired <code>urls.py</code> file.</p>
-<pre class="prettyprint lang-py"><code>from django.conf.urls import patterns, url, include
+<pre class="prettyprint lang-py"><code>from django.conf.urls import url, include
 from snippets import views
 from rest_framework.routers import DefaultRouter
 
@@ -298,10 +298,10 @@ router.register(r'users', views.UserViewSet)
 
 # The API URLs are now determined automatically by the router.
 # Additionally, we include the login URLs for the browseable API.
-urlpatterns = patterns('',
+urlpatterns = [
     url(r'^', include(router.urls)),
     url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
-)
+]
 </code></pre>
 <p>Registering the viewsets with the router is similar to providing a urlpattern.  We include two arguments - the URL prefix for the views, and the viewset itself.</p>
 <p>The <code>DefaultRouter</code> class we're using also automatically creates the API root view for us, so we can now delete the <code>api_root</code> method from our <code>views</code> module.</p>