Skip to content

Commit e628d9e

Browse files
tomchristietomchristie
committed
Update documentation
1 parent ccb2b8f commit e628d9e

File tree

57 files changed

+1906
-3734
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

57 files changed

+1906
-3734
lines changed

‎.DS_Store

15 KB
Binary file not shown.

‎api-guide/authentication/index.html

Lines changed: 49 additions & 98 deletions
Large diffs are not rendered by default.

‎api-guide/content-negotiation/index.html

Lines changed: 11 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@
6565
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../metadata">
6666
Next <i class="icon-arrow-right icon-white"></i>
6767
</a>
68-
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../pagination">
68+
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../versioning">
6969
<i class="icon-arrow-left icon-white"></i> Previous
7070
</a>
7171
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="modal"><i class="icon-search icon-white"></i> Search</a>
@@ -188,6 +188,10 @@
188188
<a href="../pagination">Pagination</a>
189189
</li>
190190

191+
<li >
192+
<a href="../versioning">Versioning</a>
193+
</li>
194+
191195
<li class="active" >
192196
<a href=".">Content negotiation</a>
193197
</li>
@@ -231,6 +235,10 @@
231235
<a href="../../topics/documenting-your-api">Documenting your API</a>
232236
</li>
233237

238+
<li >
239+
<a href="../../topics/internationalization">Internationalization</a>
240+
</li>
241+
234242
<li >
235243
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
236244
</li>
@@ -260,23 +268,11 @@
260268
</li>
261269

262270
<li >
263-
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
264-
</li>
265-
266-
<li >
267-
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
268-
</li>
269-
270-
<li >
271-
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
272-
</li>
273-
274-
<li >
275-
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
271+
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
276272
</li>
277273

278274
<li >
279-
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
275+
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
280276
</li>
281277

282278
<li >
@@ -287,10 +283,6 @@
287283
<a href="../../topics/release-notes">Release Notes</a>
288284
</li>
289285

290-
<li >
291-
<a href="../../topics/credits">Credits</a>
292-
</li>
293-
294286
</ul>
295287
</li>
296288

‎api-guide/exceptions/index.html

Lines changed: 30 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,10 @@
188188
<a href="../pagination">Pagination</a>
189189
</li>
190190

191+
<li >
192+
<a href="../versioning">Versioning</a>
193+
</li>
194+
191195
<li >
192196
<a href="../content-negotiation">Content negotiation</a>
193197
</li>
@@ -231,6 +235,10 @@
231235
<a href="../../topics/documenting-your-api">Documenting your API</a>
232236
</li>
233237

238+
<li >
239+
<a href="../../topics/internationalization">Internationalization</a>
240+
</li>
241+
234242
<li >
235243
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
236244
</li>
@@ -260,23 +268,11 @@
260268
</li>
261269

262270
<li >
263-
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
264-
</li>
265-
266-
<li >
267-
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
268-
</li>
269-
270-
<li >
271-
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
272-
</li>
273-
274-
<li >
275-
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
271+
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
276272
</li>
277273

278274
<li >
279-
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
275+
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
280276
</li>
281277

282278
<li >
@@ -287,10 +283,6 @@
287283
<a href="../../topics/release-notes">Release Notes</a>
288284
</li>
289285

290-
<li >
291-
<a href="../../topics/credits">Credits</a>
292-
</li>
293-
294286
</ul>
295287
</li>
296288

@@ -393,10 +385,18 @@ <h3 id="myModalLabel">Documentation search</h3>
393385
<a href="#permissiondenied">PermissionDenied</a>
394386
</li>
395387

388+
<li>
389+
<a href="#notfound">NotFound</a>
390+
</li>
391+
396392
<li>
397393
<a href="#methodnotallowed">MethodNotAllowed</a>
398394
</li>
399395

