You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+45-26Lines changed: 45 additions & 26 deletions
Original file line number
Diff line number
Diff line change
@@ -10,9 +10,9 @@ There are many ways you can contribute to Django REST framework. We'd like it t
10
10
11
11
The most important thing you can do to help push the REST framework project forward is to be actively involved wherever possible. Code contributions are often overvalued as being the primary way to get involved in a project, we don't believe that needs to be the case.
12
12
13
-
If you use REST framework, we'd love you to be vocal about your experiences with it - you might consider writing a blog post about using REST framework, or publishing a tutorial about building a project with a particular Javascript framework. Experiences from beginners can be particularly helpful because you'll be in the best position to assess which bits of REST framework are more difficult to understand and work with.
13
+
If you use REST framework, we'd love you to be vocal about your experiences with it - you might consider writing a blog post about using REST framework, or publishing a tutorial about building a project with a particular JavaScript framework. Experiences from beginners can be particularly helpful because you'll be in the best position to assess which bits of REST framework are more difficult to understand and work with.
14
14
15
-
Other really great ways you can help move the community forward include helping answer questions on the [discussion group][google-group], or setting up an [email alert on StackOverflow][so-filter] so that you get notified of any new questions with the `django-rest-framework` tag.
15
+
Other really great ways you can help move the community forward include helping to answer questions on the [discussion group][google-group], or setting up an [email alert on StackOverflow][so-filter] so that you get notified of any new questions with the `django-rest-framework` tag.
16
16
17
17
When answering questions make sure to help future contributors find their way around by hyperlinking wherever possible to related threads and tickets, and include backlinks from those items if relevant.
18
18
@@ -52,21 +52,55 @@ To start developing on Django REST framework, clone the repo:
Changes should broadly follow the [PEP 8][pep-8] style conventions, and we recommend you setup your editor to automatically indicated non-conforming styles.
55
+
Changes should broadly follow the [PEP 8][pep-8] style conventions, and we recommend you set up your editor to automatically indicate non-conforming styles.
56
56
57
57
## Testing
58
58
59
59
To run the tests, clone the repository, and then:
60
60
61
61
# Setup the virtual environment
62
62
virtualenv env
63
-
env/bin/activate
63
+
source env/bin/activate
64
64
pip install -r requirements.txt
65
65
66
66
# Run the tests
67
67
./runtests.py
68
68
69
-
You can also use the excellent [`tox`][tox] testing tool to run the tests against all supported versions of Python and Django. Install `tox` globally, and then simply run:
69
+
### Test options
70
+
71
+
Run using a more concise output style.
72
+
73
+
./runtests.py -q
74
+
75
+
Run the tests using a more concise output style, no coverage, no flake8.
76
+
77
+
./runtests.py --fast
78
+
79
+
Don't run the flake8 code linting.
80
+
81
+
./runtests.py --nolint
82
+
83
+
Only run the flake8 code linting, don't run the tests.
84
+
85
+
./runtests.py --lintonly
86
+
87
+
Run the tests for a given test case.
88
+
89
+
./runtests.py MyTestCase
90
+
91
+
Run the tests for a given test method.
92
+
93
+
./runtests.py MyTestCase.test_this_method
94
+
95
+
Shorter form to run the tests for a given test method.
96
+
97
+
./runtests.py test_this_method
98
+
99
+
Note: The test case and test method matching is fuzzy and will sometimes run other tests that contain a partial string match to the given command line input.
100
+
101
+
### Running against multiple environments
102
+
103
+
You can also use the excellent [tox][tox] testing tool to run the tests against all supported versions of Python and Django. Install `tox` globally, and then simply run:
70
104
71
105
tox
72
106
@@ -82,7 +116,7 @@ GitHub's documentation for working on pull requests is [available here][pull-req
82
116
83
117
Always run the tests before submitting pull requests, and ideally run `tox` in order to check that your modifications are compatible with both Python 2 and Python 3, and that they run properly on all supported versions of Django.
84
118
85
-
Once you've made a pull request take a look at the travis build status in the GitHub interface and make sure the tests are running as you'd expect.
119
+
Once you've made a pull request take a look at the Travis build status in the GitHub interface and make sure the tests are running as you'd expect.
86
120
87
121
![Travis status][travis-status]
88
122
@@ -96,15 +130,15 @@ Sometimes, in order to ensure your code works on various different versions of D
96
130
97
131
The documentation for REST framework is built from the [Markdown][markdown] source files in [the docs directory][docs].
98
132
99
-
There are many great markdown editors that make working with the documentation really easy. The [Mou editor for Mac][mou] is one such editor that comes highly recommended.
133
+
There are many great Markdown editors that make working with the documentation really easy. The [Mou editor for Mac][mou] is one such editor that comes highly recommended.
100
134
101
135
## Building the documentation
102
136
103
137
To build the documentation, install MkDocs with `pip install mkdocs` and then run the following command.
104
138
105
139
mkdocs build
106
140
107
-
This will build the html output into the `html` directory.
141
+
This will build the documentation into the `site` directory.
108
142
109
143
You can build the documentation and open a preview in a browser window by using the `serve` command.
110
144
@@ -117,8 +151,7 @@ Documentation should be in American English. The tone of the documentation is v
117
151
Some other tips:
118
152
119
153
* Keep paragraphs reasonably short.
120
-
* Use double spacing after the end of sentences.
121
-
* Don't use the abbreviations such as 'e.g.' but instead use long form, such as 'For example'.
154
+
* Don't use abbreviations such as 'e.g.' but instead use the long form, such as 'For example'.
122
155
123
156
## Markdown style
124
157
@@ -151,7 +184,7 @@ If you are hyperlinking to another REST framework document, you should use a rel
151
184
152
185
[authentication]: ../api-guide/authentication.md
153
186
154
-
Linking in this style means you'll be able to click the hyperlink in your markdown editor to open the referenced document. When the documentation is built, these links will be converted into regular links to HTML pages.
187
+
Linking in this style means you'll be able to click the hyperlink in your Markdown editor to open the referenced document. When the documentation is built, these links will be converted into regular links to HTML pages.
155
188
156
189
##### 3. Notes
157
190
@@ -163,30 +196,16 @@ If you want to draw attention to a note or warning, use a pair of enclosing line
163
196
164
197
---
165
198
166
-
# Third party packages
167
-
168
-
New features to REST framework are generally recommended to be implemented as third party libraries that are developed outside of the core framework. Ideally third party libraries should be properly documented and packaged, and made available on PyPI.
169
-
170
-
## Getting started
171
-
172
-
If you have some functionality that you would like to implement as a third party package it's worth contacting the [discussion group][google-group] 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.
173
-
174
-
We recommend the [`django-reusable-app`][django-reusable-app] template as a good resource for getting up and running with implementing a third party Django package.
175
-
176
-
## Linking to your package
177
-
178
-
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.
Copy file name to clipboardExpand all lines: docs/api-guide/authentication.md
+45-9Lines changed: 45 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -34,7 +34,7 @@ The value of `request.user` and `request.auth` for unauthenticated requests can
34
34
35
35
## Setting the authentication scheme
36
36
37
-
The default authentication schemes may be set globally, using the `DEFAULT_AUTHENTICATION` setting. For example.
37
+
The default authentication schemes may be set globally, using the `DEFAULT_AUTHENTICATION_CLASSES` setting. For example.
38
38
39
39
REST_FRAMEWORK = {
40
40
'DEFAULT_AUTHENTICATION_CLASSES': (
@@ -126,7 +126,6 @@ To use the `TokenAuthentication` scheme you'll need to [configure the authentica
126
126
'rest_framework.authtoken'
127
127
)
128
128
129
-
130
129
---
131
130
132
131
**Note:** Make sure to run `manage.py syncdb` after changing your settings. The `rest_framework.authtoken` app provides both Django (from v1.7) and South database migrations. See [Schema migrations](#schema-migrations) below.
@@ -249,8 +248,6 @@ Unauthenticated responses that are denied permission will result in an `HTTP 403
249
248
250
249
If you're using an AJAX style API with SessionAuthentication, you'll need to make sure you include a valid CSRF token for any "unsafe" HTTP method calls, such as `PUT`, `PATCH`, `POST` or `DELETE` requests. See the [Django CSRF documentation][csrf-ajax] for more details.
251
250
252
-
---
253
-
254
251
# Custom authentication
255
252
256
253
To implement a custom authentication scheme, subclass `BaseAuthentication` and override the `.authenticate(self, request)` method. The method should return a two-tuple of `(user, auth)` if authentication succeeds, or `None` otherwise.
@@ -293,13 +290,48 @@ The following example will authenticate any incoming request as the user given b
293
290
294
291
The following third party packages are also available.
295
292
296
-
## Digest Authentication
293
+
## Django OAuth Toolkit
297
294
298
-
HTTP digest authentication is a widely implemented scheme that was intended to replace HTTP basic authentication, and which provides a simple encrypted authentication mechanism. [Juan Riaza][juanriaza] maintains the [djangorestframework-digestauth][djangorestframework-digestauth]package which provides HTTP digest authentication support for REST framework.
295
+
The [Django OAuth Toolkit][django-oauth-toolkit] package provides OAuth 2.0 support, and works with Python 2.7 and Python 3.3+. The package is maintained by [Evonove][evonove] and uses the excellent [OAuthLib][oauthlib]. The package is well documented, and well supported and is currently our **recommended package for OAuth 2.0 support**.
299
296
300
-
## Django OAuth Toolkit
297
+
#### Installation & configuration
298
+
299
+
Install using `pip`.
300
+
301
+
pip install django-oauth-toolkit
302
+
303
+
Add the package to your `INSTALLED_APPS` and modify your REST framework settings.
For more details see the [Django REST framework - Getting started][django-oauth-toolkit-getting-started] documentation.
317
+
318
+
## Django REST framework OAuth
319
+
320
+
The [Django REST framework OAuth][django-rest-framework-oauth] package provides both OAuth1 and OAuth2 support for REST framework.
321
+
322
+
This package was previously included directly in REST framework but is now supported and maintained as a third party package.
301
323
302
-
The [Django OAuth Toolkit][django-oauth-toolkit] package provides OAuth 2.0 support, and works with Python 2.7 and Python 3.3+. The package is maintained by [Evonove][evonove] and uses the excellent [OAuthLib][oauthlib]. The package is well documented, and comes as a recommended alternative for OAuth 2.0 support.
324
+
#### Installation & configuration
325
+
326
+
Install the package using `pip`.
327
+
328
+
pip install djangorestframework-oauth
329
+
330
+
For details on configuration and usage see the Django REST framework OAuth documentation for [authentication][django-rest-framework-oauth-authentication] and [permissions][django-rest-framework-oauth-permissions].
331
+
332
+
## Digest Authentication
333
+
334
+
HTTP digest authentication is a widely implemented scheme that was intended to replace HTTP basic authentication, and which provides a simple encrypted authentication mechanism. [Juan Riaza][juanriaza] maintains the [djangorestframework-digestauth][djangorestframework-digestauth] package which provides HTTP digest authentication support for REST framework.
303
335
304
336
## Django OAuth2 Consumer
305
337
@@ -328,10 +360,14 @@ HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a
Copy file name to clipboardExpand all lines: docs/api-guide/exceptions.md
+11-1Lines changed: 11 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -18,7 +18,7 @@ The handled exceptions are:
18
18
19
19
In each case, REST framework will return a response with an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error.
20
20
21
-
By default all error responses will include a key `detail` in the body of the response, but other keys may also be included.
21
+
Most error responses will include a key `detail` in the body of the response.
22
22
23
23
For example, the following request:
24
24
@@ -33,6 +33,16 @@ Might receive an error response indicating that the `DELETE` method is not allow
33
33
34
34
{"detail": "Method 'DELETE' not allowed."}
35
35
36
+
Validation errors are handled slightly differently, and will include the field names as the keys in the response. If the validation error was not specific to a particular field then it will use the "non_field_errors" key, or whatever string value has been set for the `NON_FIELD_ERRORS_KEY` setting.
37
+
38
+
Any example validation error might look like this:
39
+
40
+
HTTP/1.1 400 Bad Request
41
+
Content-Type: application/json
42
+
Content-Length: 94
43
+
44
+
{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}
45
+
36
46
## Custom exception handling
37
47
38
48
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.
0 commit comments