396+
<li>
397+
<a href="#notacceptable">NotAcceptable</a>
398+
</li>
399+
400400
<li>
401401
<a href="#unsupportedmediatype">UnsupportedMediaType</a>
402402
</li>
@@ -464,7 +464,7 @@ <h2 id="exception-handling-in-rest-framework-views">Exception handling in REST f
464464
</code></pre>
465465
<h2 id="custom-exception-handling">Custom exception handling</h2>
466466
<p>You can implement custom exception handling by creating a handler function that converts exceptions raised in your API views into response objects. This allows you to control the style of error responses used by your API.</p>
467-
<p>The function must take a single argument, which is the exception to be handled, and should either return a <code>Response</code> object, or return <code>None</code> if the exception cannot be handled. If the handler returns <code>None</code> then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response.</p>
467+
<p>The function must take a pair of arguments, this first is the exception to be handled, and the second is a dictionary containing any extra context such as the view currently being handled. The exception handler function should either return a <code>Response</code> object, or return <code>None</code> if the exception cannot be handled. If the handler returns <code>None</code> then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response.</p>
468468
<p>For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so:</p>
469469
<pre><code>HTTP/1.1 405 Method Not Allowed
470470
Content-Type: application/json
@@ -475,17 +475,18 @@ <h2 id="custom-exception-handling">Custom exception handling</h2>
475475
<p>In order to alter the style of the response, you could write the following custom exception handler:</p>
476476
<pre><code>from rest_framework.views import exception_handler
477477

478-
def custom_exception_handler(exc):
478+
def custom_exception_handler(exc, context):
479479
# Call REST framework's default exception handler first,
480480
# to get the standard error response.
481-
response = exception_handler(exc)
481+
response = exception_handler(exc, context)
482482

483483
# Now add the HTTP status code to the response.
484484
if response is not None:
485485
response.data['status_code'] = response.status_code
486486

487487
return response
488488
</code></pre>
489+
<p>The context argument is not used by the default handler, but can be useful if the exception handler needs further information such as the view currently being handled, which can be accessed as <code>context['view']</code>.</p>
489490
<p>The exception handler must also be configured in your settings, using the <code>EXCEPTION_HANDLER</code> setting key. For example:</p>
490491
<pre><code>REST_FRAMEWORK = {
491492
'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
@@ -526,10 +527,18 @@ <h2 id="permissiondenied">PermissionDenied</h2>
526527
<p><strong>Signature:</strong> <code>PermissionDenied(detail=None)</code></p>
527528
<p>Raised when an authenticated request fails the permission checks.</p>
528529
<p>By default this exception results in a response with the HTTP status code "403 Forbidden".</p>
530+
<h2 id="notfound">NotFound</h2>
531+
<p><strong>Signature:</strong> <code>NotFound(detail=None)</code></p>
532+
<p>Raised when a resource does not exists at the given URL. This exception is equivalent to the standard <code>Http404</code> Django exception.</p>
533+
<p>By default this exception results in a response with the HTTP status code "404 Not Found".</p>
529534
<h2 id="methodnotallowed">MethodNotAllowed</h2>
530535
<p><strong>Signature:</strong> <code>MethodNotAllowed(method, detail=None)</code></p>
531536
<p>Raised when an incoming request occurs that does not map to a handler method on the view.</p>
532537
<p>By default this exception results in a response with the HTTP status code "405 Method Not Allowed".</p>
538+
<h2 id="notacceptable">NotAcceptable</h2>
539+
<p><strong>Signature:</strong> <code>NotAcceptable(detail=None)</code></p>
540+
<p>Raised when an incoming request occurs with an <code>Accept</code> header that cannot be satisfied by any of the available renderers.</p>
541+
<p>By default this exception results in a response with the HTTP status code "406 Not Acceptable".</p>
533542
<h2 id="unsupportedmediatype">UnsupportedMediaType</h2>
534543
<p><strong>Signature:</strong> <code>UnsupportedMediaType(media_type, detail=None)</code></p>
535544
<p>Raised if there are no parsers that can handle the content type of the request data when accessing <code>request.data</code>.</p>

‎api-guide/fields/index.html

Lines changed: 12 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,10 @@
188188
<a href="../pagination">Pagination</a>
189189
</li>
190190

191+
<li >
192+
<a href="../versioning">Versioning</a>
193+
</li>
194+
191195
<li >
192196
<a href="../content-negotiation">Content negotiation</a>
193197
</li>
@@ -231,6 +235,10 @@
231235
<a href="../../topics/documenting-your-api">Documenting your API</a>
232236
</li>
233237

238+
<li >
239+
<a href="../../topics/internationalization">Internationalization</a>
240+
</li>
241+
234242
<li >
235243
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
236244
</li>
@@ -260,23 +268,11 @@
260268
</li>
261269

262270
<li >
263-
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
264-
</li>
265-
266-
<li >
267-
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
268-
</li>
269-
270-
<li >
271-
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
272-
</li>
273-
274-
<li >
275-
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
271+
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
276272
</li>
277273

278274
<li >
279-
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
275+
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
280276
</li>
281277

282278
<li >
@@ -287,10 +283,6 @@
287283
<a href="../../topics/release-notes">Release Notes</a>
288284
</li>
289285

290-
<li >
291-
<a href="../../topics/credits">Credits</a>
292-
</li>
293-
294286
</ul>
295287
</li>
296288

@@ -661,11 +653,12 @@ <h1 id="string-fields">String fields</h1>
661653
<h2 id="charfield">CharField</h2>
662654
<p>A text representation. Optionally validates the text to be shorter than <code>max_length</code> and longer than <code>min_length</code>.</p>
663655
<p>Corresponds to <code>django.db.models.fields.CharField</code> or <code>django.db.models.fields.TextField</code>.</p>
664-
<p><strong>Signature:</strong> <code>CharField(max_length=None, min_length=None, allow_blank=False)</code></p>
656+
<p><strong>Signature:</strong> <code>CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)</code></p>
665657
<ul>
666658
<li><code>max_length</code> - Validates that the input contains no more than this number of characters.</li>
667659
<li><code>min_length</code> - Validates that the input contains no fewer than this number of characters.</li>
668660
<li><code>allow_blank</code> - If set to <code>True</code> then the empty string should be considered a valid value. If set to <code>False</code> then the empty string is considered invalid and will raise a validation error. Defaults to <code>False</code>.</li>
661+
<li><code>trim_whitespace</code> - If set to <code>True</code> then leading and trailing whitespace is trimmed. Defaults to <code>True</code>.</li>
669662
</ul>
670663
<p>The <code>allow_null</code> option is also available for string fields, although its usage is discouraged in favor of <code>allow_blank</code>. It is valid to set both <code>allow_blank=True</code> and <code>allow_null=True</code>, but doing so means that there will be two differing types of empty value permissible for string representations, which can lead to data inconsistencies and subtle application bugs.</p>
671664
<h2 id="emailfield">EmailField</h2>

‎api-guide/filtering/index.html

Lines changed: 10 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,10 @@
188188
<a href="../pagination">Pagination</a>
189189
</li>
190190

191+
<li >
192+
<a href="../versioning">Versioning</a>
193+
</li>
194+
191195
<li >
192196
<a href="../content-negotiation">Content negotiation</a>
193197
</li>
@@ -231,6 +235,10 @@
231235
<a href="../../topics/documenting-your-api">Documenting your API</a>
232236
</li>
233237

238+
<li >
239+
<a href="../../topics/internationalization">Internationalization</a>
240+
</li>
241+
234242
<li >
235243
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
236244
</li>
@@ -260,23 +268,11 @@
260268
</li>
261269

262270
<li >
263-
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
264-
</li>
265-
266-
<li >
267-
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
268-
</li>
269-
270-
<li >
271-
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
272-
</li>
273-
274-
<li >
275-
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
271+
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
276272
</li>
277273

278274
<li >
279-
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
275+
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
280276
</li>
281277

282278
<li >
@@ -287,10 +283,6 @@
287283
<a href="../../topics/release-notes">Release Notes</a>
288284
</li>
289285

290-
<li >
291-
<a href="../../topics/credits">Credits</a>
292-
</li>
293-
294286
</ul>
295287
</li>
296288

‎api-guide/format-suffixes/index.html

Lines changed: 10 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,10 @@
188188
<a href="../pagination">Pagination</a>
189189
</li>
190190

191+
<li >
192+
<a href="../versioning">Versioning</a>
193+
</li>
194+
191195
<li >
192196
<a href="../content-negotiation">Content negotiation</a>
193197
</li>
@@ -231,6 +235,10 @@
231235
<a href="../../topics/documenting-your-api">Documenting your API</a>
232236
</li>
233237

238+
<li >
239+
<a href="../../topics/internationalization">Internationalization</a>
240+
</li>
241+
234242
<li >
235243
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
236244
</li>
@@ -260,23 +268,11 @@
260268
</li>
261269

262270
<li >
263-
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
264-
</li>
265-
266-
<li >
267-
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
268-
</li>
269-
270-
<li >
271-
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
272-
</li>
273-
274-
<li >
275-
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
271+
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
276272
</li>
277273

278274
<li >
279-
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
275+
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
280276
</li>
281277

282278
<li >
@@ -287,10 +283,6 @@
287283
<a href="../../topics/release-notes">Release Notes</a>
288284
</li>
289285

290-
<li >
291-
<a href="../../topics/credits">Credits</a>
292-
</li>
293-
294286
</ul>
295287
</li>
296288

0 commit comments

Comments
 (0)