diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 000000000..5a830ca53 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,2 @@ +github: encode +custom: https://fund.django-rest-framework.org/topics/funding/ diff --git a/.github/ISSUE_TEMPLATE/1-issue.md b/.github/ISSUE_TEMPLATE/1-issue.md new file mode 100644 index 000000000..0da154953 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-issue.md @@ -0,0 +1,10 @@ +--- +name: Issue +about: Please only raise an issue if you've been advised to do so after discussion. Thanks! 🙏 +--- + +## Checklist + +- [ ] Raised initially as discussion #... +- [ ] This cannot be dealt with as a third party library. (We prefer new functionality to be [in the form of third party libraries](https://www.django-rest-framework.org/community/third-party-packages/#about-third-party-packages) where possible.) +- [ ] I have reduced the issue to the simplest possible case. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..382fc521a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,6 @@ +blank_issues_enabled: false +contact_links: +- name: Discussions + url: https://github.com/encode/django-rest-framework/discussions + about: > + The "Discussions" forum is where you want to start. 💖 diff --git a/.github/stale.yml b/.github/stale.yml new file mode 100644 index 000000000..f9ebbced4 --- /dev/null +++ b/.github/stale.yml @@ -0,0 +1,22 @@ +# Documentation: https://github.com/probot/stale + +# Number of days of inactivity before an issue becomes stale +daysUntilStale: 60 + +# Number of days of inactivity before a stale issue is closed +daysUntilClose: 7 + +# Comment to post when marking an issue as stale. Set to `false` to disable +markComment: > + This issue has been automatically marked as stale because it has not had + recent activity. It will be closed if no further activity occurs. Thank you + for your contributions. + +# Comment to post when closing a stale issue. Set to `false` to disable +closeComment: false + +# Limit the number of actions per hour, from 1-30. Default is 30 +limitPerRun: 1 + +# Label to use when marking as stale +staleLabel: stale diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 000000000..c88dc55cd --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,51 @@ +name: CI + +on: + push: + branches: + - master + pull_request: + +jobs: + tests: + name: Python ${{ matrix.python-version }} + runs-on: ubuntu-20.04 + + strategy: + matrix: + python-version: + - '3.6' + - '3.7' + - '3.8' + - '3.9' + - '3.10' + + steps: + - uses: actions/checkout@v3 + + - uses: actions/setup-python@v3 + with: + python-version: ${{ matrix.python-version }} + cache: 'pip' + cache-dependency-path: 'requirements/*.txt' + + - name: Upgrade packaging tools + run: python -m pip install --upgrade pip setuptools virtualenv wheel + + - name: Install dependencies + run: python -m pip install --upgrade codecov tox tox-py + + - name: Run tox targets for ${{ matrix.python-version }} + run: tox --py current + + - name: Run extra tox targets + if: ${{ matrix.python-version == '3.9' }} + run: | + python setup.py bdist_wheel + rm -r djangorestframework.egg-info # see #6139 + tox -e base,dist,docs + tox -e dist --installpkg ./dist/djangorestframework-*.whl + + - name: Upload coverage + run: | + codecov -e TOXENV,DJANGO diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml new file mode 100644 index 000000000..9c29ed056 --- /dev/null +++ b/.github/workflows/pre-commit.yml @@ -0,0 +1,24 @@ +name: pre-commit + +on: + push: + branches: + - master + pull_request: + +jobs: + pre-commit: + runs-on: ubuntu-20.04 + + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 0 + + - uses: actions/setup-python@v2 + with: + python-version: 3.9 + + - uses: pre-commit/action@v2.0.0 + with: + token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index 41768084c..641714d16 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,8 @@ *.db *~ .* +*.py.bak + /site/ /htmlcov/ @@ -13,6 +15,6 @@ MANIFEST coverage.* +!.github !.gitignore -!.travis.yml -!.isort.cfg +!.pre-commit-config.yaml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..5a6e554b9 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,20 @@ +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v3.4.0 + hooks: + - id: check-added-large-files + - id: check-case-conflict + - id: check-json + - id: check-merge-conflict + - id: check-symlinks + - id: check-toml +- repo: https://github.com/pycqa/isort + rev: 5.8.0 + hooks: + - id: isort +- repo: https://github.com/PyCQA/flake8 + rev: 3.9.0 + hooks: + - id: flake8 + additional_dependencies: + - flake8-tidy-imports diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 9543cb452..000000000 --- a/.travis.yml +++ /dev/null @@ -1,54 +0,0 @@ -language: python -cache: pip -dist: xenial -matrix: - fast_finish: true - include: - - { python: "2.7", env: DJANGO=1.11 } - - - { python: "3.4", env: DJANGO=1.11 } - - { python: "3.4", env: DJANGO=2.0 } - - - { python: "3.5", env: DJANGO=1.11 } - - { python: "3.5", env: DJANGO=2.0 } - - { python: "3.5", env: DJANGO=2.1 } - - { python: "3.5", env: DJANGO=2.2 } - - - { python: "3.6", env: DJANGO=1.11 } - - { python: "3.6", env: DJANGO=2.0 } - - { python: "3.6", env: DJANGO=2.1 } - - { python: "3.6", env: DJANGO=2.2 } - - { python: "3.6", env: DJANGO=master } - - - { python: "3.7", env: DJANGO=2.0 } - - { python: "3.7", env: DJANGO=2.1 } - - { python: "3.7", env: DJANGO=2.2 } - - { python: "3.7", env: DJANGO=master } - - - { python: "3.7", env: TOXENV=base } - - { python: "2.7", env: TOXENV=lint } - - { python: "2.7", env: TOXENV=docs } - - - python: "3.7" - env: TOXENV=dist - script: - - python setup.py bdist_wheel - - rm -r djangorestframework.egg-info # see #6139 - - tox --installpkg ./dist/djangorestframework-*.whl - - tox # test sdist - - allow_failures: - - env: DJANGO=master - -install: - - pip install tox tox-venv tox-travis - -script: - - tox - -after_success: - - pip install codecov - - codecov -e TOXENV,DJANGO - -notifications: - email: false diff --git a/.tx/config b/.tx/config new file mode 100644 index 000000000..e151a7e6f --- /dev/null +++ b/.tx/config @@ -0,0 +1,9 @@ +[main] +host = https://www.transifex.com +lang_map = sr@latin:sr_Latn, zh-Hans:zh_Hans, zh-Hant:zh_Hant + +[django-rest-framework.djangopo] +file_filter = rest_framework/locale//LC_MESSAGES/django.po +source_file = rest_framework/locale/en_US/LC_MESSAGES/django.po +source_lang = en_US +type = PO diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c947a7b8c..d567d45a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,207 +1,7 @@ # Contributing to REST framework -> The world can only really be changed one piece at a time. The art is picking that piece. -> -> — [Tim Berners-Lee][cite] +At this point in it's lifespan we consider Django REST framework to be essentially feature-complete. We may accept pull requests that track the continued development of Django versions, but would prefer not to accept new features or code formatting changes. -There are many ways you can contribute to Django REST framework. We'd like it to be a community-led project, so please get involved and help shape the future of the project. +Apart from minor documentation changes, the [GitHub discussions page](https://github.com/encode/django-rest-framework/discussions) should generally be your starting point. Please only raise an issue or pull request if you've been recommended to do so after discussion. -## Community - -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. - -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. - -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. - -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. - -## Code of conduct - -Please keep the tone polite & professional. For some users a discussion on the REST framework mailing list or ticket tracker may be their first engagement with the open source community. First impressions count, so let's try to make everyone feel welcome. - -Be mindful in the language you choose. As an example, in an environment that is heavily male-dominated, posts that start 'Hey guys,' can come across as unintentionally exclusive. It's just as easy, and more inclusive to use gender neutral language in those situations. (e.g. 'Hey folks,') - -The [Django code of conduct][code-of-conduct] gives a fuller set of guidelines for participating in community forums. - -# Issues - -It's really helpful if you can make sure to address issues on the correct channel. Usage questions should be directed to the [discussion group][google-group]. Feature requests, bug reports and other issues should be raised on the GitHub [issue tracker][issues]. - -Some tips on good issue reporting: - -* When describing issues try to phrase your ticket in terms of the *behavior* you think needs changing rather than the *code* you think need changing. -* Search the issue list first for related items, and make sure you're running the latest version of REST framework before reporting an issue. -* If reporting a bug, then try to include a pull request with a failing test case. This will help us quickly identify if there is a valid issue, and make sure that it gets fixed more quickly if there is one. -* Feature requests will often be closed with a recommendation that they be implemented outside of the core REST framework library. Keeping new feature requests implemented as third party libraries allows us to keep down the maintenance overhead of REST framework, so that the focus can be on continued stability, bug fixes, and great documentation. -* Closing an issue doesn't necessarily mean the end of a discussion. If you believe your issue has been closed incorrectly, explain why and we'll consider if it needs to be reopened. - -## Triaging issues - -Getting involved in triaging incoming issues is a good way to start contributing. Every single ticket that comes into the ticket tracker needs to be reviewed in order to determine what the next steps should be. Anyone can help out with this, you just need to be willing to: - -* Read through the ticket - does it make sense, is it missing any context that would help explain it better? -* Is the ticket reported in the correct place, would it be better suited as a discussion on the discussion group? -* If the ticket is a bug report, can you reproduce it? Are you able to write a failing test case that demonstrates the issue and that can be submitted as a pull request? -* If the ticket is a feature request, do you agree with it, and could the feature request instead be implemented as a third party package? -* If a ticket hasn't had much activity and it addresses something you need, then comment on the ticket and try to find out what's needed to get it moving again. - -# Development - -To start developing on Django REST framework, clone the repo: - - git clone https://github.com/encode/django-rest-framework - -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. - -## Testing - -To run the tests, clone the repository, and then: - - # Setup the virtual environment - virtualenv env - source env/bin/activate - pip install django - pip install -r requirements.txt - - # Run the tests - ./runtests.py - -### Test options - -Run using a more concise output style. - - ./runtests.py -q - -Run the tests using a more concise output style, no coverage, no flake8. - - ./runtests.py --fast - -Don't run the flake8 code linting. - - ./runtests.py --nolint - -Only run the flake8 code linting, don't run the tests. - - ./runtests.py --lintonly - -Run the tests for a given test case. - - ./runtests.py MyTestCase - -Run the tests for a given test method. - - ./runtests.py MyTestCase.test_this_method - -Shorter form to run the tests for a given test method. - - ./runtests.py test_this_method - -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. - -### Running against multiple environments - -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: - - tox - -## Pull requests - -It's a good idea to make pull requests early on. A pull request represents the start of a discussion, and doesn't necessarily need to be the final, finished submission. - -It's also always best to make a new branch before starting work on a pull request. This means that you'll be able to later switch back to working on another separate issue without interfering with an ongoing pull requests. - -It's also useful to remember that if you have an outstanding pull request then pushing new commits to your GitHub repo will also automatically update the pull requests. - -GitHub's documentation for working on pull requests is [available here][pull-requests]. - -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. - -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. - -## Managing compatibility issues - -Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries, you'll need to run slightly different code depending on the environment. Any code that branches in this way should be isolated into the `compat.py` module, and should provide a single common interface that the rest of the codebase can use. - -# Documentation - -The documentation for REST framework is built from the [Markdown][markdown] source files in [the docs directory][docs]. - -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. - -## Building the documentation - -To build the documentation, install MkDocs with `pip install mkdocs` and then run the following command. - - mkdocs build - -This will build the documentation into the `site` directory. - -You can build the documentation and open a preview in a browser window by using the `serve` command. - - mkdocs serve - -## Language style - -Documentation should be in American English. The tone of the documentation is very important - try to stick to a simple, plain, objective and well-balanced style where possible. - -Some other tips: - -* Keep paragraphs reasonably short. -* Don't use abbreviations such as 'e.g.' but instead use the long form, such as 'For example'. - -## Markdown style - -There are a couple of conventions you should follow when working on the documentation. - -##### 1. Headers - -Headers should use the hash style. For example: - - ### Some important topic - -The underline style should not be used. **Don't do this:** - - Some important topic - ==================== - -##### 2. Links - -Links should always use the reference style, with the referenced hyperlinks kept at the end of the document. - - Here is a link to [some other thing][other-thing]. - - More text... - - [other-thing]: http://example.com/other/thing - -This style helps keep the documentation source consistent and readable. - -If you are hyperlinking to another REST framework document, you should use a relative link, and link to the `.md` suffix. For example: - - [authentication]: ../api-guide/authentication.md - -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. - -##### 3. Notes - -If you want to draw attention to a note or warning, use a pair of enclosing lines, like so: - - --- - - **Note:** A useful documentation note. - - --- - - -[cite]: https://www.w3.org/People/Berners-Lee/FAQ.html -[code-of-conduct]: https://www.djangoproject.com/conduct/ -[google-group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework -[so-filter]: https://stackexchange.com/filters/66475/rest-framework -[issues]: https://github.com/encode/django-rest-framework/issues?state=open -[pep-8]: https://www.python.org/dev/peps/pep-0008/ -[pull-requests]: https://help.github.com/articles/using-pull-requests -[tox]: https://tox.readthedocs.io/en/latest/ -[markdown]: https://daringfireball.net/projects/markdown/basics -[docs]: https://github.com/encode/django-rest-framework/tree/master/docs -[mou]: http://mouapp.com/ +The [Contributing guide in the documentation](https://www.django-rest-framework.org/community/contributing/) gives some more information on our process and code of conduct. diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md deleted file mode 100644 index 566bf9543..000000000 --- a/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,14 +0,0 @@ -## Checklist - -- [ ] I have verified that that issue exists against the `master` branch of Django REST framework. -- [ ] I have searched for similar issues in both open and closed tickets and cannot find a duplicate. -- [ ] This is not a usage question. (Those should be directed to the [discussion group](https://groups.google.com/forum/#!forum/django-rest-framework) instead.) -- [ ] This cannot be dealt with as a third party library. (We prefer new functionality to be [in the form of third party libraries](https://www.django-rest-framework.org/community/third-party-packages/#about-third-party-packages) where possible.) -- [ ] I have reduced the issue to the simplest possible case. -- [ ] I have included a failing test as a pull request. (If you are unable to do so we can still accept the issue.) - -## Steps to reproduce - -## Expected behavior - -## Actual behavior diff --git a/MANIFEST.in b/MANIFEST.in index 6f7cb8f13..f7b975e6f 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,6 +1,7 @@ include README.md include LICENSE.md -recursive-include rest_framework/static *.js *.css *.png *.ico *.eot *.svg *.ttf *.woff *.woff2 +recursive-include tests/ * +recursive-include rest_framework/static *.js *.css *.map *.png *.ico *.eot *.svg *.ttf *.woff *.woff2 recursive-include rest_framework/templates *.html schema.js recursive-include rest_framework/locale *.mo global-exclude __pycache__ diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md index 70673c6c1..e9230d5c9 100644 --- a/PULL_REQUEST_TEMPLATE.md +++ b/PULL_REQUEST_TEMPLATE.md @@ -1,4 +1,4 @@ -*Note*: Before submitting this pull request, please review our [contributing guidelines](https://github.com/encode/django-rest-framework/blob/master/CONTRIBUTING.md#pull-requests). +*Note*: Before submitting this pull request, please review our [contributing guidelines](https://www.django-rest-framework.org/community/contributing/#pull-requests). ## Description diff --git a/README.md b/README.md index 66079edf0..e8375291d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # [Django REST framework][docs] -[![build-status-image]][travis] +[![build-status-image]][build-status] [![coverage-status-image]][codecov] [![pypi-version]][pypi] @@ -21,13 +21,14 @@ The initial aim is to provide a single full-time position on REST framework. [![][sentry-img]][sentry-url] [![][stream-img]][stream-url] -[![][rollbar-img]][rollbar-url] -[![][cadre-img]][cadre-url] -[![][kloudless-img]][kloudless-url] -[![][release-history-img]][release-history-url] -[![][lightson-img]][lightson-url] +[![][spacinov-img]][spacinov-url] +[![][retool-img]][retool-url] +[![][bitio-img]][bitio-url] +[![][posthog-img]][posthog-url] +[![][cryptapi-img]][cryptapi-url] +[![][fezto-img]][fezto-url] -Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry][sentry-url], [Stream][stream-url], [Rollbar][rollbar-url], [Cadre][cadre-url], [Kloudless][kloudless-url], [Release History][release-history-url], and [Lights On Software][lightson-url]. +Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry][sentry-url], [Stream][stream-url], [Spacinov][spacinov-url], [Retool][retool-url], [bit.io][bitio-url], [PostHog][posthog-url], [CryptAPI][cryptapi-url], and [FEZTO][fezto-url]. --- @@ -53,8 +54,8 @@ There is a live example API for testing purposes, [available here][sandbox]. # Requirements -* Python (2.7, 3.4, 3.5, 3.6, 3.7) -* Django (1.11, 2.0, 2.1, 2.2) +* Python 3.6+ +* Django 4.1, 4.0, 3.2, 3.1, 3.0 We **highly recommend** and only officially support the latest patch release of each Python and Django series. @@ -66,11 +67,12 @@ Install using `pip`... pip install djangorestframework Add `'rest_framework'` to your `INSTALLED_APPS` setting. - - INSTALLED_APPS = ( - ... - 'rest_framework', - ) +```python +INSTALLED_APPS = [ + ... + 'rest_framework', +] +``` # Example @@ -88,15 +90,16 @@ Startup up a new project like so... Now edit the `example/urls.py` module in your project: ```python -from django.conf.urls import url, include from django.contrib.auth.models import User -from rest_framework import serializers, viewsets, routers +from django.urls import include, path +from rest_framework import routers, serializers, viewsets + # Serializers define the API representation. class UserSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = User - fields = ('url', 'username', 'email', 'is_staff') + fields = ['url', 'username', 'email', 'is_staff'] # ViewSets define the view behavior. @@ -109,12 +112,11 @@ class UserViewSet(viewsets.ModelViewSet): router = routers.DefaultRouter() router.register(r'users', UserViewSet) - # Wire up our API using automatic URL routing. # Additionally, we include login URLs for the browsable API. urlpatterns = [ - url(r'^', include(router.urls)), - url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) + path('', include(router.urls)), + path('api-auth/', include('rest_framework.urls', namespace='rest_framework')), ] ``` @@ -123,16 +125,16 @@ We'd also like to configure a couple of settings for our API. Add the following to your `settings.py` module: ```python -INSTALLED_APPS = ( +INSTALLED_APPS = [ ... # Make sure to include the default installed apps here. 'rest_framework', -) +] REST_FRAMEWORK = { # Use Django's standard `django.contrib.auth` permissions, # or allow read-only access for unauthenticated users. 'DEFAULT_PERMISSION_CLASSES': [ - 'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly' + 'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly', ] } ``` @@ -169,48 +171,44 @@ Or to create a new user: Full documentation for the project is available at [https://www.django-rest-framework.org/][docs]. -For questions and support, use the [REST framework discussion group][group], or `#restframework` on freenode IRC. +For questions and support, use the [REST framework discussion group][group], or `#restframework` on libera.chat IRC. You may also want to [follow the author on Twitter][twitter]. # Security -If you believe you've found something in Django REST framework which has security implications, please **do not raise the issue in a public forum**. +Please see the [security policy][security-policy]. -Send a description of the issue via email to [rest-framework-security@googlegroups.com][security-mail]. The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure. - -[build-status-image]: https://secure.travis-ci.org/encode/django-rest-framework.svg?branch=master -[travis]: https://travis-ci.org/encode/django-rest-framework?branch=master +[build-status-image]: https://github.com/encode/django-rest-framework/actions/workflows/main.yml/badge.svg +[build-status]: https://github.com/encode/django-rest-framework/actions/workflows/main.yml [coverage-status-image]: https://img.shields.io/codecov/c/github/encode/django-rest-framework/master.svg [codecov]: https://codecov.io/github/encode/django-rest-framework?branch=master [pypi-version]: https://img.shields.io/pypi/v/djangorestframework.svg [pypi]: https://pypi.org/project/djangorestframework/ -[twitter]: https://twitter.com/_tomchristie +[twitter]: https://twitter.com/starletdreaming [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework [sandbox]: https://restframework.herokuapp.com/ [funding]: https://fund.django-rest-framework.org/topics/funding/ [sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors -[rover-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/rover-readme.png [sentry-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/sentry-readme.png [stream-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/stream-readme.png -[rollbar-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/rollbar-readme.png -[cadre-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/cadre-readme.png -[load-impact-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/load-impact-readme.png -[kloudless-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/kloudless-readme.png -[release-history-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/release-history.png -[lightson-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/lightson-readme.png +[spacinov-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/spacinov-readme.png +[retool-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/retool-readme.png +[bitio-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/bitio-readme.png +[posthog-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/posthog-readme.png +[cryptapi-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/cryptapi-readme.png +[fezto-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/fezto-readme.png -[rover-url]: http://jobs.rover.com/ [sentry-url]: https://getsentry.com/welcome/ -[stream-url]: https://getstream.io/try-the-api/?utm_source=drf&utm_medium=banner&utm_campaign=drf -[rollbar-url]: https://rollbar.com/ -[cadre-url]: https://cadre.com/ -[load-impact-url]: https://loadimpact.com/?utm_campaign=Sponsorship%20links&utm_source=drf&utm_medium=drf -[kloudless-url]: https://hubs.ly/H0f30Lf0 -[release-history-url]: https://releasehistory.io -[lightson-url]: https://lightsonsoftware.com +[stream-url]: https://getstream.io/?utm_source=DjangoRESTFramework&utm_medium=Webpage_Logo_Ad&utm_content=Developer&utm_campaign=DjangoRESTFramework_Jan2022_HomePage +[spacinov-url]: https://www.spacinov.com/ +[retool-url]: https://retool.com/?utm_source=djangorest&utm_medium=sponsorship +[bitio-url]: https://bit.io/jobs?utm_source=DRF&utm_medium=sponsor&utm_campaign=DRF_sponsorship +[posthog-url]: https://posthog.com?utm_source=drf&utm_medium=sponsorship&utm_campaign=open-source-sponsorship +[cryptapi-url]: https://cryptapi.io +[fezto-url]: https://www.fezto.xyz/?utm_source=DjangoRESTFramework [oauth1-section]: https://www.django-rest-framework.org/api-guide/authentication/#django-rest-framework-oauth [oauth2-section]: https://www.django-rest-framework.org/api-guide/authentication/#django-oauth-toolkit @@ -225,4 +223,4 @@ Send a description of the issue via email to [rest-framework-security@googlegrou [image]: https://www.django-rest-framework.org/img/quickstart.png [docs]: https://www.django-rest-framework.org/ -[security-mail]: mailto:rest-framework-security@googlegroups.com +[security-policy]: https://github.com/encode/django-rest-framework/security/policy diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..a92a1b0cf --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,9 @@ +# Security Policy + +## Reporting a Vulnerability + +Security issues are handled under the supervision of the [Django security team](https://www.djangoproject.com/foundation/teams/#security-team). + + **Please report security issues by emailing security@djangoproject.com**. + + The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure. diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 5b8a9844f..2eb3a2921 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -1,4 +1,7 @@ -source: authentication.py +--- +source: + - authentication.py +--- # Authentication @@ -8,9 +11,9 @@ source: authentication.py Authentication is the mechanism of associating an incoming request with a set of identifying credentials, such as the user the request came from, or the token that it was signed with. The [permission] and [throttling] policies can then use those credentials to determine if the request should be permitted. -REST framework provides a number of authentication schemes out of the box, and also allows you to implement custom schemes. +REST framework provides several authentication schemes out of the box, and also allows you to implement custom schemes. -Authentication is always run at the very start of the view, before the permission and throttling checks occur, and before any other code is allowed to proceed. +Authentication always runs at the very start of the view, before the permission and throttling checks occur, and before any other code is allowed to proceed. The `request.user` property will typically be set to an instance of the `contrib.auth` package's `User` class. @@ -20,7 +23,7 @@ The `request.auth` property is used for any additional authentication informatio **Note:** Don't forget that **authentication by itself won't allow or disallow an incoming request**, it simply identifies the credentials that the request was made with. -For information on how to setup the permission polices for your API please see the [permissions documentation][permission]. +For information on how to set up the permission policies for your API please see the [permissions documentation][permission]. --- @@ -37,10 +40,10 @@ The value of `request.user` and `request.auth` for unauthenticated requests can The default authentication schemes may be set globally, using the `DEFAULT_AUTHENTICATION_CLASSES` setting. For example. REST_FRAMEWORK = { - 'DEFAULT_AUTHENTICATION_CLASSES': ( + 'DEFAULT_AUTHENTICATION_CLASSES': [ 'rest_framework.authentication.BasicAuthentication', 'rest_framework.authentication.SessionAuthentication', - ) + ] } You can also set the authentication scheme on a per-view or per-viewset basis, @@ -52,25 +55,25 @@ using the `APIView` class-based views. from rest_framework.views import APIView class ExampleView(APIView): - authentication_classes = (SessionAuthentication, BasicAuthentication) - permission_classes = (IsAuthenticated,) + authentication_classes = [SessionAuthentication, BasicAuthentication] + permission_classes = [IsAuthenticated] def get(self, request, format=None): content = { - 'user': unicode(request.user), # `django.contrib.auth.User` instance. - 'auth': unicode(request.auth), # None + 'user': str(request.user), # `django.contrib.auth.User` instance. + 'auth': str(request.auth), # None } return Response(content) Or, if you're using the `@api_view` decorator with function based views. @api_view(['GET']) - @authentication_classes((SessionAuthentication, BasicAuthentication)) - @permission_classes((IsAuthenticated,)) + @authentication_classes([SessionAuthentication, BasicAuthentication]) + @permission_classes([IsAuthenticated]) def example_view(request, format=None): content = { - 'user': unicode(request.user), # `django.contrib.auth.User` instance. - 'auth': unicode(request.auth), # None + 'user': str(request.user), # `django.contrib.auth.User` instance. + 'auth': str(request.auth), # None } return Response(content) @@ -117,20 +120,26 @@ Unauthenticated responses that are denied permission will result in an `HTTP 401 ## TokenAuthentication +--- + +**Note:** The token authentication provided by Django REST framework is a fairly simple implementation. + +For an implementation which allows more than one token per user, has some tighter security implementation details, and supports token expiry, please see the [Django REST Knox][django-rest-knox] third party package. + +--- + This authentication scheme uses a simple token-based HTTP Authentication scheme. Token authentication is appropriate for client-server setups, such as native desktop and mobile clients. To use the `TokenAuthentication` scheme you'll need to [configure the authentication classes](#setting-the-authentication-scheme) to include `TokenAuthentication`, and additionally include `rest_framework.authtoken` in your `INSTALLED_APPS` setting: - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'rest_framework.authtoken' - ) + ] ---- +Make sure to run `manage.py migrate` after changing your settings. -**Note:** Make sure to run `manage.py migrate` after changing your settings. The `rest_framework.authtoken` app provides Django database migrations. - ---- +The `rest_framework.authtoken` app provides Django database migrations. You'll also need to create tokens for your users. @@ -143,7 +152,7 @@ For clients to authenticate, the token key should be included in the `Authorizat Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b -**Note:** If you want to use a different keyword in the header, such as `Bearer`, simply subclass `TokenAuthentication` and set the `keyword` class variable. +*If you want to use a different keyword in the header, such as `Bearer`, simply subclass `TokenAuthentication` and set the `keyword` class variable.* If successfully authenticated, `TokenAuthentication` provides the following credentials. @@ -164,9 +173,9 @@ The `curl` command line tool may be useful for testing token authenticated APIs. --- -#### Generating Tokens +### Generating Tokens -##### By using signals +#### By using signals If you want every user to have an automatically generated Token, you can simply catch the User's `post_save` signal. @@ -190,13 +199,13 @@ If you've already created some users, you can generate tokens for all existing u for user in User.objects.all(): Token.objects.get_or_create(user=user) -##### By exposing an api endpoint +#### By exposing an api endpoint When using `TokenAuthentication`, 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 `obtain_auth_token` view to your URLconf: from rest_framework.authtoken import views urlpatterns += [ - url(r'^api-token-auth/', views.obtain_auth_token) + path('api-token-auth/', views.obtain_auth_token) ] Note that the URL part of the pattern can be whatever you want to use. @@ -207,7 +216,7 @@ The `obtain_auth_token` view will return a JSON response when valid `username` a Note that the default `obtain_auth_token` view explicitly uses JSON requests and responses, rather than using default renderer and parser classes in your settings. -By default there are no permissions or throttling applied to the `obtain_auth_token` view. If you do wish to apply throttling you'll need to override the view class, +By default, there are no permissions or throttling applied to the `obtain_auth_token` view. If you do wish to apply throttling you'll need to override the view class, and include them using the `throttle_classes` attribute. If you need a customized version of the `obtain_auth_token` view, you can do so by subclassing the `ObtainAuthToken` view class, and using that in your url conf instead. @@ -235,19 +244,19 @@ For example, you may return additional user information beyond the `token` value And in your `urls.py`: urlpatterns += [ - url(r'^api-token-auth/', CustomAuthToken.as_view()) + path('api-token-auth/', CustomAuthToken.as_view()) ] -##### With Django admin +#### With Django admin -It is also possible to create Tokens manually through admin interface. In case you are using a large user base, we recommend that you monkey patch the `TokenAdmin` class to customize it to your needs, more specifically by declaring the `user` field as `raw_field`. +It is also possible to create Tokens manually through the admin interface. In case you are using a large user base, we recommend that you monkey patch the `TokenAdmin` class to customize it to your needs, more specifically by declaring the `user` field as `raw_field`. `your_app/admin.py`: from rest_framework.authtoken.admin import TokenAdmin - TokenAdmin.raw_id_fields = ('user',) + TokenAdmin.raw_id_fields = ['user'] #### Using Django manage.py command @@ -276,11 +285,11 @@ If successfully authenticated, `SessionAuthentication` provides the following cr Unauthenticated responses that are denied permission will result in an `HTTP 403 Forbidden` response. -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. +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. **Warning**: Always use Django's standard login view when creating login pages. This will ensure your login views are properly protected. -CSRF validation in REST framework works slightly differently to standard Django due to the need to support both session and non-session based authentication to the same views. This means that only authenticated requests require CSRF tokens, and anonymous requests may be sent without CSRF tokens. This behaviour is not suitable for login views, which should always have CSRF validation applied. +CSRF validation in REST framework works slightly differently from standard Django due to the need to support both session and non-session based authentication to the same views. This means that only authenticated requests require CSRF tokens, and anonymous requests may be sent without CSRF tokens. This behavior is not suitable for login views, which should always have CSRF validation applied. ## RemoteUserAuthentication @@ -290,7 +299,7 @@ environment variable. To use it, you must have `django.contrib.auth.backends.RemoteUserBackend` (or a subclass) in your `AUTHENTICATION_BACKENDS` setting. By default, `RemoteUserBackend` creates `User` objects for usernames that don't -already exist. To change this and other behaviour, consult the +already exist. To change this and other behavior, consult the [Django documentation](https://docs.djangoproject.com/en/stable/howto/auth-remote-user/). If successfully authenticated, `RemoteUserAuthentication` provides the following credentials: @@ -298,10 +307,10 @@ If successfully authenticated, `RemoteUserAuthentication` provides the following * `request.user` will be a Django `User` instance. * `request.auth` will be `None`. -Consult your web server's documentation for information about configuring an authentication method, e.g.: +Consult your web server's documentation for information about configuring an authentication method, for example: * [Apache Authentication How-To](https://httpd.apache.org/docs/2.4/howto/auth.html) -* [NGINX (Restricting Access)](https://www.nginx.com/resources/admin-guide/#restricting_access) +* [NGINX (Restricting Access)](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/) # Custom authentication @@ -313,7 +322,7 @@ In some circumstances instead of returning `None`, you may want to raise an `Aut Typically the approach you should take is: * If authentication is not attempted, return `None`. Any other authentication schemes also in use will still be checked. -* If authentication is attempted but fails, raise a `AuthenticationFailed` exception. An error response will be returned immediately, regardless of any permissions checks, and without checking any other authentication schemes. +* If authentication is attempted but fails, raise an `AuthenticationFailed` exception. An error response will be returned immediately, regardless of any permissions checks, and without checking any other authentication schemes. You *may* also override the `.authenticate_header(self, request)` method. If implemented, it should return a string that will be used as the value of the `WWW-Authenticate` header in a `HTTP 401 Unauthorized` response. @@ -321,21 +330,21 @@ If the `.authenticate_header()` method is not overridden, the authentication sch --- -**Note:** When your custom authenticator is invoked by the request object's `.user` or `.auth` properties, you may see an `AttributeError` re-raised as a `WrappedAttributeError`. This is necessary to prevent the original exception from being suppressed by the outer property access. Python will not recognize that the `AttributeError` orginates from your custom authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. These errors should be fixed or otherwise handled by your authenticator. +**Note:** When your custom authenticator is invoked by the request object's `.user` or `.auth` properties, you may see an `AttributeError` re-raised as a `WrappedAttributeError`. This is necessary to prevent the original exception from being suppressed by the outer property access. Python will not recognize that the `AttributeError` originates from your custom authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. These errors should be fixed or otherwise handled by your authenticator. --- ## Example -The following example will authenticate any incoming request as the user given by the username in a custom request header named 'X_USERNAME'. +The following example will authenticate any incoming request as the user given by the username in a custom request header named 'X-USERNAME'. - from django.contrib.auth.models import User + from django.contrib.auth.models import User from rest_framework import authentication from rest_framework import exceptions class ExampleAuthentication(authentication.BaseAuthentication): def authenticate(self, request): - username = request.META.get('X_USERNAME') + username = request.META.get('HTTP_X_USERNAME') if not username: return None @@ -350,13 +359,17 @@ The following example will authenticate any incoming request as the user given b # Third party packages -The following third party packages are also available. +The following third-party packages are also available. + +## django-rest-knox + +[Django-rest-knox][django-rest-knox] library provides models and views to handle token-based authentication in a more secure and extensible way than the built-in TokenAuthentication scheme - with Single Page Applications and Mobile clients in mind. It provides per-client tokens, and views to generate them when provided some other authentication (usually basic authentication), to delete the token (providing a server enforced logout) and to delete all tokens (logs out all clients that a user is logged into). ## Django OAuth Toolkit -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**. +The [Django OAuth Toolkit][django-oauth-toolkit] package provides OAuth 2.0 support and works with Python 3.4+. The package is maintained by [jazzband][jazzband] 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**. -#### Installation & configuration +### Installation & configuration Install using `pip`. @@ -364,15 +377,15 @@ Install using `pip`. Add the package to your `INSTALLED_APPS` and modify your REST framework settings. - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'oauth2_provider', - ) + ] REST_FRAMEWORK = { - 'DEFAULT_AUTHENTICATION_CLASSES': ( + 'DEFAULT_AUTHENTICATION_CLASSES': [ 'oauth2_provider.contrib.rest_framework.OAuth2Authentication', - ) + ] } For more details see the [Django REST framework - Getting started][django-oauth-toolkit-getting-started] documentation. @@ -381,9 +394,9 @@ For more details see the [Django REST framework - Getting started][django-oauth- The [Django REST framework OAuth][django-rest-framework-oauth] package provides both OAuth1 and OAuth2 support for REST framework. -This package was previously included directly in REST framework but is now supported and maintained as a third party package. +This package was previously included directly in the REST framework but is now supported and maintained as a third-party package. -#### Installation & configuration +### Installation & configuration Install the package using `pip`. @@ -405,23 +418,35 @@ HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a ## Djoser -[Djoser][djoser] 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. +[Djoser][djoser] 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 uses token-based authentication. This is a ready to use REST implementation of the Django authentication system. -## django-rest-auth +## django-rest-auth / dj-rest-auth -[Django-rest-auth][django-rest-auth] library provides a set of REST API endpoints for registration, authentication (including social media authentication), password reset, retrieve and update user details, etc. By having these API endpoints, your client apps such as AngularJS, iOS, Android, and others can communicate to your Django backend site independently via REST APIs for user management. +This library provides a set of REST API endpoints for registration, authentication (including social media authentication), password reset, retrieve and update user details, etc. By having these API endpoints, your client apps such as AngularJS, iOS, Android, and others can communicate to your Django backend site independently via REST APIs for user management. -## django-rest-framework-social-oauth2 -[Django-rest-framework-social-oauth2][django-rest-framework-social-oauth2] library provides an easy way to integrate social plugins (facebook, twitter, google, etc.) to your authentication system and an easy oauth2 setup. With this library, you will be able to authenticate users based on external tokens (e.g. facebook access token), convert these tokens to "in-house" oauth2 tokens and use and generate oauth2 tokens to authenticate your users. +There are currently two forks of this project. -## django-rest-knox +* [Django-rest-auth][django-rest-auth] is the original project, [but is not currently receiving updates](https://github.com/Tivix/django-rest-auth/issues/568). +* [Dj-rest-auth][dj-rest-auth] is a newer fork of the project. -[Django-rest-knox][django-rest-knox] library provides models and views to handle token based authentication in a more secure and extensible way than the built-in TokenAuthentication scheme - with Single Page Applications and Mobile clients in mind. It provides per-client tokens, and views to generate them when provided some other authentication (usually basic authentication), to delete the token (providing a server enforced logout) and to delete all tokens (logs out all clients that a user is logged into). +## drf-social-oauth2 + +[Drf-social-oauth2][drf-social-oauth2] is a framework that helps you authenticate with major social oauth2 vendors, such as Facebook, Google, Twitter, Orcid, etc. It generates tokens in a JWTed way with an easy setup. ## drfpasswordless -[drfpasswordless][drfpasswordless] adds (Medium, Square Cash inspired) passwordless support to Django REST Framework's own TokenAuthentication scheme. Users log in and sign up with a token sent to a contact point like an email address or a mobile number. +[drfpasswordless][drfpasswordless] adds (Medium, Square Cash inspired) passwordless support to Django REST Framework's TokenAuthentication scheme. Users log in and sign up with a token sent to a contact point like an email address or a mobile number. + +## django-rest-authemail + +[django-rest-authemail][django-rest-authemail] provides a RESTful API interface for user signup and authentication. Email addresses are used for authentication, rather than usernames. API endpoints are available for signup, signup email verification, login, logout, password reset, password reset verification, email change, email change verification, password change, and user detail. A fully functional example project and detailed instructions are included. + +## Django-Rest-Durin + +[Django-Rest-Durin][django-rest-durin] is built with the idea to have one library that does token auth for multiple Web/CLI/Mobile API clients via one interface but allows different token configuration for each API Client that consumes the API. It provides support for multiple tokens per user via custom models, views, permissions that work with Django-Rest-Framework. The token expiration time can be different per API client and is customizable via the Django Admin Interface. + +More information can be found in the [Documentation](https://django-rest-durin.readthedocs.io/en/latest/index.html). [cite]: https://jacobian.org/writing/rest-worst-practices/ [http401]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2 @@ -439,7 +464,7 @@ HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a [djangorestframework-digestauth]: https://github.com/juanriaza/django-rest-framework-digestauth [oauth-1.0a]: https://oauth.net/core/1.0a/ [django-oauth-toolkit]: https://github.com/evonove/django-oauth-toolkit -[evonove]: https://github.com/evonove/ +[jazzband]: https://github.com/jazzband/ [oauthlib]: https://github.com/idan/oauthlib [djangorestframework-simplejwt]: https://github.com/davesque/django-rest-framework-simplejwt [etoccalino]: https://github.com/etoccalino/ @@ -453,6 +478,9 @@ HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a [mac]: https://tools.ietf.org/html/draft-hammer-oauth-v2-mac-token-05 [djoser]: https://github.com/sunscrapers/djoser [django-rest-auth]: https://github.com/Tivix/django-rest-auth -[django-rest-framework-social-oauth2]: https://github.com/PhilipGarnero/django-rest-framework-social-oauth2 +[dj-rest-auth]: https://github.com/jazzband/dj-rest-auth +[drf-social-oauth2]: https://github.com/wagnerdelima/drf-social-oauth2 [django-rest-knox]: https://github.com/James1345/django-rest-knox [drfpasswordless]: https://github.com/aaronn/django-rest-framework-passwordless +[django-rest-authemail]: https://github.com/celiao/django-rest-authemail +[django-rest-durin]: https://github.com/eshaan7/django-rest-durin diff --git a/docs/api-guide/caching.md b/docs/api-guide/caching.md index 5342345e4..ab4f82cd2 100644 --- a/docs/api-guide/caching.md +++ b/docs/api-guide/caching.md @@ -1,6 +1,6 @@ # Caching -> A certain woman had a very sharp conciousness but almost no +> A certain woman had a very sharp consciousness but almost no > memory ... She remembered enough to work, and she worked hard. > - Lydia Davis @@ -13,17 +13,21 @@ provided in Django. Django provides a [`method_decorator`][decorator] to use decorators with class based views. This can be used with -other cache decorators such as [`cache_page`][page] and -[`vary_on_cookie`][cookie]. +other cache decorators such as [`cache_page`][page], +[`vary_on_cookie`][cookie] and [`vary_on_headers`][headers]. ```python +from django.utils.decorators import method_decorator +from django.views.decorators.cache import cache_page +from django.views.decorators.vary import vary_on_cookie, vary_on_headers + from rest_framework.response import Response from rest_framework.views import APIView from rest_framework import viewsets -class UserViewSet(viewsets.Viewset): - # Cache requested url for each user for 2 hours +class UserViewSet(viewsets.ViewSet): + # With cookie: cache requested url for each user for 2 hours @method_decorator(cache_page(60*60*2)) @method_decorator(vary_on_cookie) def list(self, request, format=None): @@ -32,8 +36,19 @@ class UserViewSet(viewsets.Viewset): } return Response(content) -class PostView(APIView): +class ProfileView(APIView): + # With auth: cache requested url for each user for 2 hours + @method_decorator(cache_page(60*60*2)) + @method_decorator(vary_on_headers("Authorization",)) + def get(self, request, format=None): + content = { + 'user_feed': request.user.get_user_feed() + } + return Response(content) + + +class PostView(APIView): # Cache page for the requested url @method_decorator(cache_page(60*60*2)) def get(self, request, format=None): @@ -49,4 +64,5 @@ class PostView(APIView): [page]: https://docs.djangoproject.com/en/dev/topics/cache/#the-per-view-cache [cookie]: https://docs.djangoproject.com/en/dev/topics/http/decorators/#django.views.decorators.vary.vary_on_cookie +[headers]: https://docs.djangoproject.com/en/dev/topics/http/decorators/#django.views.decorators.vary.vary_on_headers [decorator]: https://docs.djangoproject.com/en/dev/topics/class-based-views/intro/#decorating-the-class diff --git a/docs/api-guide/content-negotiation.md b/docs/api-guide/content-negotiation.md index 8112a2e80..81cff6a89 100644 --- a/docs/api-guide/content-negotiation.md +++ b/docs/api-guide/content-negotiation.md @@ -1,4 +1,7 @@ -source: negotiation.py +--- +source: + - negotiation.py +--- # Content negotiation @@ -79,7 +82,7 @@ The default content negotiation class may be set globally, using the `DEFAULT_CO You can also set the content negotiation used for an individual view, or viewset, using the `APIView` class-based views. - from myapp.negotiation import IgnoreClientContentNegotiation + from myapp.negotiation import IgnoreClientContentNegotiation from rest_framework.response import Response from rest_framework.views import APIView diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md index 820e6d3b8..347541d56 100644 --- a/docs/api-guide/exceptions.md +++ b/docs/api-guide/exceptions.md @@ -1,4 +1,7 @@ -source: exceptions.py +--- +source: + - exceptions.py +--- # Exceptions @@ -35,7 +38,7 @@ Might receive an error response indicating that the `DELETE` method is not allow 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. -Any example validation error might look like this: +An example validation error might look like this: HTTP/1.1 400 Bad Request Content-Type: application/json @@ -219,7 +222,7 @@ By default this exception results in a response with the HTTP status code "429 T The `ValidationError` exception is slightly different from the other `APIException` classes: * The `detail` argument is mandatory, not optional. -* The `detail` argument may be a list or dictionary of error details, and may also be a nested data structure. +* The `detail` argument may be a list or dictionary of error details, and may also be a nested data structure. By using a dictionary, you can specify field-level errors while performing object-level validation in the `validate()` method of a serializer. For example. `raise serializers.ValidationError({'name': 'Please enter a valid name.'})` * By convention you should import the serializers module and use a fully qualified `ValidationError` style, in order to differentiate it from Django's built-in validation error. For example. `raise serializers.ValidationError('This field must be an integer value.')` The `ValidationError` class should be used for serializer and field validation, and by validator classes. It is also raised when calling `serializer.is_valid` with the `raise_exception` keyword argument: @@ -257,6 +260,15 @@ Set as `handler400`: handler400 = 'rest_framework.exceptions.bad_request' +# Third party packages + +The following third-party packages are also available. + +## DRF Standardized Errors + +The [drf-standardized-errors][drf-standardized-errors] package provides an exception handler that generates the same format for all 4xx and 5xx responses. It is a drop-in replacement for the default exception handler and allows customizing the error response format without rewriting the whole exception handler. The standardized error response format is easier to document and easier to handle by API consumers. + [cite]: https://doughellmann.com/blog/2009/06/19/python-exception-handling-techniques/ [authentication]: authentication.md [django-custom-error-views]: https://docs.djangoproject.com/en/dev/topics/http/views/#customizing-error-views +[drf-standardized-errors]: https://github.com/ghazi-git/drf-standardized-errors diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index b7ed87fdc..4b4ea83cc 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -1,4 +1,7 @@ -source: fields.py +--- +source: + - fields.py +--- # Serializer fields @@ -39,17 +42,29 @@ Set to false if this field is not required to be present during deserialization. Setting this to `False` also allows the object attribute or dictionary key to be omitted from output when serializing the instance. If the key is not present it will simply not be included in the output representation. -Defaults to `True`. +Defaults to `True`. If you're using [Model Serializer](https://www.django-rest-framework.org/api-guide/serializers/#modelserializer) default value will be `False` if you have specified `blank=True` or `default` or `null=True` at your field in your `Model`. ### `default` -If set, this gives the default value that will be used for the field if no input value is supplied. If not set the default behaviour is to not populate the attribute at all. +If set, this gives the default value that will be used for the field if no input value is supplied. If not set the default behavior is to not populate the attribute at all. The `default` is not applied during partial update operations. In the partial update case only fields that are provided in the incoming data will have a validated value returned. -May be set to a function or other callable, in which case the value will be evaluated each time it is used. When called, it will receive no arguments. If the callable has a `set_context` method, that will be called each time before getting the value with the field instance as only argument. This works the same way as for [validators](validators.md#using-set_context). +May be set to a function or other callable, in which case the value will be evaluated each time it is used. When called, it will receive no arguments. If the callable has a `requires_context = True` attribute, then the serializer field will be passed as an argument. -When serializing the instance, default will be used if the the object attribute or dictionary key is not present in the instance. +For example: + + class CurrentUserDefault: + """ + May be applied as a `default=...` value on a serializer field. + Returns the current user. + """ + requires_context = True + + def __call__(self, serializer_field): + return serializer_field.context['request'].user + +When serializing the instance, default will be used if the object attribute or dictionary key is not present in the instance. Note that setting a `default` value implies that the field is not required. Including both the `default` and `required` keyword arguments is invalid and will raise an error. @@ -63,7 +78,14 @@ Defaults to `False` ### `source` -The name of the attribute that will be used to populate the field. May be a method that only takes a `self` argument, such as `URLField(source='get_absolute_url')`, or may use dotted notation to traverse attributes, such as `EmailField(source='user.email')`. When serializing fields with dotted notation, it may be necessary to provide a `default` value if any object is not present or is empty during attribute traversal. +The name of the attribute that will be used to populate the field. May be a method that only takes a `self` argument, such as `URLField(source='get_absolute_url')`, or may use dotted notation to traverse attributes, such as `EmailField(source='user.email')`. + +When serializing fields with dotted notation, it may be necessary to provide a `default` value if any object is not present or is empty during attribute traversal. Beware of possible n+1 problems when using source attribute if you are accessing a relational orm model. For example: + + class CommentSerializer(serializers.Serializer): + email = serializers.EmailField(source="user.email") + +This case would require user object to be fetched from database when it is not prefetched. If that is not wanted, be sure to be using `prefetch_related` and `select_related` methods appropriately. For more information about the methods refer to [django documentation][django-docs-select-related]. The value `source='*'` has a special meaning, and is used to indicate that the entire object should be passed through to the field. This can be useful for creating nested representations, or for fields which require access to the complete object in order to determine the output representation. @@ -129,7 +151,7 @@ Prior to Django 2.1 `models.BooleanField` fields were always `blank=True`. Thus since Django 2.1 default `serializers.BooleanField` instances will be generated without the `required` kwarg (i.e. equivalent to `required=True`) whereas with previous versions of Django, default `BooleanField` instances will be generated -with a `required=False` option. If you want to control this behaviour manually, +with a `required=False` option. If you want to control this behavior manually, explicitly declare the `BooleanField` on the serializer class, or use the `extra_kwargs` option to set the `required` flag. @@ -137,14 +159,6 @@ Corresponds to `django.db.models.fields.BooleanField`. **Signature:** `BooleanField()` -## NullBooleanField - -A boolean representation that also accepts `None` as a valid value. - -Corresponds to `django.db.models.fields.NullBooleanField`. - -**Signature:** `NullBooleanField()` - --- # String fields @@ -157,10 +171,10 @@ Corresponds to `django.db.models.fields.CharField` or `django.db.models.fields.T **Signature:** `CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)` -- `max_length` - Validates that the input contains no more than this number of characters. -- `min_length` - Validates that the input contains no fewer than this number of characters. -- `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`. -- `trim_whitespace` - If set to `True` then leading and trailing whitespace is trimmed. Defaults to `True`. +* `max_length` - Validates that the input contains no more than this number of characters. +* `min_length` - Validates that the input contains no fewer than this number of characters. +* `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`. +* `trim_whitespace` - If set to `True` then leading and trailing whitespace is trimmed. Defaults to `True`. The `allow_null` option is also available for string fields, although its usage is discouraged in favor of `allow_blank`. It is valid to set both `allow_blank=True` and `allow_null=True`, 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. @@ -208,11 +222,11 @@ A field that ensures the input is a valid UUID string. The `to_internal_value` m **Signature:** `UUIDField(format='hex_verbose')` -- `format`: Determines the representation format of the uuid value - - `'hex_verbose'` - The cannoncical hex representation, including hyphens: `"5ce0e9a5-5ffa-654b-cee0-1238041fb31a"` - - `'hex'` - The compact hex representation of the UUID, not including hyphens: `"5ce0e9a55ffa654bcee01238041fb31a"` - - `'int'` - A 128 bit integer representation of the UUID: `"123456789012312313134124512351145145114"` - - `'urn'` - RFC 4122 URN representation of the UUID: `"urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a"` +* `format`: Determines the representation format of the uuid value + * `'hex_verbose'` - The canonical hex representation, including hyphens: `"5ce0e9a5-5ffa-654b-cee0-1238041fb31a"` + * `'hex'` - The compact hex representation of the UUID, not including hyphens: `"5ce0e9a55ffa654bcee01238041fb31a"` + * `'int'` - A 128 bit integer representation of the UUID: `"123456789012312313134124512351145145114"` + * `'urn'` - RFC 4122 URN representation of the UUID: `"urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a"` Changing the `format` parameters only affects representation values. All formats are accepted by `to_internal_value` ## FilePathField @@ -223,11 +237,11 @@ Corresponds to `django.forms.fields.FilePathField`. **Signature:** `FilePathField(path, match=None, recursive=False, allow_files=True, allow_folders=False, required=None, **kwargs)` -- `path` - The absolute filesystem path to a directory from which this FilePathField should get its choice. -- `match` - A regular expression, as a string, that FilePathField will use to filter filenames. -- `recursive` - Specifies whether all subdirectories of path should be included. Default is `False`. -- `allow_files` - Specifies whether files in the specified location should be included. Default is `True`. Either this or `allow_folders` must be `True`. -- `allow_folders` - Specifies whether folders in the specified location should be included. Default is `False`. Either this or `allow_files` must be `True`. +* `path` - The absolute filesystem path to a directory from which this FilePathField should get its choice. +* `match` - A regular expression, as a string, that FilePathField will use to filter filenames. +* `recursive` - Specifies whether all subdirectories of path should be included. Default is `False`. +* `allow_files` - Specifies whether files in the specified location should be included. Default is `True`. Either this or `allow_folders` must be `True`. +* `allow_folders` - Specifies whether folders in the specified location should be included. Default is `False`. Either this or `allow_files` must be `True`. ## IPAddressField @@ -237,8 +251,8 @@ Corresponds to `django.forms.fields.IPAddressField` and `django.forms.fields.Gen **Signature**: `IPAddressField(protocol='both', unpack_ipv4=False, **options)` -- `protocol` Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case insensitive. -- `unpack_ipv4` Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'. +* `protocol` Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case insensitive. +* `unpack_ipv4` Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'. --- @@ -252,8 +266,8 @@ Corresponds to `django.db.models.fields.IntegerField`, `django.db.models.fields. **Signature**: `IntegerField(max_value=None, min_value=None)` -- `max_value` Validate that the number provided is no greater than this value. -- `min_value` Validate that the number provided is no less than this value. +* `max_value` Validate that the number provided is no greater than this value. +* `min_value` Validate that the number provided is no less than this value. ## FloatField @@ -263,8 +277,8 @@ Corresponds to `django.db.models.fields.FloatField`. **Signature**: `FloatField(max_value=None, min_value=None)` -- `max_value` Validate that the number provided is no greater than this value. -- `min_value` Validate that the number provided is no less than this value. +* `max_value` Validate that the number provided is no greater than this value. +* `min_value` Validate that the number provided is no less than this value. ## DecimalField @@ -274,14 +288,14 @@ Corresponds to `django.db.models.fields.DecimalField`. **Signature**: `DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None)` -- `max_digits` The maximum number of digits allowed in the number. It must be either `None` or an integer greater than or equal to `decimal_places`. -- `decimal_places` The number of decimal places to store with the number. -- `coerce_to_string` Set to `True` if string values should be returned for the representation, or `False` if `Decimal` objects should be returned. Defaults to the same value as the `COERCE_DECIMAL_TO_STRING` settings key, which will be `True` unless overridden. If `Decimal` objects are returned by the serializer, then the final output format will be determined by the renderer. Note that setting `localize` will force the value to `True`. -- `max_value` Validate that the number provided is no greater than this value. -- `min_value` Validate that the number provided is no less than this value. -- `localize` Set to `True` to enable localization of input and output based on the current locale. This will also force `coerce_to_string` to `True`. Defaults to `False`. Note that data formatting is enabled if you have set `USE_L10N=True` in your settings file. -- `rounding` Sets the rounding mode used when quantising to the configured precision. Valid values are [`decimal` module rounding modes][python-decimal-rounding-modes]. Defaults to `None`. -- `normalize_output` Will normalize the decimal value when serialized. This will strip all trailing zeroes and change the value's precision to the minimum required precision to be able to represent the value without loosing data. Defaults to `False`. +* `max_digits` The maximum number of digits allowed in the number. It must be either `None` or an integer greater than or equal to `decimal_places`. +* `decimal_places` The number of decimal places to store with the number. +* `coerce_to_string` Set to `True` if string values should be returned for the representation, or `False` if `Decimal` objects should be returned. Defaults to the same value as the `COERCE_DECIMAL_TO_STRING` settings key, which will be `True` unless overridden. If `Decimal` objects are returned by the serializer, then the final output format will be determined by the renderer. Note that setting `localize` will force the value to `True`. +* `max_value` Validate that the number provided is no greater than this value. +* `min_value` Validate that the number provided is no less than this value. +* `localize` Set to `True` to enable localization of input and output based on the current locale. This will also force `coerce_to_string` to `True`. Defaults to `False`. Note that data formatting is enabled if you have set `USE_L10N=True` in your settings file. +* `rounding` Sets the rounding mode used when quantising to the configured precision. Valid values are [`decimal` module rounding modes][python-decimal-rounding-modes]. Defaults to `None`. +* `normalize_output` Will normalize the decimal value when serialized. This will strip all trailing zeroes and change the value's precision to the minimum required precision to be able to represent the value without loosing data. Defaults to `False`. #### Example usage @@ -293,10 +307,6 @@ And to validate numbers up to anything less than one billion with a resolution o serializers.DecimalField(max_digits=19, decimal_places=10) -This field also takes an optional argument, `coerce_to_string`. If set to `True` the representation will be output as a string. If set to `False` the representation will be left as a `Decimal` instance and the final representation will be determined by the renderer. - -If unset, this will default to the same value as the `COERCE_DECIMAL_TO_STRING` setting, which is `True` unless set otherwise. - --- # Date and time fields @@ -311,7 +321,7 @@ Corresponds to `django.db.models.fields.DateTimeField`. * `format` - A string representing the output format. If not specified, this defaults to the same value as the `DATETIME_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `datetime` objects should be returned by `to_representation`. In this case the datetime encoding will be determined by the renderer. * `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `DATETIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`. -* `default_timezone` - A `pytz.timezone` representing the timezone. If not specified and the `USE_TZ` setting is enabled, this defaults to the [current timezone][django-current-timezone]. If `USE_TZ` is disabled, then datetime objects will be naive. +* `default_timezone` - A `tzinfo` subclass (`zoneinfo` or `pytz`) prepresenting the timezone. If not specified and the `USE_TZ` setting is enabled, this defaults to the [current timezone][django-current-timezone]. If `USE_TZ` is disabled, then datetime objects will be naive. #### `DateTimeField` format strings. @@ -357,7 +367,7 @@ Corresponds to `django.db.models.fields.TimeField` * `format` - A string representing the output format. If not specified, this defaults to the same value as the `TIME_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `time` objects should be returned by `to_representation`. In this case the time encoding will be determined by the renderer. * `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `TIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`. -#### `TimeField` format strings +#### `TimeField` format strings Format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style times should be used. (eg `'12:34:56.000000'`) @@ -371,8 +381,8 @@ The representation is a string following this format `'[DD] [HH:[MM:]]ss[.uuuuuu **Signature:** `DurationField(max_value=None, min_value=None)` -- `max_value` Validate that the duration provided is no greater than this value. -- `min_value` Validate that the duration provided is no less than this value. +* `max_value` Validate that the duration provided is no greater than this value. +* `min_value` Validate that the duration provided is no less than this value. --- @@ -386,10 +396,10 @@ Used by `ModelSerializer` to automatically generate fields if the corresponding **Signature:** `ChoiceField(choices)` -- `choices` - A list of valid values, or a list of `(key, display_name)` tuples. -- `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`. -- `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Can be used to ensure that automatically generated ChoiceFields with very large possible selections do not prevent a template from rendering. Defaults to `None`. -- `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"` +* `choices` - A list of valid values, or a list of `(key, display_name)` tuples. +* `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`. +* `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Can be used to ensure that automatically generated ChoiceFields with very large possible selections do not prevent a template from rendering. Defaults to `None`. +* `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"` Both the `allow_blank` and `allow_null` are valid options on `ChoiceField`, although it is highly recommended that you only use one and not both. `allow_blank` should be preferred for textual choices, and `allow_null` should be preferred for numeric or other non-textual choices. @@ -399,10 +409,10 @@ A field that can accept a set of zero, one or many values, chosen from a limited **Signature:** `MultipleChoiceField(choices)` -- `choices` - A list of valid values, or a list of `(key, display_name)` tuples. -- `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`. -- `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Can be used to ensure that automatically generated ChoiceFields with very large possible selections do not prevent a template from rendering. Defaults to `None`. -- `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"` +* `choices` - A list of valid values, or a list of `(key, display_name)` tuples. +* `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`. +* `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Can be used to ensure that automatically generated ChoiceFields with very large possible selections do not prevent a template from rendering. Defaults to `None`. +* `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"` As with `ChoiceField`, both the `allow_blank` and `allow_null` options are valid, although it is highly recommended that you only use one and not both. `allow_blank` should be preferred for textual choices, and `allow_null` should be preferred for numeric or other non-textual choices. @@ -423,9 +433,9 @@ Corresponds to `django.forms.fields.FileField`. **Signature:** `FileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)` - - `max_length` - Designates the maximum length for the file name. - - `allow_empty_file` - Designates if empty files are allowed. -- `use_url` - If set to `True` then URL string values will be used for the output representation. If set to `False` then filename string values will be used for the output representation. Defaults to the value of the `UPLOADED_FILES_USE_URL` settings key, which is `True` unless set otherwise. +* `max_length` - Designates the maximum length for the file name. +* `allow_empty_file` - Designates if empty files are allowed. +* `use_url` - If set to `True` then URL string values will be used for the output representation. If set to `False` then filename string values will be used for the output representation. Defaults to the value of the `UPLOADED_FILES_USE_URL` settings key, which is `True` unless set otherwise. ## ImageField @@ -435,9 +445,9 @@ Corresponds to `django.forms.fields.ImageField`. **Signature:** `ImageField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)` - - `max_length` - Designates the maximum length for the file name. - - `allow_empty_file` - Designates if empty files are allowed. -- `use_url` - If set to `True` then URL string values will be used for the output representation. If set to `False` then filename string values will be used for the output representation. Defaults to the value of the `UPLOADED_FILES_USE_URL` settings key, which is `True` unless set otherwise. +* `max_length` - Designates the maximum length for the file name. +* `allow_empty_file` - Designates if empty files are allowed. +* `use_url` - If set to `True` then URL string values will be used for the output representation. If set to `False` then filename string values will be used for the output representation. Defaults to the value of the `UPLOADED_FILES_USE_URL` settings key, which is `True` unless set otherwise. Requires either the `Pillow` package or `PIL` package. The `Pillow` package is recommended, as `PIL` is no longer actively maintained. @@ -449,11 +459,12 @@ Requires either the `Pillow` package or `PIL` package. The `Pillow` package is A field class that validates a list of objects. -**Signature**: `ListField(child=, min_length=None, max_length=None)` +**Signature**: `ListField(child=, allow_empty=True, min_length=None, max_length=None)` -- `child` - A field instance that should be used for validating the objects in the list. If this argument is not provided then objects in the list will not be validated. -- `min_length` - Validates that the list contains no fewer than this number of elements. -- `max_length` - Validates that the list contains no more than this number of elements. +* `child` - A field instance that should be used for validating the objects in the list. If this argument is not provided then objects in the list will not be validated. +* `allow_empty` - Designates if empty lists are allowed. +* `min_length` - Validates that the list contains no fewer than this number of elements. +* `max_length` - Validates that the list contains no more than this number of elements. For example, to validate a list of integers you might use something like the following: @@ -472,9 +483,10 @@ We can now reuse our custom `StringListField` class throughout our application, A field class that validates a dictionary of objects. The keys in `DictField` are always assumed to be string values. -**Signature**: `DictField(child=)` +**Signature**: `DictField(child=, allow_empty=True)` -- `child` - A field instance that should be used for validating the values in the dictionary. If this argument is not provided then values in the mapping will not be validated. +* `child` - A field instance that should be used for validating the values in the dictionary. If this argument is not provided then values in the mapping will not be validated. +* `allow_empty` - Designates if empty dictionaries are allowed. For example, to create a field that validates a mapping of strings to strings, you would write something like this: @@ -489,9 +501,10 @@ You can also use the declarative style, as with `ListField`. For example: A preconfigured `DictField` that is compatible with Django's postgres `HStoreField`. -**Signature**: `HStoreField(child=)` +**Signature**: `HStoreField(child=, allow_empty=True)` -- `child` - A field instance that is used for validating the values in the dictionary. The default child field accepts both empty strings and null values. +* `child` - A field instance that is used for validating the values in the dictionary. The default child field accepts both empty strings and null values. +* `allow_empty` - Designates if empty dictionaries are allowed. Note that the child field **must** be an instance of `CharField`, as the hstore extension stores values as strings. @@ -499,9 +512,10 @@ Note that the child field **must** be an instance of `CharField`, as the hstore A field class that validates that the incoming data structure consists of valid JSON primitives. In its alternate binary mode, it will represent and validate JSON-encoded binary strings. -**Signature**: `JSONField(binary)` +**Signature**: `JSONField(binary, encoder)` -- `binary` - If set to `True` then the field will output and validate a JSON encoded string, rather than a primitive data structure. Defaults to `False`. +* `binary` - If set to `True` then the field will output and validate a JSON encoded string, rather than a primitive data structure. Defaults to `False`. +* `encoder` - Use this JSON encoder to serialize input object. Defaults to `None`. --- @@ -520,7 +534,7 @@ For example, if `has_expired` was a property on the `Account` model, then the fo class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - fields = ('id', 'account_name', 'has_expired') + fields = ['id', 'account_name', 'has_expired'] ## HiddenField @@ -552,7 +566,7 @@ This is a read-only field. It gets its value by calling a method on the serializ **Signature**: `SerializerMethodField(method_name=None)` -- `method_name` - The name of the method on the serializer to be called. If not included this defaults to `get_`. +* `method_name` - The name of the method on the serializer to be called. If not included this defaults to `get_`. The serializer method referred to by the `method_name` argument should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. For example: @@ -565,6 +579,7 @@ The serializer method referred to by the `method_name` argument should accept a class Meta: model = User + fields = '__all__' def get_days_since_joined(self, obj): return (now() - obj.date_joined).days @@ -577,9 +592,7 @@ If you want to create a custom field, you'll need to subclass `Field` and then o The `.to_representation()` method is called to convert the initial datatype into a primitive, serializable datatype. -The `to_internal_value()` method is called to restore a primitive datatype into its internal python representation. This method should raise a `serializers.ValidationError` if the data is invalid. - -Note that the `WritableField` class that was present in version 2.x no longer exists. You should subclass `Field` and override `to_internal_value()` if the field supports data input. +The `.to_internal_value()` method is called to restore a primitive datatype into its internal python representation. This method should raise a `serializers.ValidationError` if the data is invalid. ## Examples @@ -587,7 +600,7 @@ Note that the `WritableField` class that was present in version 2.x no longer ex Let's look at an example of serializing a class that represents an RGB color value: - class Color(object): + class Color: """ A color represented in the RGB colorspace. """ @@ -630,7 +643,7 @@ Our `ColorField` class above currently does not perform any data validation. To indicate invalid data, we should raise a `serializers.ValidationError`, like so: def to_internal_value(self, data): - if not isinstance(data, six.text_type): + if not isinstance(data, str): msg = 'Incorrect type. Expected a string, but got %s' raise ValidationError(msg % type(data).__name__) @@ -654,7 +667,7 @@ The `.fail()` method is a shortcut for raising `ValidationError` that takes a me } def to_internal_value(self, data): - if not isinstance(data, six.text_type): + if not isinstance(data, str): self.fail('incorrect_type', input_type=type(data).__name__) if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data): @@ -707,7 +720,7 @@ the coordinate pair: fields = ['label', 'coordinates'] Note that this example doesn't handle validation. Partly for that reason, in a -real project, the coordinate nesting might be better handled with a nested serialiser +real project, the coordinate nesting might be better handled with a nested serializer using `source='*'`, with two `IntegerField` instances, each with their own `source` pointing to the relevant field. @@ -719,7 +732,7 @@ to the desired output. >>> instance = DataPoint(label='Example', x_coordinate=1, y_coordinate=2) >>> out_serializer = DataPointSerializer(instance) >>> out_serializer.data - ReturnDict([('label', 'testing'), ('coordinates', {'x': 1, 'y': 2})]) + ReturnDict([('label', 'Example'), ('coordinates', {'x': 1, 'y': 2})]) * Unless our field is to be read-only, `to_internal_value` must map back to a dict suitable for updating our target object. With `source='*'`, the return from @@ -740,7 +753,7 @@ suitable for updating our target object. With `source='*'`, the return from ('y_coordinate', 4), ('x_coordinate', 3)]) -For completeness lets do the same thing again but with the nested serialiser +For completeness lets do the same thing again but with the nested serializer approach suggested above: class NestedCoordinateSerializer(serializers.Serializer): @@ -759,17 +772,17 @@ Here the mapping between the target and source attribute pairs (`x` and `x_coordinate`, `y` and `y_coordinate`) is handled in the `IntegerField` declarations. It's our `NestedCoordinateSerializer` that takes `source='*'`. -Our new `DataPointSerializer` exhibits the same behaviour as the custom field +Our new `DataPointSerializer` exhibits the same behavior as the custom field approach. -Serialising: +Serializing: >>> out_serializer = DataPointSerializer(instance) >>> out_serializer.data ReturnDict([('label', 'testing'), ('coordinates', OrderedDict([('x', 1), ('y', 2)]))]) -Deserialising: +Deserializing: >>> in_serializer = DataPointSerializer(data=data) >>> in_serializer.is_valid() @@ -796,8 +809,8 @@ But we also get the built-in validation for free: {'x': ['A valid integer is required.'], 'y': ['A valid integer is required.']})]) -For this reason, the nested serialiser approach would be the first to try. You -would use the custom field approach when the nested serialiser becomes infeasible +For this reason, the nested serializer approach would be the first to try. You +would use the custom field approach when the nested serializer becomes infeasible or overly complex. @@ -819,7 +832,7 @@ the [djangorestframework-recursive][djangorestframework-recursive] package provi ## django-rest-framework-gis -The [django-rest-framework-gis][django-rest-framework-gis] package provides geographic addons for django rest framework like a `GeometryField` field and a GeoJSON serializer. +The [django-rest-framework-gis][django-rest-framework-gis] package provides geographic addons for django rest framework like a `GeometryField` field and a GeoJSON serializer. ## django-rest-framework-hstore @@ -838,3 +851,4 @@ The [django-rest-framework-hstore][django-rest-framework-hstore] package provide [django-hstore]: https://github.com/djangonauts/django-hstore [python-decimal-rounding-modes]: https://docs.python.org/3/library/decimal.html#rounding-modes [django-current-timezone]: https://docs.djangoproject.com/en/stable/topics/i18n/timezones/#default-time-zone-and-current-time-zone +[django-docs-select-related]: https://docs.djangoproject.com/en/3.1/ref/models/querysets/#django.db.models.query.QuerySet.select_related diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index 8a500f386..9a4ae2745 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -1,4 +1,7 @@ -source: filters.py +--- +source: + - filters.py +--- # Filtering @@ -42,7 +45,7 @@ Another style of filtering might involve restricting the queryset based on some For example if your URL config contained an entry like this: - url('^purchases/(?P.+)/$', PurchaseList.as_view()), + re_path('^purchases/(?P.+)/$', PurchaseList.as_view()), You could then write a view that returned a purchase queryset filtered by the username portion of the URL: @@ -72,7 +75,7 @@ We can override `.get_queryset()` to deal with URLs such as `http://example.com/ by filtering against a `username` query parameter in the URL. """ queryset = Purchase.objects.all() - username = self.request.query_params.get('username', None) + username = self.request.query_params.get('username') if username is not None: queryset = queryset.filter(purchaser__username=username) return queryset @@ -92,7 +95,7 @@ Generic filters can also present themselves as HTML controls in the browsable AP The default filter backends may be set globally, using the `DEFAULT_FILTER_BACKENDS` setting. For example. REST_FRAMEWORK = { - 'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',) + 'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend'] } You can also set the filter backends on a per-view, or per-viewset basis, @@ -106,7 +109,7 @@ using the `GenericAPIView` class-based views. class UserListView(generics.ListAPIView): queryset = User.objects.all() serializer_class = UserSerializer - filter_backends = (django_filters.rest_framework.DjangoFilterBackend,) + filter_backends = [django_filters.rest_framework.DjangoFilterBackend] ## Filtering and object lookups @@ -139,17 +142,25 @@ Note that you can use both an overridden `.get_queryset()` and generic filtering ## DjangoFilterBackend -The `django-filter` library includes a `DjangoFilterBackend` class which +The [`django-filter`][django-filter-docs] library includes a `DjangoFilterBackend` class which supports highly customizable field filtering for REST framework. -To use `DjangoFilterBackend`, first install `django-filter`. Then add `django_filters` to Django's `INSTALLED_APPS` +To use `DjangoFilterBackend`, first install `django-filter`. pip install django-filter +Then add `'django_filters'` to Django's `INSTALLED_APPS`: + + INSTALLED_APPS = [ + ... + 'django_filters', + ... + ] + You should now either add the filter backend to your settings: REST_FRAMEWORK = { - 'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',) + 'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend'] } Or add the filter backend to an individual View or ViewSet. @@ -158,15 +169,15 @@ Or add the filter backend to an individual View or ViewSet. class UserListView(generics.ListAPIView): ... - filter_backends = (DjangoFilterBackend,) + filter_backends = [DjangoFilterBackend] If all you need is simple equality-based filtering, you can set a `filterset_fields` attribute on the view, or viewset, listing the set of fields you wish to filter against. class ProductList(generics.ListAPIView): queryset = Product.objects.all() serializer_class = ProductSerializer - filter_backends = (DjangoFilterBackend,) - filterset_fields = ('category', 'in_stock') + filter_backends = [DjangoFilterBackend] + filterset_fields = ['category', 'in_stock'] This will automatically create a `FilterSet` class for the given fields, and will allow you to make requests such as: @@ -192,8 +203,8 @@ The `SearchFilter` class will only be applied if the view has a `search_fields` class UserListView(generics.ListAPIView): queryset = User.objects.all() serializer_class = UserSerializer - filter_backends = (filters.SearchFilter,) - search_fields = ('username', 'email') + filter_backends = [filters.SearchFilter] + search_fields = ['username', 'email'] This will allow the client to filter the items in the list by making queries such as: @@ -201,7 +212,11 @@ This will allow the client to filter the items in the list by making queries suc You can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation: - search_fields = ('username', 'email', 'profile__profession') + search_fields = ['username', 'email', 'profile__profession'] + +For [JSONField][JSONField] and [HStoreField][HStoreField] fields you can filter based on nested values within the data structure using the same double-underscore notation: + + search_fields = ['data__breed', 'data__owner__other_pets__0__name'] By default, searches will use case-insensitive partial matches. The search parameter may contain multiple search terms, which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched. @@ -209,24 +224,24 @@ The search behavior may be restricted by prepending various characters to the `s * '^' Starts-with search. * '=' Exact matches. -* '@' Full-text search. (Currently only supported Django's MySQL backend.) +* '@' Full-text search. (Currently only supported Django's [PostgreSQL backend][postgres-search].) * '$' Regex search. For example: - search_fields = ('=username', '=email') + search_fields = ['=username', '=email'] -By default, the search parameter is named `'search`', but this may be overridden with the `SEARCH_PARAM` setting. +By default, the search parameter is named `'search'`, but this may be overridden with the `SEARCH_PARAM` setting. To dynamically change search fields based on request content, it's possible to subclass the `SearchFilter` and override the `get_search_fields()` function. For example, the following subclass will only search on `title` if the query parameter `title_only` is in the request: from rest_framework import filters - + class CustomSearchFilter(filters.SearchFilter): def get_search_fields(self, view, request): if request.query_params.get('title_only'): - return ('title',) - return super(CustomSearchFilter, self).get_search_fields(view, request) + return ['title'] + return super().get_search_fields(view, request) For more details, see the [Django documentation][search-django-admin]. @@ -259,8 +274,8 @@ It's recommended that you explicitly specify which fields the API should allowin class UserListView(generics.ListAPIView): queryset = User.objects.all() serializer_class = UserSerializer - filter_backends = (filters.OrderingFilter,) - ordering_fields = ('username', 'email') + filter_backends = [filters.OrderingFilter] + ordering_fields = ['username', 'email'] This helps prevent unexpected data leakage, such as allowing users to order against a password hash field or other sensitive data. @@ -271,7 +286,7 @@ If you are confident that the queryset being used by the view doesn't contain an class BookingsListView(generics.ListAPIView): queryset = Booking.objects.all() serializer_class = BookingSerializer - filter_backends = (filters.OrderingFilter,) + filter_backends = [filters.OrderingFilter] ordering_fields = '__all__' ### Specifying a default ordering @@ -283,61 +298,14 @@ Typically you'd instead control this by setting `order_by` on the initial querys class UserListView(generics.ListAPIView): queryset = User.objects.all() serializer_class = UserSerializer - filter_backends = (filters.OrderingFilter,) - ordering_fields = ('username', 'email') - ordering = ('username',) + filter_backends = [filters.OrderingFilter] + ordering_fields = ['username', 'email'] + ordering = ['username'] The `ordering` attribute may be either a string or a list/tuple of strings. --- -## DjangoObjectPermissionsFilter - -The `DjangoObjectPermissionsFilter` is intended to be used together with the [`django-guardian`][guardian] package, with custom `'view'` permissions added. The filter will ensure that querysets only returns objects for which the user has the appropriate view permission. - ---- - -**Note:** This filter has been deprecated as of version 3.9 and moved to the 3rd-party [`djangorestframework-guardian` package][django-rest-framework-guardian]. - ---- - -If you're using `DjangoObjectPermissionsFilter`, you'll probably also want to add an appropriate object permissions class, to ensure that users can only operate on instances if they have the appropriate object permissions. The easiest way to do this is to subclass `DjangoObjectPermissions` and add `'view'` permissions to the `perms_map` attribute. - -A complete example using both `DjangoObjectPermissionsFilter` and `DjangoObjectPermissions` might look something like this. - -**permissions.py**: - - class CustomObjectPermissions(permissions.DjangoObjectPermissions): - """ - Similar to `DjangoObjectPermissions`, but adding 'view' permissions. - """ - perms_map = { - 'GET': ['%(app_label)s.view_%(model_name)s'], - 'OPTIONS': ['%(app_label)s.view_%(model_name)s'], - 'HEAD': ['%(app_label)s.view_%(model_name)s'], - 'POST': ['%(app_label)s.add_%(model_name)s'], - 'PUT': ['%(app_label)s.change_%(model_name)s'], - 'PATCH': ['%(app_label)s.change_%(model_name)s'], - 'DELETE': ['%(app_label)s.delete_%(model_name)s'], - } - -**views.py**: - - class EventViewSet(viewsets.ModelViewSet): - """ - Viewset that only lists events if user has 'view' permissions, and only - allows operations on individual events if user has appropriate 'view', 'add', - 'change' or 'delete' permissions. - """ - queryset = Event.objects.all() - serializer_class = EventSerializer - filter_backends = (filters.DjangoObjectPermissionsFilter,) - permission_classes = (myapp.permissions.CustomObjectPermissions,) - -For more information on adding `'view'` permissions for models, see the [relevant section][view-permissions] of the `django-guardian` documentation, and [this blogpost][view-permissions-blogpost]. - ---- - # Custom generic filtering You can also provide your own generic filtering backend, or write an installable app for other developers to use. @@ -367,7 +335,7 @@ Generic filters may also present an interface in the browsable API. To do so you The method should return a rendered HTML string. -## Pagination & schemas +## Filtering & schemas You can also make the filter controls available to the schema autogeneration that REST framework provides, by implementing a `get_schema_fields()` method. This method should have the following signature: @@ -399,12 +367,11 @@ The [djangorestframework-word-filter][django-rest-framework-word-search-filter] [cite]: https://docs.djangoproject.com/en/stable/topics/db/queries/#retrieving-specific-objects-with-filters [django-filter-docs]: https://django-filter.readthedocs.io/en/latest/index.html [django-filter-drf-docs]: https://django-filter.readthedocs.io/en/latest/guide/rest_framework.html -[guardian]: https://django-guardian.readthedocs.io/ -[view-permissions]: https://django-guardian.readthedocs.io/en/latest/userguide/assign.html -[view-permissions-blogpost]: https://blog.nyaruka.com/adding-a-view-permission-to-django-models [search-django-admin]: https://docs.djangoproject.com/en/stable/ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields [django-rest-framework-filters]: https://github.com/philipn/django-rest-framework-filters -[django-rest-framework-guardian]: https://github.com/rpkilby/django-rest-framework-guardian [django-rest-framework-word-search-filter]: https://github.com/trollknurr/django-rest-framework-word-search-filter [django-url-filter]: https://github.com/miki725/django-url-filter [drf-url-filter]: https://github.com/manjitkumar/drf-url-filters +[HStoreField]: https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/fields/#hstorefield +[JSONField]: https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/fields/#jsonfield +[postgres-search]: https://docs.djangoproject.com/en/stable/ref/contrib/postgres/search/ diff --git a/docs/api-guide/format-suffixes.md b/docs/api-guide/format-suffixes.md index 629f003f3..9b4e5b9da 100644 --- a/docs/api-guide/format-suffixes.md +++ b/docs/api-guide/format-suffixes.md @@ -1,4 +1,7 @@ -source: urlpatterns.py +--- +source: + - urlpatterns.py +--- # Format suffixes @@ -20,8 +23,8 @@ Returns a URL pattern list which includes format suffix patterns appended to eac Arguments: * **urlpatterns**: Required. A URL pattern list. -* **suffix_required**: Optional. A boolean indicating if suffixes in the URLs should be optional or mandatory. Defaults to `False`, meaning that suffixes are optional by default. -* **allowed**: Optional. A list or tuple of valid format suffixes. If not provided, a wildcard format suffix pattern will be used. +* **suffix_required**: Optional. A boolean indicating if suffixes in the URLs should be optional or mandatory. Defaults to `False`, meaning that suffixes are optional by default. +* **allowed**: Optional. A list or tuple of valid format suffixes. If not provided, a wildcard format suffix pattern will be used. Example: @@ -29,16 +32,16 @@ Example: from blog import views urlpatterns = [ - url(r'^/$', views.apt_root), - url(r'^comments/$', views.comment_list), - url(r'^comments/(?P[0-9]+)/$', views.comment_detail) + path('', views.apt_root), + path('comments/', views.comment_list), + path('comments//', views.comment_detail) ] urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'html']) When using `format_suffix_patterns`, you must make sure to add the `'format'` keyword argument to the corresponding views. For example: - @api_view(('GET', 'POST')) + @api_view(['GET', 'POST']) def comment_list(request, format=None): # do stuff... @@ -59,7 +62,7 @@ Also note that `format_suffix_patterns` does not support descending into `includ If using the `i18n_patterns` function provided by Django, as well as `format_suffix_patterns` you should make sure that the `i18n_patterns` function is applied as the final, or outermost function. For example: - url patterns = [ + urlpatterns = [ … ] diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index a0ed7bdea..410e3518d 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -1,5 +1,8 @@ -source: mixins.py - generics.py +--- +source: + - mixins.py + - generics.py +--- # Generic views @@ -25,14 +28,14 @@ Typically when using the generic views, you'll override the view, and set severa class UserList(generics.ListCreateAPIView): queryset = User.objects.all() serializer_class = UserSerializer - permission_classes = (IsAdminUser,) + permission_classes = [IsAdminUser] For more complex cases you might also want to override various methods on the view class. For example. class UserList(generics.ListCreateAPIView): queryset = User.objects.all() serializer_class = UserSerializer - permission_classes = (IsAdminUser,) + permission_classes = [IsAdminUser] def list(self, request): # Note the use of `get_queryset()` instead of `self.queryset` @@ -42,7 +45,7 @@ For more complex cases you might also want to override various methods on the vi For very simple cases you might want to pass through any class attributes using the `.as_view()` method. For example, your URLconf might include something like the following entry: - url(r'^/users/', ListCreateAPIView.as_view(queryset=User.objects.all(), serializer_class=UserSerializer), name='user-list') + path('users/', ListCreateAPIView.as_view(queryset=User.objects.all(), serializer_class=UserSerializer), name='user-list') --- @@ -62,7 +65,7 @@ The following attributes control the basic view behavior. * `queryset` - The queryset that should be used for returning objects from this view. Typically, you must either set this attribute, or override the `get_queryset()` method. If you are overriding a view method, it is important that you call `get_queryset()` instead of accessing this property directly, as `queryset` will get evaluated once, and those results will be cached for all subsequent requests. * `serializer_class` - The serializer class that should be used for validating and deserializing input, and for serializing output. Typically, you must either set this attribute, or override the `get_serializer_class()` method. -* `lookup_field` - The model field that should be used to for performing object lookup of individual model instances. Defaults to `'pk'`. Note that when using hyperlinked APIs you'll need to ensure that *both* the API views *and* the serializer classes set the lookup fields if you need to use a custom value. +* `lookup_field` - The model field that should be used for performing object lookup of individual model instances. Defaults to `'pk'`. Note that when using hyperlinked APIs you'll need to ensure that *both* the API views *and* the serializer classes set the lookup fields if you need to use a custom value. * `lookup_url_kwarg` - The URL keyword argument that should be used for object lookup. The URL conf should include a keyword argument corresponding to this value. If unset this defaults to using the same value as `lookup_field`. **Pagination**: @@ -93,6 +96,12 @@ For example: user = self.request.user return user.accounts.all() +--- + +**Note:** If the `serializer_class` used in the generic view spans orm relations, leading to an n+1 problem, you could optimize your queryset in this method using `select_related` and `prefetch_related`. To get more information about n+1 problem and use cases of the mentioned methods refer to related section in [django documentation][django-docs-select-related]. + +--- + #### `get_object(self)` Returns an object instance that should be used for detail views. Defaults to using the `lookup_field` parameter to filter the base queryset. @@ -120,12 +129,12 @@ Given a queryset, filter it with whichever filter backends are in use, returning For example: def filter_queryset(self, queryset): - filter_backends = (CategoryFilter,) + filter_backends = [CategoryFilter] if 'geo_route' in self.request.query_params: - filter_backends = (GeoRouteFilter, CategoryFilter) + filter_backends = [GeoRouteFilter, CategoryFilter] elif 'geo_point' in self.request.query_params: - filter_backends = (GeoPointFilter, CategoryFilter) + filter_backends = [GeoPointFilter, CategoryFilter] for backend in list(filter_backends): queryset = backend().filter_queryset(self.request, queryset, view=self) @@ -172,8 +181,6 @@ You can also use these hooks to provide additional validation, by raising a `Val raise ValidationError('You have already signed up') serializer.save(user=self.request.user) -**Note**: These methods replace the old-style version 2.x `pre_save`, `post_save`, `pre_delete` and `post_delete` methods, which are no longer available. - **Other methods**: You won't typically need to override the following methods, although you might need to call into them if you're writing custom views using `GenericAPIView`. @@ -210,7 +217,7 @@ If the request data provided for creating the object was invalid, a `400 Bad Req Provides a `.retrieve(request, *args, **kwargs)` method, that implements returning an existing model instance in a response. -If an object can be retrieved this returns a `200 OK` response, with a serialized representation of the object as the body of the response. Otherwise it will return a `404 Not Found`. +If an object can be retrieved this returns a `200 OK` response, with a serialized representation of the object as the body of the response. Otherwise, it will return a `404 Not Found`. ## UpdateModelMixin @@ -318,7 +325,7 @@ Often you'll want to use the existing generic views, but use some slightly custo For example, if you need to lookup objects based on multiple fields in the URL conf, you could create a mixin class like the following: - class MultipleFieldLookupMixin(object): + class MultipleFieldLookupMixin: """ Apply this mixin to any view or viewset to get multiple field filtering based on a `lookup_fields` attribute, instead of the default single field filtering. @@ -328,7 +335,7 @@ For example, if you need to lookup objects based on multiple fields in the URL c queryset = self.filter_queryset(queryset) # Apply any filter backends filter = {} for field in self.lookup_fields: - if self.kwargs[field]: # Ignore empty fields. + if self.kwargs.get(field): # Ignore empty fields. filter[field] = self.kwargs[field] obj = get_object_or_404(queryset, **filter) # Lookup the object self.check_object_permissions(self.request, obj) @@ -339,7 +346,7 @@ You can then simply apply this mixin to a view or viewset anytime you need to ap class RetrieveUserView(MultipleFieldLookupMixin, generics.RetrieveAPIView): queryset = User.objects.all() serializer_class = UserSerializer - lookup_fields = ('account', 'username') + lookup_fields = ['account', 'username'] Using custom mixins is a good option if you have custom behavior that needs to be used. @@ -375,10 +382,6 @@ If you need to generic PUT-as-create behavior you may want to include something The following third party packages provide additional generic view implementations. -## Django REST Framework bulk - -The [django-rest-framework-bulk package][django-rest-framework-bulk] implements generic view mixins as well as some common concrete generic views to allow to apply bulk operations via API requests. - ## Django Rest Multiple Models [Django Rest Multiple Models][django-rest-multiple-models] provides a generic view (and mixin) for sending multiple serialized models and/or querysets via a single API request. @@ -391,5 +394,5 @@ The [django-rest-framework-bulk package][django-rest-framework-bulk] implements [RetrieveModelMixin]: #retrievemodelmixin [UpdateModelMixin]: #updatemodelmixin [DestroyModelMixin]: #destroymodelmixin -[django-rest-framework-bulk]: https://github.com/miki725/django-rest-framework-bulk [django-rest-multiple-models]: https://github.com/MattBroach/DjangoRestMultipleModels +[django-docs-select-related]: https://docs.djangoproject.com/en/3.1/ref/models/querysets/#django.db.models.query.QuerySet.select_related diff --git a/docs/api-guide/metadata.md b/docs/api-guide/metadata.md index a3ba9ac20..20708c6e3 100644 --- a/docs/api-guide/metadata.md +++ b/docs/api-guide/metadata.md @@ -1,4 +1,7 @@ -source: metadata.py +--- +source: + - metadata.py +--- # Metadata @@ -68,7 +71,7 @@ If you have specific requirements for creating schema endpoints that are accesse For example, the following additional route could be used on a viewset to provide a linkable schema endpoint. @action(methods=['GET'], detail=False) - def schema(self, request): + def api_schema(self, request): meta = self.metadata_class() data = meta.determine_metadata(request, self) return Response(data) diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index 99612ef46..3081e2bc3 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -1,4 +1,7 @@ -source: pagination.py +--- +source: + - pagination.py +--- # Pagination @@ -75,7 +78,7 @@ This pagination style accepts a single number page number in the request query p HTTP 200 OK { - "count": 1023 + "count": 1023, "next": "https://api.example.org/accounts/?page=5", "previous": "https://api.example.org/accounts/?page=3", "results": [ @@ -123,7 +126,7 @@ This pagination style mirrors the syntax used when looking up multiple database HTTP 200 OK { - "count": 1023 + "count": 1023, "next": "https://api.example.org/accounts/?limit=100&offset=500", "previous": "https://api.example.org/accounts/?limit=100&offset=300", "results": [ @@ -215,16 +218,16 @@ To set these attributes you should override the `CursorPagination` class, and th # Custom pagination styles -To create a custom pagination serializer class you should subclass `pagination.BasePagination` and override the `paginate_queryset(self, queryset, request, view=None)` and `get_paginated_response(self, data)` methods: +To create a custom pagination serializer class, you should inherit the subclass `pagination.BasePagination`, override the `paginate_queryset(self, queryset, request, view=None)`, and `get_paginated_response(self, data)` methods: -* The `paginate_queryset` method is passed the initial queryset and should return an iterable object that contains only the data in the requested page. -* The `get_paginated_response` method is passed the serialized page data and should return a `Response` instance. +* The `paginate_queryset` method is passed to the initial queryset and should return an iterable object. That object contains only the data in the requested page. +* The `get_paginated_response` method is passed to the serialized page data and should return a `Response` instance. Note that the `paginate_queryset` method may set state on the pagination instance, that may later be used by the `get_paginated_response` method. ## Example -Suppose we want to replace the default pagination output style with a modified format that includes the next and previous links under in a nested 'links' key. We could specify a custom pagination class like so: +Suppose we want to replace the default pagination output style with a modified format that includes the next and previous links under in a nested 'links' key. We could specify a custom pagination class like so: class CustomPagination(pagination.PageNumberPagination): def get_paginated_response(self, data): @@ -257,6 +260,10 @@ To have your custom pagination class be used by default, use the `DEFAULT_PAGINA API responses for list endpoints will now include a `Link` header, instead of including the pagination links as part of the body of the response, for example: +![Link Header][link-header] + +*A custom pagination style, using the 'Link' header'* + ## Pagination & schemas You can also make the pagination controls available to the schema autogeneration @@ -268,12 +275,6 @@ The method should return a list of `coreapi.Field` instances. --- -![Link Header][link-header] - -*A custom pagination style, using the 'Link' header'* - ---- - # HTML pagination controls By default using the pagination classes will cause HTML pagination controls to be displayed in the browsable API. There are two built-in display styles. The `PageNumberPagination` and `LimitOffsetPagination` classes display a list of page numbers with previous and next controls. The `CursorPagination` class displays a simpler style that only displays a previous and next control. @@ -311,7 +312,7 @@ The [`drf-proxy-pagination` package][drf-proxy-pagination] includes a `ProxyPagi ## link-header-pagination -The [`django-rest-framework-link-header-pagination` package][drf-link-header-pagination] includes a `LinkHeaderPagination` class which provides pagination via an HTTP `Link` header as described in [Github's developer documentation](github-link-pagination). +The [`django-rest-framework-link-header-pagination` package][drf-link-header-pagination] includes a `LinkHeaderPagination` class which provides pagination via an HTTP `Link` header as described in [GitHub REST API documentation][github-traversing-with-pagination]. [cite]: https://docs.djangoproject.com/en/stable/topics/pagination/ [link-header]: ../img/link-header-pagination.png @@ -321,3 +322,4 @@ The [`django-rest-framework-link-header-pagination` package][drf-link-header-pag [drf-link-header-pagination]: https://github.com/tbeadle/django-rest-framework-link-header-pagination [disqus-cursor-api]: https://cra.mr/2011/03/08/building-cursors-for-the-disqus-api [float_cursor_pagination_example]: https://gist.github.com/keturn/8bc88525a183fd41c73ffb729b8865be#file-fpcursorpagination-py +[github-traversing-with-pagination]: https://docs.github.com/en/rest/guides/traversing-with-pagination diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md index be48ae7e5..0a85d474f 100644 --- a/docs/api-guide/parsers.md +++ b/docs/api-guide/parsers.md @@ -1,4 +1,7 @@ -source: parsers.py +--- +source: + - parsers.py +--- # Parsers @@ -12,7 +15,7 @@ REST framework includes a number of built in Parser classes, that allow you to a ## How the parser is determined -The set of valid parsers for a view is always defined as a list of classes. When `request.data` is accessed, REST framework will examine the `Content-Type` header on the incoming request, and determine which parser to use to parse the request content. +The set of valid parsers for a view is always defined as a list of classes. When `request.data` is accessed, REST framework will examine the `Content-Type` header on the incoming request, and determine which parser to use to parse the request content. --- @@ -29,9 +32,9 @@ As an example, if you are sending `json` encoded data using jQuery with the [.aj The default set of parsers may be set globally, using the `DEFAULT_PARSER_CLASSES` setting. For example, the following settings would allow only requests with `JSON` content, instead of the default of JSON or form data. REST_FRAMEWORK = { - 'DEFAULT_PARSER_CLASSES': ( + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework.parsers.JSONParser', - ) + ] } You can also set the parsers used for an individual view, or viewset, @@ -45,7 +48,7 @@ using the `APIView` class-based views. """ A view that can accept POST requests with JSON content. """ - parser_classes = (JSONParser,) + parser_classes = [JSONParser] def post(self, request, format=None): return Response({'received data': request.data}) @@ -57,7 +60,7 @@ Or, if you're using the `@api_view` decorator with function based views. from rest_framework.parsers import JSONParser @api_view(['POST']) - @parser_classes((JSONParser,)) + @parser_classes([JSONParser]) def example_view(request, format=None): """ A view that can accept POST requests with JSON content. @@ -70,7 +73,7 @@ Or, if you're using the `@api_view` decorator with function based views. ## JSONParser -Parses `JSON` request content. +Parses `JSON` request content. `request.data` will be populated with a dictionary of data. **.media_type**: `application/json` @@ -84,7 +87,7 @@ You will typically want to use both `FormParser` and `MultiPartParser` together ## MultiPartParser -Parses multipart HTML form content, which supports file uploads. Both `request.data` will be populated with a `QueryDict`. +Parses multipart HTML form content, which supports file uploads. `request.data` and `request.FILES` will be populated with a `QueryDict` and `MultiValueDict` respectively. You will typically want to use both `FormParser` and `MultiPartParser` together in order to fully support HTML form data. @@ -110,7 +113,7 @@ If it is called without a `filename` URL keyword argument, then the client must # views.py class FileUploadView(views.APIView): - parser_classes = (FileUploadParser,) + parser_classes = [FileUploadParser] def put(self, request, filename, format=None): file_obj = request.data['file'] @@ -122,7 +125,7 @@ If it is called without a `filename` URL keyword argument, then the client must # urls.py urlpatterns = [ # ... - url(r'^upload/(?P[^/]+)$', FileUploadView.as_view()) + re_path(r'^upload/(?P[^/]+)$', FileUploadView.as_view()) ] --- @@ -186,12 +189,12 @@ Install using pip. Modify your REST framework settings. REST_FRAMEWORK = { - 'DEFAULT_PARSER_CLASSES': ( + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework_yaml.parsers.YAMLParser', - ), - 'DEFAULT_RENDERER_CLASSES': ( + ], + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_yaml.renderers.YAMLRenderer', - ), + ], } ## XML @@ -207,12 +210,12 @@ Install using pip. Modify your REST framework settings. REST_FRAMEWORK = { - 'DEFAULT_PARSER_CLASSES': ( + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework_xml.parsers.XMLParser', - ), - 'DEFAULT_RENDERER_CLASSES': ( + ], + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_xml.renderers.XMLRenderer', - ), + ], } ## MessagePack diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index 6a1297e60..6e164d220 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -1,4 +1,7 @@ -source: permissions.py +--- +source: + - permissions.py +--- # Permissions @@ -21,9 +24,9 @@ A slightly less strict style of permission would be to allow full access to auth Permissions in REST framework are always defined as a list of permission classes. Before running the main body of the view each permission in the list is checked. -If any permission check fails an `exceptions.PermissionDenied` or `exceptions.NotAuthenticated` exception will be raised, and the main body of the view will not run. +If any permission check fails, an `exceptions.PermissionDenied` or `exceptions.NotAuthenticated` exception will be raised, and the main body of the view will not run. -When the permissions checks fail either a "403 Forbidden" or a "401 Unauthorized" response will be returned, according to the following rules: +When the permission checks fail, either a "403 Forbidden" or a "401 Unauthorized" response will be returned, according to the following rules: * The request was successfully authenticated, but permission was denied. *— An HTTP 403 Forbidden response will be returned.* * The request was not successfully authenticated, and the highest priority authentication class *does not* use `WWW-Authenticate` headers. *— An HTTP 403 Forbidden response will be returned.* @@ -51,7 +54,7 @@ For example: --- **Note**: With the exception of `DjangoObjectPermissions`, the provided -permission classes in `rest_framework.permssions` **do not** implement the +permission classes in `rest_framework.permissions` **do not** implement the methods necessary to check object permissions. If you wish to use the provided permission classes in order to check object @@ -67,21 +70,23 @@ For performance reasons the generic views will not automatically apply object le Often when you're using object level permissions you'll also want to [filter the queryset][filtering] appropriately, to ensure that users only have visibility onto instances that they are permitted to view. +Because the `get_object()` method is not called, object level permissions from the `has_object_permission()` method **are not applied** when creating objects. In order to restrict object creation you need to implement the permission check either in your Serializer class or override the `perform_create()` method of your ViewSet class. + ## Setting the permission policy The default permission policy may be set globally, using the `DEFAULT_PERMISSION_CLASSES` setting. For example. REST_FRAMEWORK = { - 'DEFAULT_PERMISSION_CLASSES': ( + 'DEFAULT_PERMISSION_CLASSES': [ 'rest_framework.permissions.IsAuthenticated', - ) + ] } If not specified, this setting defaults to allowing unrestricted access: - 'DEFAULT_PERMISSION_CLASSES': ( + 'DEFAULT_PERMISSION_CLASSES': [ 'rest_framework.permissions.AllowAny', - ) + ] You can also set the authentication policy on a per-view, or per-viewset basis, using the `APIView` class-based views. @@ -91,7 +96,7 @@ using the `APIView` class-based views. from rest_framework.views import APIView class ExampleView(APIView): - permission_classes = (IsAuthenticated,) + permission_classes = [IsAuthenticated] def get(self, request, format=None): content = { @@ -106,14 +111,14 @@ Or, if you're using the `@api_view` decorator with function based views. from rest_framework.response import Response @api_view(['GET']) - @permission_classes((IsAuthenticated, )) + @permission_classes([IsAuthenticated]) def example_view(request, format=None): content = { 'status': 'request was permitted' } return Response(content) -__Note:__ when you set new permission classes through class attribute or decorators you're telling the view to ignore the default list set over the __settings.py__ file. +__Note:__ when you set new permission classes via the class attribute or decorators you're telling the view to ignore the default list set in the __settings.py__ file. Provided they inherit from `rest_framework.permissions.BasePermission`, permissions can be composed using standard Python bitwise operators. For example, `IsAuthenticatedOrReadOnly` could be written: @@ -126,7 +131,7 @@ Provided they inherit from `rest_framework.permissions.BasePermission`, permissi return request.method in SAFE_METHODS class ExampleView(APIView): - permission_classes = (IsAuthenticated|ReadOnly,) + permission_classes = [IsAuthenticated|ReadOnly] def get(self, request, format=None): content = { @@ -166,22 +171,16 @@ This permission is suitable if you want to your API to allow read permissions to ## DjangoModelPermissions -This permission class ties into Django's standard `django.contrib.auth` [model permissions][contribauth]. This permission must only be applied to views that have a `.queryset` property set. Authorization will only be granted if the user *is authenticated* and has the *relevant model permissions* assigned. +This permission class ties into Django's standard `django.contrib.auth` [model permissions][contribauth]. This permission must only be applied to views that have a `.queryset` property or `get_queryset()` method. Authorization will only be granted if the user *is authenticated* and has the *relevant model permissions* assigned. The appropriate model is determined by checking `get_queryset().model` or `queryset.model`. * `POST` requests require the user to have the `add` permission on the model. * `PUT` and `PATCH` requests require the user to have the `change` permission on the model. * `DELETE` requests require the user to have the `delete` permission on the model. -The default behaviour can also be overridden to support custom model permissions. For example, you might want to include a `view` model permission for `GET` requests. +The default behavior can also be overridden to support custom model permissions. For example, you might want to include a `view` model permission for `GET` requests. To use custom model permissions, override `DjangoModelPermissions` and set the `.perms_map` property. Refer to the source code for details. -#### Using with views that do not include a `queryset` attribute. - -If you're using this permission with a view that uses an overridden `get_queryset()` method there may not be a `queryset` attribute on the view. In this case we suggest also marking the view with a sentinel queryset, so that this class can determine the required permissions. For example: - - queryset = User.objects.none() # Required for DjangoModelPermissions - ## DjangoModelPermissionsOrAnonReadOnly Similar to `DjangoModelPermissions`, but also allows unauthenticated users to have read-only access to the API. @@ -228,7 +227,7 @@ If you need to test if a request is a read operation or a write operation, you s --- -Custom permissions will raise a `PermissionDenied` exception if the test fails. To change the error message associated with the exception, implement a `message` attribute directly on your custom permission. Otherwise the `default_detail` attribute from `PermissionDenied` will be used. +Custom permissions will raise a `PermissionDenied` exception if the test fails. To change the error message associated with the exception, implement a `message` attribute directly on your custom permission. Otherwise the `default_detail` attribute from `PermissionDenied` will be used. Similarly, to change the code identifier associated with the exception, implement a `code` attribute directly on your custom permission - otherwise the `default_code` attribute from `PermissionDenied` will be used. from rest_framework import permissions @@ -240,19 +239,19 @@ Custom permissions will raise a `PermissionDenied` exception if the test fails. ## Examples -The following is an example of a permission class that checks the incoming request's IP address against a blacklist, and denies the request if the IP has been blacklisted. +The following is an example of a permission class that checks the incoming request's IP address against a blocklist, and denies the request if the IP has been blocked. from rest_framework import permissions - class BlacklistPermission(permissions.BasePermission): + class BlocklistPermission(permissions.BasePermission): """ - Global permission check for blacklisted IPs. + Global permission check for blocked IPs. """ def has_permission(self, request, view): ip_addr = request.META['REMOTE_ADDR'] - blacklisted = Blacklist.objects.filter(ip_addr=ip_addr).exists() - return not blacklisted + blocked = Blocklist.objects.filter(ip_addr=ip_addr).exists() + return not blocked As well as global permissions, that are run against all incoming requests, you can also create object-level permissions, that are only run against operations that affect a particular object instance. For example: @@ -275,12 +274,40 @@ Note that the generic views will check the appropriate object level permissions, Also note that the generic views will only check the object-level permissions for views that retrieve a single model instance. If you require object-level filtering of list views, you'll need to filter the queryset separately. See the [filtering documentation][filtering] for more details. +# Overview of access restriction methods + +REST framework offers three different methods to customize access restrictions on a case-by-case basis. These apply in different scenarios and have different effects and limitations. + + * `queryset`/`get_queryset()`: Limits the general visibility of existing objects from the database. The queryset limits which objects will be listed and which objects can be modified or deleted. The `get_queryset()` method can apply different querysets based on the current action. + * `permission_classes`/`get_permissions()`: General permission checks based on the current action, request and targeted object. Object level permissions can only be applied to retrieve, modify and deletion actions. Permission checks for list and create will be applied to the entire object type. (In case of list: subject to restrictions in the queryset.) + * `serializer_class`/`get_serializer()`: Instance level restrictions that apply to all objects on input and output. The serializer may have access to the request context. The `get_serializer()` method can apply different serializers based on the current action. + +The following table lists the access restriction methods and the level of control they offer over which actions. + +| | `queryset` | `permission_classes` | `serializer_class` | +|------------------------------------|------------|----------------------|--------------------| +| Action: list | global | global | object-level* | +| Action: create | no | global | object-level | +| Action: retrieve | global | object-level | object-level | +| Action: update | global | object-level | object-level | +| Action: partial_update | global | object-level | object-level | +| Action: destroy | global | object-level | no | +| Can reference action in decision | no** | yes | no** | +| Can reference request in decision | no** | yes | yes | + + \* A Serializer class should not raise PermissionDenied in a list action, or the entire list would not be returned.
+ \** The `get_*()` methods have access to the current view and can return different Serializer or QuerySet instances based on the request or action. + --- # Third party packages The following third party packages are also available. +## DRF - Access Policy + +The [Django REST - Access Policy][drf-access-policy] package provides a way to define complex access rules in declarative policy classes that are attached to view sets or function-based views. The policies are defined in JSON in a format similar to AWS' Identity & Access Management policies. + ## Composed Permissions The [Composed Permissions][composed-permissions] package provides a simple way to define complex and multi-depth (with logic operators) permission objects, using small and reusable components. @@ -299,12 +326,17 @@ The [Django Rest Framework Roles][django-rest-framework-roles] package makes it ## Django REST Framework API Key -The [Django REST Framework API Key][djangorestframework-api-key] package provides the ability to authorize clients based on customizable API key headers. This package is targeted at situations in which regular user-based authentication (e.g. `TokenAuthentication`) is not suitable, e.g. allowing non-human clients to safely use your API. API keys are generated and validated through cryptographic methods and can be created and revoked from the Django admin interface at anytime. +The [Django REST Framework API Key][djangorestframework-api-key] package provides permissions classes, models and helpers to add API key authorization to your API. It can be used to authorize internal or third-party backends and services (i.e. _machines_) which do not have a user account. API keys are stored securely using Django's password hashing infrastructure, and they can be viewed, edited and revoked at anytime in the Django admin. ## Django Rest Framework Role Filters The [Django Rest Framework Role Filters][django-rest-framework-role-filters] package provides simple filtering over multiple types of roles. +## Django Rest Framework PSQ + +The [Django Rest Framework PSQ][drf-psq] package is an extension that gives support for having action-based **permission_classes**, **serializer_class**, and **queryset** dependent on permission-based rules. + + [cite]: https://developer.apple.com/library/mac/#documentation/security/Conceptual/AuthenticationAndAuthorizationGuide/Authorization/Authorization.html [authentication]: authentication.md [throttling]: throttling.md @@ -315,8 +347,10 @@ The [Django Rest Framework Role Filters][django-rest-framework-role-filters] pac [filtering]: filtering.md [composed-permissions]: https://github.com/niwibe/djangorestframework-composed-permissions [rest-condition]: https://github.com/caxap/rest_condition -[dry-rest-permissions]: https://github.com/Helioscene/dry-rest-permissions +[dry-rest-permissions]: https://github.com/FJNR-inc/dry-rest-permissions [django-rest-framework-roles]: https://github.com/computer-lab/django-rest-framework-roles -[djangorestframework-api-key]: https://github.com/florimondmanca/djangorestframework-api-key +[djangorestframework-api-key]: https://florimondmanca.github.io/djangorestframework-api-key/ [django-rest-framework-role-filters]: https://github.com/allisson/django-rest-framework-role-filters [django-rest-framework-guardian]: https://github.com/rpkilby/django-rest-framework-guardian +[drf-access-policy]: https://github.com/rsinger86/drf-access-policy +[drf-psq]: https://github.com/drf-psq/drf-psq diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md index 8665e80f6..56eb61e43 100644 --- a/docs/api-guide/relations.md +++ b/docs/api-guide/relations.md @@ -1,4 +1,7 @@ -source: relations.py +--- +source: + - relations.py +--- # Serializer relations @@ -14,6 +17,37 @@ Relational fields are used to represent model relationships. They can be applie --- +--- + +**Note:** REST Framework does not attempt to automatically optimize querysets passed to serializers in terms of `select_related` and `prefetch_related` since it would be too much magic. A serializer with a field spanning an orm relation through its source attribute could require an additional database hit to fetch related objects from the database. It is the programmer's responsibility to optimize queries to avoid additional database hits which could occur while using such a serializer. + +For example, the following serializer would lead to a database hit each time evaluating the tracks field if it is not prefetched: + + class AlbumSerializer(serializers.ModelSerializer): + tracks = serializers.SlugRelatedField( + many=True, + read_only=True, + slug_field='title' + ) + + class Meta: + model = Album + fields = ['album_name', 'artist', 'tracks'] + + # For each album object, tracks should be fetched from database + qs = Album.objects.all() + print(AlbumSerializer(qs, many=True).data) + +If `AlbumSerializer` is used to serialize a fairly large queryset with `many=True` then it could be a serious performance problem. Optimizing the queryset passed to `AlbumSerializer` with: + + qs = Album.objects.prefetch_related('tracks') + # No additional database hits required + print(AlbumSerializer(qs, many=True).data) + +would solve the issue. + +--- + #### Inspecting relationships. When using the `ModelSerializer` class, serializer fields and relationships will be automatically generated for you. Inspecting these automatically generated fields can be a useful tool for determining how to customize the relationship style. @@ -43,7 +77,7 @@ In order to explain the various types of relational fields, we'll use a couple o duration = models.IntegerField() class Meta: - unique_together = ('album', 'order') + unique_together = ['album', 'order'] ordering = ['order'] def __str__(self): @@ -53,16 +87,16 @@ In order to explain the various types of relational fields, we'll use a couple o `StringRelatedField` may be used to represent the target of the relationship using its `__str__` method. -For example, the following serializer. +For example, the following serializer: class AlbumSerializer(serializers.ModelSerializer): tracks = serializers.StringRelatedField(many=True) class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] -Would serialize to the following representation. +Would serialize to the following representation: { 'album_name': 'Things We Lost In The Fire', @@ -92,7 +126,7 @@ For example, the following serializer: class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] Would serialize to a representation like this: @@ -132,7 +166,7 @@ For example, the following serializer: class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] Would serialize to a representation like this: @@ -184,7 +218,7 @@ For example, the following serializer: class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] Would serialize to a representation like this: @@ -212,14 +246,14 @@ When using `SlugRelatedField` as a read-write field, you will normally want to e ## HyperlinkedIdentityField -This field can be applied as an identity relationship, such as the `'url'` field on a HyperlinkedModelSerializer. It can also be used for an attribute on the object. For example, the following serializer: +This field can be applied as an identity relationship, such as the `'url'` field on a HyperlinkedModelSerializer. It can also be used for an attribute on the object. For example, the following serializer: class AlbumSerializer(serializers.HyperlinkedModelSerializer): track_listing = serializers.HyperlinkedIdentityField(view_name='track-list') class Meta: model = Album - fields = ('album_name', 'artist', 'track_listing') + fields = ['album_name', 'artist', 'track_listing'] Would serialize to a representation like this: @@ -242,7 +276,9 @@ This field is always read-only. # Nested relationships -Nested relationships can be expressed by using serializers as fields. +As opposed to previously discussed _references_ to another entity, the referred entity can instead also be embedded or _nested_ +in the representation of the object that refers to it. +Such nested relationships can be expressed by using serializers as fields. If the field is used to represent a to-many relationship, you should add the `many=True` flag to the serializer field. @@ -253,14 +289,14 @@ For example, the following serializer: class TrackSerializer(serializers.ModelSerializer): class Meta: model = Track - fields = ('order', 'title', 'duration') + fields = ['order', 'title', 'duration'] class AlbumSerializer(serializers.ModelSerializer): tracks = TrackSerializer(many=True, read_only=True) class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] Would serialize to a nested representation like this: @@ -286,19 +322,19 @@ Would serialize to a nested representation like this: ## Writable nested serializers -By default nested serializers are read-only. If you want to support write-operations to a nested serializer field you'll need to create `create()` and/or `update()` methods in order to explicitly specify how the child relationships should be saved. +By default nested serializers are read-only. If you want to support write-operations to a nested serializer field you'll need to create `create()` and/or `update()` methods in order to explicitly specify how the child relationships should be saved: class TrackSerializer(serializers.ModelSerializer): class Meta: model = Track - fields = ('order', 'title', 'duration') + fields = ['order', 'title', 'duration'] class AlbumSerializer(serializers.ModelSerializer): tracks = TrackSerializer(many=True) class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] def create(self, validated_data): tracks_data = validated_data.pop('tracks') @@ -332,13 +368,13 @@ output representation should be generated from the model instance. To implement a custom relational field, you should override `RelatedField`, and implement the `.to_representation(self, value)` method. This method takes the target of the field as the `value` argument, and should return the representation that should be used to serialize the target. The `value` argument will typically be a model instance. -If you want to implement a read-write relational field, you must also implement the `.to_internal_value(self, data)` method. +If you want to implement a read-write relational field, you must also implement the [`.to_internal_value(self, data)` method][to_internal_value]. To provide a dynamic queryset based on the `context`, you can also override `.get_queryset(self)` instead of specifying `.queryset` on the class or when initializing the field. ## Example -For example, we could define a relational field to serialize a track to a custom string representation, using its ordering, title, and duration. +For example, we could define a relational field to serialize a track to a custom string representation, using its ordering, title, and duration: import time @@ -352,9 +388,9 @@ For example, we could define a relational field to serialize a track to a custom class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] -This custom field would then serialize to the following representation. +This custom field would then serialize to the following representation: { 'album_name': 'Sometimes I Wish We Were an Eagle', @@ -458,8 +494,8 @@ This behavior is intended to prevent a template from being unable to render in a There are two keyword arguments you can use to control this behavior: -- `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Set to `None` to disable any limiting. Defaults to `1000`. -- `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"` +* `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Set to `None` to disable any limiting. Defaults to `1000`. +* `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"` You can also control these globally using the settings `HTML_SELECT_CUTOFF` and `HTML_SELECT_CUTOFF_TEXT`. @@ -477,7 +513,7 @@ Note that reverse relationships are not automatically included by the `ModelSeri class AlbumSerializer(serializers.ModelSerializer): class Meta: - fields = ('tracks', ...) + fields = ['tracks', ...] You'll normally want to ensure that you've set an appropriate `related_name` argument on the relationship, that you can use as the field name. For example: @@ -489,7 +525,7 @@ If you have not set a related name for the reverse relationship, you'll need to class AlbumSerializer(serializers.ModelSerializer): class Meta: - fields = ('track_set', ...) + fields = ['track_set', ...] See the Django documentation on [reverse relationships][reverse-relationships] for more details. @@ -530,7 +566,7 @@ And the following two models, which may have associated tags: text = models.CharField(max_length=1000) tags = GenericRelation(TaggedItem) -We could define a custom field that could be used to serialize tagged instances, using the type of each instance to determine how it should be serialized. +We could define a custom field that could be used to serialize tagged instances, using the type of each instance to determine how it should be serialized: class TaggedObjectRelatedField(serializers.RelatedField): """ @@ -576,6 +612,8 @@ If you explicitly specify a relational field pointing to a ``ManyToManyField`` with a through model, be sure to set ``read_only`` to ``True``. +If you wish to represent [extra fields on a through model][django-intermediary-manytomany] then you may serialize the through model as [a nested object][dealing-with-nested-objects]. + --- # Third Party Packages @@ -596,3 +634,6 @@ The [rest-framework-generic-relations][drf-nested-relations] library provides re [generic-relations]: https://docs.djangoproject.com/en/stable/ref/contrib/contenttypes/#id1 [drf-nested-routers]: https://github.com/alanjds/drf-nested-routers [drf-nested-relations]: https://github.com/Ian-Foote/rest-framework-generic-relations +[django-intermediary-manytomany]: https://docs.djangoproject.com/en/stable/topics/db/models/#intermediary-manytomany +[dealing-with-nested-objects]: https://www.django-rest-framework.org/api-guide/serializers/#dealing-with-nested-objects +[to_internal_value]: https://www.django-rest-framework.org/api-guide/serializers/#to_internal_valueself-data diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index 4ec409681..44f1b6021 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -1,4 +1,7 @@ -source: renderers.py +--- +source: + - renderers.py +--- # Renderers @@ -21,10 +24,10 @@ For more information see the documentation on [content negotiation][conneg]. The default set of renderers may be set globally, using the `DEFAULT_RENDERER_CLASSES` setting. For example, the following settings would use `JSON` as the main media type and also include the self describing API. REST_FRAMEWORK = { - 'DEFAULT_RENDERER_CLASSES': ( + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.BrowsableAPIRenderer', - ) + ] } You can also set the renderers used for an individual view, or viewset, @@ -39,7 +42,7 @@ using the `APIView` class-based views. """ A view that returns the count of active users in JSON. """ - renderer_classes = (JSONRenderer, ) + renderer_classes = [JSONRenderer] def get(self, request, format=None): user_count = User.objects.filter(active=True).count() @@ -49,7 +52,7 @@ using the `APIView` class-based views. Or, if you're using the `@api_view` decorator with function based views. @api_view(['GET']) - @renderer_classes((JSONRenderer,)) + @renderer_classes([JSONRenderer]) def user_count_view(request, format=None): """ A view that returns the count of active users in JSON. @@ -100,6 +103,16 @@ Unlike other renderers, the data passed to the `Response` does not need to be se The TemplateHTMLRenderer will create a `RequestContext`, using the `response.data` as the context dict, and determine a template name to use to render the context. +--- + +**Note:** When used with a view that makes use of a serializer the `Response` sent for rendering may not be a dictionary and will need to be wrapped in a dict before returning to allow the `TemplateHTMLRenderer` to render it. For example: + +``` +response.data = {'results': response.data} +``` + +--- + The template name is determined by (in order of preference): 1. An explicit `template_name` argument passed to the response. @@ -113,7 +126,7 @@ An example of a view that uses `TemplateHTMLRenderer`: A view that returns a templated HTML representation of a given user. """ queryset = User.objects.all() - renderer_classes = (TemplateHTMLRenderer,) + renderer_classes = [TemplateHTMLRenderer] def get(self, request, *args, **kwargs): self.object = self.get_object() @@ -139,8 +152,8 @@ A simple renderer that simply returns pre-rendered HTML. Unlike other renderers An example of a view that uses `StaticHTMLRenderer`: - @api_view(('GET',)) - @renderer_classes((StaticHTMLRenderer,)) + @api_view(['GET']) + @renderer_classes([StaticHTMLRenderer]) def simple_html_view(request): data = '

Hello, world

' return Response(data) @@ -179,7 +192,7 @@ By default the response content will be rendered with the highest priority rende def get_default_renderer(self, view): return JSONRenderer() -## AdminRenderer +## AdminRenderer Renders data into HTML for an admin-like display: @@ -244,7 +257,7 @@ This renderer is used for rendering HTML multipart form data. **It is not suita # Custom renderers -To implement a custom renderer, you should override `BaseRenderer`, set the `.media_type` and `.format` properties, and implement the `.render(self, data, media_type=None, renderer_context=None)` method. +To implement a custom renderer, you should override `BaseRenderer`, set the `.media_type` and `.format` properties, and implement the `.render(self, data, accepted_media_type=None, renderer_context=None)` method. The method should return a bytestring, which will be used as the body of the HTTP response. @@ -254,7 +267,7 @@ The arguments passed to the `.render()` method are: The request data, as set by the `Response()` instantiation. -### `media_type=None` +### `accepted_media_type=None` Optional. If provided, this is the accepted media type, as determined by the content negotiation stage. @@ -270,7 +283,7 @@ By default this will include the following keys: `view`, `request`, `response`, The following is an example plaintext renderer that will return a response with the `data` parameter as the content of the response. - from django.utils.encoding import smart_unicode + from django.utils.encoding import smart_text from rest_framework import renderers @@ -278,8 +291,8 @@ The following is an example plaintext renderer that will return a response with media_type = 'text/plain' format = 'txt' - def render(self, data, media_type=None, renderer_context=None): - return data.encode(self.charset) + def render(self, data, accepted_media_type=None, renderer_context=None): + return smart_text(data, encoding=self.charset) ## Setting the character set @@ -290,7 +303,7 @@ By default renderer classes are assumed to be using the `UTF-8` encoding. To us format = 'txt' charset = 'iso-8859-1' - def render(self, data, media_type=None, renderer_context=None): + def render(self, data, accepted_media_type=None, renderer_context=None): return data.encode(self.charset) Note that if a renderer class returns a unicode string, then the response content will be coerced into a bytestring by the `Response` class, with the `charset` attribute set on the renderer used to determine the encoding. @@ -305,7 +318,7 @@ In some cases you may also want to set the `render_style` attribute to `'binary' charset = None render_style = 'binary' - def render(self, data, media_type=None, renderer_context=None): + def render(self, data, accepted_media_type=None, renderer_context=None): return data --- @@ -319,14 +332,14 @@ You can do some pretty flexible things using REST framework's renderers. Some e * Specify multiple types of HTML representation for API clients to use. * Underspecify a renderer's media type, such as using `media_type = 'image/*'`, and use the `Accept` header to vary the encoding of the response. -## Varying behaviour by media type +## Varying behavior by media type In some cases you might want your view to use different serialization styles depending on the accepted media type. If you need to do this you can access `request.accepted_renderer` to determine the negotiated renderer that will be used for the response. For example: - @api_view(('GET',)) - @renderer_classes((TemplateHTMLRenderer, JSONRenderer)) + @api_view(['GET']) + @renderer_classes([TemplateHTMLRenderer, JSONRenderer]) def list_users(request): """ A view that can return JSON or HTML representations @@ -398,12 +411,12 @@ Install using pip. Modify your REST framework settings. REST_FRAMEWORK = { - 'DEFAULT_PARSER_CLASSES': ( + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework_yaml.parsers.YAMLParser', - ), - 'DEFAULT_RENDERER_CLASSES': ( + ], + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_yaml.renderers.YAMLRenderer', - ), + ], } ## XML @@ -419,12 +432,12 @@ Install using pip. Modify your REST framework settings. REST_FRAMEWORK = { - 'DEFAULT_PARSER_CLASSES': ( + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework_xml.parsers.XMLParser', - ), - 'DEFAULT_RENDERER_CLASSES': ( + ], + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_xml.renderers.XMLRenderer', - ), + ], } ## JSONP @@ -448,42 +461,42 @@ Install using pip. Modify your REST framework settings. REST_FRAMEWORK = { - 'DEFAULT_RENDERER_CLASSES': ( + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_jsonp.renderers.JSONPRenderer', - ), + ], } ## MessagePack [MessagePack][messagepack] is a fast, efficient binary serialization format. [Juan Riaza][juanriaza] maintains the [djangorestframework-msgpack][djangorestframework-msgpack] package which provides MessagePack renderer and parser support for REST framework. -## XLSX (Binary Spreadsheet Endpoints) +## Microsoft Excel: XLSX (Binary Spreadsheet Endpoints) -XLSX is the world's most popular binary spreadsheet format. [Tim Allen][flipperpa] of [The Wharton School][wharton] maintains [drf-renderer-xlsx][drf-renderer-xlsx], which renders an endpoint as an XLSX spreadsheet using OpenPyXL, and allows the client to download it. Spreadsheets can be styled on a per-view basis. +XLSX is the world's most popular binary spreadsheet format. [Tim Allen][flipperpa] of [The Wharton School][wharton] maintains [drf-excel][drf-excel], which renders an endpoint as an XLSX spreadsheet using OpenPyXL, and allows the client to download it. Spreadsheets can be styled on a per-view basis. #### Installation & configuration Install using pip. - $ pip install drf-renderer-xlsx + $ pip install drf-excel Modify your REST framework settings. REST_FRAMEWORK = { ... - 'DEFAULT_RENDERER_CLASSES': ( + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.BrowsableAPIRenderer', - 'drf_renderer_xlsx.renderers.XLSXRenderer', - ), + 'drf_excel.renderers.XLSXRenderer', + ], } To avoid having a file streamed without a filename (which the browser will often default to the filename "download", with no extension), we need to use a mixin to override the `Content-Disposition` header. If no filename is provided, it will default to `export.xlsx`. For example: from rest_framework.viewsets import ReadOnlyModelViewSet - from drf_renderer_xlsx.mixins import XLSXFileMixin - from drf_renderer_xlsx.renderers import XLSXRenderer + from drf_excel.mixins import XLSXFileMixin + from drf_excel.renderers import XLSXRenderer from .models import MyExampleModel from .serializers import MyExampleSerializer @@ -491,7 +504,7 @@ To avoid having a file streamed without a filename (which the browser will often class MyExampleViewSet(XLSXFileMixin, ReadOnlyModelViewSet): queryset = MyExampleModel.objects.all() serializer_class = MyExampleSerializer - renderer_classes = (XLSXRenderer,) + renderer_classes = [XLSXRenderer] filename = 'my_export.xlsx' ## CSV @@ -500,7 +513,7 @@ Comma-separated values are a plain-text tabular data format, that can be easily ## UltraJSON -[UltraJSON][ultrajson] is an optimized C JSON encoder which can give significantly faster JSON rendering. [Jacob Haslehurst][hzy] maintains the [drf-ujson-renderer][drf-ujson-renderer] package which implements JSON rendering using the UJSON package. +[UltraJSON][ultrajson] is an optimized C JSON encoder which can give significantly faster JSON rendering. [Adam Mertz][Amertz08] maintains [drf_ujson2][drf_ujson2], a fork of the now unmaintained [drf-ujson-renderer][drf-ujson-renderer], which implements JSON rendering using the UJSON package. ## CamelCase JSON @@ -515,7 +528,7 @@ Comma-separated values are a plain-text tabular data format, that can be easily [Rest Framework Latex] provides a renderer that outputs PDFs using Laulatex. It is maintained by [Pebble (S/F Software)][mypebble]. -[cite]: https://docs.djangoproject.com/en/stable/stable/template-response/#the-rendering-process +[cite]: https://docs.djangoproject.com/en/stable/ref/template-response/#the-rendering-process [conneg]: content-negotiation.md [html-and-forms]: ../topics/html-and-forms.md [browser-accept-headers]: http://www.gethifi.com/blog/browser-rest-http-accept-headers @@ -534,9 +547,9 @@ Comma-separated values are a plain-text tabular data format, that can be easily [messagepack]: https://msgpack.org/ [juanriaza]: https://github.com/juanriaza [mjumbewu]: https://github.com/mjumbewu -[flipperpa]: https://githuc.com/flipperpa +[flipperpa]: https://github.com/flipperpa [wharton]: https://github.com/wharton -[drf-renderer-xlsx]: https://github.com/wharton/drf-renderer-xlsx +[drf-excel]: https://github.com/wharton/drf-excel [vbabiy]: https://github.com/vbabiy [rest-framework-yaml]: https://jpadilla.github.io/django-rest-framework-yaml/ [rest-framework-xml]: https://jpadilla.github.io/django-rest-framework-xml/ @@ -544,8 +557,9 @@ Comma-separated values are a plain-text tabular data format, that can be easily [djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack [djangorestframework-csv]: https://github.com/mjumbewu/django-rest-framework-csv [ultrajson]: https://github.com/esnme/ultrajson -[hzy]: https://github.com/hzy +[Amertz08]: https://github.com/Amertz08 [drf-ujson-renderer]: https://github.com/gizmag/drf-ujson-renderer +[drf_ujson2]: https://github.com/Amertz08/drf_ujson2 [djangorestframework-camel-case]: https://github.com/vbabiy/djangorestframework-camel-case [Django REST Pandas]: https://github.com/wq/django-rest-pandas [Pandas]: https://pandas.pydata.org/ diff --git a/docs/api-guide/requests.md b/docs/api-guide/requests.md index 28450f082..d072ac436 100644 --- a/docs/api-guide/requests.md +++ b/docs/api-guide/requests.md @@ -1,4 +1,7 @@ -source: request.py +--- +source: + - request.py +--- # Requests @@ -20,7 +23,7 @@ REST framework's Request objects provide flexible request parsing that allows yo * It includes all parsed content, including *file and non-file* inputs. * It supports parsing the content of HTTP methods other than `POST`, meaning that you can access the content of `PUT` and `PATCH` requests. -* It supports REST framework's flexible request parsing, rather than just supporting form data. For example you can handle incoming JSON data in the same way that you handle incoming form data. +* It supports REST framework's flexible request parsing, rather than just supporting form data. For example you can handle incoming [JSON data] similarly to how you handle incoming [form data]. For more details see the [parsers documentation]. @@ -46,7 +49,7 @@ If a client sends a request with a content-type that cannot be parsed then a `Un # Content negotiation -The request exposes some properties that allow you to determine the result of the content negotiation stage. This allows you to implement behaviour such as selecting a different serialisation schemes for different media types. +The request exposes some properties that allow you to determine the result of the content negotiation stage. This allows you to implement behavior such as selecting a different serialization schemes for different media types. ## .accepted_renderer @@ -90,7 +93,7 @@ You won't typically need to access this property. --- -**Note:** You may see a `WrappedAttributeError` raised when calling the `.user` or `.auth` properties. These errors originate from an authenticator as a standard `AttributeError`, however it's necessary that they be re-raised as a different exception type in order to prevent them from being suppressed by the outer property access. Python will not recognize that the `AttributeError` orginates from the authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. The authenticator will need to be fixed. +**Note:** You may see a `WrappedAttributeError` raised when calling the `.user` or `.auth` properties. These errors originate from an authenticator as a standard `AttributeError`, however it's necessary that they be re-raised as a different exception type in order to prevent them from being suppressed by the outer property access. Python will not recognize that the `AttributeError` originates from the authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. The authenticator will need to be fixed. --- @@ -133,5 +136,7 @@ Note that due to implementation reasons the `Request` class does not inherit fro [cite]: https://groups.google.com/d/topic/django-developers/dxI4qVzrBY4/discussion [parsers documentation]: parsers.md +[JSON data]: parsers.md#jsonparser +[form data]: parsers.md#formparser [authentication documentation]: authentication.md [browser enhancements documentation]: ../topics/browser-enhancements.md diff --git a/docs/api-guide/responses.md b/docs/api-guide/responses.md index e9c2d41f1..dbdc8ff2c 100644 --- a/docs/api-guide/responses.md +++ b/docs/api-guide/responses.md @@ -1,4 +1,7 @@ -source: response.py +--- +source: + - response.py +--- # Responses @@ -91,5 +94,5 @@ As with any other `TemplateResponse`, this method is called to render the serial You won't typically need to call `.render()` yourself, as it's handled by Django's standard response cycle. -[cite]: https://docs.djangoproject.com/en/stable/stable/template-response/ +[cite]: https://docs.djangoproject.com/en/stable/ref/template-response/ [statuscodes]: status-codes.md diff --git a/docs/api-guide/reverse.md b/docs/api-guide/reverse.md index 00abcf571..82dd16881 100644 --- a/docs/api-guide/reverse.md +++ b/docs/api-guide/reverse.md @@ -1,4 +1,7 @@ -source: reverse.py +--- +source: + - reverse.py +--- # Returning URLs @@ -29,16 +32,16 @@ You should **include the request as a keyword argument** to the function, for ex from rest_framework.reverse import reverse from rest_framework.views import APIView - from django.utils.timezone import now + from django.utils.timezone import now - class APIRootView(APIView): - def get(self, request): - year = now().year - data = { - ... - 'year-summary-url': reverse('year-summary', args=[year], request=request) + class APIRootView(APIView): + def get(self, request): + year = now().year + data = { + ... + 'year-summary-url': reverse('year-summary', args=[year], request=request) } - return Response(data) + return Response(data) ## reverse_lazy diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md index 09c6c39cb..70c05fdde 100644 --- a/docs/api-guide/routers.md +++ b/docs/api-guide/routers.md @@ -1,4 +1,7 @@ -source: routers.py +--- +source: + - routers.py +--- # Routers @@ -60,7 +63,7 @@ For example, you can append `router.urls` to a list of existing views... router.register(r'accounts', AccountViewSet) urlpatterns = [ - url(r'^forgot-password/$', ForgotPasswordFormView.as_view()), + path('forgot-password/', ForgotPasswordFormView.as_view()), ] urlpatterns += router.urls @@ -68,22 +71,22 @@ For example, you can append `router.urls` to a list of existing views... Alternatively you can use Django's `include` function, like so... urlpatterns = [ - url(r'^forgot-password/$', ForgotPasswordFormView.as_view()), - url(r'^', include(router.urls)), + path('forgot-password', ForgotPasswordFormView.as_view()), + path('', include(router.urls)), ] You may use `include` with an application namespace: urlpatterns = [ - url(r'^forgot-password/$', ForgotPasswordFormView.as_view()), - url(r'^api/', include((router.urls, 'app_name'))), + path('forgot-password/', ForgotPasswordFormView.as_view()), + path('api/', include((router.urls, 'app_name'))), ] Or both an application and instance namespace: urlpatterns = [ - url(r'^forgot-password/$', ForgotPasswordFormView.as_view()), - url(r'^api/', include((router.urls, 'app_name'), namespace='instance_name')), + path('forgot-password/', ForgotPasswordFormView.as_view()), + path('api/', include((router.urls, 'app_name'), namespace='instance_name')), ] See Django's [URL namespaces docs][url-namespace-docs] and the [`include` API reference][include-api-reference] for more details. @@ -335,5 +338,5 @@ The [`DRF-extensions` package][drf-extensions] provides [routers][drf-extensions [drf-extensions-nested-viewsets]: https://chibisov.github.io/drf-extensions/docs/#nested-routes [drf-extensions-collection-level-controllers]: https://chibisov.github.io/drf-extensions/docs/#collection-level-controllers [drf-extensions-customizable-endpoint-names]: https://chibisov.github.io/drf-extensions/docs/#controller-endpoint-name -[url-namespace-docs]: https://docs.djangoproject.com/en/1.11/topics/http/urls/#url-namespaces -[include-api-reference]: https://docs.djangoproject.com/en/2.0/ref/urls/#include +[url-namespace-docs]: https://docs.djangoproject.com/en/4.0/topics/http/urls/#url-namespaces +[include-api-reference]: https://docs.djangoproject.com/en/4.0/ref/urls/#include diff --git a/docs/api-guide/schemas.md b/docs/api-guide/schemas.md index 3d07ed621..e402019a4 100644 --- a/docs/api-guide/schemas.md +++ b/docs/api-guide/schemas.md @@ -1,6 +1,9 @@ -source: schemas.py +--- +source: + - schemas +--- -# Schemas +# Schema > A machine-readable [schema] describes what resources are available via the API, what their URLs are, how they are represented and what operations they support. > @@ -10,24 +13,43 @@ API schemas are a useful tool that allow for a range of use cases, including generating reference documentation, or driving dynamic client libraries that can interact with your API. -## Install Core API & PyYAML +Django REST Framework provides support for automatic generation of +[OpenAPI][openapi] schemas. -You'll need to install the `coreapi` package in order to add schema support -for REST framework. You probably also want to install `pyyaml`, so that you -can render the schema into the commonly used YAML-based OpenAPI format. +## Overview - pip install coreapi pyyaml +Schema generation has several moving parts. It's worth having an overview: -## Quickstart +* `SchemaGenerator` is a top-level class that is responsible for walking your + configured URL patterns, finding `APIView` subclasses, enquiring for their + schema representation, and compiling the final schema object. +* `AutoSchema` encapsulates all the details necessary for per-view schema + introspection. Is attached to each view via the `schema` attribute. You + subclass `AutoSchema` in order to customize your schema. +* The `generateschema` management command allows you to generate a static schema + offline. +* Alternatively, you can route `SchemaView` to dynamically generate and serve + your schema. +* `settings.DEFAULT_SCHEMA_CLASS` allows you to specify an `AutoSchema` + subclass to serve as your project's default. -There are two different ways you can serve a schema description for you API. +The following sections explain more. -### Generating a schema with the `generateschema` management command +## Generating an OpenAPI Schema -To generate a static API schema, use the `generateschema` management command. +### Install dependencies -```shell -$ python manage.py generateschema > schema.yml + pip install pyyaml uritemplate + +* `pyyaml` is used to generate schema into YAML-based OpenAPI format. +* `uritemplate` is used internally to get parameters in path. + +### Generating a static schema with the `generateschema` management command + +If your schema is static, you can use the `generateschema` management command: + +```bash +./manage.py generateschema --file openapi-schema.yml ``` Once you've generated a schema in this way you can annotate it with any @@ -37,802 +59,382 @@ generator. You might want to check your API schema into version control and update it with each new release, or serve the API schema from your site's static media. -### Adding a view with `get_schema_view` +### Generating a dynamic schema with `SchemaView` -To add a dynamically generated schema view to your API, use `get_schema_view`. +If you require a dynamic schema, because foreign key choices depend on database +values, for example, you can route a `SchemaView` that will generate and serve +your schema on demand. + +To route a `SchemaView`, use the `get_schema_view()` helper. + +In `urls.py`: ```python from rest_framework.schemas import get_schema_view -schema_view = get_schema_view(title="Example API") - urlpatterns = [ - url('^schema$', schema_view), - ... + # ... + # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs. + # * `title` and `description` parameters are passed to `SchemaGenerator`. + # * Provide view name for use with `reverse()`. + path('openapi', get_schema_view( + title="Your Project", + description="API for all things …", + version="1.0.0" + ), name='openapi-schema'), + # ... ] ``` -See below [for more details](#the-get_schema_view-shortcut) on customizing a -dynamically generated schema view. +#### `get_schema_view()` + +The `get_schema_view()` helper takes the following keyword arguments: + +* `title`: May be used to provide a descriptive title for the schema definition. +* `description`: Longer descriptive text. +* `version`: The version of the API. +* `url`: May be used to pass a canonical base URL for the schema. + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/' + ) + +* `urlconf`: A string representing the import path to the URL conf that you want + to generate an API schema for. This defaults to the value of Django's + `ROOT_URLCONF` setting. + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + urlconf='myproject.urls' + ) + +* `patterns`: List of url patterns to limit the schema introspection to. If you + only want the `myproject.api` urls to be exposed in the schema: + + schema_url_patterns = [ + path('api/', include('myproject.api.urls')), + ] + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + patterns=schema_url_patterns, + ) +* `public`: May be used to specify if schema should bypass views permissions. Default to False + +* `generator_class`: May be used to specify a `SchemaGenerator` subclass to be + passed to the `SchemaView`. +* `authentication_classes`: May be used to specify the list of authentication + classes that will apply to the schema endpoint. Defaults to + `settings.DEFAULT_AUTHENTICATION_CLASSES` +* `permission_classes`: May be used to specify the list of permission classes + that will apply to the schema endpoint. Defaults to + `settings.DEFAULT_PERMISSION_CLASSES`. +* `renderer_classes`: May be used to pass the set of renderer classes that can + be used to render the API root endpoint. -## Internal schema representation - -REST framework uses [Core API][coreapi] in order to model schema information in -a format-independent representation. This information can then be rendered -into various different schema formats, or used to generate API documentation. - -When using Core API, a schema is represented as a `Document` which is the -top-level container object for information about the API. Available API -interactions are represented using `Link` objects. Each link includes a URL, -HTTP method, and may include a list of `Field` instances, which describe any -parameters that may be accepted by the API endpoint. The `Link` and `Field` -instances may also include descriptions, that allow an API schema to be -rendered into user documentation. - -Here's an example of an API description that includes a single `search` -endpoint: - - coreapi.Document( - title='Flight Search API', - url='https://api.example.org/', - content={ - 'search': coreapi.Link( - url='/search/', - action='get', - fields=[ - coreapi.Field( - name='from', - required=True, - location='query', - description='City name or airport code.' - ), - coreapi.Field( - name='to', - required=True, - location='query', - description='City name or airport code.' - ), - coreapi.Field( - name='date', - required=True, - location='query', - description='Flight date in "YYYY-MM-DD" format.' - ) - ], - description='Return flight availability and prices.' - ) - } - ) - -## Schema output formats - -In order to be presented in an HTTP response, the internal representation -has to be rendered into the actual bytes that are used in the response. - -REST framework includes a few different renderers that you can use for -encoding the API schema. - -* `renderers.OpenAPIRenderer` - Renders into YAML-based [OpenAPI][open-api], the most widely used API schema format. -* `renderers.JSONOpenAPIRenderer` - Renders into JSON-based [OpenAPI][open-api]. -* `renderers.CoreJSONRenderer` - Renders into [Core JSON][corejson], a format designed for -use with the `coreapi` client library. - - -[Core JSON][corejson] is designed as a canonical format for use with Core API. -REST framework includes a renderer class for handling this media type, which -is available as `renderers.CoreJSONRenderer`. - - -## Schemas vs Hypermedia - -It's worth pointing out here that Core API can also be used to model hypermedia -responses, which present an alternative interaction style to API schemas. - -With an API schema, the entire available interface is presented up-front -as a single endpoint. Responses to individual API endpoints are then typically -presented as plain data, without any further interactions contained in each -response. - -With Hypermedia, the client is instead presented with a document containing -both data and available interactions. Each interaction results in a new -document, detailing both the current state and the available interactions. - -Further information and support on building Hypermedia APIs with REST framework -is planned for a future version. - - ---- - -# Creating a schema - -REST framework includes functionality for auto-generating a schema, -or allows you to specify one explicitly. - -## Manual Schema Specification - -To manually specify a schema you create a Core API `Document`, similar to the -example above. - - schema = coreapi.Document( - title='Flight Search API', - content={ - ... - } - ) - - -## Automatic Schema Generation - -Automatic schema generation is provided by the `SchemaGenerator` class. - -`SchemaGenerator` processes a list of routed URL patterns and compiles the -appropriately structured Core API Document. - -Basic usage is just to provide the title for your schema and call -`get_schema()`: - - generator = schemas.SchemaGenerator(title='Flight Search API') - schema = generator.get_schema() - -## Per-View Schema Customisation - -By default, view introspection is performed by an `AutoSchema` instance -accessible via the `schema` attribute on `APIView`. This provides the -appropriate Core API `Link` object for the view, request method and path: - - auto_schema = view.schema - coreapi_link = auto_schema.get_link(...) - -(In compiling the schema, `SchemaGenerator` calls `view.schema.get_link()` for -each view, allowed method and path.) - ---- - -**Note**: For basic `APIView` subclasses, default introspection is essentially -limited to the URL kwarg path parameters. For `GenericAPIView` -subclasses, which includes all the provided class based views, `AutoSchema` will -attempt to introspect serialiser, pagination and filter fields, as well as -provide richer path field descriptions. (The key hooks here are the relevant -`GenericAPIView` attributes and methods: `get_serializer`, `pagination_class`, -`filter_backends` and so on.) - ---- - -To customise the `Link` generation you may: - -* Instantiate `AutoSchema` on your view with the `manual_fields` kwarg: - - from rest_framework.views import APIView - from rest_framework.schemas import AutoSchema - - class CustomView(APIView): - ... - schema = AutoSchema( - manual_fields=[ - coreapi.Field("extra_field", ...), - ] - ) - - This allows extension for the most common case without subclassing. - -* Provide an `AutoSchema` subclass with more complex customisation: - - from rest_framework.views import APIView - from rest_framework.schemas import AutoSchema - - class CustomSchema(AutoSchema): - def get_link(...): - # Implement custom introspection here (or in other sub-methods) - - class CustomView(APIView): - ... - schema = CustomSchema() - - This provides complete control over view introspection. - -* Instantiate `ManualSchema` on your view, providing the Core API `Fields` for - the view explicitly: - - from rest_framework.views import APIView - from rest_framework.schemas import ManualSchema - - class CustomView(APIView): - ... - schema = ManualSchema(fields=[ - coreapi.Field( - "first_field", - required=True, - location="path", - schema=coreschema.String() - ), - coreapi.Field( - "second_field", - required=True, - location="path", - schema=coreschema.String() - ), - ]) - - This allows manually specifying the schema for some views whilst maintaining - automatic generation elsewhere. - -You may disable schema generation for a view by setting `schema` to `None`: - - class CustomView(APIView): - ... - schema = None # Will not appear in schema - -This also applies to extra actions for `ViewSet`s: - - class CustomViewSet(viewsets.ModelViewSet): - - @action(detail=True, schema=None) - def extra_action(self, request, pk=None): - ... - ---- - -**Note**: For full details on `SchemaGenerator` plus the `AutoSchema` and -`ManualSchema` descriptors see the [API Reference below](#api-reference). - ---- - -# Adding a schema view - -There are a few different ways to add a schema view to your API, depending on -exactly what you need. - -## The get_schema_view shortcut - -The simplest way to include a schema in your project is to use the -`get_schema_view()` function. - - from rest_framework.schemas import get_schema_view - - schema_view = get_schema_view(title="Server Monitoring API") - - urlpatterns = [ - url('^$', schema_view), - ... - ] - -Once the view has been added, you'll be able to make API requests to retrieve -the auto-generated schema definition. - - $ http http://127.0.0.1:8000/ Accept:application/coreapi+json - HTTP/1.0 200 OK - Allow: GET, HEAD, OPTIONS - Content-Type: application/vnd.coreapi+json - - { - "_meta": { - "title": "Server Monitoring API" - }, - "_type": "document", - ... - } - -The arguments to `get_schema_view()` are: - -#### `title` - -May be used to provide a descriptive title for the schema definition. - -#### `url` - -May be used to pass a canonical URL for the schema. - - schema_view = get_schema_view( - title='Server Monitoring API', - url='https://www.example.org/api/' - ) - -#### `urlconf` - -A string representing the import path to the URL conf that you want -to generate an API schema for. This defaults to the value of Django's -ROOT_URLCONF setting. - - schema_view = get_schema_view( - title='Server Monitoring API', - url='https://www.example.org/api/', - urlconf='myproject.urls' - ) - -#### `renderer_classes` - -May be used to pass the set of renderer classes that can be used to render the API root endpoint. - - from rest_framework.schemas import get_schema_view - from rest_framework.renderers import JSONOpenAPIRenderer - - schema_view = get_schema_view( - title='Server Monitoring API', - url='https://www.example.org/api/', - renderer_classes=[JSONOpenAPIRenderer] - ) - -#### `patterns` - -List of url patterns to limit the schema introspection to. If you only want the `myproject.api` urls -to be exposed in the schema: - - schema_url_patterns = [ - url(r'^api/', include('myproject.api.urls')), - ] - - schema_view = get_schema_view( - title='Server Monitoring API', - url='https://www.example.org/api/', - patterns=schema_url_patterns, - ) - -#### `generator_class` - -May be used to specify a `SchemaGenerator` subclass to be passed to the -`SchemaView`. - -#### `authentication_classes` - -May be used to specify the list of authentication classes that will apply to the schema endpoint. -Defaults to `settings.DEFAULT_AUTHENTICATION_CLASSES` - -#### `permission_classes` - -May be used to specify the list of permission classes that will apply to the schema endpoint. -Defaults to `settings.DEFAULT_PERMISSION_CLASSES` - -## Using an explicit schema view - -If you need a little more control than the `get_schema_view()` shortcut gives you, -then you can use the `SchemaGenerator` class directly to auto-generate the -`Document` instance, and to return that from a view. - -This option gives you the flexibility of setting up the schema endpoint -with whatever behaviour you want. For example, you can apply different -permission, throttling, or authentication policies to the schema endpoint. - -Here's an example of using `SchemaGenerator` together with a view to -return the schema. - -**views.py:** - - from rest_framework.decorators import api_view, renderer_classes - from rest_framework import renderers, response, schemas - - generator = schemas.SchemaGenerator(title='Bookings API') - - @api_view() - @renderer_classes([renderers.OpenAPIRenderer]) - def schema_view(request): - schema = generator.get_schema(request) - return response.Response(schema) - -**urls.py:** - - urlpatterns = [ - url('/', schema_view), - ... - ] - -You can also serve different schemas to different users, depending on the -permissions they have available. This approach can be used to ensure that -unauthenticated requests are presented with a different schema to -authenticated requests, or to ensure that different parts of the API are -made visible to different users depending on their role. - -In order to present a schema with endpoints filtered by user permissions, -you need to pass the `request` argument to the `get_schema()` method, like so: - - @api_view() - @renderer_classes([renderers.OpenAPIRenderer]) - def schema_view(request): - generator = schemas.SchemaGenerator(title='Bookings API') - return response.Response(generator.get_schema(request=request)) - -## Explicit schema definition - -An alternative to the auto-generated approach is to specify the API schema -explicitly, by declaring a `Document` object in your codebase. Doing so is a -little more work, but ensures that you have full control over the schema -representation. - - import coreapi - from rest_framework.decorators import api_view, renderer_classes - from rest_framework import renderers, response - - schema = coreapi.Document( - title='Bookings API', - content={ - ... - } - ) - - @api_view() - @renderer_classes([renderers.OpenAPIRenderer]) - def schema_view(request): - return response.Response(schema) - ---- - -# Schemas as documentation - -One common usage of API schemas is to use them to build documentation pages. - -The schema generation in REST framework uses docstrings to automatically -populate descriptions in the schema document. - -These descriptions will be based on: - -* The corresponding method docstring if one exists. -* A named section within the class docstring, which can be either single line or multi-line. -* The class docstring. - -## Examples - -An `APIView`, with an explicit method docstring. - - class ListUsernames(APIView): - def get(self, request): - """ - Return a list of all user names in the system. - """ - usernames = [user.username for user in User.objects.all()] - return Response(usernames) - -A `ViewSet`, with an explict action docstring. - - class ListUsernames(ViewSet): - def list(self, request): - """ - Return a list of all user names in the system. - """ - usernames = [user.username for user in User.objects.all()] - return Response(usernames) - -A generic view with sections in the class docstring, using single-line style. - - class UserList(generics.ListCreateAPIView): - """ - get: List all the users. - post: Create a new user. - """ - queryset = User.objects.all() - serializer_class = UserSerializer - permission_classes = (IsAdminUser,) - -A generic viewset with sections in the class docstring, using multi-line style. - - class UserViewSet(viewsets.ModelViewSet): - """ - API endpoint that allows users to be viewed or edited. - - retrieve: - Return a user instance. - - list: - Return all users, ordered by most recently joined. - """ - queryset = User.objects.all().order_by('-date_joined') - serializer_class = UserSerializer - ---- - -# API Reference ## SchemaGenerator -A class that walks a list of routed URL patterns, requests the schema for each view, -and collates the resulting CoreAPI Document. +**Schema-level customization** -Typically you'll instantiate `SchemaGenerator` with a single argument, like so: +```python +from rest_framework.schemas.openapi import SchemaGenerator +``` + +`SchemaGenerator` is a class that walks a list of routed URL patterns, requests +the schema for each view and collates the resulting OpenAPI schema. + +Typically you won't need to instantiate `SchemaGenerator` yourself, but you can +do so like so: generator = SchemaGenerator(title='Stock Prices API') Arguments: -* `title` **required** - The name of the API. -* `url` - The root URL of the API schema. This option is not required unless the schema is included under path prefix. -* `patterns` - A list of URLs to inspect when generating the schema. Defaults to the project's URL conf. -* `urlconf` - A URL conf module name to use when generating the schema. Defaults to `settings.ROOT_URLCONF`. +* `title` **required**: The name of the API. +* `description`: Longer descriptive text. +* `version`: The version of the API. Defaults to `0.1.0`. +* `url`: The root URL of the API schema. This option is not required unless the schema is included under path prefix. +* `patterns`: A list of URLs to inspect when generating the schema. Defaults to the project's URL conf. +* `urlconf`: A URL conf module name to use when generating the schema. Defaults to `settings.ROOT_URLCONF`. -### get_schema(self, request) +In order to customize the top-level schema, subclass +`rest_framework.schemas.openapi.SchemaGenerator` and provide your subclass +as an argument to the `generateschema` command or `get_schema_view()` helper +function. -Returns a `coreapi.Document` instance that represents the API schema. +### get_schema(self, request=None, public=False) - @api_view - @renderer_classes([renderers.OpenAPIRenderer]) - def schema_view(request): - generator = schemas.SchemaGenerator(title='Bookings API') - return Response(generator.get_schema()) +Returns a dictionary that represents the OpenAPI schema: -The `request` argument is optional, and may be used if you want to apply per-user -permissions to the resulting schema generation. + generator = SchemaGenerator(title='Stock Prices API') + schema = generator.get_schema() -### get_links(self, request) +The `request` argument is optional, and may be used if you want to apply +per-user permissions to the resulting schema generation. -Return a nested dictionary containing all the links that should be included in the API schema. - -This is a good point to override if you want to modify the resulting structure of the generated schema, -as you can build a new dictionary with a different layout. +This is a good point to override if you want to customize the generated +dictionary For example you might wish to add terms of service to the [top-level +`info` object][info-object]: +``` +class TOSSchemaGenerator(SchemaGenerator): + def get_schema(self, *args, **kwargs): + schema = super().get_schema(*args, **kwargs) + schema["info"]["termsOfService"] = "https://example.com/tos.html" + return schema +``` ## AutoSchema -A class that deals with introspection of individual views for schema generation. - -`AutoSchema` is attached to `APIView` via the `schema` attribute. - -The `AutoSchema` constructor takes a single keyword argument `manual_fields`. - -**`manual_fields`**: a `list` of `coreapi.Field` instances that will be added to -the generated fields. Generated fields with a matching `name` will be overwritten. - - class CustomView(APIView): - schema = AutoSchema(manual_fields=[ - coreapi.Field( - "my_extra_field", - required=True, - location="path", - schema=coreschema.String() - ), - ]) - -For more advanced customisation subclass `AutoSchema` to customise schema generation. - - class CustomViewSchema(AutoSchema): - """ - Overrides `get_link()` to provide Custom Behavior X - """ - - def get_link(self, path, method, base_url): - link = super().get_link(path, method, base_url) - # Do something to customize link here... - return link - - class MyView(APIView): - schema = CustomViewSchema() - -The following methods are available to override. - -### get_link(self, path, method, base_url) - -Returns a `coreapi.Link` instance corresponding to the given view. - -This is the main entry point. -You can override this if you need to provide custom behaviors for particular views. - -### get_description(self, path, method) - -Returns a string to use as the link description. By default this is based on the -view docstring as described in the "Schemas as Documentation" section above. - -### get_encoding(self, path, method) - -Returns a string to indicate the encoding for any request body, when interacting -with the given view. Eg. `'application/json'`. May return a blank string for views -that do not expect a request body. - -### get_path_fields(self, path, method): - -Return a list of `coreapi.Field()` instances. One for each path parameter in the URL. - -### get_serializer_fields(self, path, method) - -Return a list of `coreapi.Field()` instances. One for each field in the serializer class used by the view. - -### get_pagination_fields(self, path, method) - -Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method on any pagination class used by the view. - -### get_filter_fields(self, path, method) - -Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method of any filter classes used by the view. - -### get_manual_fields(self, path, method) - -Return a list of `coreapi.Field()` instances to be added to or replace generated fields. Defaults to (optional) `manual_fields` passed to `AutoSchema` constructor. - -May be overridden to customise manual fields by `path` or `method`. For example, a per-method adjustment may look like this: +**Per-View Customization** ```python -def get_manual_fields(self, path, method): - """Example adding per-method fields.""" - - extra_fields = [] - if method=='GET': - extra_fields = # ... list of extra fields for GET ... - if method=='POST': - extra_fields = # ... list of extra fields for POST ... - - manual_fields = super().get_manual_fields(path, method) - return manual_fields + extra_fields +from rest_framework.schemas.openapi import AutoSchema ``` -### update_fields(fields, update_with) +By default, view introspection is performed by an `AutoSchema` instance +accessible via the `schema` attribute on `APIView`. -Utility `staticmethod`. Encapsulates logic to add or replace fields from a list -by `Field.name`. May be overridden to adjust replacement criteria. + auto_schema = some_view.schema +`AutoSchema` provides the OpenAPI elements needed for each view, request method +and path: -## ManualSchema +* A list of [OpenAPI components][openapi-components]. In DRF terms these are + mappings of serializers that describe request and response bodies. +* The appropriate [OpenAPI operation object][openapi-operation] that describes + the endpoint, including path and query parameters for pagination, filtering, + and so on. -Allows manually providing a list of `coreapi.Field` instances for the schema, -plus an optional description. +```python +components = auto_schema.get_components(...) +operation = auto_schema.get_operation(...) +``` - class MyView(APIView): - schema = ManualSchema(fields=[ - coreapi.Field( - "first_field", - required=True, - location="path", - schema=coreschema.String() - ), - coreapi.Field( - "second_field", - required=True, - location="path", - schema=coreschema.String() - ), - ] - ) +In compiling the schema, `SchemaGenerator` calls `get_components()` and +`get_operation()` for each view, allowed method, and path. -The `ManualSchema` constructor takes two arguments: +---- -**`fields`**: A list of `coreapi.Field` instances. Required. +**Note**: The automatic introspection of components, and many operation +parameters relies on the relevant attributes and methods of +`GenericAPIView`: `get_serializer()`, `pagination_class`, `filter_backends`, +etc. For basic `APIView` subclasses, default introspection is essentially limited to +the URL kwarg path parameters for this reason. -**`description`**: A string description. Optional. +---- -**`encoding`**: Default `None`. A string encoding, e.g `application/json`. Optional. +`AutoSchema` encapsulates the view introspection needed for schema generation. +Because of this all the schema generation logic is kept in a single place, +rather than being spread around the already extensive view, serializer and +field APIs. ---- +Keeping with this pattern, try not to let schema logic leak into your own +views, serializers, or fields when customizing the schema generation. You might +be tempted to do something like this: -## Core API +```python +class CustomSchema(AutoSchema): + """ + AutoSchema subclass using schema_extra_info on the view. + """ + ... -This documentation gives a brief overview of the components within the `coreapi` -package that are used to represent an API schema. +class CustomView(APIView): + schema = CustomSchema() + schema_extra_info = ... some extra info ... +``` -Note that these classes are imported from the `coreapi` package, rather than -from the `rest_framework` package. +Here, the `AutoSchema` subclass goes looking for `schema_extra_info` on the +view. This is _OK_ (it doesn't actually hurt) but it means you'll end up with +your schema logic spread out in a number of different places. -### Document +Instead try to subclass `AutoSchema` such that the `extra_info` doesn't leak +out into the view: -Represents a container for the API schema. +```python +class BaseSchema(AutoSchema): + """ + AutoSchema subclass that knows how to use extra_info. + """ + ... -#### `title` +class CustomSchema(BaseSchema): + extra_info = ... some extra info ... -A name for the API. +class CustomView(APIView): + schema = CustomSchema() +``` -#### `url` +This style is slightly more verbose but maintains the encapsulation of the +schema related code. It's more _cohesive_ in the _parlance_. It'll keep the +rest of your API code more tidy. -A canonical URL for the API. +If an option applies to many view classes, rather than creating a specific +subclass per-view, you may find it more convenient to allow specifying the +option as an `__init__()` kwarg to your base `AutoSchema` subclass: -#### `content` +```python +class CustomSchema(BaseSchema): + def __init__(self, **kwargs): + # store extra_info for later + self.extra_info = kwargs.pop("extra_info") + super().__init__(**kwargs) -A dictionary, containing the `Link` objects that the schema contains. +class CustomView(APIView): + schema = CustomSchema( + extra_info=... some extra info ... + ) +``` -In order to provide more structure to the schema, the `content` dictionary -may be nested, typically to a second level. For example: +This saves you having to create a custom subclass per-view for a commonly used option. - content={ - "bookings": { - "list": Link(...), - "create": Link(...), - ... - }, - "venues": { - "list": Link(...), - ... - }, - ... - } +Not all `AutoSchema` methods expose related `__init__()` kwargs, but those for +the more commonly needed options do. -### Link +### `AutoSchema` methods -Represents an individual API endpoint. +#### `get_components()` -#### `url` +Generates the OpenAPI components that describe request and response bodies, +deriving their properties from the serializer. -The URL of the endpoint. May be a URI template, such as `/users/{username}/`. +Returns a dictionary mapping the component name to the generated +representation. By default this has just a single pair but you may override +`get_components()` to return multiple pairs if your view uses multiple +serializers. -#### `action` +#### `get_component_name()` -The HTTP method associated with the endpoint. Note that URLs that support -more than one HTTP method, should correspond to a single `Link` for each. +Computes the component's name from the serializer. -#### `fields` +You may see warnings if your API has duplicate component names. If so you can override `get_component_name()` or pass the `component_name` `__init__()` kwarg (see below) to provide different names. -A list of `Field` instances, describing the available parameters on the input. +#### `get_reference()` -#### `description` +Returns a reference to the serializer component. This may be useful if you override `get_schema()`. -A short description of the meaning and intended usage of the endpoint. -### Field +#### `map_serializer()` -Represents a single input parameter on a given API endpoint. +Maps serializers to their OpenAPI representations. -#### `name` +Most serializers should conform to the standard OpenAPI `object` type, but you may +wish to override `map_serializer()` in order to customize this or other +serializer-level fields. -A descriptive name for the input. +#### `map_field()` -#### `required` +Maps individual serializer fields to their schema representation. The base implementation +will handle the default fields that Django REST Framework provides. -A boolean, indicated if the client is required to included a value, or if -the parameter can be omitted. +For `SerializerMethodField` instances, for which the schema is unknown, or custom field subclasses you should override `map_field()` to generate the correct schema: -#### `location` +```python +class CustomSchema(AutoSchema): + """Extension of ``AutoSchema`` to add support for custom field schemas.""" -Determines how the information is encoded into the request. Should be one of -the following strings: + def map_field(self, field): + # Handle SerializerMethodFields or custom fields here... + # ... + return super().map_field(field) +``` -**"path"** +Authors of third-party packages should aim to provide an `AutoSchema` subclass, +and a mixin, overriding `map_field()` so that users can easily generate schemas +for their custom fields. -Included in a templated URI. For example a `url` value of `/products/{product_code}/` could be used together with a `"path"` field, to handle API inputs in a URL path such as `/products/slim-fit-jeans/`. +#### `get_tags()` -These fields will normally correspond with [named arguments in the project URL conf][named-arguments]. +OpenAPI groups operations by tags. By default tags taken from the first path +segment of the routed URL. For example, a URL like `/users/{id}/` will generate +the tag `users`. -**"query"** +You can pass an `__init__()` kwarg to manually specify tags (see below), or +override `get_tags()` to provide custom logic. -Included as a URL query parameter. For example `?search=sale`. Typically for `GET` requests. +#### `get_operation()` -These fields will normally correspond with pagination and filtering controls on a view. +Returns the [OpenAPI operation object][openapi-operation] that describes the +endpoint, including path and query parameters for pagination, filtering, and so +on. -**"form"** +Together with `get_components()`, this is the main entry point to the view +introspection. -Included in the request body, as a single item of a JSON object or HTML form. For example `{"colour": "blue", ...}`. Typically for `POST`, `PUT` and `PATCH` requests. Multiple `"form"` fields may be included on a single link. +#### `get_operation_id()` -These fields will normally correspond with serializer fields on a view. +There must be a unique [operationid](openapi-operationid) for each operation. +By default the `operationId` is deduced from the model name, serializer name or +view name. The operationId looks like "listItems", "retrieveItem", +"updateItem", etc. The `operationId` is camelCase by convention. -**"body"** +#### `get_operation_id_base()` -Included as the complete request body. Typically for `POST`, `PUT` and `PATCH` requests. No more than one `"body"` field may exist on a link. May not be used together with `"form"` fields. +If you have several views with the same model name, you may see duplicate +operationIds. -These fields will normally correspond with views that use `ListSerializer` to validate the request input, or with file upload views. +In order to work around this, you can override `get_operation_id_base()` to +provide a different base for name part of the ID. -#### `encoding` +#### `get_serializer()` -**"application/json"** +If the view has implemented `get_serializer()`, returns the result. -JSON encoded request content. Corresponds to views using `JSONParser`. -Valid only if either one or more `location="form"` fields, or a single -`location="body"` field is included on the `Link`. +#### `get_request_serializer()` -**"multipart/form-data"** +By default returns `get_serializer()` but can be overridden to +differentiate between request and response objects. -Multipart encoded request content. Corresponds to views using `MultiPartParser`. -Valid only if one or more `location="form"` fields is included on the `Link`. +#### `get_response_serializer()` -**"application/x-www-form-urlencoded"** +By default returns `get_serializer()` but can be overridden to +differentiate between request and response objects. -URL encoded request content. Corresponds to views using `FormParser`. Valid -only if one or more `location="form"` fields is included on the `Link`. +### `AutoSchema.__init__()` kwargs -**"application/octet-stream"** +`AutoSchema` provides a number of `__init__()` kwargs that can be used for +common customizations, if the default generated values are not appropriate. -Binary upload request content. Corresponds to views using `FileUploadParser`. -Valid only if a `location="body"` field is included on the `Link`. +The available kwargs are: -#### `description` +* `tags`: Specify a list of tags. +* `component_name`: Specify the component name. +* `operation_id_base`: Specify the resource-name part of operation IDs. -A short description of the meaning and intended usage of the input field. +You pass the kwargs when declaring the `AutoSchema` instance on your view: +``` +class PetDetailView(generics.RetrieveUpdateDestroyAPIView): + schema = AutoSchema( + tags=['Pets'], + component_name='Pet', + operation_id_base='Pet', + ) + ... +``` ---- +Assuming a `Pet` model and `PetSerializer` serializer, the kwargs in this +example are probably not needed. Often, though, you'll need to pass the kwargs +if you have multiple view targeting the same model, or have multiple views with +identically named serializers. -# Third party packages - -## drf-yasg - Yet Another Swagger Generator - -[drf-yasg][drf-yasg] generates [OpenAPI][open-api] documents suitable for code generation - nested schemas, -named models, response bodies, enum/pattern/min/max validators, form parameters, etc. +If your views have related customizations that are needed frequently, you can +create a base `AutoSchema` subclass for your project that takes additional +`__init__()` kwargs to save subclassing `AutoSchema` for each view. [cite]: https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api -[coreapi]: https://www.coreapi.org/ -[corejson]: https://www.coreapi.org/specification/encoding/#core-json-encoding -[drf-yasg]: https://github.com/axnsan12/drf-yasg/ -[open-api]: https://openapis.org/ -[json-hyperschema]: https://json-schema.org/latest/json-schema-hypermedia.html -[api-blueprint]: https://apiblueprint.org/ -[static-files]: https://docs.djangoproject.com/en/stable/howto/static-files/ -[named-arguments]: https://docs.djangoproject.com/en/stable/topics/http/urls/#named-groups +[openapi]: https://github.com/OAI/OpenAPI-Specification +[openapi-specification-extensions]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#specification-extensions +[openapi-operation]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject +[openapi-tags]: https://swagger.io/specification/#tagObject +[openapi-operationid]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#fixed-fields-17 +[openapi-components]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#componentsObject +[openapi-reference]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#referenceObject +[openapi-generator]: https://github.com/OpenAPITools/openapi-generator +[swagger-codegen]: https://github.com/swagger-api/swagger-codegen +[info-object]: https://swagger.io/specification/#infoObject diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index e25053936..0d14cac46 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -1,4 +1,7 @@ -source: serializers.py +--- +source: + - serializers.py +--- # Serializers @@ -18,7 +21,7 @@ Let's start by creating a simple object we can use for example purposes: from datetime import datetime - class Comment(object): + class Comment: def __init__(self, email, content, created=None): self.email = email self.content = content @@ -113,7 +116,7 @@ Calling `.save()` will either create a new instance, or update an existing insta # .save() will update the existing `comment` instance. serializer = CommentSerializer(comment, data=data) -Both the `.create()` and `.update()` methods are optional. You can implement either neither, one, or both of them, depending on the use-case for your serializer class. +Both the `.create()` and `.update()` methods are optional. You can implement either none, one, or both of them, depending on the use-case for your serializer class. #### Passing additional attributes to `.save()` @@ -158,7 +161,7 @@ Each key in the dictionary will be the field name, and the values will be lists When deserializing a list of items, errors will be returned as a list of dictionaries representing each of the deserialized items. -#### Raising an exception on invalid data +#### Raising an exception on invalid data The `.is_valid()` method takes an optional `raise_exception` flag that will cause it to raise a `serializers.ValidationError` exception if there are validation errors. @@ -235,10 +238,12 @@ Serializer classes can also include reusable validators that are applied to the class Meta: # Each room only has one event per day. - validators = UniqueTogetherValidator( - queryset=Event.objects.all(), - fields=['room_number', 'date'] - ) + validators = [ + UniqueTogetherValidator( + queryset=Event.objects.all(), + fields=['room_number', 'date'] + ) + ] For more information see the [validators documentation](validators.md). @@ -246,7 +251,7 @@ For more information see the [validators documentation](validators.md). When passing an initial object or queryset to a serializer instance, the object will be made available as `.instance`. If no initial object is passed then the `.instance` attribute will be `None`. -When passing data to a serializer instance, the unmodified data will be made available as `.initial_data`. If the data keyword argument is not passed then the `.initial_data` attribute will not exist. +When passing data to a serializer instance, the unmodified data will be made available as `.initial_data`. If the `data` keyword argument is not passed then the `.initial_data` attribute will not exist. ## Partial updates @@ -277,7 +282,7 @@ If a nested representation may optionally accept the `None` value you should pas content = serializers.CharField(max_length=200) created = serializers.DateTimeField() -Similarly if a nested representation should be a list of items, you should pass the `many=True` flag to the nested serialized. +Similarly if a nested representation should be a list of items, you should pass the `many=True` flag to the nested serializer. class CommentSerializer(serializers.Serializer): user = UserSerializer(required=False) @@ -308,7 +313,7 @@ The following example demonstrates how you might handle creating a user with a n class Meta: model = User - fields = ('username', 'email', 'profile') + fields = ['username', 'email', 'profile'] def create(self, validated_data): profile_data = validated_data.pop('profile') @@ -330,7 +335,7 @@ Here's an example for an `.update()` method on our previous `UserSerializer` cla def update(self, instance, validated_data): profile_data = validated_data.pop('profile') # Unless the application properly enforces that this field is - # always set, the follow could raise a `DoesNotExist`, which + # always set, the following could raise a `DoesNotExist`, which # would need to be handled. profile = instance.profile @@ -379,8 +384,8 @@ This manager class now more nicely encapsulates that user instances and profile def create(self, validated_data): return User.objects.create( username=validated_data['username'], - email=validated_data['email'] - is_premium_member=validated_data['profile']['is_premium_member'] + email=validated_data['email'], + is_premium_member=validated_data['profile']['is_premium_member'], has_support_contract=validated_data['profile']['has_support_contract'] ) @@ -438,7 +443,7 @@ Declaring a `ModelSerializer` looks like this: class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - fields = ('id', 'account_name', 'users', 'created') + fields = ['id', 'account_name', 'users', 'created'] By default, all the model fields on the class will be mapped to a corresponding serializer fields. @@ -467,7 +472,7 @@ For example: class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - fields = ('id', 'account_name', 'users', 'created') + fields = ['id', 'account_name', 'users', 'created'] You can also set the `fields` attribute to the special value `'__all__'` to indicate that all fields in the model should be used. @@ -485,7 +490,7 @@ For example: class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - exclude = ('users',) + exclude = ['users'] In the example above, if the `Account` model had 3 fields `account_name`, `users`, and `created`, this will result in the fields `account_name` and `created` to be serialized. @@ -502,7 +507,7 @@ The default `ModelSerializer` uses primary keys for relationships, but you can a class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - fields = ('id', 'account_name', 'users', 'created') + fields = ['id', 'account_name', 'users', 'created'] depth = 1 The `depth` option should be set to an integer value that indicates the depth of relationships that should be traversed before reverting to a flat representation. @@ -519,6 +524,7 @@ You can add extra fields to a `ModelSerializer` or override the default fields b class Meta: model = Account + fields = ['url', 'groups'] Extra fields can correspond to any property or callable on the model. @@ -531,8 +537,8 @@ This option should be a list or tuple of field names, and is declared as follows class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - fields = ('id', 'account_name', 'users', 'created') - read_only_fields = ('account_name',) + fields = ['id', 'account_name', 'users', 'created'] + read_only_fields = ['account_name'] Model fields which have `editable=False` set, and `AutoField` fields will be set to read-only by default, and do not need to be added to the `read_only_fields` option. @@ -560,7 +566,7 @@ This option is a dictionary, mapping field names to a dictionary of keyword argu class CreateUserSerializer(serializers.ModelSerializer): class Meta: model = User - fields = ('email', 'username', 'password') + fields = ['email', 'username', 'password'] extra_kwargs = {'password': {'write_only': True}} def create(self, validated_data): @@ -572,6 +578,8 @@ This option is a dictionary, mapping field names to a dictionary of keyword argu user.save() return user +Please keep in mind that, if the field has already been explicitly declared on the serializer class, then the `extra_kwargs` option will be ignored. + ## Relational fields When serializing model instances, there are a number of different ways you might choose to represent relationships. The default representation for `ModelSerializer` is to use the primary keys of the related instances. @@ -586,15 +594,15 @@ The ModelSerializer class also exposes an API that you can override in order to Normally if a `ModelSerializer` does not generate the fields you need by default then you should either add them to the class explicitly, or simply use a regular `Serializer` class instead. However in some cases you may want to create a new base class that defines how the serializer fields are created for any given model. -### `.serializer_field_mapping` +### `serializer_field_mapping` -A mapping of Django model classes to REST framework serializer classes. You can override this mapping to alter the default serializer classes that should be used for each model class. +A mapping of Django model fields to REST framework serializer fields. You can override this mapping to alter the default serializer fields that should be used for each model field. -### `.serializer_related_field` +### `serializer_related_field` This property should be the serializer field class, that is used for relational fields by default. -For `ModelSerializer` this defaults to `PrimaryKeyRelatedField`. +For `ModelSerializer` this defaults to `serializers.PrimaryKeyRelatedField`. For `HyperlinkedModelSerializer` this defaults to `serializers.HyperlinkedRelatedField`. @@ -614,21 +622,21 @@ Defaults to `serializers.ChoiceField` The following methods are called to determine the class and keyword arguments for each field that should be automatically included on the serializer. Each of these methods should return a two tuple of `(field_class, field_kwargs)`. -### `.build_standard_field(self, field_name, model_field)` +### `build_standard_field(self, field_name, model_field)` Called to generate a serializer field that maps to a standard model field. The default implementation returns a serializer class based on the `serializer_field_mapping` attribute. -### `.build_relational_field(self, field_name, relation_info)` +### `build_relational_field(self, field_name, relation_info)` Called to generate a serializer field that maps to a relational model field. -The default implementation returns a serializer class based on the `serializer_relational_field` attribute. +The default implementation returns a serializer class based on the `serializer_related_field` attribute. The `relation_info` argument is a named tuple, that contains `model_field`, `related_model`, `to_many` and `has_through_model` properties. -### `.build_nested_field(self, field_name, relation_info, nested_depth)` +### `build_nested_field(self, field_name, relation_info, nested_depth)` Called to generate a serializer field that maps to a relational model field, when the `depth` option has been set. @@ -638,17 +646,17 @@ The `nested_depth` will be the value of the `depth` option, minus one. The `relation_info` argument is a named tuple, that contains `model_field`, `related_model`, `to_many` and `has_through_model` properties. -### `.build_property_field(self, field_name, model_class)` +### `build_property_field(self, field_name, model_class)` Called to generate a serializer field that maps to a property or zero-argument method on the model class. The default implementation returns a `ReadOnlyField` class. -### `.build_url_field(self, field_name, model_class)` +### `build_url_field(self, field_name, model_class)` Called to generate a serializer field for the serializer's own `url` field. The default implementation returns a `HyperlinkedIdentityField` class. -### `.build_unknown_field(self, field_name, model_class)` +### `build_unknown_field(self, field_name, model_class)` Called when the field name did not map to any model field or model property. The default implementation raises an error, although subclasses may customize this behavior. @@ -668,7 +676,7 @@ You can explicitly include the primary key by adding it to the `fields` option, class AccountSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = Account - fields = ('url', 'id', 'account_name', 'users', 'created') + fields = ['url', 'id', 'account_name', 'users', 'created'] ## Absolute and relative URLs @@ -700,7 +708,7 @@ You can override a URL field view name and lookup field by using either, or both class AccountSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = Account - fields = ('account_url', 'account_name', 'users', 'created') + fields = ['account_url', 'account_name', 'users', 'created'] extra_kwargs = { 'url': {'view_name': 'accounts', 'lookup_field': 'account_name'}, 'users': {'lookup_field': 'username'} @@ -722,7 +730,7 @@ Alternatively you can set the fields on the serializer explicitly. For example: class Meta: model = Account - fields = ('url', 'account_name', 'users', 'created') + fields = ['url', 'account_name', 'users', 'created'] --- @@ -748,6 +756,14 @@ The following argument can also be passed to a `ListSerializer` field or a seria This is `True` by default, but can be set to `False` if you want to disallow empty lists as valid input. +### `max_length` + +This is `None` by default, but can be set to a positive integer if you want to validates that the list contains no more than this number of elements. + +### `min_length` + +This is `None` by default, but can be set to a positive integer if you want to validates that the list contains no fewer than this number of elements. + ### Customizing `ListSerializer` behavior There *are* a few use cases when you might want to customize the `ListSerializer` behavior. For example: @@ -870,7 +886,7 @@ Because this class provides the same interface as the `Serializer` class, you ca The only difference you'll notice when doing so is the `BaseSerializer` classes will not generate HTML forms in the browsable API. This is because the data they return does not include all the field information that would allow each field to be rendered into a suitable HTML input. -##### Read-only `BaseSerializer` classes +#### Read-only `BaseSerializer` classes To implement a read-only serializer using the `BaseSerializer` class, we just need to override the `.to_representation()` method. Let's take a look at an example using a simple Django model: @@ -882,10 +898,10 @@ To implement a read-only serializer using the `BaseSerializer` class, we just ne It's simple to create a read-only serializer for converting `HighScore` instances into primitive data types. class HighScoreSerializer(serializers.BaseSerializer): - def to_representation(self, obj): + def to_representation(self, instance): return { - 'score': obj.score, - 'player_name': obj.player_name + 'score': instance.score, + 'player_name': instance.player_name } We can now use this class to serialize single `HighScore` instances: @@ -894,7 +910,7 @@ We can now use this class to serialize single `HighScore` instances: def high_score(request, pk): instance = HighScore.objects.get(pk=pk) serializer = HighScoreSerializer(instance) - return Response(serializer.data) + return Response(serializer.data) Or use it to serialize multiple instances: @@ -902,9 +918,9 @@ Or use it to serialize multiple instances: def all_high_scores(request): queryset = HighScore.objects.order_by('-score') serializer = HighScoreSerializer(queryset, many=True) - return Response(serializer.data) + return Response(serializer.data) -##### Read-write `BaseSerializer` classes +#### Read-write `BaseSerializer` classes To create a read-write serializer we first need to implement a `.to_internal_value()` method. This method returns the validated values that will be used to construct the object instance, and may raise a `serializers.ValidationError` if the supplied data is in an incorrect format. @@ -933,17 +949,17 @@ Here's a complete example of our previous `HighScoreSerializer`, that's been upd 'player_name': 'May not be more than 10 characters.' }) - # Return the validated values. This will be available as - # the `.validated_data` property. + # Return the validated values. This will be available as + # the `.validated_data` property. return { 'score': int(score), 'player_name': player_name } - def to_representation(self, obj): + def to_representation(self, instance): return { - 'score': obj.score, - 'player_name': obj.player_name + 'score': instance.score, + 'player_name': instance.player_name } def create(self, validated_data): @@ -953,17 +969,18 @@ Here's a complete example of our previous `HighScoreSerializer`, that's been upd The `BaseSerializer` class is also useful if you want to implement new generic serializer classes for dealing with particular serialization styles, or for integrating with alternative storage backends. -The following class is an example of a generic serializer that can handle coercing arbitrary objects into primitive representations. +The following class is an example of a generic serializer that can handle coercing arbitrary complex objects into primitive representations. class ObjectSerializer(serializers.BaseSerializer): """ A read-only serializer that coerces arbitrary complex objects into primitive representations. """ - def to_representation(self, obj): - for attribute_name in dir(obj): - attribute = getattr(obj, attribute_name) - if attribute_name('_'): + def to_representation(self, instance): + output = {} + for attribute_name in dir(instance): + attribute = getattr(instance, attribute_name) + if attribute_name.startswith('_'): # Ignore private attributes. pass elif hasattr(attribute, '__call__'): @@ -986,6 +1003,7 @@ The following class is an example of a generic serializer that can handle coerci else: # Force anything else to its string representation. output[attribute_name] = str(attribute) + return output --- @@ -1003,11 +1021,11 @@ Some reasons this might be useful include... The signatures for these methods are as follows: -#### `.to_representation(self, obj)` +#### `to_representation(self, instance)` Takes the object instance that requires serialization, and should return a primitive representation. Typically this means returning a structure of built-in Python datatypes. The exact types that can be handled will depend on the render classes you have configured for your API. -May be overridden in order modify the representation style. For example: +May be overridden in order to modify the representation style. For example: def to_representation(self, instance): """Convert `username` to lowercase.""" @@ -1015,7 +1033,7 @@ May be overridden in order modify the representation style. For example: ret['username'] = ret['username'].lower() return ret -#### ``.to_internal_value(self, data)`` +#### ``to_internal_value(self, data)`` Takes the unvalidated incoming data as input and should return the validated data that will be made available as `serializer.validated_data`. The return value will also be passed to the `.create()` or `.update()` methods if `.save()` is called on the serializer class. @@ -1078,7 +1096,7 @@ For example, if you wanted to be able to set which fields should be used by a se fields = kwargs.pop('fields', None) # Instantiate the superclass normally - super(DynamicFieldsModelSerializer, self).__init__(*args, **kwargs) + super().__init__(*args, **kwargs) if fields is not None: # Drop any fields that are not specified in the `fields` argument. @@ -1092,7 +1110,7 @@ This would then allow you to do the following: >>> class UserSerializer(DynamicFieldsModelSerializer): >>> class Meta: >>> model = User - >>> fields = ('id', 'username', 'email') + >>> fields = ['id', 'username', 'email'] >>> >>> print(UserSerializer(user)) {'id': 2, 'username': 'jonwatts', 'email': 'jon@example.com'} @@ -1169,6 +1187,11 @@ The [html-json-forms][html-json-forms] package provides an algorithm and seriali The [drf-writable-nested][drf-writable-nested] package provides writable nested model serializer which allows to create/update models with nested related data. +## DRF Encrypt Content + +The [drf-encrypt-content][drf-encrypt-content] package helps you encrypt your data, serialized through ModelSerializer. It also contains some helper functions. Which helps you to encrypt your data. + + [cite]: https://groups.google.com/d/topic/django-users/sVFaOfQi4wY/discussion [relations]: relations.md [model-managers]: https://docs.djangoproject.com/en/stable/topics/db/managers/ @@ -1190,3 +1213,4 @@ The [drf-writable-nested][drf-writable-nested] package provides writable nested [drf-serializer-extensions]: https://github.com/evenicoulddoit/django-rest-framework-serializer-extensions [djangorestframework-queryfields]: https://djangorestframework-queryfields.readthedocs.io/ [drf-writable-nested]: https://github.com/beda-software/drf-writable-nested +[drf-encrypt-content]: https://github.com/oguzhancelikarslan/drf-encrypt-content diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 85e38185e..d42000260 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -1,4 +1,7 @@ -source: settings.py +--- +source: + - settings.py +--- # Settings @@ -11,12 +14,12 @@ Configuration for REST framework is all namespaced inside a single Django settin For example your project's `settings.py` file might include something like this: REST_FRAMEWORK = { - 'DEFAULT_RENDERER_CLASSES': ( + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework.renderers.JSONRenderer', - ), - 'DEFAULT_PARSER_CLASSES': ( + ], + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework.parsers.JSONParser', - ) + ] } ## Accessing settings @@ -44,10 +47,10 @@ A list or tuple of renderer classes, that determines the default set of renderer Default: - ( + [ 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.BrowsableAPIRenderer', - ) + ] #### DEFAULT_PARSER_CLASSES @@ -55,11 +58,11 @@ A list or tuple of parser classes, that determines the default set of parsers us Default: - ( + [ 'rest_framework.parsers.JSONParser', 'rest_framework.parsers.FormParser', 'rest_framework.parsers.MultiPartParser' - ) + ] #### DEFAULT_AUTHENTICATION_CLASSES @@ -67,10 +70,10 @@ A list or tuple of authentication classes, that determines the default set of au Default: - ( + [ 'rest_framework.authentication.SessionAuthentication', 'rest_framework.authentication.BasicAuthentication' - ) + ] #### DEFAULT_PERMISSION_CLASSES @@ -78,15 +81,15 @@ A list or tuple of permission classes, that determines the default set of permis Default: - ( + [ 'rest_framework.permissions.AllowAny', - ) + ] #### DEFAULT_THROTTLE_CLASSES A list or tuple of throttle classes, that determines the default set of throttles checked at the start of a view. -Default: `()` +Default: `[]` #### DEFAULT_CONTENT_NEGOTIATION_CLASS @@ -98,7 +101,7 @@ Default: `'rest_framework.negotiation.DefaultContentNegotiation'` A view inspector class that will be used for schema generation. -Default: `'rest_framework.schemas.AutoSchema'` +Default: `'rest_framework.schemas.openapi.AutoSchema'` --- @@ -106,32 +109,19 @@ Default: `'rest_framework.schemas.AutoSchema'` *The following settings control the behavior of the generic class-based views.* -#### DEFAULT_PAGINATION_SERIALIZER_CLASS - ---- - -**This setting has been removed.** - -The pagination API does not use serializers to determine the output format, and -you'll need to instead override the `get_paginated_response method on a -pagination class in order to specify how the output format is controlled. - ---- - #### DEFAULT_FILTER_BACKENDS A list of filter backend classes that should be used for generic filtering. If set to `None` then generic filtering is disabled. -#### PAGINATE_BY +#### DEFAULT_PAGINATION_CLASS ---- +The default class to use for queryset pagination. If set to `None`, pagination +is disabled by default. See the pagination documentation for further guidance on +[setting](pagination.md#setting-the-pagination-style) and +[modifying](pagination.md#modifying-the-pagination-style) the pagination style. -**This setting has been removed.** - -See the pagination documentation for further guidance on [setting the pagination style](pagination.md#modifying-the-pagination-style). - ---- +Default: `None` #### PAGE_SIZE @@ -139,26 +129,6 @@ The default page size to use for pagination. If set to `None`, pagination is di Default: `None` -#### PAGINATE_BY_PARAM - ---- - -**This setting has been removed.** - -See the pagination documentation for further guidance on [setting the pagination style](pagination.md#modifying-the-pagination-style). - ---- - -#### MAX_PAGINATE_BY - ---- - -**This setting has been removed.** - -See the pagination documentation for further guidance on [setting the pagination style](pagination.md#modifying-the-pagination-style). - ---- - ### SEARCH_PARAM The name of a query parameter, which can be used to specify the search term used by `SearchFilter`. @@ -235,10 +205,10 @@ The format of any of these renderer classes may be used when constructing a test Default: - ( + [ 'rest_framework.renderers.MultiPartRenderer', 'rest_framework.renderers.JSONRenderer' - ) + ] --- @@ -404,7 +374,7 @@ This should be a function with the following signature: If the view instance inherits `ViewSet`, it may have been initialized with several optional arguments: -* `name`: A name expliticly provided to a view in the viewset. Typically, this value should be used as-is when provided. +* `name`: A name explicitly provided to a view in the viewset. Typically, this value should be used as-is when provided. * `suffix`: Text used when differentiating individual views in a viewset. This argument is mutually exclusive to `name`. * `detail`: Boolean that differentiates an individual view in a viewset as either being a 'list' or 'detail' view. diff --git a/docs/api-guide/status-codes.md b/docs/api-guide/status-codes.md index 1016f3374..a37ba15d4 100644 --- a/docs/api-guide/status-codes.md +++ b/docs/api-guide/status-codes.md @@ -1,4 +1,7 @@ -source: status.py +--- +source: + - status.py +--- # Status Codes @@ -20,13 +23,13 @@ The full set of HTTP status codes included in the `status` module is listed belo The module also includes a set of helper functions for testing if a status code is in a given range. from rest_framework import status - from rest_framework.test import APITestCase + from rest_framework.test import APITestCase - class ExampleTestCase(APITestCase): - def test_url_root(self): - url = reverse('index') - response = self.client.get(url) - self.assertTrue(status.is_success(response.status_code)) + class ExampleTestCase(APITestCase): + def test_url_root(self): + url = reverse('index') + response = self.client.get(url) + self.assertTrue(status.is_success(response.status_code)) For more information on proper usage of HTTP status codes see [RFC 2616][rfc2616] @@ -51,6 +54,8 @@ This class of status code indicates that the client's request was successfully r HTTP_205_RESET_CONTENT HTTP_206_PARTIAL_CONTENT HTTP_207_MULTI_STATUS + HTTP_208_ALREADY_REPORTED + HTTP_226_IM_USED ## Redirection - 3xx @@ -64,6 +69,7 @@ This class of status code indicates that further action needs to be taken by the HTTP_305_USE_PROXY HTTP_306_RESERVED HTTP_307_TEMPORARY_REDIRECT + HTTP_308_PERMANENT_REDIRECT ## Client Error - 4xx @@ -90,6 +96,7 @@ The 4xx class of status code is intended for cases in which the client seems to HTTP_422_UNPROCESSABLE_ENTITY HTTP_423_LOCKED HTTP_424_FAILED_DEPENDENCY + HTTP_426_UPGRADE_REQUIRED HTTP_428_PRECONDITION_REQUIRED HTTP_429_TOO_MANY_REQUESTS HTTP_431_REQUEST_HEADER_FIELDS_TOO_LARGE @@ -105,7 +112,11 @@ Response status codes beginning with the digit "5" indicate cases in which the s HTTP_503_SERVICE_UNAVAILABLE HTTP_504_GATEWAY_TIMEOUT HTTP_505_HTTP_VERSION_NOT_SUPPORTED + HTTP_506_VARIANT_ALSO_NEGOTIATES HTTP_507_INSUFFICIENT_STORAGE + HTTP_508_LOOP_DETECTED + HTTP_509_BANDWIDTH_LIMIT_EXCEEDED + HTTP_510_NOT_EXTENDED HTTP_511_NETWORK_AUTHENTICATION_REQUIRED ## Helper functions diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md index 5ca01b4e7..261df80f2 100644 --- a/docs/api-guide/testing.md +++ b/docs/api-guide/testing.md @@ -1,4 +1,7 @@ -source: test.py +--- +source: + - test.py +--- # Testing @@ -218,7 +221,7 @@ If you're using `RequestsClient` you'll want to ensure that test setup, and resu ## Headers & Authentication Custom headers and authentication credentials can be provided in the same way -as [when using a standard `requests.Session` instance](http://docs.python-requests.org/en/master/user/advanced/#session-objects). +as [when using a standard `requests.Session` instance][session_objects]. from requests.auth import HTTPBasicAuth @@ -231,7 +234,7 @@ If you're using `SessionAuthentication` then you'll need to include a CSRF token for any `POST`, `PUT`, `PATCH` or `DELETE` requests. You can do so by following the same flow that a JavaScript based client would use. -First make a `GET` request in order to obtain a CRSF token, then present that +First, make a `GET` request in order to obtain a CSRF token, then present that token in the following request. For example... @@ -256,7 +259,7 @@ With careful usage both the `RequestsClient` and the `CoreAPIClient` provide the ability to write test cases that can run either in development, or be run directly against your staging server or production environment. -Using this style to create basic tests of a few core piece of functionality is +Using this style to create basic tests of a few core pieces of functionality is a powerful way to validate your live service. Doing so may require some careful attention to setup and teardown to ensure that the tests run in a way that they do not directly affect customer data. @@ -296,7 +299,7 @@ similar way as with `RequestsClient`. # API Test cases -REST framework includes the following test case classes, that mirror the existing Django test case classes, but use `APIClient` instead of Django's default `Client`. +REST framework includes the following test case classes, that mirror the existing [Django's test case classes][provided_test_case_classes], but use `APIClient` instead of Django's default `Client`. * `APISimpleTestCase` * `APITransactionTestCase` @@ -399,15 +402,17 @@ For example, to add support for using `format='html'` in test requests, you migh REST_FRAMEWORK = { ... - 'TEST_REQUEST_RENDERER_CLASSES': ( + 'TEST_REQUEST_RENDERER_CLASSES': [ 'rest_framework.renderers.MultiPartRenderer', 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.TemplateHTMLRenderer' - ) + ] } [cite]: https://jacobian.org/writing/django-apps-with-buildout/#s-create-a-test-wrapper [client]: https://docs.djangoproject.com/en/stable/topics/testing/tools/#the-test-client [requestfactory]: https://docs.djangoproject.com/en/stable/topics/testing/advanced/#django.test.client.RequestFactory [configuration]: #configuration -[refresh_from_db_docs]: https://docs.djangoproject.com/en/1.11/ref/models/instances/#django.db.models.Model.refresh_from_db +[refresh_from_db_docs]: https://docs.djangoproject.com/en/stable/ref/models/instances/#django.db.models.Model.refresh_from_db +[session_objects]: https://requests.readthedocs.io/en/master/user/advanced/#session-objects +[provided_test_case_classes]: https://docs.djangoproject.com/en/stable/topics/testing/tools/#provided-test-case-classes diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index dade47460..4c58fa713 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -1,4 +1,7 @@ -source: throttling.py +--- +source: + - throttling.py +--- # Throttling @@ -16,6 +19,10 @@ Multiple throttles can also be used if you want to impose both burst throttling Throttles do not necessarily only refer to rate-limiting requests. For example a storage service might also need to throttle against bandwidth, and a paid data service might want to throttle against a certain number of a records being accessed. +**The application-level throttling that REST framework provides should not be considered a security measure or protection against brute forcing or denial-of-service attacks. Deliberately malicious actors will always be able to spoof IP origins. In addition to this, the built-in throttling implementations are implemented using Django's cache framework, and use non-atomic operations to determine the request rate, which may sometimes result in some fuzziness. + +The application-level throttling provided by REST framework is intended for implementing policies such as different business tiers and basic protections against service over-use.** + ## How throttling is determined As with permissions and authentication, throttling in REST framework is always defined as a list of classes. @@ -28,10 +35,10 @@ If any throttle check fails an `exceptions.Throttled` exception will be raised, The default throttling policy may be set globally, using the `DEFAULT_THROTTLE_CLASSES` and `DEFAULT_THROTTLE_RATES` settings. For example. REST_FRAMEWORK = { - 'DEFAULT_THROTTLE_CLASSES': ( + 'DEFAULT_THROTTLE_CLASSES': [ 'rest_framework.throttling.AnonRateThrottle', 'rest_framework.throttling.UserRateThrottle' - ), + ], 'DEFAULT_THROTTLE_RATES': { 'anon': '100/day', 'user': '1000/day' @@ -43,12 +50,12 @@ The rate descriptions used in `DEFAULT_THROTTLE_RATES` may include `second`, `mi You can also set the throttling policy on a per-view or per-viewset basis, using the `APIView` class-based views. - from rest_framework.response import Response + from rest_framework.response import Response from rest_framework.throttling import UserRateThrottle - from rest_framework.views import APIView + from rest_framework.views import APIView class ExampleView(APIView): - throttle_classes = (UserRateThrottle,) + throttle_classes = [UserRateThrottle] def get(self, request, format=None): content = { @@ -56,7 +63,7 @@ using the `APIView` class-based views. } return Response(content) -Or, if you're using the `@api_view` decorator with function based views. +If you're using the `@api_view` decorator with function based views you can use the following decorator. @api_view(['GET']) @throttle_classes([UserRateThrottle]) @@ -66,7 +73,17 @@ Or, if you're using the `@api_view` decorator with function based views. } return Response(content) -## How clients are identified +It's also possible to set throttle classes for routes that are created using the `@action` decorator. +Throttle classes set in this way will override any viewset level class settings. + + @action(detail=True, methods=["post"], throttle_classes=[UserRateThrottle]) + def example_adhoc_method(request, pk=None): + content = { + 'status': 'request was permitted' + } + return Response(content) + +## How clients are identified The `X-Forwarded-For` HTTP header and `REMOTE_ADDR` WSGI variable are used to uniquely identify client IP addresses for throttling. If the `X-Forwarded-For` header is present then it will be used, otherwise the value of the `REMOTE_ADDR` variable from the WSGI environment will be used. @@ -74,7 +91,7 @@ If you need to strictly identify unique client IP addresses, you'll need to firs It is important to understand that if you configure the `NUM_PROXIES` setting, then all clients behind a unique [NAT'd](https://en.wikipedia.org/wiki/Network_address_translation) gateway will be treated as a single client. -Further context on how the `X-Forwarded-For` header works, and identifying a remote client IP can be [found here][identifing-clients]. +Further context on how the `X-Forwarded-For` header works, and identifying a remote client IP can be [found here][identifying-clients]. ## Setting up the cache @@ -89,6 +106,12 @@ If you need to use a cache other than `'default'`, you can do so by creating a c You'll need to remember to also set your custom throttle class in the `'DEFAULT_THROTTLE_CLASSES'` settings key, or using the `throttle_classes` view attribute. +## A note on concurrency + +The built-in throttle implementations are open to [race conditions][race], so under high concurrency they may allow a few extra requests through. + +If your project relies on guaranteeing the number of requests during concurrent requests, you will need to implement your own throttle class. See [issue #5181][gh5181] for more details. + --- # API Reference @@ -126,10 +149,10 @@ For example, multiple user throttle rates could be implemented by using the foll ...and the following settings. REST_FRAMEWORK = { - 'DEFAULT_THROTTLE_CLASSES': ( + 'DEFAULT_THROTTLE_CLASSES': [ 'example.throttles.BurstRateThrottle', 'example.throttles.SustainedRateThrottle' - ), + ], 'DEFAULT_THROTTLE_RATES': { 'burst': '60/min', 'sustained': '1000/day' @@ -161,9 +184,9 @@ For example, given the following views... ...and the following settings. REST_FRAMEWORK = { - 'DEFAULT_THROTTLE_CLASSES': ( + 'DEFAULT_THROTTLE_CLASSES': [ 'rest_framework.throttling.ScopedRateThrottle', - ), + ], 'DEFAULT_THROTTLE_RATES': { 'contacts': '1000/day', 'uploads': '20/day' @@ -194,6 +217,8 @@ The following is an example of a rate throttle, that will randomly throttle 1 in [cite]: https://developer.twitter.com/en/docs/basics/rate-limiting [permissions]: permissions.md -[identifing-clients]: http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#Multiple_Proxies_in_front_of_the_cluster +[identifying-clients]: http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#Multiple_Proxies_in_front_of_the_cluster [cache-setting]: https://docs.djangoproject.com/en/stable/ref/settings/#caches [cache-docs]: https://docs.djangoproject.com/en/stable/topics/cache/#setting-up-the-cache +[gh5181]: https://github.com/encode/django-rest-framework/issues/5181 +[race]: https://en.wikipedia.org/wiki/Race_condition#Data_race diff --git a/docs/api-guide/validators.md b/docs/api-guide/validators.md index 3b50442cc..bb8466a2c 100644 --- a/docs/api-guide/validators.md +++ b/docs/api-guide/validators.md @@ -1,4 +1,7 @@ -source: validators.py +--- +source: + - validators.py +--- # Validators @@ -17,7 +20,7 @@ Validation in Django REST framework serializers is handled a little differently With `ModelForm` the validation is performed partially on the form, and partially on the model instance. With REST framework the validation is performed entirely on the serializer class. This is advantageous for the following reasons: * It introduces a proper separation of concerns, making your code behavior more obvious. -* It is easy to switch between using shortcut `ModelSerializer` classes and using explicit `Serializer` classes. Any validation behavior being used for `ModelSerializer` is simple to replicate. +* It is easy to switch between using shortcut `ModelSerializer` classes and using explicit `Serializer` classes. Any validation behavior being used for `ModelSerializer` is simple to replicate. * Printing the `repr` of a serializer instance will show you exactly what validation rules it applies. There's no extra hidden validation behavior being called on the model instance. When you're using `ModelSerializer` all of this is handled automatically for you. If you want to drop down to using `Serializer` classes instead, then you need to define the validation rules explicitly. @@ -94,13 +97,13 @@ The validator should be applied to *serializer classes*, like so: validators = [ UniqueTogetherValidator( queryset=ToDoItem.objects.all(), - fields=('list', 'position') + fields=['list', 'position'] ) ] --- -**Note**: The `UniqueTogetherValidation` class always imposes an implicit constraint that all the fields it applies to are always treated as required. Fields with `default` values are an exception to this as they always supply a value even when omitted from user input. +**Note**: The `UniqueTogetherValidator` class always imposes an implicit constraint that all the fields it applies to are always treated as required. Fields with `default` values are an exception to this as they always supply a value even when omitted from user input. --- @@ -149,8 +152,6 @@ If you want the date field to be visible, but not editable by the user, then set published = serializers.DateTimeField(read_only=True, default=timezone.now) -The field will not be writable to the user, but the default value will still be passed through to the `validated_data`. - #### Using with a hidden date field. If you want the date field to be entirely hidden from the user, then use `HiddenField`. This field type does not accept user input, but instead always returns its default value to the `validated_data` in the serializer. @@ -159,7 +160,7 @@ If you want the date field to be entirely hidden from the user, then use `Hidden --- -**Note**: The `UniqueForValidation` classes impose an implicit constraint that the fields they are applied to are always treated as required. Fields with `default` values are an exception to this as they always supply a value even when omitted from user input. +**Note**: The `UniqueForValidator` classes impose an implicit constraint that the fields they are applied to are always treated as required. Fields with `default` values are an exception to this as they always supply a value even when omitted from user input. --- @@ -207,7 +208,7 @@ by specifying an empty list for the serializer `Meta.validators` attribute. By default "unique together" validation enforces that all fields be `required=True`. In some cases, you might want to explicit apply -`required=False` to one of the fields, in which case the desired behaviour +`required=False` to one of the fields, in which case the desired behavior of the validation is ambiguous. In this case you will typically need to exclude the validator from the @@ -217,11 +218,11 @@ in the `.validate()` method, or else in the view. For example: class BillingRecordSerializer(serializers.ModelSerializer): - def validate(self, data): + def validate(self, attrs): # Apply custom validation either here, or in the view. class Meta: - fields = ('client', 'date', 'amount') + fields = ['client', 'date', 'amount'] extra_kwargs = {'client': {'required': False}} validators = [] # Remove a default "unique together" constraint. @@ -237,7 +238,7 @@ In the case of update operations on *nested* serializers there's no way of applying this exclusion, because the instance is not available. Again, you'll probably want to explicitly remove the validator from the -serializer class, and write the code the for the validation constraint +serializer class, and write the code for the validation constraint explicitly, in a `.validate()` method, or in the view. ## Debugging complex cases @@ -281,7 +282,7 @@ to your `Serializer` subclass. This is documented in the To write a class-based validator, use the `__call__` method. Class-based validators are useful as they allow you to parameterize and reuse behavior. - class MultipleOf(object): + class MultipleOf: def __init__(self, base): self.base = base @@ -290,13 +291,17 @@ To write a class-based validator, use the `__call__` method. Class-based validat message = 'This field must be a multiple of %d.' % self.base raise serializers.ValidationError(message) -#### Using `set_context()` +#### Accessing the context -In some advanced cases you might want a validator to be passed the serializer field it is being used with as additional context. You can do so by declaring a `set_context` method on a class-based validator. +In some advanced cases you might want a validator to be passed the serializer +field it is being used with as additional context. You can do so by setting +a `requires_context = True` attribute on the validator. The `__call__` method +will then be called with the `serializer_field` +or `serializer` as an additional argument. - def set_context(self, serializer_field): - # Determine if this is an update or a create operation. - # In `__call__` we can then use that information to modify the validation behavior. - self.is_update = serializer_field.parent.instance is not None + requires_context = True + + def __call__(self, value, serializer_field): + ... [cite]: https://docs.djangoproject.com/en/stable/ref/validators/ diff --git a/docs/api-guide/versioning.md b/docs/api-guide/versioning.md index c106e536d..6076b1ed2 100644 --- a/docs/api-guide/versioning.md +++ b/docs/api-guide/versioning.md @@ -1,4 +1,7 @@ -source: versioning.py +--- +source: + - versioning.py +--- # Versioning @@ -129,12 +132,12 @@ This scheme requires the client to specify the version as part of the URL path. Your URL conf must include a pattern that matches the version with a `'version'` keyword argument, so that this information is available to the versioning scheme. urlpatterns = [ - url( + re_path( r'^(?P(v1|v2))/bookings/$', bookings_list, name='bookings-list' ), - url( + re_path( r'^(?P(v1|v2))/bookings/(?P[0-9]+)/$', bookings_detail, name='bookings-detail' @@ -155,14 +158,14 @@ In the following example we're giving a set of views two different possible URL # bookings/urls.py urlpatterns = [ - url(r'^$', bookings_list, name='bookings-list'), - url(r'^(?P[0-9]+)/$', bookings_detail, name='bookings-detail') + re_path(r'^$', bookings_list, name='bookings-list'), + re_path(r'^(?P[0-9]+)/$', bookings_detail, name='bookings-detail') ] # urls.py urlpatterns = [ - url(r'^v1/bookings/', include('bookings.urls', namespace='v1')), - url(r'^v2/bookings/', include('bookings.urls', namespace='v2')) + re_path(r'^v1/bookings/', include('bookings.urls', namespace='v1')), + re_path(r'^v2/bookings/', include('bookings.urls', namespace='v2')) ] Both `URLPathVersioning` and `NamespaceVersioning` are reasonable if you just need a simple versioning scheme. The `URLPathVersioning` approach might be better suitable for small ad-hoc projects, and the `NamespaceVersioning` is probably easier to manage for larger projects. diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md index 7b2c4eff7..b293de75a 100644 --- a/docs/api-guide/views.md +++ b/docs/api-guide/views.md @@ -1,5 +1,8 @@ -source: decorators.py - views.py +--- +source: + - decorators.py + - views.py +--- # Class-based Views @@ -32,8 +35,8 @@ For example: * Requires token authentication. * Only admin users are able to access this view. """ - authentication_classes = (authentication.TokenAuthentication,) - permission_classes = (permissions.IsAdminUser,) + authentication_classes = [authentication.TokenAuthentication] + permission_classes = [permissions.IsAdminUser] def get(self, request, format=None): """ @@ -142,6 +145,7 @@ REST framework also allows you to work with regular function based views. It pr The core of this functionality is the `api_view` decorator, which takes a list of HTTP methods that your view should respond to. For example, this is how you would write a very simple view that just manually returns some data: from rest_framework.decorators import api_view + from rest_framework.response import Response @api_view() def hello_world(request): @@ -149,7 +153,7 @@ The core of this functionality is the `api_view` decorator, which takes a list o This view will use the default renderers, parsers, authentication classes etc specified in the [settings]. -By default only `GET` methods will be accepted. Other methods will respond with "405 Method Not Allowed". To alter this behaviour, specify which methods the view allows, like so: +By default only `GET` methods will be accepted. Other methods will respond with "405 Method Not Allowed". To alter this behavior, specify which methods the view allows, like so: @api_view(['GET', 'POST']) def hello_world(request): @@ -166,7 +170,7 @@ To override the default settings, REST framework provides a set of additional de from rest_framework.throttling import UserRateThrottle class OncePerDayUserThrottle(UserRateThrottle): - rate = '1/day' + rate = '1/day' @api_view(['GET']) @throttle_classes([OncePerDayUserThrottle]) diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index e7cf4d48f..5d5491a83 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -1,4 +1,7 @@ -source: viewsets.py +--- +source: + - viewsets.py +--- # ViewSets @@ -113,7 +116,7 @@ During dispatch, the following attributes are available on the `ViewSet`. * `name` - the display name for the viewset. This argument is mutually exclusive to `suffix`. * `description` - the display description for the individual view of a viewset. -You may inspect these attributes to adjust behaviour based on the current action. For example, you could restrict permissions to everything except the `list` action similar to this: +You may inspect these attributes to adjust behavior based on the current action. For example, you could restrict permissions to everything except the `list` action similar to this: def get_permissions(self): """ @@ -122,7 +125,7 @@ You may inspect these attributes to adjust behaviour based on the current action if self.action == 'list': permission_classes = [IsAuthenticated] else: - permission_classes = [IsAdmin] + permission_classes = [IsAdminUser] return [permission() for permission in permission_classes] ## Marking extra actions for routing @@ -149,7 +152,7 @@ A more complete example of extra actions: user = self.get_object() serializer = PasswordSerializer(data=request.data) if serializer.is_valid(): - user.set_password(serializer.data['password']) + user.set_password(serializer.validated_data['password']) user.save() return Response({'status': 'password set'}) else: @@ -168,11 +171,6 @@ A more complete example of extra actions: serializer = self.get_serializer(recent_users, many=True) return Response(serializer.data) -The decorator can additionally take extra arguments that will be set for the routed view only. For example: - - @action(detail=True, methods=['post'], permission_classes=[IsAdminOrIsSelf]) - def set_password(self, request, pk=None): - ... The `action` decorator will route `GET` requests by default, but may also accept other HTTP methods by setting the `methods` argument. For example: @@ -180,7 +178,14 @@ The `action` decorator will route `GET` requests by default, but may also accept def unset_password(self, request, pk=None): ... -The two new actions will then be available at the urls `^users/{pk}/set_password/$` and `^users/{pk}/unset_password/$` + +The decorator allows you to override any viewset-level configuration such as `permission_classes`, `serializer_class`, `filter_backends`...: + + @action(detail=True, methods=['post'], permission_classes=[IsAdminOrIsSelf]) + def set_password(self, request, pk=None): + ... + +The two new actions will then be available at the urls `^users/{pk}/set_password/$` and `^users/{pk}/unset_password/$`. Use the `url_path` and `url_name` parameters to change the URL segment and the reverse URL name of the action. To view all extra actions, call the `.get_extra_actions()` method. @@ -242,7 +247,7 @@ In order to use a `GenericViewSet` class you'll override the class and either mi The `ModelViewSet` class inherits from `GenericAPIView` and includes implementations for various actions, by mixing in the behavior of the various mixin classes. -The actions provided by the `ModelViewSet` class are `.list()`, `.retrieve()`, `.create()`, `.update()`, `.partial_update()`, and `.destroy()`. +The actions provided by the `ModelViewSet` class are `.list()`, `.retrieve()`, `.create()`, `.update()`, `.partial_update()`, and `.destroy()`. #### Example @@ -314,5 +319,5 @@ To create a base viewset class that provides `create`, `list` and `retrieve` ope By creating your own base `ViewSet` classes, you can provide common behavior that can be reused in multiple viewsets across your API. -[cite]: https://guides.rubyonrails.org/routing.html +[cite]: https://guides.rubyonrails.org/action_controller_overview.html [routers]: routers.md diff --git a/docs/community/3.0-announcement.md b/docs/community/3.0-announcement.md index dc118d70c..0cb79fc2e 100644 --- a/docs/community/3.0-announcement.md +++ b/docs/community/3.0-announcement.md @@ -24,7 +24,7 @@ Notable features of this new release include: * Support for overriding how validation errors are handled by your API. * A metadata API that allows you to customize how `OPTIONS` requests are handled by your API. * A more compact JSON output with unicode style encoding turned on by default. -* Templated based HTML form rendering for serializers. This will be finalized as public API in the upcoming 3.1 release. +* Templated based HTML form rendering for serializers. This will be finalized as public API in the upcoming 3.1 release. Significant new functionality continues to be planned for the 3.1 and 3.2 releases. These releases will correspond to the two [Kickstarter stretch goals](https://www.kickstarter.com/projects/tomchristie/django-rest-framework-3) - "Feature improvements" and "Admin interface". Further 3.x releases will present simple upgrades, without the same level of fundamental API changes necessary for the 3.0 release. @@ -258,13 +258,13 @@ If you try to use a writable nested serializer without writing a custom `create( >>> class ProfileSerializer(serializers.ModelSerializer): >>> class Meta: >>> model = Profile - >>> fields = ('address', 'phone') + >>> fields = ['address', 'phone'] >>> >>> class UserSerializer(serializers.ModelSerializer): >>> profile = ProfileSerializer() >>> class Meta: >>> model = User - >>> fields = ('username', 'email', 'profile') + >>> fields = ['username', 'email', 'profile'] >>> >>> data = { >>> 'username': 'lizzy', @@ -283,7 +283,7 @@ To use writable nested serialization you'll want to declare a nested field on th class Meta: model = User - fields = ('username', 'email', 'profile') + fields = ['username', 'email', 'profile'] def create(self, validated_data): profile_data = validated_data.pop('profile') @@ -327,7 +327,7 @@ The `write_only_fields` option on `ModelSerializer` has been moved to `PendingDe class MySerializer(serializer.ModelSerializer): class Meta: model = MyModel - fields = ('id', 'email', 'notes', 'is_admin') + fields = ['id', 'email', 'notes', 'is_admin'] extra_kwargs = { 'is_admin': {'write_only': True} } @@ -339,7 +339,7 @@ Alternatively, specify the field explicitly on the serializer class: class Meta: model = MyModel - fields = ('id', 'email', 'notes', 'is_admin') + fields = ['id', 'email', 'notes', 'is_admin'] The `read_only_fields` option remains as a convenient shortcut for the more common case. @@ -350,7 +350,7 @@ The `view_name` and `lookup_field` options have been moved to `PendingDeprecatio class MySerializer(serializer.HyperlinkedModelSerializer): class Meta: model = MyModel - fields = ('url', 'email', 'notes', 'is_admin') + fields = ['url', 'email', 'notes', 'is_admin'] extra_kwargs = { 'url': {'lookup_field': 'uuid'} } @@ -365,7 +365,7 @@ Alternatively, specify the field explicitly on the serializer class: class Meta: model = MyModel - fields = ('url', 'email', 'notes', 'is_admin') + fields = ['url', 'email', 'notes', 'is_admin'] #### Fields for model methods and properties. @@ -384,7 +384,7 @@ You can include `expiry_date` as a field option on a `ModelSerializer` class. class InvitationSerializer(serializers.ModelSerializer): class Meta: model = Invitation - fields = ('to_email', 'message', 'expiry_date') + fields = ['to_email', 'message', 'expiry_date'] These fields will be mapped to `serializers.ReadOnlyField()` instances. @@ -523,7 +523,7 @@ The following class is an example of a generic serializer that can handle coerci def to_representation(self, obj): for attribute_name in dir(obj): attribute = getattr(obj, attribute_name) - if attribute_name('_'): + if attribute_name.startswith('_'): # Ignore private attributes. pass elif hasattr(attribute, '__call__'): @@ -632,7 +632,7 @@ The `MultipleChoiceField` class has been added. This field acts like `ChoiceFiel The `from_native(self, value)` and `to_native(self, data)` method names have been replaced with the more obviously named `to_internal_value(self, data)` and `to_representation(self, value)`. -The `field_from_native()` and `field_to_native()` methods are removed. Previously you could use these methods if you wanted to customise the behaviour in a way that did not simply lookup the field value from the object. For example... +The `field_from_native()` and `field_to_native()` methods are removed. Previously you could use these methods if you wanted to customise the behavior in a way that did not simply lookup the field value from the object. For example... def field_to_native(self, obj, field_name): """A custom read-only field that returns the class name.""" @@ -738,7 +738,7 @@ The `UniqueTogetherValidator` should be applied to a serializer, and takes a `qu class Meta: validators = [UniqueTogetherValidator( queryset=RaceResult.objects.all(), - fields=('category', 'position') + fields=['category', 'position'] )] #### The `UniqueForDateValidator` classes. diff --git a/docs/community/3.1-announcement.md b/docs/community/3.1-announcement.md index 2213c379d..641f313d0 100644 --- a/docs/community/3.1-announcement.md +++ b/docs/community/3.1-announcement.md @@ -61,7 +61,7 @@ For example, when using `NamespaceVersioning`, and the following hyperlinked ser class AccountsSerializer(serializer.HyperlinkedModelSerializer): class Meta: model = Accounts - fields = ('account_name', 'users') + fields = ['account_name', 'users'] The output representation would match the version used on the incoming request. Like so: diff --git a/docs/community/3.10-announcement.md b/docs/community/3.10-announcement.md new file mode 100644 index 000000000..19748aa40 --- /dev/null +++ b/docs/community/3.10-announcement.md @@ -0,0 +1,147 @@ + + +# Django REST framework 3.10 + +The 3.10 release drops support for Python 2. + +* Our supported Python versions are now: 3.5, 3.6, and 3.7. +* Our supported Django versions are now: 1.11, 2.0, 2.1, and 2.2. + +## OpenAPI Schema Generation + +Since we first introduced schema support in Django REST Framework 3.5, OpenAPI has emerged as the widely adopted standard for modeling Web APIs. + +This release begins the deprecation process for the CoreAPI based schema generation, and introduces OpenAPI schema generation in its place. + +--- + +## Continuing to use CoreAPI + +If you're currently using the CoreAPI schemas, you'll need to make sure to +update your REST framework settings to include `DEFAULT_SCHEMA_CLASS` explicitly. + +**settings.py**: + +```python +REST_FRAMEWORK = { + ... + 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema' +} +``` + +You'll still be able to keep using CoreAPI schemas, API docs, and client for the +foreseeable future. We'll aim to ensure that the CoreAPI schema generator remains +available as a third party package, even once it has eventually been removed +from REST framework, scheduled for version 3.12. + +We have removed the old documentation for the CoreAPI based schema generation. +You may view the [Legacy CoreAPI documentation here][legacy-core-api-docs]. + +---- + +## OpenAPI Quickstart + +You can generate a static OpenAPI schema, using the `generateschema` management +command. + +Alternately, to have the project serve an API schema, use the `get_schema_view()` +shortcut. + +In your `urls.py`: + +```python +from rest_framework.schemas import get_schema_view + +urlpatterns = [ + # ... + # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs. + # * `title` and `description` parameters are passed to `SchemaGenerator`. + # * Provide view name for use with `reverse()`. + path('openapi', get_schema_view( + title="Your Project", + description="API for all things …" + ), name='openapi-schema'), + # ... +] +``` + +### Customization + +For customizations that you want to apply across the entire API, you can subclass `rest_framework.schemas.openapi.SchemaGenerator` and provide it as an argument +to the `generateschema` command or `get_schema_view()` helper function. + +For specific per-view customizations, you can subclass `AutoSchema`, +making sure to set `schema = ` on the view. + +For more details, see the [API Schema documentation](../api-guide/schemas.md). + +### API Documentation + +There are some great third party options for documenting your API, based on the +OpenAPI schema. + +See the [Documenting you API](../topics/documenting-your-api.md) section for more details. + +--- + +## Feature Roadmap + +Given that our OpenAPI schema generation is a new feature, it's likely that there +will still be some iterative improvements for us to make. There will be two +main cases here: + +* Expanding the supported range of OpenAPI schemas that are generated by default. +* Improving the ability for developers to customize the output. + +We'll aim to bring the first type of change quickly in point releases. For the +second kind we'd like to adopt a slower approach, to make sure we keep the API +simple, and as widely applicable as possible, before we bring in API changes. + +It's also possible that we'll end up implementing API documentation and API client +tooling that are driven by the OpenAPI schema. The `apistar` project has a +significant amount of work towards this. However, if we do so, we'll plan +on keeping any tooling outside of the core framework. + +--- + +## Funding + +REST framework is a *collaboratively funded project*. If you use +REST framework commercially we strongly encourage you to invest in its +continued development by **[signing up for a paid plan][funding]**. + +*Every single sign-up helps us make REST framework long-term financially sustainable.* + + +
+ +*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [ESG](https://software.esg-usa.com/), [Rollbar](https://rollbar.com/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), and [Lights On Software](https://lightsonsoftware.com).* + +[legacy-core-api-docs]:https://github.com/encode/django-rest-framework/blob/master/docs/coreapi/index.md +[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors +[funding]: funding.md diff --git a/docs/community/3.11-announcement.md b/docs/community/3.11-announcement.md new file mode 100644 index 000000000..83dd636d1 --- /dev/null +++ b/docs/community/3.11-announcement.md @@ -0,0 +1,117 @@ + + +# Django REST framework 3.11 + +The 3.11 release adds support for Django 3.0. + +* Our supported Python versions are now: 3.5, 3.6, 3.7, and 3.8. +* Our supported Django versions are now: 1.11, 2.0, 2.1, 2.2, and 3.0. + +This release will be the last to support Python 3.5 or Django 1.11. + +## OpenAPI Schema Generation Improvements + +The OpenAPI schema generation continues to mature. Some highlights in 3.11 +include: + +* Automatic mapping of Django REST Framework renderers and parsers into OpenAPI + request and response media-types. +* Improved mapping JSON schema mapping types, for example in HStoreFields, and + with large integer values. +* Porting of the old CoreAPI parsing of docstrings to form OpenAPI operation + descriptions. + +In this example view operation descriptions for the `get` and `post` methods will +be extracted from the class docstring: + +```python +class DocStringExampleListView(APIView): +""" +get: A description of my GET operation. +post: A description of my POST operation. +""" + permission_classes = [permissions.IsAuthenticatedOrReadOnly] + + def get(self, request, *args, **kwargs): + ... + + def post(self, request, *args, **kwargs): + ... +``` + +## Validator / Default Context + +In some circumstances a Validator class or a Default class may need to access the serializer field with which it is called, or the `.context` with which the serializer was instantiated. In particular: + +* Uniqueness validators need to be able to determine the name of the field to which they are applied, in order to run an appropriate database query. +* The `CurrentUserDefault` needs to be able to determine the context with which the serializer was instantiated, in order to return the current user instance. + +Previous our approach to this was that implementations could include a `set_context` method, which would be called prior to validation. However this approach had issues with potential race conditions. We have now move this approach into a pending deprecation state. It will continue to function, but will be escalated to a deprecated state in 3.12, and removed entirely in 3.13. + +Instead, validators or defaults which require the serializer context, should include a `requires_context = True` attribute on the class. + +The `__call__` method should then include an additional `serializer_field` argument. + +Validator implementations will look like this: + +```python +class CustomValidator: + requires_context = True + + def __call__(self, value, serializer_field): + ... +``` + +Default implementations will look like this: + +```python +class CustomDefault: + requires_context = True + + def __call__(self, serializer_field): + ... +``` + +--- + +## Funding + +REST framework is a *collaboratively funded project*. If you use +REST framework commercially we strongly encourage you to invest in its +continued development by **[signing up for a paid plan][funding]**. + +*Every single sign-up helps us make REST framework long-term financially sustainable.* + + +
+ +*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [ESG](https://software.esg-usa.com/), [Rollbar](https://rollbar.com/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), [Lights On Software](https://lightsonsoftware.com), and [Retool](https://retool.com/?utm_source=djangorest&utm_medium=sponsorship).* + +[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors +[funding]: funding.md diff --git a/docs/community/3.12-announcement.md b/docs/community/3.12-announcement.md new file mode 100644 index 000000000..4a589e39c --- /dev/null +++ b/docs/community/3.12-announcement.md @@ -0,0 +1,169 @@ + + +# Django REST framework 3.12 + +REST framework 3.12 brings a handful of refinements to the OpenAPI schema +generation, plus support for Django's new database-agnostic `JSONField`, +and some improvements to the `SearchFilter` class. + +## Grouping operations with tags. + +Open API schemas will now automatically include tags, based on the first element +in the URL path. + +For example... + +Method | Path | Tags +--------------------------------|-----------------|------------- +`GET`, `PUT`, `PATCH`, `DELETE` | `/users/{id}/` | `['users']` +`GET`, `POST` | `/users/` | `['users']` +`GET`, `PUT`, `PATCH`, `DELETE` | `/orders/{id}/` | `['orders']` +`GET`, `POST` | `/orders/` | `['orders']` + +The tags used for a particular view may also be overridden... + +```python +class MyOrders(APIView): + schema = AutoSchema(tags=['users', 'orders']) + ... +``` + +See [the schema documentation](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags) for more information. + +## Customizing the operation ID. + +REST framework automatically determines operation IDs to use in OpenAPI +schemas. The latest version provides more control for overriding the behaviour +used to generate the operation IDs. + +See [the schema documentation](https://www.django-rest-framework.org/api-guide/schemas/#operationid) for more information. + +## Support for OpenAPI components. + +In order to output more graceful OpenAPI schemes, REST framework 3.12 now +defines components in the schema, and then references them inside request +and response objects. This is in contrast with the previous approach, which +fully expanded the request and response bodies for each operation. + +The names used for a component default to using the serializer class name, [but +may be overridden if needed](https://www.django-rest-framework.org/api-guide/schemas/#components +)... + +```python +class MyOrders(APIView): + schema = AutoSchema(component_name="OrderDetails") +``` + +## More Public API + +Many methods on the `AutoSchema` class have now been promoted to public API, +allowing you to more fully customize the schema generation. The following methods +are now available for overriding... + +* `get_path_parameters` +* `get_pagination_parameters` +* `get_filter_parameters` +* `get_request_body` +* `get_responses` +* `get_serializer` +* `get_paginator` +* `map_serializer` +* `map_field` +* `map_choice_field` +* `map_field_validators` +* `allows_filters`. + +See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#per-view-customization) +for details on using custom `AutoSchema` subclasses. + +## Support for JSONField. + +Django 3.1 deprecated the existing `django.contrib.postgres.fields.JSONField` +in favour of a new database-agnositic `JSONField`. + +REST framework 3.12 now supports this new model field, and `ModelSerializer` +classes will correctly map the model field. + +## SearchFilter improvements + +There are a couple of significant improvements to the `SearchFilter` class. + +### Nested searches against JSONField and HStoreField + +The class now supports nested search within `JSONField` and `HStoreField`, using +the double underscore notation for traversing which element of the field the +search should apply to. + +```python +class SitesSearchView(generics.ListAPIView): + """ + An API view to return a list of archaeological sites, optionally filtered + by a search against the site name or location. (Location searches are + matched against the region and country names.) + """ + queryset = Sites.objects.all() + serializer_class = SitesSerializer + filter_backends = [filters.SearchFilter] + search_fields = ['site_name', 'location__region', 'location__country'] +``` + +### Searches against annotate fields + +Django allows querysets to create additional virtual fields, using the `.annotate` +method. We now support searching against annotate fields. + +```python +class PublisherSearchView(generics.ListAPIView): + """ + Search for publishers, optionally filtering the search against the average + rating of all their books. + """ + queryset = Publisher.objects.annotate(avg_rating=Avg('book__rating')) + serializer_class = PublisherSerializer + filter_backends = [filters.SearchFilter] + search_fields = ['avg_rating'] +``` + +--- + +## Funding + +REST framework is a *collaboratively funded project*. If you use +REST framework commercially we strongly encourage you to invest in its +continued development by **[signing up for a paid plan][funding]**. + +*Every single sign-up helps us make REST framework long-term financially sustainable.* + + +
+ +*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [ESG](https://software.esg-usa.com/), [Rollbar](https://rollbar.com/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), [Lights On Software](https://lightsonsoftware.com), and [Retool](https://retool.com/?utm_source=djangorest&utm_medium=sponsorship).* + +[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors +[funding]: funding.md diff --git a/docs/community/3.13-announcement.md b/docs/community/3.13-announcement.md new file mode 100644 index 000000000..e2c1fefa6 --- /dev/null +++ b/docs/community/3.13-announcement.md @@ -0,0 +1,55 @@ + + +# Django REST framework 3.13 + +## Django 4.0 support + +The latest release now fully supports Django 4.0. + +Our requirements are now: + +* Python 3.6+ +* Django 4.0, 3.2, 3.1, 2.2 (LTS) + +## Fields arguments are now keyword-only + +When instantiating fields on serializers, you should always use keyword arguments, +such as `serializers.CharField(max_length=200)`. This has always been the case, +and all the examples that we have in the documentation use keyword arguments, +rather than positional arguments. + +From REST framework 3.13 onwards, this is now *explicitly enforced*. + +The most feasible cases where users might be accidentally omitting the keyword arguments +are likely in the composite fields, `ListField` and `DictField`. For instance... + +```python +aliases = serializers.ListField(serializers.CharField()) +``` + +They must now use the more explicit keyword argument style... + +```python +aliases = serializers.ListField(child=serializers.CharField()) +``` + +This change has been made because using positional arguments here *does not* result in the expected behaviour. + +See Pull Request [#7632](https://github.com/encode/django-rest-framework/pull/7632) for more details. diff --git a/docs/community/3.14-announcement.md b/docs/community/3.14-announcement.md new file mode 100644 index 000000000..0543d0d6d --- /dev/null +++ b/docs/community/3.14-announcement.md @@ -0,0 +1,62 @@ + + +# Django REST framework 3.14 + +## Django 4.1 support + +The latest release now fully supports Django 4.1, and drops support for Django 2.2. + +Our requirements are now: + +* Python 3.6+ +* Django 4.1, 4.0, 3.2, 3.1, 3.0 + +## `raise_exceptions` argument for `is_valid` is now keyword-only. + +Calling `serializer_instance.is_valid(True)` is no longer acceptable syntax. +If you'd like to use the `raise_exceptions` argument, you must use it as a +keyword argument. + +See Pull Request [#7952](https://github.com/encode/django-rest-framework/pull/7952) for more details. + +## `ManyRelatedField` supports returning the default when the source attribute doesn't exist. + +Previously, if you used a serializer field with `many=True` with a dot notated source field +that didn't exist, it would raise an `AttributeError`. Now it will return the default or be +skipped depending on the other arguments. + +See Pull Request [#7574](https://github.com/encode/django-rest-framework/pull/7574) for more details. + + +## Make Open API `get_reference` public. + +Returns a reference to the serializer component. This may be useful if you override `get_schema()`. + +## Change semantic of OR of two permission classes. + +When OR-ing two permissions, the request has to pass either class's `has_permission() and has_object_permission()`. + +Previously, both class's `has_permission()` was ignored when OR-ing two permissions together. + +See Pull Request [#7522](https://github.com/encode/django-rest-framework/pull/7522) for more details. + +## Minor fixes and improvements + +There are a number of minor fixes and improvements in this release. See the [release notes](release-notes.md) page for a complete listing. diff --git a/docs/community/3.2-announcement.md b/docs/community/3.2-announcement.md index a66ad5d29..eda4071b2 100644 --- a/docs/community/3.2-announcement.md +++ b/docs/community/3.2-announcement.md @@ -64,7 +64,7 @@ These are a little subtle and probably won't affect most users, but are worth un ### ManyToMany fields and blank=True -We've now added an `allow_empty` argument, which can be used with `ListSerializer`, or with `many=True` relationships. This is `True` by default, but can be set to `False` if you want to disallow empty lists as valid input. +We've now added an `allow_empty` argument, which can be used with `ListSerializer`, or with `many=True` relationships. This is `True` by default, but can be set to `False` if you want to disallow empty lists as valid input. As a follow-up to this we are now able to properly mirror the behavior of Django's `ModelForm` with respect to how many-to-many fields are validated. diff --git a/docs/community/3.3-announcement.md b/docs/community/3.3-announcement.md index 5dcbe3b3b..24f493dcd 100644 --- a/docs/community/3.3-announcement.md +++ b/docs/community/3.3-announcement.md @@ -38,7 +38,7 @@ The AJAX based support for the browsable API means that there are a number of in * To support form based `PUT` and `DELETE`, or to support form content types such as JSON, you should now use the [AJAX forms][ajax-form] javascript library. This replaces the previous 'method and content type overloading' that required significant internal complexity to the request class. * The `accept` query parameter is no longer supported by the default content negotiation class. If you require it then you'll need to [use a custom content negotiation class][accept-headers]. -* The custom `HTTP_X_HTTP_METHOD_OVERRIDE` header is no longer supported by default. If you require it then you'll need to [use custom middleware][method-override]. +* The custom `HTTP_X_HTTP_METHOD_OVERRIDE` header is no longer supported by default. If you require it then you'll need to [use custom middleware][method-override]. The following pagination view attributes and settings have been moved into attributes on the pagination class since 3.1. Their usage was formerly deprecated, and has now been removed entirely, in line with the deprecation policy. diff --git a/docs/community/3.4-announcement.md b/docs/community/3.4-announcement.md index 67192ecbb..6d5f0399c 100644 --- a/docs/community/3.4-announcement.md +++ b/docs/community/3.4-announcement.md @@ -89,7 +89,7 @@ Name | Support | PyPI pa ---------------------------------|-------------------------------------|-------------------------------- [Core JSON][core-json] | Schema generation & client support. | Built-in support in `coreapi`. [Swagger / OpenAPI][swagger] | Schema generation & client support. | The `openapi-codec` package. -[JSON Hyper-Schema][hyperschema] | Currently client support only. | The `hyperschema-codec` package. +[JSON Hyper-Schema][hyperschema] | Currently client support only. | The `hyperschema-codec` package. [API Blueprint][api-blueprint] | Not yet available. | Not yet available. --- diff --git a/docs/community/3.5-announcement.md b/docs/community/3.5-announcement.md index cce2dd050..91bfce428 100644 --- a/docs/community/3.5-announcement.md +++ b/docs/community/3.5-announcement.md @@ -69,7 +69,7 @@ schema_view = get_schema_view( ) urlpatterns = [ - url(r'^swagger/$', schema_view), + path('swagger/', schema_view), ... ] ``` @@ -198,8 +198,8 @@ Make sure to include the view before your router urls. For example: schema_view = get_schema_view(title='Example API') urlpatterns = [ - url('^$', schema_view), - url(r'^', include(router.urls)), + path('', schema_view), + path('', include(router.urls)), ] ### Schema path representations diff --git a/docs/community/3.6-announcement.md b/docs/community/3.6-announcement.md index c6e8dfa06..35704eb58 100644 --- a/docs/community/3.6-announcement.md +++ b/docs/community/3.6-announcement.md @@ -60,7 +60,7 @@ REST framework's new API documentation supports a number of features: * Support for various authentication schemes. * Code snippets for the Python, JavaScript, and Command Line clients. -The `coreapi` library is required as a dependancy for the API docs. Make sure +The `coreapi` library is required as a dependency for the API docs. Make sure to install the latest version (2.3.0 or above). The `pygments` and `markdown` libraries are optional but recommended. @@ -73,7 +73,7 @@ To install the API documentation, you'll need to include it in your projects URL urlpatterns = [ ... - url(r'^docs/', include_docs_urls(title=API_TITLE, description=API_DESCRIPTION)) + path('docs/', include_docs_urls(title=API_TITLE, description=API_DESCRIPTION)) ] Once installed you should see something a little like this: diff --git a/docs/community/3.8-announcement.md b/docs/community/3.8-announcement.md index 507299782..f33b220fd 100644 --- a/docs/community/3.8-announcement.md +++ b/docs/community/3.8-announcement.md @@ -89,7 +89,7 @@ for a complete listing. We're currently working towards moving to using [OpenAPI][openapi] as our default schema output. We'll also be revisiting our API documentation generation and client libraries. -We're doing some consolidation in order to make this happen. It's planned that 3.9 will drop the `coreapi` and `coreschema` libraries, and instead use `apistar` for the API documentation generation, schema generation, and API client libraries. +We're doing some consolidation in order to make this happen. It's planned that 3.9 will drop the `coreapi` and `coreschema` libraries, and instead use `apistar` for the API documentation generation, schema generation, and API client libraries. [funding]: funding.md [gh5886]: https://github.com/encode/django-rest-framework/issues/5886 diff --git a/docs/community/3.9-announcement.md b/docs/community/3.9-announcement.md index 1cf4464d6..d673fdd18 100644 --- a/docs/community/3.9-announcement.md +++ b/docs/community/3.9-announcement.md @@ -62,6 +62,7 @@ Here's an example of adding an OpenAPI schema to the URL conf: ```python from rest_framework.schemas import get_schema_view from rest_framework.renderers import JSONOpenAPIRenderer +from django.urls import path schema_view = get_schema_view( title='Server Monitoring API', @@ -70,7 +71,7 @@ schema_view = get_schema_view( ) urlpatterns = [ - url('^schema.json$', schema_view), + path('schema.json', schema_view), ... ] ``` @@ -109,7 +110,7 @@ You can now compose permission classes using the and/or operators, `&` and `|`. For example... ```python -permission_classes = [IsAuthenticated & (ReadOnly | IsAdmin)] +permission_classes = [IsAuthenticated & (ReadOnly | IsAdminUser)] ``` If you're using custom permission classes then make sure that you are subclassing diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 9cc6ccee0..994226b97 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -6,6 +6,12 @@ There are many ways you can contribute to Django REST framework. We'd like it to be a community-led project, so please get involved and help shape the future of the project. +--- + +**Note**: At this point in it's lifespan we consider Django REST framework to be essentially feature-complete. We may accept pull requests that track the continued development of Django versions, but would prefer not to accept new features or code formatting changes. + +--- + ## Community 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. @@ -26,14 +32,13 @@ The [Django code of conduct][code-of-conduct] gives a fuller set of guidelines f # Issues -It's really helpful if you can make sure to address issues on the correct channel. Usage questions should be directed to the [discussion group][google-group]. Feature requests, bug reports and other issues should be raised on the GitHub [issue tracker][issues]. +Our contribution process is that the [GitHub discussions page](https://github.com/encode/django-rest-framework/discussions) should generally be your starting point. Please only raise an issue or pull request if you've been recommended to do so after discussion. -Some tips on good issue reporting: +Some tips on good potential issue reporting: * When describing issues try to phrase your ticket in terms of the *behavior* you think needs changing rather than the *code* you think need changing. -* Search the issue list first for related items, and make sure you're running the latest version of REST framework before reporting an issue. -* If reporting a bug, then try to include a pull request with a failing test case. This will help us quickly identify if there is a valid issue, and make sure that it gets fixed more quickly if there is one. -* Feature requests will often be closed with a recommendation that they be implemented outside of the core REST framework library. Keeping new feature requests implemented as third party libraries allows us to keep down the maintenance overhead of REST framework, so that the focus can be on continued stability, bugfixes, and great documentation. +* Search the GitHub project page for related items, and make sure you're running the latest version of REST framework before reporting an issue. +* Feature requests will often be closed with a recommendation that they be implemented outside of the core REST framework library. Keeping new feature requests implemented as third party libraries allows us to keep down the maintenance overhead of REST framework, so that the focus can be on continued stability, bugfixes, and great documentation. At this point in it's lifespan we consider Django REST framework to be essentially feature-complete. * Closing an issue doesn't necessarily mean the end of a discussion. If you believe your issue has been closed incorrectly, explain why and we'll consider if it needs to be reopened. ## Triaging issues @@ -54,20 +59,28 @@ To start developing on Django REST framework, first create a Fork from the Then clone your fork. The clone command will look like this, with your GitHub username instead of YOUR-USERNAME: - git clone https://github.com/YOUR-USERNAME/Spoon-Knife + git clone https://github.com/YOUR-USERNAME/django-rest-framework See GitHub's [_Fork a Repo_][how-to-fork] Guide for more help. 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. +You can check your contributions against these conventions each time you commit using the [pre-commit](https://pre-commit.com/) hooks, which we also run on CI. +To set them up, first ensure you have the pre-commit tool installed, for example: + + python -m pip install pre-commit + +Then run: + + pre-commit install ## Testing To run the tests, clone the repository, and then: # Setup the virtual environment - virtualenv env + python3 -m venv env source env/bin/activate - pip install django + pip install -e . pip install -r requirements.txt # Run the tests @@ -79,18 +92,6 @@ Run using a more concise output style. ./runtests.py -q -Run the tests using a more concise output style, no coverage, no flake8. - - ./runtests.py --fast - -Don't run the flake8 code linting. - - ./runtests.py --nolint - -Only run the flake8 code linting, don't run the tests. - - ./runtests.py --lintonly - Run the tests for a given test case. ./runtests.py MyTestCase @@ -121,13 +122,13 @@ It's also useful to remember that if you have an outstanding pull request then p GitHub's documentation for working on pull requests is [available here][pull-requests]. -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. +Always run the tests before submitting pull requests, and ideally run `tox` in order to check that your modifications are compatible on all supported versions of Python and Django. -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. +Once you've made a pull request take a look at the build status in the GitHub interface and make sure the tests are running as you'd expect. -![Travis status][travis-status] +![Build status][build-status] -*Above: Travis build notifications* +*Above: build notifications* ## Managing compatibility issues @@ -210,7 +211,7 @@ If you want to draw attention to a note or warning, use a pair of enclosing line [so-filter]: https://stackexchange.com/filters/66475/rest-framework [issues]: https://github.com/encode/django-rest-framework/issues?state=open [pep-8]: https://www.python.org/dev/peps/pep-0008/ -[travis-status]: ../img/travis-status.png +[build-status]: ../img/build-status.png [pull-requests]: https://help.github.com/articles/using-pull-requests [tox]: https://tox.readthedocs.io/en/latest/ [markdown]: https://daringfireball.net/projects/markdown/basics diff --git a/docs/community/funding.md b/docs/community/funding.md index 662e3d5d9..951833682 100644 --- a/docs/community/funding.md +++ b/docs/community/funding.md @@ -124,7 +124,7 @@ REST framework continues to be open-source and permissively licensed, but we fir ## What funding has enabled so far * The [3.4](https://www.django-rest-framework.org/community/3.4-announcement/) and [3.5](https://www.django-rest-framework.org/community/3.5-announcement/) releases, including schema generation for both Swagger and RAML, a Python client library, a Command Line client, and addressing of a large number of outstanding issues. -* The [3.6](https://www.django-rest-framework.org/community/3.6-announcement/) release, including JavaScript client library, and API documentation, complete with auto-generated code samples. +* The [3.6](https://www.django-rest-framework.org/community/3.6-announcement/) release, including JavaScript client library, and API documentation, complete with auto-generated code samples. * The [3.7 release](https://www.django-rest-framework.org/community/3.7-announcement/), made possible due to our collaborative funding model, focuses on improvements to schema generation and the interactive API documentation. * The recent [3.8 release](https://www.django-rest-framework.org/community/3.8-announcement/). * Tom Christie, the creator of Django REST framework, working on the project full-time. @@ -137,7 +137,7 @@ REST framework continues to be open-source and permissively licensed, but we fir ## What future funding will enable * Realtime API support, using WebSockets. This will consist of documentation and support for using REST framework together with Django Channels, plus integrating WebSocket support into the client libraries. -* Better authentication defaults, possibly bringing JWT & CORs support into the core package. +* Better authentication defaults, possibly bringing JWT & CORS support into the core package. * Securing the community & operations manager position long-term. * Opening up and securing a part-time position to focus on ticket triage and resolution. * Paying for development time on building API client libraries in a range of programming languages. These would be integrated directly into the upcoming API documentation. @@ -154,13 +154,13 @@ Sign up for a paid plan today, and help ensure that REST framework becomes a sus   -> The number one feature of the Python programming language is its community. Such a community is only possible because of the Open Source nature of the language and all the culture that comes from it. Building great Open Source projects require great minds. Given that, we at Vinta are not only proud to sponsor the team behind DRF but we also recognize the ROI that comes from it. +> The number one feature of the Python programming language is its community. Such a community is only possible because of the Open Source nature of the language and all the culture that comes from it. Building great Open Source projects require great minds. Given that, we at Vinta are not only proud to sponsor the team behind DRF but we also recognize the ROI that comes from it. > > — Filipe Ximenes, Vinta Software   -> It's really awesome that this project continues to endure. The code base is top notch and the maintainers are committed to the highest level of quality. +> It's really awesome that this project continues to endure. The code base is top notch and the maintainers are committed to the highest level of quality. DRF is one of the core reasons why Django is top choice among web frameworks today. In my opinion, it sets the standard for rest frameworks for the development community at large. > > — Andrew Conti, Django REST framework user diff --git a/docs/community/jobs.md b/docs/community/jobs.md index e74b78c7f..aa1c5d4b4 100644 --- a/docs/community/jobs.md +++ b/docs/community/jobs.md @@ -9,12 +9,14 @@ Looking for a new Django REST Framework related role? On this site we provide a * [https://www.python.org/jobs/][python-org-jobs] * [https://djangogigs.com][django-gigs-com] * [https://djangojobs.net/jobs/][django-jobs-net] +* [https://findwork.dev/django-rest-framework-jobs][findwork-dev] * [https://www.indeed.com/q-Django-jobs.html][indeed-com] -* [https://stackoverflow.com/jobs/developer-jobs-using-django][stackoverflow-com] +* [https://stackoverflow.com/jobs/companies?tl=django][stackoverflow-com] * [https://www.upwork.com/o/jobs/browse/skill/django-framework/][upwork-com] * [https://www.technojobs.co.uk/django-jobs][technobjobs-co-uk] -* [https://remoteok.io/remote-django-jobs][remoteok-io] +* [https://remoteok.com/remote-django-jobs][remoteok-com] * [https://www.remotepython.com/jobs/][remotepython-com] +* [https://www.pyjobs.com/][pyjobs-com] Know of any other great resources for Django REST Framework jobs that are missing in our list? Please [submit a pull request][submit-pr] or [email us][anna-email]. @@ -26,12 +28,14 @@ Wonder how else you can help? One of the best ways you can help Django REST Fram [python-org-jobs]: https://www.python.org/jobs/ [django-gigs-com]: https://djangogigs.com [django-jobs-net]: https://djangojobs.net/jobs/ +[findwork-dev]: https://findwork.dev/django-rest-framework-jobs [indeed-com]: https://www.indeed.com/q-Django-jobs.html -[stackoverflow-com]: https://stackoverflow.com/jobs/developer-jobs-using-django +[stackoverflow-com]: https://stackoverflow.com/jobs/companies?tl=django [upwork-com]: https://www.upwork.com/o/jobs/browse/skill/django-framework/ [technobjobs-co-uk]: https://www.technojobs.co.uk/django-jobs -[remoteok-io]: https://remoteok.io/remote-django-jobs +[remoteok-com]: https://remoteok.com/remote-django-jobs [remotepython-com]: https://www.remotepython.com/jobs/ +[pyjobs-com]: https://www.pyjobs.com/ [drf-funding]: https://fund.django-rest-framework.org/topics/funding/ [submit-pr]: https://github.com/encode/django-rest-framework [anna-email]: mailto:anna@django-rest-framework.org diff --git a/docs/community/project-management.md b/docs/community/project-management.md index 5d7dab561..293c65e24 100644 --- a/docs/community/project-management.md +++ b/docs/community/project-management.md @@ -195,7 +195,6 @@ If `@tomchristie` ceases to participate in the project then `@j4mie` has respons The following issues still need to be addressed: -* [Consider moving the repo into a proper GitHub organization][github-org]. * Ensure `@jamie` has back-up access to the `django-rest-framework.org` domain setup and admin. * Document ownership of the [live example][sandbox] API. * Document ownership of the [mailing list][mailing-list] and IRC channel. @@ -206,6 +205,5 @@ The following issues still need to be addressed: [transifex-project]: https://www.transifex.com/projects/p/django-rest-framework/ [transifex-client]: https://pypi.org/project/transifex-client/ [translation-memory]: http://docs.transifex.com/guides/tm#let-tm-automatically-populate-translations -[github-org]: https://github.com/encode/django-rest-framework/issues/2162 [sandbox]: https://restframework.herokuapp.com/ [mailing-list]: https://groups.google.com/forum/#!forum/django-rest-framework diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index 0f08342f5..887cae3b4 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -1,9 +1,5 @@ # Release Notes -> Release Early, Release Often -> -> — Eric S. Raymond, [The Cathedral and the Bazaar][cite]. - ## Versioning Minor version numbers (0.0.x) are used for changes that are API compatible. You should be able to upgrade between minor point releases without any other code changes. @@ -38,11 +34,236 @@ You can determine your currently installed version using `pip show`: --- +## 3.14.x series + +### 3.14.0 + +Date: 22nd September 2022 + +* Django 2.2 is no longer supported. [[#8662](https://github.com/encode/django-rest-framework/pull/8662)] +* Django 4.1 compatibility. [[#8591](https://github.com/encode/django-rest-framework/pull/8591)] +* Add `--api-version` CLI option to `generateschema` management command. [[#8663](https://github.com/encode/django-rest-framework/pull/8663)] +* Enforce `is_valid(raise_exception=False)` as a keyword-only argument. [[#7952](https://github.com/encode/django-rest-framework/pull/7952)] +* Stop calling `set_context` on Validators. [[#8589](https://github.com/encode/django-rest-framework/pull/8589)] +* Return `NotImplemented` from `ErrorDetails.__ne__`. [[#8538](https://github.com/encode/django-rest-framework/pull/8538)] +* Don't evaluate `DateTimeField.default_timezone` when a custom timezone is set. [[#8531](https://github.com/encode/django-rest-framework/pull/8531)] +* Make relative URLs clickable in Browseable API. [[#8464](https://github.com/encode/django-rest-framework/pull/8464)] +* Support `ManyRelatedField` falling back to the default value when the attribute specified by dot notation doesn't exist. Matches `ManyRelatedField.get_attribute` to `Field.get_attribute`. [[#7574](https://github.com/encode/django-rest-framework/pull/7574)] +* Make `schemas.openapi.get_reference` public. [[#7515](https://github.com/encode/django-rest-framework/pull/7515)] +* Make `ReturnDict` support `dict` union operators on Python 3.9 and later. [[#8302](https://github.com/encode/django-rest-framework/pull/8302)] +* Update throttling to check if `request.user` is set before checking if the user is authenticated. [[#8370](https://github.com/encode/django-rest-framework/pull/8370)] + +## 3.13.x series + +### 3.13.1 + +Date: 15th December 2021 + +* Revert schema naming changes with function based `@api_view`. [#8297] + +### 3.13.0 + +Date: 13th December 2021 + +* Django 4.0 compatability. [#8178] +* Add `max_length` and `min_length` options to `ListSerializer`. [#8165] +* Add `get_request_serializer` and `get_response_serializer` hooks to `AutoSchema`. [#7424] +* Fix OpenAPI representation of null-able read only fields. [#8116] +* Respect `UNICODE_JSON` setting in API schema outputs. [#7991] +* Fix for `RemoteUserAuthentication`. [#7158] +* Make Field constructors keyword-only. [#7632] + +--- + +## 3.12.x series + +### 3.12.4 + +Date: 26th March 2021 + +* Revert use of `deque` instead of `list` for tracking throttling `.history`. (Due to incompatibility with DjangoRedis cache backend. See #7870) [#7872] + +### 3.12.3 + +Date: 25th March 2021 + +* Properly handle ATOMIC_REQUESTS when multiple database configurations are used. [#7739] +* Bypass `COUNT` query when `LimitOffsetPagination` is configured but pagination params are not included on the request. [#6098] +* Respect `allow_null=True` on `DecimalField`. [#7718] +* Allow title cased `"Yes"`/`"No"` values with `BooleanField`. [#7739] +* Add `PageNumberPagination.get_page_number()` method for overriding behavior. [#7652] +* Fixed rendering of timedelta values in OpenAPI schemas, when present as default, min, or max fields. [#7641] +* Render JSONFields with indentation in browsable API forms. [#6243] +* Remove unnecessary database query in admin Token views. [#7852] +* Raise validation errors when bools are passed to `PrimaryKeyRelatedField` fields, instead of casting to ints. [#7597] +* Don't include model properties as automatically generated ordering fields with `OrderingFilter`. [#7609] +* Use `deque` instead of `list` for tracking throttling `.history`. [#7849] + +### 3.12.2 + +Date: 13th October 2020 + +* Fix issue if `rest_framework.authtoken.models` is imported, but `rest_framework.authtoken` is not in INSTALLED_APPS. [#7571] +* Ignore subclasses of BrowsableAPIRenderer in OpenAPI schema. [#7497] +* Narrower exception catching in serilizer fields, to ensure that any errors in broken `get_queryset()` methods are not masked. [#7480] + +### 3.12.1 + +Date: 28th September 2020 + +* Add `TokenProxy` migration. [#7557] + +### 3.12.0 + +Date: 28th September 2020 + +* Add `--file` option to `generateschema` command. [#7130] +* Support `tags` for OpenAPI schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags). [#7184] +* Support customising the operation ID for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#operationid). [#7190] +* Support OpenAPI components for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#components). [#7124] +* The following methods on `AutoSchema` become public API: `get_path_parameters`, `get_pagination_parameters`, `get_filter_parameters`, `get_request_body`, `get_responses`, `get_serializer`, `get_paginator`, `map_serializer`, `map_field`, `map_choice_field`, `map_field_validators`, `allows_filters`. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#autoschema) +* Add support for Django 3.1's database-agnositic `JSONField`. [#7467] +* `SearchFilter` now supports nested search on `JSONField` and `HStoreField` model fields. [#7121] +* `SearchFilter` now supports searching on `annotate()` fields. [#6240] +* The authtoken model no longer exposes the `pk` in the admin URL. [#7341] +* Add `__repr__` for Request instances. [#7239] +* UTF-8 decoding with Latin-1 fallback for basic auth credentials. [#7193] +* CharField treats surrogate characters as a validation failure. [#7026] +* Don't include callables as default values in schemas. [#7105] +* Improve `ListField` schema output to include all available child information. [#7137] +* Allow `default=False` to be included for `BooleanField` schema outputs. [#7165] +* Include `"type"` information in `ChoiceField` schema outputs. [#7161] +* Include `"type": "object"` on schema objects. [#7169] +* Don't include component in schema output for DELETE requests. [#7229] +* Fix schema types for `DecimalField`. [#7254] +* Fix schema generation for `ObtainAuthToken` view. [#7211] +* Support passing `context=...` to view `.get_serializer()` methods. [#7298] +* Pass custom code to `PermissionDenied` if permission class has one set. [#7306] +* Include "example" in schema pagination output. [#7275] +* Default status code of 201 on schema output for POST requests. [#7206] +* Use camelCase for operation IDs in schema output. [#7208] +* Warn if duplicate operation IDs exist in schema output. [#7207] +* Improve handling of decimal type when mapping `ChoiceField` to a schema output. [#7264] +* Disable YAML aliases for OpenAPI schema outputs. [#7131] +* Fix action URL names for APIs included under a namespaced URL. [#7287] +* Update jQuery version from 3.4 to 3.5. [#7313] +* Fix `UniqueTogether` handling when serializer fields use `source=...`. [#7143] +* HTTP `HEAD` requests now set `self.action` correctly on a ViewSet instance. [#7223] +* Return a valid OpenAPI schema for the case where no API schema paths exist. [#7125] +* Include tests in package distribution. [#7145] +* Allow type checkers to support annotations like `ModelSerializer[Author]`. [#7385] +* Don't include invalid `charset=None` portion in the request `Content-Type` header when using APIClient. [#7400] +* Fix `\Z`/`\z` tokens in OpenAPI regexs. [#7389] +* Fix `PrimaryKeyRelatedField` and `HyperlinkedRelatedField` when source field is actually a property. [#7142] +* `Token.generate_key` is now a class method. [#7502] +* `@action` warns if method is wrapped in a decorator that does not preserve information using `@functools.wraps`. [#7098] + +--- + +## 3.11.x series + +### 3.11.2 + +**Date**: 30th September 2020 + +* **Security**: Drop `urlize_quoted_links` template tag in favour of Django's built-in `urlize`. Removes a XSS vulnerability for some kinds of content in the browsable API. + +### 3.11.1 + +**Date**: 5th August 2020 + +* Fix compat with Django 3.1 + +### 3.11.0 + +**Date**: 12th December 2019 + +* Drop `.set_context` API [in favour of a `requires_context` marker](3.11-announcement.md#validator-default-context). +* Changed default widget for TextField with choices to select box. [#6892][gh6892] +* Supported nested writes on non-relational fields, such as JSONField. [#6916][gh6916] +* Include request/response media types in OpenAPI schemas, based on configured parsers/renderers. [#6865][gh6865] +* Include operation descriptions in OpenAPI schemas, based on the docstring on the view. [#6898][gh6898] +* Fix representation of serializers with all optional fields in OpenAPI schemas. [#6941][gh6941], [#6944][gh6944] +* Fix representation of `serializers.HStoreField` in OpenAPI schemas. [#6914][gh6914] +* Fix OpenAPI generation when title or version is not provided. [#6912][gh6912] +* Use `int64` representation for large integers in OpenAPI schemas. [#7018][gh7018] +* Improved error messages if no `.to_representation` implementation is provided on a field subclass. [#6996][gh6996] +* Fix for serializer classes that use multiple inheritance. [#6980][gh6980] +* Fix for reversing Hyperlinked URL fields with percent encoded components in the path. [#7059][gh7059] +* Update bootstrap to 3.4.1. [#6923][gh6923] + +## 3.10.x series + +### 3.10.3 + +**Date**: 4th September 2019 + +* Include API version in OpenAPI schema generation, defaulting to empty string. +* Add pagination properties to OpenAPI response schemas. +* Add missing "description" property to OpenAPI response schemas. +* Only include "required" for non-empty cases in OpenAPI schemas. +* Fix response schemas for "DELETE" case in OpenAPI schemas. +* Use an array type for list view response schemas. +* Use consistent `lowerInitialCamelCase` style in OpenAPI operation IDs. +* Fix `minLength`/`maxLength`/`minItems`/`maxItems` properties in OpenAPI schemas. +* Only call `FileField.url` once in serialization, for improved performance. +* Fix an edge case where throttling calculations could error after a configuration change. + +### 3.10.2 + +**Date**: 29th July 2019 + +* Various `OpenAPI` schema fixes. +* Ability to specify urlconf in include_docs_urls. + +### 3.10.1 + +**Date**: 17th July 2019 + +* Don't include autocomplete fields on TokenAuth admin, since it forces constraints on custom user models & admin. +* Require `uritemplate` for OpenAPI schema generation, but not `coreapi`. + +### 3.10.0 + +**Date**: [15th July 2019][3.10.0-milestone] + +* Switch to OpenAPI schema generation. +* Drop Python 2 support. +* Add `generateschema --generator_class` CLI option +* Updated PyYaml dependency for OpenAPI schema generation to `pyyaml>=5.1` [#6680][gh6680] +* Resolve DeprecationWarning with markdown. [#6317][gh6317] +* Use `user.get_username` in templates, in preference to `user.username`. +* Fix for cursor pagination issue that could occur after object deletions. +* Fix for nullable fields with `source="*"` +* Always apply all throttle classes during throttling checks. +* Updates to jQuery and Markdown dependencies. +* Don't strict disallow redundant `SerializerMethodField` field name arguments. +* Don't render extra actions in browable API if not authenticated. +* Strip null characters from search parameters. +* Deprecate the `detail_route` decorator in favor of `action`, which accepts a `detail` bool. Use `@action(detail=True)` instead. [gh6687] +* Deprecate the `list_route` decorator in favor of `action`, which accepts a `detail` bool. Use `@action(detail=False)` instead. [gh6687] + ## 3.9.x series +### 3.9.4 + +**Date**: 10th May 2019 + +This is a maintenance release that fixes an error handling bug under Python 2. + +### 3.9.3 + +**Date**: 29th April 2019 + +This is the last Django REST Framework release that will support Python 2. +Be sure to upgrade to Python 3 before upgrading to Django REST Framework 3.10. + +* Adjusted the compat check for django-guardian to allow the last guardian + version (v1.4.9) compatible with Python 2. [#6613][gh6613] + ### 3.9.2 -**Date**: [3rd March 2019][3.9.1-milestone] +**Date**: [3rd March 2019][3.9.2-milestone] * Routers: invalidate `_urls` cache on `register()` [#6407][gh6407] * Deferred schema renderer creation to avoid requiring pyyaml. [#6416][gh6416] @@ -93,7 +314,7 @@ You can determine your currently installed version using `pip show`: * Add testing of Python 3.7 support [#6141][gh6141] * Test using Django 2.1 final release. [#6109][gh6109] * Added djangorestframework-datatables to third-party packages [#5931][gh5931] -* Change ISO 8601 date format to exclude year/month [#5936][gh5936] +* Change ISO 8601 date format to exclude year/month-only options [#5936][gh5936] * Update all pypi.python.org URLs to pypi.org [#5942][gh5942] * Ensure that html forms (multipart form data) respect optional fields [#5927][gh5927] * Allow hashing of ErrorDetail. [#5932][gh5932] @@ -106,7 +327,7 @@ You can determine your currently installed version using `pip show`: * Fixed Javascript `e.indexOf` is not a function error [#5982][gh5982] * Fix schemas for extra actions [#5992][gh5992] * Improved get_error_detail to use error_dict/error_list [#5785][gh5785] -* Imprvied URLs in Admin renderer [#5988][gh5988] +* Improved URLs in Admin renderer [#5988][gh5988] * Add "Community" section to docs, minor cleanup [#5993][gh5993] * Moved guardian imports out of compat [#6054][gh6054] * Deprecate the `DjangoObjectPermissionsFilter` class, moved to the `djangorestframework-guardian` package. [#6075][gh6075] @@ -157,11 +378,11 @@ You can determine your currently installed version using `pip show`: def perform_create(self, serializer): serializer.save(owner=self.request.user) - Alternatively you may override `save()` or `create()` or `update()` on the serialiser as appropriate. + Alternatively you may override `save()` or `create()` or `update()` on the serializer as appropriate. * Correct allow_null behaviour when required=False [#5888][gh5888] - Without an explicit `default`, `allow_null` implies a default of `null` for outgoing serialisation. Previously such + Without an explicit `default`, `allow_null` implies a default of `null` for outgoing serialization. Previously such fields were being skipped when read-only or otherwise not required. **Possible backwards compatibility break** if you were relying on such fields being excluded from the outgoing @@ -294,7 +515,7 @@ You can determine your currently installed version using `pip show`: Note: `AutoSchema.__init__` now ensures `manual_fields` is a list. Previously may have been stored internally as `None`. -* Remove ulrparse compatability shim; use six instead [#5579][gh5579] +* Remove ulrparse compatibility shim; use six instead [#5579][gh5579] * Drop compat wrapper for `TimeDelta.total_seconds()` [#5577][gh5577] * Clean up all whitespace throughout project [#5578][gh5578] * Compat cleanup [#5581][gh5581] @@ -399,7 +620,7 @@ You can determine your currently installed version using `pip show`: * Deprecated `exclude_from_schema` on `APIView` and `api_view` decorator. Set `schema = None` or `@schema(None)` as appropriate. [#5422][gh5422] * Timezone-aware `DateTimeField`s now respect active or default `timezone` during serialization, instead of always using UTC. [#5435][gh5435] - Resolves inconsistency whereby instances were serialised with supplied datetime for `create` but UTC for `retrieve`. [#3732][gh3732] + Resolves inconsistency whereby instances were serialized with supplied datetime for `create` but UTC for `retrieve`. [#3732][gh3732] **Possible backwards compatibility break** if you were relying on datetime strings being UTC. Have client interpret datetimes or [set default or active timezone (docs)][djangodocs-set-timezone] to UTC if needed. @@ -1165,7 +1386,8 @@ For older release notes, [please see the version 2.x documentation][old-release- [3.8.2-milestone]: https://github.com/encode/django-rest-framework/milestone/68?closed=1 [3.9.0-milestone]: https://github.com/encode/django-rest-framework/milestone/66?closed=1 [3.9.1-milestone]: https://github.com/encode/django-rest-framework/milestone/70?closed=1 -[3.9.1-milestone]: https://github.com/encode/django-rest-framework/milestone/71?closed=1 +[3.9.2-milestone]: https://github.com/encode/django-rest-framework/milestone/71?closed=1 +[3.10.0-milestone]: https://github.com/encode/django-rest-framework/milestone/69?closed=1 [gh2013]: https://github.com/encode/django-rest-framework/issues/2013 @@ -2106,3 +2328,26 @@ For older release notes, [please see the version 2.x documentation][old-release- [gh6340]: https://github.com/encode/django-rest-framework/issues/6340 [gh6416]: https://github.com/encode/django-rest-framework/issues/6416 [gh6407]: https://github.com/encode/django-rest-framework/issues/6407 + + +[gh6613]: https://github.com/encode/django-rest-framework/issues/6613 + + +[gh6680]: https://github.com/encode/django-rest-framework/issues/6680 +[gh6317]: https://github.com/encode/django-rest-framework/issues/6317 +[gh6687]: https://github.com/encode/django-rest-framework/issues/6687 + + +[gh6892]: https://github.com/encode/django-rest-framework/issues/6892 +[gh6916]: https://github.com/encode/django-rest-framework/issues/6916 +[gh6865]: https://github.com/encode/django-rest-framework/issues/6865 +[gh6898]: https://github.com/encode/django-rest-framework/issues/6898 +[gh6941]: https://github.com/encode/django-rest-framework/issues/6941 +[gh6944]: https://github.com/encode/django-rest-framework/issues/6944 +[gh6914]: https://github.com/encode/django-rest-framework/issues/6914 +[gh6912]: https://github.com/encode/django-rest-framework/issues/6912 +[gh7018]: https://github.com/encode/django-rest-framework/issues/7018 +[gh6996]: https://github.com/encode/django-rest-framework/issues/6996 +[gh6980]: https://github.com/encode/django-rest-framework/issues/6980 +[gh7059]: https://github.com/encode/django-rest-framework/issues/7059 +[gh6923]: https://github.com/encode/django-rest-framework/issues/6923 diff --git a/docs/community/third-party-packages.md b/docs/community/third-party-packages.md index 0d36b8ee0..1a40539da 100644 --- a/docs/community/third-party-packages.md +++ b/docs/community/third-party-packages.md @@ -14,142 +14,9 @@ We aim to make creating third party packages as easy as possible, whilst keeping If you have an idea for a new feature please consider how it may be packaged as a Third Party Package. We're always happy to discuss ideas on the [Mailing List][discussion-group]. -## How to create a Third Party Package +## Creating a Third Party Package -### Creating your package - -You can use [this cookiecutter template][cookiecutter] for creating reusable Django REST Framework packages quickly. Cookiecutter creates projects from project templates. While optional, this cookiecutter template includes best practices from Django REST framework and other packages, as well as a Travis CI configuration, Tox configuration, and a sane setup.py for easy PyPI registration/distribution. - -Note: Let us know if you have an alternate cookiecuter package so we can also link to it. - -#### Running the initial cookiecutter command - -To run the initial cookiecutter command, you'll first need to install the Python `cookiecutter` package. - - $ pip install cookiecutter - -Once `cookiecutter` is installed just run the following to create a new project. - - $ cookiecutter gh:jpadilla/cookiecutter-django-rest-framework - -You'll be prompted for some questions, answer them, then it'll create your Python package in the current working directory based on those values. - - full_name (default is "Your full name here")? Johnny Appleseed - email (default is "you@example.com")? jappleseed@example.com - github_username (default is "yourname")? jappleseed - pypi_project_name (default is "dj-package")? djangorestframework-custom-auth - repo_name (default is "dj-package")? django-rest-framework-custom-auth - app_name (default is "djpackage")? custom_auth - project_short_description (default is "Your project description goes here")? - year (default is "2014")? - version (default is "0.1.0")? - -#### Getting it onto GitHub - -To put your project up on GitHub, you'll need a repository for it to live in. You can create a new repository [here][new-repo]. If you need help, check out the [Create A Repo][create-a-repo] article on GitHub. - - -#### Adding to Travis CI - -We recommend using [Travis CI][travis-ci], a hosted continuous integration service which integrates well with GitHub and is free for public repositories. - -To get started with Travis CI, [sign in][travis-ci] with your GitHub account. Once you're signed in, go to your [profile page][travis-profile] and enable the service hook for the repository you want. - -If you use the cookiecutter template, your project will already contain a `.travis.yml` file which Travis CI will use to build your project and run tests. By default, builds are triggered everytime you push to your repository or create Pull Request. - -#### Uploading to PyPI - -Once you've got at least a prototype working and tests running, you should publish it on PyPI to allow others to install it via `pip`. - -You must [register][pypi-register] an account before publishing to PyPI. - -To register your package on PyPI run the following command. - - $ python setup.py register - -If this is the first time publishing to PyPI, you'll be prompted to login. - -Note: Before publishing you'll need to make sure you have the latest pip that supports `wheel` as well as install the `wheel` package. - - $ pip install --upgrade pip - $ pip install wheel - -After this, every time you want to release a new version on PyPI just run the following command. - - $ python setup.py publish - You probably want to also tag the version now: - git tag -a {0} -m 'version 0.1.0' - git push --tags - -After releasing a new version to PyPI, it's always a good idea to tag the version and make available as a GitHub Release. - -We recommend to follow [Semantic Versioning][semver] for your package's versions. - -### Development - -#### Version requirements - -The cookiecutter template assumes a set of supported versions will be provided for Python and Django. Make sure you correctly update your requirements, docs, `tox.ini`, `.travis.yml`, and `setup.py` to match the set of versions you wish to support. - -#### Tests - -The cookiecutter template includes a `runtests.py` which uses the `pytest` package as a test runner. - -Before running, you'll need to install a couple test requirements. - - $ pip install -r requirements.txt - -Once requirements installed, you can run `runtests.py`. - - $ ./runtests.py - -Run using a more concise output style. - - $ ./runtests.py -q - -Run the tests using a more concise output style, no coverage, no flake8. - - $ ./runtests.py --fast - -Don't run the flake8 code linting. - - $ ./runtests.py --nolint - -Only run the flake8 code linting, don't run the tests. - - $ ./runtests.py --lintonly - -Run the tests for a given test case. - - $ ./runtests.py MyTestCase - -Run the tests for a given test method. - - $ ./runtests.py MyTestCase.test_this_method - -Shorter form to run the tests for a given test method. - - $ ./runtests.py test_this_method - -To run your tests against multiple versions of Python as different versions of requirements such as Django we recommend using `tox`. [Tox][tox-docs] is a generic virtualenv management and test command line tool. - -First, install `tox` globally. - - $ pip install tox - -To run `tox`, just simply run: - - $ tox - -To run a particular `tox` environment: - - $ tox -e envlist - -`envlist` is a comma-separated value to that specifies the environments to run tests against. To view a list of all possible test environments, run: - - $ tox -l - -#### Version compatibility +### Version compatibility Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries, you'll need to run slightly different code depending on the environment. Any code that branches in this way should be isolated into a `compat.py` module, and should provide a single common interface that the rest of the codebase can use. @@ -187,9 +54,10 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque * [hawkrest][hawkrest] - Provides Hawk HTTP Authorization. * [djangorestframework-httpsignature][djangorestframework-httpsignature] - Provides an easy to use HTTP Signature Authentication mechanism. * [djoser][djoser] - Provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation. -* [django-rest-auth][django-rest-auth] - Provides a set of REST API endpoints for registration, authentication (including social media authentication), password reset, retrieve and update user details, etc. +* [dj-rest-auth][dj-rest-auth] - Provides a set of REST API endpoints for registration, authentication (including social media authentication), password reset, retrieve and update user details, etc. * [drf-oidc-auth][drf-oidc-auth] - Implements OpenID Connect token authentication for DRF. * [drfpasswordless][drfpasswordless] - Adds (Medium, Square Cash inspired) passwordless logins and signups via email and mobile numbers. +* [django-rest-authemail][django-rest-authemail] - Provides a RESTful API for user signup and authentication using email addresses. ### Permissions @@ -197,6 +65,8 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque * [djangorestframework-composed-permissions][djangorestframework-composed-permissions] - Provides a simple way to define complex permissions. * [rest_condition][rest-condition] - Another extension for building complex permissions in a simple and convenient way. * [dry-rest-permissions][dry-rest-permissions] - Provides a simple way to define permissions for individual api actions. +* [drf-access-policy][drf-access-policy] - Declarative and flexible permissions inspired by AWS' IAM policies. +* [drf-psq][drf-psq] - An extension that gives support for having action-based **permission_classes**, **serializer_class**, and **queryset** dependent on permission-based rules. ### Serializers @@ -208,17 +78,23 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque * [django-rest-framework-serializer-extensions][drf-serializer-extensions] - Enables black/whitelisting fields, and conditionally expanding child serializers on a per-view/request basis. * [djangorestframework-queryfields][djangorestframework-queryfields] - Serializer mixin allowing clients to control which fields will be sent in the API response. +* [drf-flex-fields][drf-flex-fields] - Serializer providing dynamic field expansion and sparse field sets via URL parameters. +* [drf-action-serializer][drf-action-serializer] - Serializer providing per-action fields config for use with ViewSets to prevent having to write multiple serializers. +* [djangorestframework-dataclasses][djangorestframework-dataclasses] - Serializer providing automatic field generation for Python dataclasses, like the built-in ModelSerializer does for models. +* [django-restql][django-restql] - Turn your REST API into a GraphQL like API(It allows clients to control which fields will be sent in a response, uses GraphQL like syntax, supports read and write on both flat and nested fields). +* [graphwrap][graphwrap] - Transform your REST API into a fully compliant GraphQL API with just two lines of code. Leverages [Graphene-Django](https://docs.graphene-python.org/projects/django/en/latest/) to dynamically build, at runtime, a GraphQL ObjectType for each view in your API. ### Serializer fields * [drf-compound-fields][drf-compound-fields] - Provides "compound" serializer fields, such as lists of simple values. -* [django-extra-fields][django-extra-fields] - Provides extra serializer fields. +* [drf-extra-fields][drf-extra-fields] - Provides extra serializer fields. * [django-versatileimagefield][django-versatileimagefield] - Provides a drop-in replacement for Django's stock `ImageField` that makes it easy to serve images in multiple sizes/renditions from a single field. For DRF-specific implementation docs, [click here][django-versatileimagefield-drf-docs]. ### Views -* [djangorestframework-bulk][djangorestframework-bulk] - Implements generic view mixins as well as some common concrete generic views to allow to apply bulk operations via API requests. * [django-rest-multiple-models][django-rest-multiple-models] - Provides a generic view (and mixin) for sending multiple serialized models and/or querysets via a single API request. +* [drf-typed-views][drf-typed-views] - Use Python type annotations to validate/deserialize request parameters. Inspired by API Star, Hug and FastAPI. +* [rest-framework-actions][rest-framework-actions] - Provides control over each action in ViewSets. Serializers per action, method. ### Routers @@ -230,12 +106,13 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque * [djangorestframework-msgpack][djangorestframework-msgpack] - Provides MessagePack renderer and parser support. * [djangorestframework-jsonapi][djangorestframework-jsonapi] - Provides a parser, renderer, serializers, and other tools to help build an API that is compliant with the jsonapi.org spec. * [djangorestframework-camel-case][djangorestframework-camel-case] - Provides camel case JSON renderers and parsers. +* [nested-multipart-parser][nested-multipart-parser] - Provides nested parser for http multipart request ### Renderers * [djangorestframework-csv][djangorestframework-csv] - Provides CSV renderer support. * [djangorestframework-jsonapi][djangorestframework-jsonapi] - Provides a parser, renderer, serializers, and other tools to help build an API that is compliant with the jsonapi.org spec. -* [drf_ujson][drf_ujson] - Implements JSON rendering using the UJSON package. +* [drf_ujson2][drf_ujson2] - Implements JSON rendering using the UJSON package. * [rest-pandas][rest-pandas] - Pandas DataFrame-powered renderers including Excel, CSV, and SVG formats. * [djangorestframework-rapidjson][djangorestframework-rapidjson] - Provides rapidjson support with parser and renderer. @@ -244,12 +121,12 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque * [djangorestframework-chain][djangorestframework-chain] - Allows arbitrary chaining of both relations and lookup filters. * [django-url-filter][django-url-filter] - Allows a safe way to filter data via human-friendly URLs. It is a generic library which is not tied to DRF but it provides easy integration with DRF. * [drf-url-filter][drf-url-filter] is a simple Django app to apply filters on drf `ModelViewSet`'s `Queryset` in a clean, simple and configurable way. It also supports validations on incoming query params and their values. +* [django-rest-framework-guardian][django-rest-framework-guardian] - Provides integration with django-guardian, including the `DjangoObjectPermissionsFilter` previously found in DRF. ### Misc * [cookiecutter-django-rest][cookiecutter-django-rest] - A cookiecutter template that takes care of the setup and configuration so you can focus on making your REST apis awesome. -* [djangorestrelationalhyperlink][djangorestrelationalhyperlink] - A hyperlinked serialiser that can can be used to alter relationships via hyperlinks, but otherwise like a hyperlink model serializer. -* [django-rest-swagger][django-rest-swagger] - An API documentation generator for Swagger UI. +* [djangorestrelationalhyperlink][djangorestrelationalhyperlink] - A hyperlinked serializer that can can be used to alter relationships via hyperlinks, but otherwise like a hyperlink model serializer. * [django-rest-framework-proxy][django-rest-framework-proxy] - Proxy to redirect incoming request to another API server. * [gaiarestframework][gaiarestframework] - Utils for django-rest-framework * [drf-extensions][drf-extensions] - A collection of custom extensions @@ -263,13 +140,21 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque * [django-rest-messaging][django-rest-messaging], [django-rest-messaging-centrifugo][django-rest-messaging-centrifugo] and [django-rest-messaging-js][django-rest-messaging-js] - A real-time pluggable messaging service using DRM. * [djangorest-alchemy][djangorest-alchemy] - SQLAlchemy support for REST framework. * [djangorestframework-datatables][djangorestframework-datatables] - Seamless integration between Django REST framework and [Datatables](https://datatables.net). +* [django-rest-framework-condition][django-rest-framework-condition] - Decorators for managing HTTP cache headers for Django REST framework (ETag and Last-modified). +* [django-rest-witchcraft][django-rest-witchcraft] - Provides DRF integration with SQLAlchemy with SQLAlchemy model serializers/viewsets and a bunch of other goodies +* [djangorestframework-mvt][djangorestframework-mvt] - An extension for creating views that serve Postgres data as Map Box Vector Tiles. +* [drf-viewset-profiler][drf-viewset-profiler] - Lib to profile all methods from a viewset line by line. +* [djangorestframework-features][djangorestframework-features] - Advanced schema generation and more based on named features. +* [django-elasticsearch-dsl-drf][django-elasticsearch-dsl-drf] - Integrate Elasticsearch DSL with Django REST framework. Package provides views, serializers, filter backends, pagination and other handy add-ons. +* [django-api-client][django-api-client] - DRF client that groups the Endpoint response, for use in CBVs and FBV as if you were working with Django's Native Models.. +* [fast-drf] - A model based library for making API development faster and easier. +* [django-requestlogs] - Providing middleware and other helpers for audit logging for REST framework. +* [drf-standardized-errors][drf-standardized-errors] - DRF exception handler to standardize error responses for all API endpoints. [cite]: http://www.software-ecosystems.com/Software_Ecosystems/Ecosystems.html [cookiecutter]: https://github.com/jpadilla/cookiecutter-django-rest-framework [new-repo]: https://github.com/new [create-a-repo]: https://help.github.com/articles/create-a-repo/ -[travis-ci]: https://travis-ci.org -[travis-profile]: https://travis-ci.org/profile [pypi-register]: https://pypi.org/account/register/ [semver]: https://semver.org/ [tox-docs]: https://tox.readthedocs.io/en/latest/ @@ -295,33 +180,32 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque [djangorestframework-gis]: https://github.com/djangonauts/django-rest-framework-gis [djangorestframework-hstore]: https://github.com/djangonauts/django-rest-framework-hstore [drf-compound-fields]: https://github.com/estebistec/drf-compound-fields -[django-extra-fields]: https://github.com/Hipo/drf-extra-fields -[djangorestframework-bulk]: https://github.com/miki725/django-rest-framework-bulk +[drf-extra-fields]: https://github.com/Hipo/drf-extra-fields [django-rest-multiple-models]: https://github.com/MattBroach/DjangoRestMultipleModels [drf-nested-routers]: https://github.com/alanjds/drf-nested-routers [wq.db.rest]: https://wq.io/docs/about-rest [djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack [djangorestframework-camel-case]: https://github.com/vbabiy/djangorestframework-camel-case +[nested-multipart-parser]: https://github.com/remigermain/nested-multipart-parser [djangorestframework-csv]: https://github.com/mjumbewu/django-rest-framework-csv -[drf_ujson]: https://github.com/gizmag/drf-ujson-renderer +[drf_ujson2]: https://github.com/Amertz08/drf_ujson2 [rest-pandas]: https://github.com/wq/django-rest-pandas [djangorestframework-rapidjson]: https://github.com/allisson/django-rest-framework-rapidjson [djangorestframework-chain]: https://github.com/philipn/django-rest-framework-chain [djangorestrelationalhyperlink]: https://github.com/fredkingham/django_rest_model_hyperlink_serializers_project -[django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger [django-rest-framework-proxy]: https://github.com/eofs/django-rest-framework-proxy [gaiarestframework]: https://github.com/AppsFuel/gaiarestframework [drf-extensions]: https://github.com/chibisov/drf-extensions [ember-django-adapter]: https://github.com/dustinfarris/ember-django-adapter -[django-rest-auth]: https://github.com/Tivix/django-rest-auth/ +[dj-rest-auth]: https://github.com/iMerica/dj-rest-auth [django-versatileimagefield]: https://github.com/WGBH/django-versatileimagefield [django-versatileimagefield-drf-docs]:https://django-versatileimagefield.readthedocs.io/en/latest/drf_integration.html [drf-tracking]: https://github.com/aschn/drf-tracking [django-rest-framework-braces]: https://github.com/dealertrack/django-rest-framework-braces -[dry-rest-permissions]: https://github.com/Helioscene/dry-rest-permissions +[dry-rest-permissions]: https://github.com/FJNR-inc/dry-rest-permissions [django-url-filter]: https://github.com/miki725/django-url-filter [drf-url-filter]: https://github.com/manjitkumar/drf-url-filters -[cookiecutter-django-rest]: https://github.com/agconti/cookiecutter-django-rest +[cookiecutter-django-rest]: https://github.com/agconti/cookiecutter-django-rest [drf-haystack]: https://drf-haystack.readthedocs.io/en/latest/ [django-rest-framework-version-transforms]: https://github.com/mrhwick/django-rest-framework-version-transforms [djangorestframework-jsonapi]: https://github.com/django-json-api/django-rest-framework-json-api @@ -336,3 +220,24 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque [drfpasswordless]: https://github.com/aaronn/django-rest-framework-passwordless [djangorest-alchemy]: https://github.com/dealertrack/djangorest-alchemy [djangorestframework-datatables]: https://github.com/izimobil/django-rest-framework-datatables +[django-rest-framework-condition]: https://github.com/jozo/django-rest-framework-condition +[django-rest-witchcraft]: https://github.com/shosca/django-rest-witchcraft +[drf-access-policy]: https://github.com/rsinger86/drf-access-policy +[drf-flex-fields]: https://github.com/rsinger86/drf-flex-fields +[drf-typed-views]: https://github.com/rsinger86/drf-typed-views +[drf-action-serializer]: https://github.com/gregschmit/drf-action-serializer +[djangorestframework-dataclasses]: https://github.com/oxan/djangorestframework-dataclasses +[django-restql]: https://github.com/yezyilomo/django-restql +[djangorestframework-mvt]: https://github.com/corteva/djangorestframework-mvt +[django-rest-framework-guardian]: https://github.com/rpkilby/django-rest-framework-guardian +[drf-viewset-profiler]: https://github.com/fvlima/drf-viewset-profiler +[djangorestframework-features]: https://github.com/cloudcode-hungary/django-rest-framework-features/ +[django-elasticsearch-dsl-drf]: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf +[django-api-client]: https://github.com/rhenter/django-api-client +[drf-psq]: https://github.com/drf-psq/drf-psq +[django-rest-authemail]: https://github.com/celiao/django-rest-authemail +[graphwrap]: https://github.com/PaulGilmartin/graph_wrap +[rest-framework-actions]: https://github.com/AlexisMunera98/rest-framework-actions +[fast-drf]: https://github.com/iashraful/fast-drf +[django-requestlogs]: https://github.com/Raekkeri/django-requestlogs +[drf-standardized-errors]: https://github.com/ghazi-git/drf-standardized-errors diff --git a/docs/community/tutorials-and-resources.md b/docs/community/tutorials-and-resources.md index a03d63a3c..23faf7912 100644 --- a/docs/community/tutorials-and-resources.md +++ b/docs/community/tutorials-and-resources.md @@ -11,8 +11,8 @@ There are a wide range of resources available for learning and using Django REST - - + + @@ -76,6 +76,7 @@ There are a wide range of resources available for learning and using Django REST * [Chatbot Using Django REST Framework + api.ai + Slack — Part 1/3][chatbot-using-drf-part1] * [New Django Admin with DRF and EmberJS... What are the News?][new-django-admin-with-drf-and-emberjs] * [Blog posts about Django REST Framework][medium-django-rest-framework] +* [Implementing Rest APIs With Embedded Privacy][doordash-implementing-rest-apis] ### Documentations * [Classy Django REST Framework][cdrf.co] @@ -85,28 +86,28 @@ Want your Django REST Framework talk/tutorial/article to be added to our website [beginners-guide-to-the-django-rest-framework]: https://code.tutsplus.com/tutorials/beginners-guide-to-the-django-rest-framework--cms-19786 -[getting-started-with-django-rest-framework-and-angularjs]: https://blog.kevinastone.com/getting-started-with-django-rest-framework-and-angularjs.html +[getting-started-with-django-rest-framework-and-angularjs]: https://blog.kevinastone.com/django-rest-framework-and-angular-js [end-to-end-web-app-with-django-rest-framework-angularjs]: https://mourafiq.com/2013/07/01/end-to-end-web-app-with-django-angular-1.html -[start-your-api-django-rest-framework-part-1]: https://godjango.com/41-start-your-api-django-rest-framework-part-1/ -[permissions-authentication-django-rest-framework-part-2]: https://godjango.com/43-permissions-authentication-django-rest-framework-part-2/ -[viewsets-and-routers-django-rest-framework-part-3]: https://godjango.com/45-viewsets-and-routers-django-rest-framework-part-3/ +[start-your-api-django-rest-framework-part-1]: https://www.youtube.com/watch?v=hqo2kk91WpE +[permissions-authentication-django-rest-framework-part-2]: https://www.youtube.com/watch?v=R3xvUDUZxGU +[viewsets-and-routers-django-rest-framework-part-3]: https://www.youtube.com/watch?v=2d6w4DGQ4OU [django-rest-framework-user-endpoint]: https://richardtier.com/2014/02/25/django-rest-framework-user-endpoint/ [check-credentials-using-django-rest-framework]: https://richardtier.com/2014/03/06/110/ [ember-and-django-part 1-video]: http://www.neckbeardrepublic.com/screencasts/ember-and-django-part-1 [django-rest-framework-part-1-video]: http://www.neckbeardrepublic.com/screencasts/django-rest-framework-part-1 [web-api-performance-profiling-django-rest-framework]: https://www.dabapps.com/blog/api-performance-profiling-django-rest-framework/ -[api-development-with-django-and-django-rest-framework]: https://bnotions.com/api-development-with-django-and-django-rest-framework/ +[api-development-with-django-and-django-rest-framework]: https://bnotions.com/news-and-insights/api-development-with-django-and-django-rest-framework/ [cdrf.co]:http://www.cdrf.co [medium-django-rest-framework]: https://medium.com/django-rest-framework [django-rest-framework-course]: https://teamtreehouse.com/library/django-rest-framework [pycon-uk-2016]: https://www.youtube.com/watch?v=FjmiGh7OqVg [django-under-hood-2014]: https://www.youtube.com/watch?v=3cSsbe-tA0E -[integrating-pandas-drf-and-bokeh]: https://machinalis.com/blog/pandas-django-rest-framework-bokeh/ -[controlling-uncertainty-on-web-apps-and-apis]: https://machinalis.com/blog/controlling-uncertainty-on-web-applications-and-apis/ -[full-text-search-in-drf]: https://machinalis.com/blog/full-text-search-on-django-rest-framework/ -[oauth2-authentication-with-drf]: https://machinalis.com/blog/oauth2-authentication/ -[nested-resources-with-drf]: https://machinalis.com/blog/nested-resources-with-django/ -[image-fields-with-drf]: https://machinalis.com/blog/image-fields-with-django-rest-framework/ +[integrating-pandas-drf-and-bokeh]: https://web.archive.org/web/20180104205117/http://machinalis.com/blog/pandas-django-rest-framework-bokeh/ +[controlling-uncertainty-on-web-apps-and-apis]: https://web.archive.org/web/20180104205043/https://machinalis.com/blog/controlling-uncertainty-on-web-applications-and-apis/ +[full-text-search-in-drf]: https://web.archive.org/web/20180104205059/http://machinalis.com/blog/full-text-search-on-django-rest-framework/ +[oauth2-authentication-with-drf]: https://web.archive.org/web/20180104205054/http://machinalis.com/blog/oauth2-authentication/ +[nested-resources-with-drf]: https://web.archive.org/web/20180104205109/http://machinalis.com/blog/nested-resources-with-django/ +[image-fields-with-drf]: https://web.archive.org/web/20180104205048/http://machinalis.com/blog/image-fields-with-django-rest-framework/ [chatbot-using-drf-part1]: https://chatbotslife.com/chatbot-using-django-rest-framework-api-ai-slack-part-1-3-69c7e38b7b1e#.g2aceuncf [new-django-admin-with-drf-and-emberjs]: https://blog.levit.be/new-django-admin-with-emberjs-what-are-the-news/ [drf-schema]: https://drf-schema-adapter.readthedocs.io/en/latest/ @@ -128,3 +129,4 @@ Want your Django REST Framework talk/tutorial/article to be added to our website [anna-email]: mailto:anna@django-rest-framework.org [pycon-us-2017]: https://www.youtube.com/watch?v=Rk6MHZdust4 [django-rest-react-valentinog]: https://www.valentinog.com/blog/tutorial-api-django-rest-react/ +[doordash-implementing-rest-apis]: https://doordash.engineering/2013/10/07/implementing-rest-apis-with-embedded-privacy/ diff --git a/docs/tutorial/7-schemas-and-client-libraries.md b/docs/coreapi/7-schemas-and-client-libraries.md similarity index 94% rename from docs/tutorial/7-schemas-and-client-libraries.md rename to docs/coreapi/7-schemas-and-client-libraries.md index 203d81ea5..d95019dab 100644 --- a/docs/tutorial/7-schemas-and-client-libraries.md +++ b/docs/coreapi/7-schemas-and-client-libraries.md @@ -1,5 +1,16 @@ # Tutorial 7: Schemas & client libraries +---- + +**DEPRECATION NOTICE:** Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation as of Django REST Framework v3.10. See the [Version 3.10 Release Announcement](../community/3.10-announcement.md) for more details. + +If you are looking for information regarding schemas, you might want to look at these updated resources: + +1. [Schema](../api-guide/schemas.md) +2. [Documenting your API](../topics/documenting-your-api.md) + +---- + A schema is a machine-readable document that describes the available API endpoints, their URLS, and what operations they support. diff --git a/docs/coreapi/from-documenting-your-api.md b/docs/coreapi/from-documenting-your-api.md new file mode 100644 index 000000000..f8ddff019 --- /dev/null +++ b/docs/coreapi/from-documenting-your-api.md @@ -0,0 +1,182 @@ + +## Built-in API documentation + +---- + +**DEPRECATION NOTICE:** Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation as of Django REST Framework v3.10. See the [Version 3.10 Release Announcement](../community/3.10-announcement.md) for more details. + +If you are looking for information regarding schemas, you might want to look at these updated resources: + +1. [Schema](../api-guide/schemas.md) +2. [Documenting your API](../topics/documenting-your-api.md) + +---- + +The built-in API documentation includes: + +* Documentation of API endpoints. +* Automatically generated code samples for each of the available API client libraries. +* Support for API interaction. + +### Installation + +The `coreapi` library is required as a dependency for the API docs. Make sure +to install the latest version. The `Pygments` and `Markdown` libraries +are optional but recommended. + +To install the API documentation, you'll need to include it in your project's URLconf: + + from rest_framework.documentation import include_docs_urls + + urlpatterns = [ + ... + path('docs/', include_docs_urls(title='My API title')) + ] + +This will include two different views: + + * `/docs/` - The documentation page itself. + * `/docs/schema.js` - A JavaScript resource that exposes the API schema. + +--- + +**Note**: By default `include_docs_urls` configures the underlying `SchemaView` to generate _public_ schemas. +This means that views will not be instantiated with a `request` instance. i.e. Inside the view `self.request` will be `None`. + +To be compatible with this behavior, methods (such as `get_serializer` or `get_serializer_class` etc.) which inspect `self.request` or, particularly, `self.request.user` may need to be adjusted to handle this case. + +You may ensure views are given a `request` instance by calling `include_docs_urls` with `public=False`: + + from rest_framework.documentation import include_docs_urls + + urlpatterns = [ + ... + # Generate schema with valid `request` instance: + path('docs/', include_docs_urls(title='My API title', public=False)) + ] + + +--- + + +### Documenting your views + +You can document your views by including docstrings that describe each of the available actions. +For example: + + class UserList(generics.ListAPIView): + """ + Return a list of all the existing users. + """ + +If a view supports multiple methods, you should split your documentation using `method:` style delimiters. + + class UserList(generics.ListCreateAPIView): + """ + get: + Return a list of all the existing users. + + post: + Create a new user instance. + """ + +When using viewsets, you should use the relevant action names as delimiters. + + class UserViewSet(viewsets.ModelViewSet): + """ + retrieve: + Return the given user. + + list: + Return a list of all the existing users. + + create: + Create a new user instance. + """ + +Custom actions on viewsets can also be documented in a similar way using the method names +as delimiters or by attaching the documentation to action mapping methods. + + class UserViewSet(viewsets.ModelViewset): + ... + + @action(detail=False, methods=['get', 'post']) + def some_action(self, request, *args, **kwargs): + """ + get: + A description of the get method on the custom action. + + post: + A description of the post method on the custom action. + """ + + @some_action.mapping.put + def put_some_action(): + """ + A description of the put method on the custom action. + """ + + +### `documentation` API Reference + +The `rest_framework.documentation` module provides three helper functions to help configure the interactive API documentation, `include_docs_urls` (usage shown above), `get_docs_view` and `get_schemajs_view`. + + `include_docs_urls` employs `get_docs_view` and `get_schemajs_view` to generate the url patterns for the documentation page and JavaScript resource that exposes the API schema respectively. They expose the following options for customisation. (`get_docs_view` and `get_schemajs_view` ultimately call `rest_frameworks.schemas.get_schema_view()`, see the Schemas docs for more options there.) + +#### `include_docs_urls` + +* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. +* `description`: Default `None`. May be used to provide a description for the schema definition. +* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. +* `public`: Default `True`. Should the schema be considered _public_? If `True` schema is generated without a `request` instance being passed to views. +* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. +* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. +* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. +* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`. +* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. + +#### `get_docs_view` + +* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. +* `description`: Default `None`. May be used to provide a description for the schema definition. +* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. +* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views. +* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. +* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. +* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. +* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES`. May be used to pass custom permission classes to the `SchemaView`. +* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. If `None` the `SchemaView` will be configured with `DocumentationRenderer` and `CoreJSONRenderer` renderers, corresponding to the (default) `html` and `corejson` formats. + +#### `get_schemajs_view` + +* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. +* `description`: Default `None`. May be used to provide a description for the schema definition. +* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. +* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views. +* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. +* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. +* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. +* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`. + + +### Customising code samples + +The built-in API documentation includes automatically generated code samples for +each of the available API client libraries. + +You may customise these samples by subclassing `DocumentationRenderer`, setting +`languages` to the list of languages you wish to support: + + from rest_framework.renderers import DocumentationRenderer + + + class CustomRenderer(DocumentationRenderer): + languages = ['ruby', 'go'] + +For each language you need to provide an `intro` template, detailing installation instructions and such, +plus a generic template for making API requests, that can be filled with individual request details. +See the [templates for the bundled languages][client-library-templates] for examples. + +--- + +[client-library-templates]: https://github.com/encode/django-rest-framework/tree/master/rest_framework/templates/rest_framework/docs/langs \ No newline at end of file diff --git a/docs/coreapi/index.md b/docs/coreapi/index.md new file mode 100644 index 000000000..dbcb11584 --- /dev/null +++ b/docs/coreapi/index.md @@ -0,0 +1,29 @@ +# Legacy CoreAPI Schemas Docs + +Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation as of Django REST Framework v3.10. + +See the [Version 3.10 Release Announcement](../community/3.10-announcement.md) for more details. + +---- + +You can continue to use CoreAPI schemas by setting the appropriate default schema class: + +```python +# In settings.py +REST_FRAMEWORK = { + 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema', +} +``` + +Under-the-hood, any subclass of `coreapi.AutoSchema` here will trigger use of the old CoreAPI schemas. +**Otherwise** you will automatically be opted-in to the new OpenAPI schemas. + +All CoreAPI related code will be removed in Django REST Framework v3.12. Switch to OpenAPI schemas by then. + +---- + +For reference this folder contains the old CoreAPI related documentation: + +* [Tutorial 7: Schemas & client libraries](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//7-schemas-and-client-libraries.md). +* [Excerpts from _Documenting your API_ topic page](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//from-documenting-your-api.md). +* [`rest_framework.schemas` API Reference](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//schemas.md). diff --git a/docs/coreapi/schemas.md b/docs/coreapi/schemas.md new file mode 100644 index 000000000..73fc7b67d --- /dev/null +++ b/docs/coreapi/schemas.md @@ -0,0 +1,854 @@ +source: schemas.py + +# Schemas + +---- + +**DEPRECATION NOTICE:** Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation as of Django REST Framework v3.10. See the [Version 3.10 Release Announcement](../community/3.10-announcement.md) for more details. + +You are probably looking for [this page](../api-guide/schemas.md) if you want latest information regarding schemas. + +---- + +> A machine-readable [schema] describes what resources are available via the API, what their URLs are, how they are represented and what operations they support. +> +> — Heroku, [JSON Schema for the Heroku Platform API][cite] + +API schemas are a useful tool that allow for a range of use cases, including +generating reference documentation, or driving dynamic client libraries that +can interact with your API. + +## Install Core API & PyYAML + +You'll need to install the `coreapi` package in order to add schema support +for REST framework. You probably also want to install `pyyaml`, so that you +can render the schema into the commonly used YAML-based OpenAPI format. + + pip install coreapi pyyaml + +## Quickstart + +There are two different ways you can serve a schema description for your API. + +### Generating a schema with the `generateschema` management command + +To generate a static API schema, use the `generateschema` management command. + +```shell +$ python manage.py generateschema > schema.yml +``` + +Once you've generated a schema in this way you can annotate it with any +additional information that cannot be automatically inferred by the schema +generator. + +You might want to check your API schema into version control and update it +with each new release, or serve the API schema from your site's static media. + +### Adding a view with `get_schema_view` + +To add a dynamically generated schema view to your API, use `get_schema_view`. + +```python +from rest_framework.schemas import get_schema_view +from django.urls import path + +schema_view = get_schema_view(title="Example API") + +urlpatterns = [ + path('schema', schema_view), + ... +] +``` + +See below [for more details](#the-get_schema_view-shortcut) on customizing a +dynamically generated schema view. + +## Internal schema representation + +REST framework uses [Core API][coreapi] in order to model schema information in +a format-independent representation. This information can then be rendered +into various different schema formats, or used to generate API documentation. + +When using Core API, a schema is represented as a `Document` which is the +top-level container object for information about the API. Available API +interactions are represented using `Link` objects. Each link includes a URL, +HTTP method, and may include a list of `Field` instances, which describe any +parameters that may be accepted by the API endpoint. The `Link` and `Field` +instances may also include descriptions, that allow an API schema to be +rendered into user documentation. + +Here's an example of an API description that includes a single `search` +endpoint: + + coreapi.Document( + title='Flight Search API', + url='https://api.example.org/', + content={ + 'search': coreapi.Link( + url='/search/', + action='get', + fields=[ + coreapi.Field( + name='from', + required=True, + location='query', + description='City name or airport code.' + ), + coreapi.Field( + name='to', + required=True, + location='query', + description='City name or airport code.' + ), + coreapi.Field( + name='date', + required=True, + location='query', + description='Flight date in "YYYY-MM-DD" format.' + ) + ], + description='Return flight availability and prices.' + ) + } + ) + +## Schema output formats + +In order to be presented in an HTTP response, the internal representation +has to be rendered into the actual bytes that are used in the response. + +REST framework includes a few different renderers that you can use for +encoding the API schema. + +* `renderers.OpenAPIRenderer` - Renders into YAML-based [OpenAPI][open-api], the most widely used API schema format. +* `renderers.JSONOpenAPIRenderer` - Renders into JSON-based [OpenAPI][open-api]. +* `renderers.CoreJSONRenderer` - Renders into [Core JSON][corejson], a format designed for +use with the `coreapi` client library. + + +[Core JSON][corejson] is designed as a canonical format for use with Core API. +REST framework includes a renderer class for handling this media type, which +is available as `renderers.CoreJSONRenderer`. + + +## Schemas vs Hypermedia + +It's worth pointing out here that Core API can also be used to model hypermedia +responses, which present an alternative interaction style to API schemas. + +With an API schema, the entire available interface is presented up-front +as a single endpoint. Responses to individual API endpoints are then typically +presented as plain data, without any further interactions contained in each +response. + +With Hypermedia, the client is instead presented with a document containing +both data and available interactions. Each interaction results in a new +document, detailing both the current state and the available interactions. + +Further information and support on building Hypermedia APIs with REST framework +is planned for a future version. + + +--- + +# Creating a schema + +REST framework includes functionality for auto-generating a schema, +or allows you to specify one explicitly. + +## Manual Schema Specification + +To manually specify a schema you create a Core API `Document`, similar to the +example above. + + schema = coreapi.Document( + title='Flight Search API', + content={ + ... + } + ) + + +## Automatic Schema Generation + +Automatic schema generation is provided by the `SchemaGenerator` class. + +`SchemaGenerator` processes a list of routed URL patterns and compiles the +appropriately structured Core API Document. + +Basic usage is just to provide the title for your schema and call +`get_schema()`: + + generator = schemas.SchemaGenerator(title='Flight Search API') + schema = generator.get_schema() + +## Per-View Schema Customisation + +By default, view introspection is performed by an `AutoSchema` instance +accessible via the `schema` attribute on `APIView`. This provides the +appropriate Core API `Link` object for the view, request method and path: + + auto_schema = view.schema + coreapi_link = auto_schema.get_link(...) + +(In compiling the schema, `SchemaGenerator` calls `view.schema.get_link()` for +each view, allowed method and path.) + +--- + +**Note**: For basic `APIView` subclasses, default introspection is essentially +limited to the URL kwarg path parameters. For `GenericAPIView` +subclasses, which includes all the provided class based views, `AutoSchema` will +attempt to introspect serializer, pagination and filter fields, as well as +provide richer path field descriptions. (The key hooks here are the relevant +`GenericAPIView` attributes and methods: `get_serializer`, `pagination_class`, +`filter_backends` and so on.) + +--- + +To customise the `Link` generation you may: + +* Instantiate `AutoSchema` on your view with the `manual_fields` kwarg: + + from rest_framework.views import APIView + from rest_framework.schemas import AutoSchema + + class CustomView(APIView): + ... + schema = AutoSchema( + manual_fields=[ + coreapi.Field("extra_field", ...), + ] + ) + + This allows extension for the most common case without subclassing. + +* Provide an `AutoSchema` subclass with more complex customisation: + + from rest_framework.views import APIView + from rest_framework.schemas import AutoSchema + + class CustomSchema(AutoSchema): + def get_link(...): + # Implement custom introspection here (or in other sub-methods) + + class CustomView(APIView): + ... + schema = CustomSchema() + + This provides complete control over view introspection. + +* Instantiate `ManualSchema` on your view, providing the Core API `Fields` for + the view explicitly: + + from rest_framework.views import APIView + from rest_framework.schemas import ManualSchema + + class CustomView(APIView): + ... + schema = ManualSchema(fields=[ + coreapi.Field( + "first_field", + required=True, + location="path", + schema=coreschema.String() + ), + coreapi.Field( + "second_field", + required=True, + location="path", + schema=coreschema.String() + ), + ]) + + This allows manually specifying the schema for some views whilst maintaining + automatic generation elsewhere. + +You may disable schema generation for a view by setting `schema` to `None`: + + class CustomView(APIView): + ... + schema = None # Will not appear in schema + +This also applies to extra actions for `ViewSet`s: + + class CustomViewSet(viewsets.ModelViewSet): + + @action(detail=True, schema=None) + def extra_action(self, request, pk=None): + ... + +--- + +**Note**: For full details on `SchemaGenerator` plus the `AutoSchema` and +`ManualSchema` descriptors see the [API Reference below](#api-reference). + +--- + +# Adding a schema view + +There are a few different ways to add a schema view to your API, depending on +exactly what you need. + +## The get_schema_view shortcut + +The simplest way to include a schema in your project is to use the +`get_schema_view()` function. + + from rest_framework.schemas import get_schema_view + + schema_view = get_schema_view(title="Server Monitoring API") + + urlpatterns = [ + path('', schema_view), + ... + ] + +Once the view has been added, you'll be able to make API requests to retrieve +the auto-generated schema definition. + + $ http http://127.0.0.1:8000/ Accept:application/coreapi+json + HTTP/1.0 200 OK + Allow: GET, HEAD, OPTIONS + Content-Type: application/vnd.coreapi+json + + { + "_meta": { + "title": "Server Monitoring API" + }, + "_type": "document", + ... + } + +The arguments to `get_schema_view()` are: + +#### `title` + +May be used to provide a descriptive title for the schema definition. + +#### `url` + +May be used to pass a canonical URL for the schema. + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/' + ) + +#### `urlconf` + +A string representing the import path to the URL conf that you want +to generate an API schema for. This defaults to the value of Django's +ROOT_URLCONF setting. + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + urlconf='myproject.urls' + ) + +#### `renderer_classes` + +May be used to pass the set of renderer classes that can be used to render the API root endpoint. + + from rest_framework.schemas import get_schema_view + from rest_framework.renderers import JSONOpenAPIRenderer + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + renderer_classes=[JSONOpenAPIRenderer] + ) + +#### `patterns` + +List of url patterns to limit the schema introspection to. If you only want the `myproject.api` urls +to be exposed in the schema: + + schema_url_patterns = [ + path('api/', include('myproject.api.urls')), + ] + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + patterns=schema_url_patterns, + ) + +#### `generator_class` + +May be used to specify a `SchemaGenerator` subclass to be passed to the +`SchemaView`. + +#### `authentication_classes` + +May be used to specify the list of authentication classes that will apply to the schema endpoint. +Defaults to `settings.DEFAULT_AUTHENTICATION_CLASSES` + +#### `permission_classes` + +May be used to specify the list of permission classes that will apply to the schema endpoint. +Defaults to `settings.DEFAULT_PERMISSION_CLASSES` + +## Using an explicit schema view + +If you need a little more control than the `get_schema_view()` shortcut gives you, +then you can use the `SchemaGenerator` class directly to auto-generate the +`Document` instance, and to return that from a view. + +This option gives you the flexibility of setting up the schema endpoint +with whatever behavior you want. For example, you can apply different +permission, throttling, or authentication policies to the schema endpoint. + +Here's an example of using `SchemaGenerator` together with a view to +return the schema. + +**views.py:** + + from rest_framework.decorators import api_view, renderer_classes + from rest_framework import renderers, response, schemas + + generator = schemas.SchemaGenerator(title='Bookings API') + + @api_view() + @renderer_classes([renderers.OpenAPIRenderer]) + def schema_view(request): + schema = generator.get_schema(request) + return response.Response(schema) + +**urls.py:** + + urlpatterns = [ + path('', schema_view), + ... + ] + +You can also serve different schemas to different users, depending on the +permissions they have available. This approach can be used to ensure that +unauthenticated requests are presented with a different schema to +authenticated requests, or to ensure that different parts of the API are +made visible to different users depending on their role. + +In order to present a schema with endpoints filtered by user permissions, +you need to pass the `request` argument to the `get_schema()` method, like so: + + @api_view() + @renderer_classes([renderers.OpenAPIRenderer]) + def schema_view(request): + generator = schemas.SchemaGenerator(title='Bookings API') + return response.Response(generator.get_schema(request=request)) + +## Explicit schema definition + +An alternative to the auto-generated approach is to specify the API schema +explicitly, by declaring a `Document` object in your codebase. Doing so is a +little more work, but ensures that you have full control over the schema +representation. + + import coreapi + from rest_framework.decorators import api_view, renderer_classes + from rest_framework import renderers, response + + schema = coreapi.Document( + title='Bookings API', + content={ + ... + } + ) + + @api_view() + @renderer_classes([renderers.OpenAPIRenderer]) + def schema_view(request): + return response.Response(schema) + +--- + +# Schemas as documentation + +One common usage of API schemas is to use them to build documentation pages. + +The schema generation in REST framework uses docstrings to automatically +populate descriptions in the schema document. + +These descriptions will be based on: + +* The corresponding method docstring if one exists. +* A named section within the class docstring, which can be either single line or multi-line. +* The class docstring. + +## Examples + +An `APIView`, with an explicit method docstring. + + class ListUsernames(APIView): + def get(self, request): + """ + Return a list of all user names in the system. + """ + usernames = [user.username for user in User.objects.all()] + return Response(usernames) + +A `ViewSet`, with an explicit action docstring. + + class ListUsernames(ViewSet): + def list(self, request): + """ + Return a list of all user names in the system. + """ + usernames = [user.username for user in User.objects.all()] + return Response(usernames) + +A generic view with sections in the class docstring, using single-line style. + + class UserList(generics.ListCreateAPIView): + """ + get: List all the users. + post: Create a new user. + """ + queryset = User.objects.all() + serializer_class = UserSerializer + permission_classes = [IsAdminUser] + +A generic viewset with sections in the class docstring, using multi-line style. + + class UserViewSet(viewsets.ModelViewSet): + """ + API endpoint that allows users to be viewed or edited. + + retrieve: + Return a user instance. + + list: + Return all users, ordered by most recently joined. + """ + queryset = User.objects.all().order_by('-date_joined') + serializer_class = UserSerializer + +--- + +# API Reference + +## SchemaGenerator + +A class that walks a list of routed URL patterns, requests the schema for each view, +and collates the resulting CoreAPI Document. + +Typically you'll instantiate `SchemaGenerator` with a single argument, like so: + + generator = SchemaGenerator(title='Stock Prices API') + +Arguments: + +* `title` **required** - The name of the API. +* `url` - The root URL of the API schema. This option is not required unless the schema is included under path prefix. +* `patterns` - A list of URLs to inspect when generating the schema. Defaults to the project's URL conf. +* `urlconf` - A URL conf module name to use when generating the schema. Defaults to `settings.ROOT_URLCONF`. + +### get_schema(self, request) + +Returns a `coreapi.Document` instance that represents the API schema. + + @api_view + @renderer_classes([renderers.OpenAPIRenderer]) + def schema_view(request): + generator = schemas.SchemaGenerator(title='Bookings API') + return Response(generator.get_schema()) + +The `request` argument is optional, and may be used if you want to apply per-user +permissions to the resulting schema generation. + +### get_links(self, request) + +Return a nested dictionary containing all the links that should be included in the API schema. + +This is a good point to override if you want to modify the resulting structure of the generated schema, +as you can build a new dictionary with a different layout. + + +## AutoSchema + +A class that deals with introspection of individual views for schema generation. + +`AutoSchema` is attached to `APIView` via the `schema` attribute. + +The `AutoSchema` constructor takes a single keyword argument `manual_fields`. + +**`manual_fields`**: a `list` of `coreapi.Field` instances that will be added to +the generated fields. Generated fields with a matching `name` will be overwritten. + + class CustomView(APIView): + schema = AutoSchema(manual_fields=[ + coreapi.Field( + "my_extra_field", + required=True, + location="path", + schema=coreschema.String() + ), + ]) + +For more advanced customisation subclass `AutoSchema` to customise schema generation. + + class CustomViewSchema(AutoSchema): + """ + Overrides `get_link()` to provide Custom Behavior X + """ + + def get_link(self, path, method, base_url): + link = super().get_link(path, method, base_url) + # Do something to customize link here... + return link + + class MyView(APIView): + schema = CustomViewSchema() + +The following methods are available to override. + +### get_link(self, path, method, base_url) + +Returns a `coreapi.Link` instance corresponding to the given view. + +This is the main entry point. +You can override this if you need to provide custom behaviors for particular views. + +### get_description(self, path, method) + +Returns a string to use as the link description. By default this is based on the +view docstring as described in the "Schemas as Documentation" section above. + +### get_encoding(self, path, method) + +Returns a string to indicate the encoding for any request body, when interacting +with the given view. Eg. `'application/json'`. May return a blank string for views +that do not expect a request body. + +### get_path_fields(self, path, method): + +Return a list of `coreapi.Field()` instances. One for each path parameter in the URL. + +### get_serializer_fields(self, path, method) + +Return a list of `coreapi.Field()` instances. One for each field in the serializer class used by the view. + +### get_pagination_fields(self, path, method) + +Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method on any pagination class used by the view. + +### get_filter_fields(self, path, method) + +Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method of any filter classes used by the view. + +### get_manual_fields(self, path, method) + +Return a list of `coreapi.Field()` instances to be added to or replace generated fields. Defaults to (optional) `manual_fields` passed to `AutoSchema` constructor. + +May be overridden to customise manual fields by `path` or `method`. For example, a per-method adjustment may look like this: + +```python +def get_manual_fields(self, path, method): + """Example adding per-method fields.""" + + extra_fields = [] + if method == 'GET': + extra_fields = ... # list of extra fields for GET + if method == 'POST': + extra_fields = ... # list of extra fields for POST + + manual_fields = super().get_manual_fields(path, method) + return manual_fields + extra_fields +``` + +### update_fields(fields, update_with) + +Utility `staticmethod`. Encapsulates logic to add or replace fields from a list +by `Field.name`. May be overridden to adjust replacement criteria. + + +## ManualSchema + +Allows manually providing a list of `coreapi.Field` instances for the schema, +plus an optional description. + + class MyView(APIView): + schema = ManualSchema(fields=[ + coreapi.Field( + "first_field", + required=True, + location="path", + schema=coreschema.String() + ), + coreapi.Field( + "second_field", + required=True, + location="path", + schema=coreschema.String() + ), + ] + ) + +The `ManualSchema` constructor takes two arguments: + +**`fields`**: A list of `coreapi.Field` instances. Required. + +**`description`**: A string description. Optional. + +**`encoding`**: Default `None`. A string encoding, e.g `application/json`. Optional. + +--- + +## Core API + +This documentation gives a brief overview of the components within the `coreapi` +package that are used to represent an API schema. + +Note that these classes are imported from the `coreapi` package, rather than +from the `rest_framework` package. + +### Document + +Represents a container for the API schema. + +#### `title` + +A name for the API. + +#### `url` + +A canonical URL for the API. + +#### `content` + +A dictionary, containing the `Link` objects that the schema contains. + +In order to provide more structure to the schema, the `content` dictionary +may be nested, typically to a second level. For example: + + content={ + "bookings": { + "list": Link(...), + "create": Link(...), + ... + }, + "venues": { + "list": Link(...), + ... + }, + ... + } + +### Link + +Represents an individual API endpoint. + +#### `url` + +The URL of the endpoint. May be a URI template, such as `/users/{username}/`. + +#### `action` + +The HTTP method associated with the endpoint. Note that URLs that support +more than one HTTP method, should correspond to a single `Link` for each. + +#### `fields` + +A list of `Field` instances, describing the available parameters on the input. + +#### `description` + +A short description of the meaning and intended usage of the endpoint. + +### Field + +Represents a single input parameter on a given API endpoint. + +#### `name` + +A descriptive name for the input. + +#### `required` + +A boolean, indicated if the client is required to included a value, or if +the parameter can be omitted. + +#### `location` + +Determines how the information is encoded into the request. Should be one of +the following strings: + +**"path"** + +Included in a templated URI. For example a `url` value of `/products/{product_code}/` could be used together with a `"path"` field, to handle API inputs in a URL path such as `/products/slim-fit-jeans/`. + +These fields will normally correspond with [named arguments in the project URL conf][named-arguments]. + +**"query"** + +Included as a URL query parameter. For example `?search=sale`. Typically for `GET` requests. + +These fields will normally correspond with pagination and filtering controls on a view. + +**"form"** + +Included in the request body, as a single item of a JSON object or HTML form. For example `{"colour": "blue", ...}`. Typically for `POST`, `PUT` and `PATCH` requests. Multiple `"form"` fields may be included on a single link. + +These fields will normally correspond with serializer fields on a view. + +**"body"** + +Included as the complete request body. Typically for `POST`, `PUT` and `PATCH` requests. No more than one `"body"` field may exist on a link. May not be used together with `"form"` fields. + +These fields will normally correspond with views that use `ListSerializer` to validate the request input, or with file upload views. + +#### `encoding` + +**"application/json"** + +JSON encoded request content. Corresponds to views using `JSONParser`. +Valid only if either one or more `location="form"` fields, or a single +`location="body"` field is included on the `Link`. + +**"multipart/form-data"** + +Multipart encoded request content. Corresponds to views using `MultiPartParser`. +Valid only if one or more `location="form"` fields is included on the `Link`. + +**"application/x-www-form-urlencoded"** + +URL encoded request content. Corresponds to views using `FormParser`. Valid +only if one or more `location="form"` fields is included on the `Link`. + +**"application/octet-stream"** + +Binary upload request content. Corresponds to views using `FileUploadParser`. +Valid only if a `location="body"` field is included on the `Link`. + +#### `description` + +A short description of the meaning and intended usage of the input field. + + +--- + +# Third party packages + +## drf-yasg - Yet Another Swagger Generator + +[drf-yasg][drf-yasg] generates [OpenAPI][open-api] documents suitable for code generation - nested schemas, +named models, response bodies, enum/pattern/min/max validators, form parameters, etc. + + +## drf-spectacular - Sane and flexible OpenAPI 3.0 schema generation for Django REST framework + +[drf-spectacular][drf-spectacular] is a [OpenAPI 3][open-api] schema generation tool with explicit focus on extensibility, +customizability and client generation. It's usage patterns are very similar to [drf-yasg][drf-yasg]. + +[cite]: https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api +[coreapi]: https://www.coreapi.org/ +[corejson]: https://www.coreapi.org/specification/encoding/#core-json-encoding +[drf-yasg]: https://github.com/axnsan12/drf-yasg/ +[drf-spectacular]: https://github.com/tfranzel/drf-spectacular/ +[open-api]: https://openapis.org/ +[json-hyperschema]: https://json-schema.org/latest/json-schema-hypermedia.html +[api-blueprint]: https://apiblueprint.org/ +[static-files]: https://docs.djangoproject.com/en/stable/howto/static-files/ +[named-arguments]: https://docs.djangoproject.com/en/stable/topics/http/urls/#named-groups diff --git a/docs/img/apiary.png b/docs/img/apiary.png deleted file mode 100644 index 923d384eb..000000000 Binary files a/docs/img/apiary.png and /dev/null differ diff --git a/docs/img/books/dfa-cover.jpg b/docs/img/books/dfa-cover.jpg new file mode 100644 index 000000000..09ed268f2 Binary files /dev/null and b/docs/img/books/dfa-cover.jpg differ diff --git a/docs/img/books/rad-cover.png b/docs/img/books/rad-cover.png deleted file mode 100644 index 75b19df64..000000000 Binary files a/docs/img/books/rad-cover.png and /dev/null differ diff --git a/docs/img/build-status.png b/docs/img/build-status.png new file mode 100644 index 000000000..bb043cb9e Binary files /dev/null and b/docs/img/build-status.png differ diff --git a/docs/img/django-rest-swagger.png b/docs/img/django-rest-swagger.png deleted file mode 100644 index 96a6b2380..000000000 Binary files a/docs/img/django-rest-swagger.png and /dev/null differ diff --git a/docs/img/drfdocs.png b/docs/img/drfdocs.png deleted file mode 100644 index 0cccb41f7..000000000 Binary files a/docs/img/drfdocs.png and /dev/null differ diff --git a/docs/img/premium/bitio-readme.png b/docs/img/premium/bitio-readme.png new file mode 100644 index 000000000..d5d6259e6 Binary files /dev/null and b/docs/img/premium/bitio-readme.png differ diff --git a/docs/img/premium/cadre-readme.png b/docs/img/premium/cadre-readme.png index b61539469..412a09359 100644 Binary files a/docs/img/premium/cadre-readme.png and b/docs/img/premium/cadre-readme.png differ diff --git a/docs/img/premium/cryptapi-readme.png b/docs/img/premium/cryptapi-readme.png new file mode 100644 index 000000000..10839b13b Binary files /dev/null and b/docs/img/premium/cryptapi-readme.png differ diff --git a/docs/img/premium/esg-readme.png b/docs/img/premium/esg-readme.png new file mode 100644 index 000000000..8f84e5669 Binary files /dev/null and b/docs/img/premium/esg-readme.png differ diff --git a/docs/img/premium/fezto-readme.png b/docs/img/premium/fezto-readme.png new file mode 100644 index 000000000..7cc3be6e6 Binary files /dev/null and b/docs/img/premium/fezto-readme.png differ diff --git a/docs/img/premium/kloudless-readme.png b/docs/img/premium/kloudless-readme.png index 5d32b31b6..054ab9394 100644 Binary files a/docs/img/premium/kloudless-readme.png and b/docs/img/premium/kloudless-readme.png differ diff --git a/docs/img/premium/lightson-readme.png b/docs/img/premium/lightson-readme.png index 3c8c6c62a..9afc1eee9 100644 Binary files a/docs/img/premium/lightson-readme.png and b/docs/img/premium/lightson-readme.png differ diff --git a/docs/img/premium/load-impact-readme.png b/docs/img/premium/load-impact-readme.png deleted file mode 100644 index c46d36ada..000000000 Binary files a/docs/img/premium/load-impact-readme.png and /dev/null differ diff --git a/docs/img/premium/machinalis-readme.png b/docs/img/premium/machinalis-readme.png deleted file mode 100644 index cd98c23c7..000000000 Binary files a/docs/img/premium/machinalis-readme.png and /dev/null differ diff --git a/docs/img/premium/micropyramid-readme.png b/docs/img/premium/micropyramid-readme.png deleted file mode 100644 index 9fa9500e1..000000000 Binary files a/docs/img/premium/micropyramid-readme.png and /dev/null differ diff --git a/docs/img/premium/posthog-readme.png b/docs/img/premium/posthog-readme.png new file mode 100644 index 000000000..0fc09f0b8 Binary files /dev/null and b/docs/img/premium/posthog-readme.png differ diff --git a/docs/img/premium/release-history.png b/docs/img/premium/release-history.png index b732b1ca2..d14024f32 100644 Binary files a/docs/img/premium/release-history.png and b/docs/img/premium/release-history.png differ diff --git a/docs/img/premium/retool-readme.png b/docs/img/premium/retool-readme.png new file mode 100644 index 000000000..971563427 Binary files /dev/null and b/docs/img/premium/retool-readme.png differ diff --git a/docs/img/premium/rollbar-readme.png b/docs/img/premium/rollbar-readme.png index b0655f783..3c07105ae 100644 Binary files a/docs/img/premium/rollbar-readme.png and b/docs/img/premium/rollbar-readme.png differ diff --git a/docs/img/premium/rover-readme.png b/docs/img/premium/rover-readme.png deleted file mode 100644 index b8055d62e..000000000 Binary files a/docs/img/premium/rover-readme.png and /dev/null differ diff --git a/docs/img/premium/sentry-readme.png b/docs/img/premium/sentry-readme.png index 5536ce52f..3c8858aca 100644 Binary files a/docs/img/premium/sentry-readme.png and b/docs/img/premium/sentry-readme.png differ diff --git a/docs/img/premium/spacinov-readme.png b/docs/img/premium/spacinov-readme.png new file mode 100644 index 000000000..20e925211 Binary files /dev/null and b/docs/img/premium/spacinov-readme.png differ diff --git a/docs/img/premium/stream-readme.png b/docs/img/premium/stream-readme.png index fc3733c70..a6a7317b7 100644 Binary files a/docs/img/premium/stream-readme.png and b/docs/img/premium/stream-readme.png differ diff --git a/docs/img/quickstart.png b/docs/img/quickstart.png index 5006d60fe..e3581f308 100644 Binary files a/docs/img/quickstart.png and b/docs/img/quickstart.png differ diff --git a/docs/img/travis-status.png b/docs/img/travis-status.png deleted file mode 100644 index fec98cf9b..000000000 Binary files a/docs/img/travis-status.png and /dev/null differ diff --git a/docs/index.md b/docs/index.md index 9f5d3fa15..0c428c8ec 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,8 +20,8 @@

- - + + @@ -52,7 +52,7 @@ Some reasons you might want to use REST framework: * [Authentication policies][authentication] including packages for [OAuth1a][oauth1-section] and [OAuth2][oauth2-section]. * [Serialization][serializers] that supports both [ORM][modelserializer-section] and [non-ORM][serializer-section] data sources. * Customizable all the way down - just use [regular function-based views][functionview-section] if you don't need the [more][generic-views] [powerful][viewsets] [features][routers]. -* [Extensive documentation][index], and [great community support][group]. +* Extensive documentation, and [great community support][group]. * Used and trusted by internationally recognised companies including [Mozilla][mozilla], [Red Hat][redhat], [Heroku][heroku], and [Eventbrite][eventbrite]. --- @@ -67,16 +67,17 @@ continued development by **[signing up for a paid plan][funding]**.

-*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Release History](https://releasehistory.io), [Rollbar](https://rollbar.com), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), and [Lights On Software](https://lightsonsoftware.com).* +*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=DjangoRESTFramework&utm_medium=Webpage_Logo_Ad&utm_content=Developer&utm_campaign=DjangoRESTFramework_Jan2022_HomePage), [Spacinov](https://www.spacinov.com/), [Retool](https://retool.com/?utm_source=djangorest&utm_medium=sponsorship), [bit.io](https://bit.io/jobs?utm_source=DRF&utm_medium=sponsor&utm_campaign=DRF_sponsorship), [PostHog](https://posthog.com?utm_source=DRF&utm_medium=sponsor&utm_campaign=DRF_sponsorship), [CryptAPI](https://cryptapi.io), and [FEZTO](https://www.fezto.xyz/?utm_source=DjangoRESTFramework).* --- @@ -84,18 +85,18 @@ continued development by **[signing up for a paid plan][funding]**. REST framework requires the following: -* Python (2.7, 3.4, 3.5, 3.6, 3.7) -* Django (1.11, 2.0, 2.1, 2.2) +* Python (3.6, 3.7, 3.8, 3.9, 3.10) +* Django (2.2, 3.0, 3.1, 3.2, 4.0, 4.1) We **highly recommend** and only officially support the latest patch release of each Python and Django series. The following packages are optional: -* [coreapi][coreapi] (1.32.0+) - Schema generation support. -* [Markdown][markdown] (2.1.0+) - Markdown support for the browsable API. +* [PyYAML][pyyaml], [uritemplate][uriteemplate] (5.1+, 3.0.0+) - Schema generation support. +* [Markdown][markdown] (3.0.0+) - Markdown support for the browsable API. +* [Pygments][pygments] (2.4.0+) - Add syntax highlighting to Markdown processing. * [django-filter][django-filter] (1.0.1+) - Filtering support. -* [django-crispy-forms][django-crispy-forms] - Improved HTML display for filtering. * [django-guardian][django-guardian] (1.1.1+) - Object level permissions support. ## Installation @@ -112,16 +113,16 @@ Install using `pip`, including any optional packages you want... Add `'rest_framework'` to your `INSTALLED_APPS` setting. - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'rest_framework', - ) + ] 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 `urls.py` file. urlpatterns = [ ... - url(r'^api-auth/', include('rest_framework.urls')) + path('api-auth/', include('rest_framework.urls')) ] Note that the URL path can be whatever you want. @@ -147,7 +148,7 @@ Don't forget to make sure you've also added `rest_framework` to your `INSTALLED_ We're ready to create our API now. Here's our project's root `urls.py` module: - from django.conf.urls import url, include + from django.urls import path, include from django.contrib.auth.models import User from rest_framework import routers, serializers, viewsets @@ -155,7 +156,7 @@ Here's our project's root `urls.py` module: class UserSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = User - fields = ('url', 'username', 'email', 'is_staff') + fields = ['url', 'username', 'email', 'is_staff'] # ViewSets define the view behavior. class UserViewSet(viewsets.ModelViewSet): @@ -169,8 +170,8 @@ Here's our project's root `urls.py` module: # Wire up our API using automatic URL routing. # Additionally, we include login URLs for the browsable API. urlpatterns = [ - url(r'^', include(router.urls)), - url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) + path('', include(router.urls)), + path('api-auth/', include('rest_framework.urls', namespace='rest_framework')) ] You can now open the API in your browser at [http://127.0.0.1:8000/](http://127.0.0.1:8000/), and view your new 'users' API. If you use the login control in the top right corner you'll also be able to add, create and delete users from the system. @@ -187,20 +188,17 @@ Framework. ## Support -For support please see the [REST framework discussion group][group], try the `#restframework` channel on `irc.freenode.net`, search [the IRC archives][botbot], or raise a question on [Stack Overflow][stack-overflow], making sure to include the ['django-rest-framework'][django-rest-framework-tag] tag. +For support please see the [REST framework discussion group][group], try the `#restframework` channel on `irc.libera.chat`, or raise a question on [Stack Overflow][stack-overflow], making sure to include the ['django-rest-framework'][django-rest-framework-tag] tag. For priority support please sign up for a [professional or premium sponsorship plan](https://fund.django-rest-framework.org/topics/funding/). -For updates on REST framework development, you may also want to follow [the author][twitter] on Twitter. - - - - ## Security -If you believe you’ve found something in Django REST framework which has security implications, please **do not raise the issue in a public forum**. +Security issues are handled under the supervision of the [Django security team](https://www.djangoproject.com/foundation/teams/#security-team). -Send a description of the issue via email to [rest-framework-security@googlegroups.com][security-mail]. The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure. +**Please report security issues by emailing security@djangoproject.com**. + +The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure. ## License @@ -236,10 +234,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [redhat]: https://www.redhat.com/ [heroku]: https://www.heroku.com/ [eventbrite]: https://www.eventbrite.co.uk/about/ -[coreapi]: https://pypi.org/project/coreapi/ +[pyyaml]: https://pypi.org/project/PyYAML/ +[uriteemplate]: https://pypi.org/project/uritemplate/ [markdown]: https://pypi.org/project/Markdown/ +[pygments]: https://pypi.org/project/Pygments/ [django-filter]: https://pypi.org/project/django-filter/ -[django-crispy-forms]: https://github.com/maraujop/django-crispy-forms [django-guardian]: https://github.com/django-guardian/django-guardian [index]: . [oauth1-section]: api-guide/authentication/#django-rest-framework-oauth @@ -262,7 +261,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [funding]: community/funding.md [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework -[botbot]: https://botbot.me/freenode/restframework/ [stack-overflow]: https://stackoverflow.com/ [django-rest-framework-tag]: https://stackoverflow.com/questions/tagged/django-rest-framework [security-mail]: mailto:rest-framework-security@googlegroups.com diff --git a/docs/topics/ajax-csrf-cors.md b/docs/topics/ajax-csrf-cors.md index 646f3f563..094ecc4a4 100644 --- a/docs/topics/ajax-csrf-cors.md +++ b/docs/topics/ajax-csrf-cors.md @@ -2,7 +2,7 @@ > "Take a close look at possible CSRF / XSRF vulnerabilities on your own websites. They're the worst kind of vulnerability — very easy to exploit by attackers, yet not so intuitively easy to understand for software developers, at least until you've been bitten by one." > -> — [Jeff Atwood][cite] +> — [Jeff Atwood][cite] ## Javascript clients @@ -31,11 +31,11 @@ In order to make AJAX requests, you need to include CSRF token in the HTTP heade The best way to deal with CORS in REST framework is to add the required response headers in middleware. This ensures that CORS is supported transparently, without having to change any behavior in your views. -[Otto Yiu][ottoyiu] maintains the [django-cors-headers] package, which is known to work correctly with REST framework APIs. +[Adam Johnson][adamchainz] maintains the [django-cors-headers] package, which is known to work correctly with REST framework APIs. [cite]: https://blog.codinghorror.com/preventing-csrf-and-xsrf-attacks/ [csrf]: https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF) [csrf-ajax]: https://docs.djangoproject.com/en/stable/ref/csrf/#ajax [cors]: https://www.w3.org/TR/cors/ -[ottoyiu]: https://github.com/ottoyiu/ -[django-cors-headers]: https://github.com/ottoyiu/django-cors-headers/ +[adamchainz]: https://github.com/adamchainz +[django-cors-headers]: https://github.com/adamchainz/django-cors-headers diff --git a/docs/topics/api-clients.md b/docs/topics/api-clients.md index 3fd560634..3732d3f93 100644 --- a/docs/topics/api-clients.md +++ b/docs/topics/api-clients.md @@ -230,7 +230,7 @@ started. In order to start working with an API, we first need a `Client` instance. The client holds any configuration around which codecs and transports are supported when interacting with an API, which allows you to provide for more advanced -kinds of behaviour. +kinds of behavior. import coreapi client = coreapi.Client() @@ -384,7 +384,7 @@ First, install the API documentation views. These will include the schema resour urlpatterns = [ ... - url(r'^docs/', include_docs_urls(title='My API service')) + path('docs/', include_docs_urls(title='My API service'), name='api-docs'), ] Once the API documentation URLs are installed, you'll be able to include both the required JavaScript resources. Note that the ordering of these two lines is important, as the schema loading requires CoreAPI to already be installed. @@ -401,14 +401,14 @@ Once the API documentation URLs are installed, you'll be able to include both th The `coreapi` library, and the `schema` object will now both be available on the `window` instance. - const coreapi = window.coreapi - const schema = window.schema + const coreapi = window.coreapi; + const schema = window.schema; ## Instantiating a client In order to interact with the API you'll need a client instance. - var client = new coreapi.Client() + var client = new coreapi.Client(); Typically you'll also want to provide some authentication credentials when instantiating the client. @@ -421,9 +421,9 @@ the user to login, and then instantiate a client using session authentication: let auth = new coreapi.auth.SessionAuthentication({ csrfCookieName: 'csrftoken', - csrfHeaderName: 'X-CSRFToken' - }) - let client = new coreapi.Client({auth: auth}) + csrfHeaderName: 'X-CSRFToken', + }); + let client = new coreapi.Client({auth: auth}); The authentication scheme will handle including a CSRF header in any outgoing requests for unsafe HTTP methods. @@ -434,10 +434,10 @@ The `TokenAuthentication` class can be used to support REST framework's built-in `TokenAuthentication`, as well as OAuth and JWT schemes. let auth = new coreapi.auth.TokenAuthentication({ - scheme: 'JWT' - token: '' - }) - let client = new coreapi.Client({auth: auth}) + scheme: 'JWT', + token: '', + }); + let client = new coreapi.Client({auth: auth}); When using TokenAuthentication you'll probably need to implement a login flow using the CoreAPI client. @@ -448,20 +448,20 @@ request to an "obtain token" endpoint For example, using the "Django REST framework JWT" package // Setup some globally accessible state - window.client = new coreapi.Client() - window.loggedIn = false + window.client = new coreapi.Client(); + window.loggedIn = false; function loginUser(username, password) { - let action = ["api-token-auth", "obtain-token"] - let params = {username: "example", email: "example@example.com"} + let action = ["api-token-auth", "obtain-token"]; + let params = {username: username, password: password}; client.action(schema, action, params).then(function(result) { // On success, instantiate an authenticated client. let auth = window.coreapi.auth.TokenAuthentication({ scheme: 'JWT', - token: result['token'] + token: result['token'], }) - window.client = coreapi.Client({auth: auth}) - window.loggedIn = true + window.client = coreapi.Client({auth: auth}); + window.loggedIn = true; }).catch(function (error) { // Handle error case where eg. user provides incorrect credentials. }) @@ -473,23 +473,23 @@ The `BasicAuthentication` class can be used to support HTTP Basic Authentication let auth = new coreapi.auth.BasicAuthentication({ username: '', - password: '' + password: '', }) - let client = new coreapi.Client({auth: auth}) + let client = new coreapi.Client({auth: auth}); ## Using the client Making requests: - let action = ["users", "list"] + let action = ["users", "list"]; client.action(schema, action).then(function(result) { // Return value is in 'result' }) Including parameters: - let action = ["users", "create"] - let params = {username: "example", email: "example@example.com"} + let action = ["users", "create"]; + let params = {username: "example", email: "example@example.com"}; client.action(schema, action, params).then(function(result) { // Return value is in 'result' }) @@ -512,12 +512,12 @@ The coreapi package is available on NPM. You'll either want to include the API schema in your codebase directly, by copying it from the `schema.js` resource, or else load the schema asynchronously. For example: - let client = new coreapi.Client() - let schema = null + let client = new coreapi.Client(); + let schema = null; client.get("https://api.example.org/").then(function(data) { // Load a CoreJSON API schema. - schema = data - console.log('schema loaded') + schema = data; + console.log('schema loaded'); }) [heroku-api]: https://devcenter.heroku.com/categories/platform-api diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index ed70c4901..2cdf2a884 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -17,7 +17,7 @@ By default, the API will return the format specified by the headers, which in th ## Customizing -The browsable API is built with [Twitter's Bootstrap][bootstrap] (v 3.3.5), making it easy to customize the look-and-feel. +The browsable API is built with [Twitter's Bootstrap][bootstrap] (v 3.4.1), making it easy to customize the look-and-feel. To customize the default style, create a template called `rest_framework/api.html` that extends from `rest_framework/base.html`. For example: @@ -35,7 +35,7 @@ To replace the default theme, add a `bootstrap_theme` block to your `api.html` a {% endblock %} -Suitable pre-made replacement themes are available at [Bootswatch][bswatch]. To use any of the Bootswatch themes, simply download the theme's `bootstrap.min.css` file, add it to your project, and replace the default one as described above. +Suitable pre-made replacement themes are available at [Bootswatch][bswatch]. To use any of the Bootswatch themes, simply download the theme's `bootstrap.min.css` file, add it to your project, and replace the default one as described above. Make sure that the Bootstrap version of the new theme matches that of the default theme. You can also change the navbar variant, which by default is `navbar-inverse`, using the `bootstrap_navbar_variant` block. The empty `{% block bootstrap_navbar_variant %}{% endblock %}` will use the original Bootstrap navbar style. @@ -44,7 +44,7 @@ Full example: {% extends "rest_framework/base.html" %} {% block bootstrap_theme %} - + {% endblock %} {% block bootstrap_navbar_variant %}{% endblock %} diff --git a/docs/topics/browser-enhancements.md b/docs/topics/browser-enhancements.md index fa07b6064..67c1c1898 100644 --- a/docs/topics/browser-enhancements.md +++ b/docs/topics/browser-enhancements.md @@ -51,13 +51,15 @@ For example: METHOD_OVERRIDE_HEADER = 'HTTP_X_HTTP_METHOD_OVERRIDE' - class MethodOverrideMiddleware(object): - def process_view(self, request, callback, callback_args, callback_kwargs): - if request.method != 'POST': - return - if METHOD_OVERRIDE_HEADER not in request.META: - return - request.method = request.META[METHOD_OVERRIDE_HEADER] + class MethodOverrideMiddleware: + + def __init__(self, get_response): + self.get_response = get_response + + def __call__(self, request): + if request.method == 'POST' and METHOD_OVERRIDE_HEADER in request.META: + request.method = request.META[METHOD_OVERRIDE_HEADER] + return self.get_response(request) ## URL based accept headers diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index 7eab08ecf..5eabeee7b 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -4,176 +4,125 @@ > > — Roy Fielding, [REST APIs must be hypertext driven][cite] -REST framework provides built-in support for API documentation. There are also a number of great third-party documentation tools available. +REST framework provides built-in support for generating OpenAPI schemas, which +can be used with tools that allow you to build API documentation. -## Built-in API documentation +There are also a number of great third-party documentation packages available. -The built-in API documentation includes: +## Generating documentation from OpenAPI schemas -* Documentation of API endpoints. -* Automatically generated code samples for each of the available API client libraries. -* Support for API interaction. +There are a number of packages available that allow you to generate HTML +documentation pages from OpenAPI schemas. -### Installation +Two popular options are [Swagger UI][swagger-ui] and [ReDoc][redoc]. -The `coreapi` library is required as a dependency for the API docs. Make sure -to install the latest version. The `pygments` and `markdown` libraries -are optional but recommended. +Both require little more than the location of your static schema file or +dynamic `SchemaView` endpoint. -To install the API documentation, you'll need to include it in your project's URLconf: +### A minimal example with Swagger UI - from rest_framework.documentation import include_docs_urls +Assuming you've followed the example from the schemas documentation for routing +a dynamic `SchemaView`, a minimal Django template for using Swagger UI might be +this: - urlpatterns = [ - ... - url(r'^docs/', include_docs_urls(title='My API title')) - ] +```html + + + + Swagger + + + + + +
+ + + + +``` -This will include two different views: +Save this in your templates folder as `swagger-ui.html`. Then route a +`TemplateView` in your project's URL conf: - * `/docs/` - The documentation page itself. - * `/docs/schema.js` - A JavaScript resource that exposes the API schema. +```python +from django.views.generic import TemplateView ---- +urlpatterns = [ + # ... + # Route TemplateView to serve Swagger UI template. + # * Provide `extra_context` with view name of `SchemaView`. + path('swagger-ui/', TemplateView.as_view( + template_name='swagger-ui.html', + extra_context={'schema_url':'openapi-schema'} + ), name='swagger-ui'), +] +``` -**Note**: By default `include_docs_urls` configures the underlying `SchemaView` to generate _public_ schemas. -This means that views will not be instantiated with a `request` instance. i.e. Inside the view `self.request` will be `None`. +See the [Swagger UI documentation][swagger-ui] for advanced usage. -To be compatible with this behaviour, methods (such as `get_serializer` or `get_serializer_class` etc.) which inspect `self.request` or, particularly, `self.request.user` may need to be adjusted to handle this case. +### A minimal example with ReDoc. -You may ensure views are given a `request` instance by calling `include_docs_urls` with `public=False`: +Assuming you've followed the example from the schemas documentation for routing +a dynamic `SchemaView`, a minimal Django template for using ReDoc might be +this: - from rest_framework.documentation import include_docs_urls +```html + + + + ReDoc + + + + + + + + + + + + +``` - urlpatterns = [ - ... - # Generate schema with valid `request` instance: - url(r'^docs/', include_docs_urls(title='My API title', public=False)) - ] +Save this in your templates folder as `redoc.html`. Then route a `TemplateView` +in your project's URL conf: +```python +from django.views.generic import TemplateView ---- +urlpatterns = [ + # ... + # Route TemplateView to serve the ReDoc template. + # * Provide `extra_context` with view name of `SchemaView`. + path('redoc/', TemplateView.as_view( + template_name='redoc.html', + extra_context={'schema_url':'openapi-schema'} + ), name='redoc'), +] +``` - -### Documenting your views - -You can document your views by including docstrings that describe each of the available actions. -For example: - - class UserList(generics.ListAPIView): - """ - Return a list of all the existing users. - """ - -If a view supports multiple methods, you should split your documentation using `method:` style delimiters. - - class UserList(generics.ListCreateAPIView): - """ - get: - Return a list of all the existing users. - - post: - Create a new user instance. - """ - -When using viewsets, you should use the relevant action names as delimiters. - - class UserViewSet(viewsets.ModelViewSet): - """ - retrieve: - Return the given user. - - list: - Return a list of all the existing users. - - create: - Create a new user instance. - """ - -Custom actions on viewsets can also be documented in a similar way using the method names -as delimiters or by attaching the documentation to action mapping methods. - - class UserViewSet(viewsets.ModelViewset): - ... - - @action(detail=False, methods=['get', 'post']) - def some_action(self, request, *args, **kwargs): - """ - get: - A description of the get method on the custom action. - - post: - A description of the post method on the custom action. - """ - - @some_action.mapping.put - def put_some_action(): - """ - A description of the put method on the custom action. - """ - - -### `documentation` API Reference - -The `rest_framework.documentation` module provides three helper functions to help configure the interactive API documentation, `include_docs_urls` (usage shown above), `get_docs_view` and `get_schemajs_view`. - - `include_docs_urls` employs `get_docs_view` and `get_schemajs_view` to generate the url patterns for the documentation page and JavaScript resource that exposes the API schema respectively. They expose the following options for customisation. (`get_docs_view` and `get_schemajs_view` ultimately call `rest_frameworks.schemas.get_schema_view()`, see the Schemas docs for more options there.) - -#### `include_docs_urls` - -* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. -* `description`: Default `None`. May be used to provide a description for the schema definition. -* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. -* `public`: Default `True`. Should the schema be considered _public_? If `True` schema is generated without a `request` instance being passed to views. -* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. -* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. -* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. -* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`. -* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. - -#### `get_docs_view` - -* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. -* `description`: Default `None`. May be used to provide a description for the schema definition. -* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. -* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views. -* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. -* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. -* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. -* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES`. May be used to pass custom permission classes to the `SchemaView`. -* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. If `None` the `SchemaView` will be configured with `DocumentationRenderer` and `CoreJSONRenderer` renderers, corresponding to the (default) `html` and `corejson` formats. - -#### `get_schemajs_view` - -* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. -* `description`: Default `None`. May be used to provide a description for the schema definition. -* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. -* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views. -* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. -* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. -* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. -* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`. - - -### Customising code samples - -The built-in API documentation includes automatically generated code samples for -each of the available API client libraries. - -You may customise these samples by subclassing `DocumentationRenderer`, setting -`languages` to the list of languages you wish to support: - - from rest_framework.renderers import DocumentationRenderer - - - class CustomRenderer(DocumentationRenderer): - languages = ['ruby', 'go'] - -For each language you need to provide an `intro` template, detailing installation instructions and such, -plus a generic template for making API requests, that can be filled with individual request details. -See the [templates for the bundled languages][client-library-templates] for examples. - ---- +See the [ReDoc documentation][redoc] for advanced usage. ## Third party packages @@ -193,67 +142,15 @@ This also translates into a very useful interactive documentation viewer in the ![Screenshot - drf-yasg][image-drf-yasg] ---- +#### drf-spectacular - Sane and flexible OpenAPI 3.0 schema generation for Django REST framework -#### DRF Docs +[drf-spectacular][drf-spectacular] is a [OpenAPI 3][open-api] schema generation tool with explicit focus on extensibility, +customizability and client generation. Usage patterns are very similar to [drf-yasg][drf-yasg]. -[DRF Docs][drfdocs-repo] allows you to document Web APIs made with Django REST Framework and it is authored by Emmanouil Konstantinidis. It's made to work out of the box and its setup should not take more than a couple of minutes. Complete documentation can be found on the [website][drfdocs-website] while there is also a [demo][drfdocs-demo] available for people to see what it looks like. **Live API Endpoints** allow you to utilize the endpoints from within the documentation in a neat way. - -Features include customizing the template with your branding, settings for hiding the docs depending on the environment and more. - -Both this package and Django REST Swagger are fully documented, well supported, and come highly recommended. - -![Screenshot - DRF docs][image-drf-docs] - ---- - -#### Django REST Swagger - -Marc Gibbons' [Django REST Swagger][django-rest-swagger] integrates REST framework with the [Swagger][swagger] API documentation tool. The package produces well presented API documentation, and includes interactive tools for testing API endpoints. - -Django REST Swagger supports REST framework versions 2.3 and above. - -Mark is also the author of the [REST Framework Docs][rest-framework-docs] package which offers clean, simple autogenerated documentation for your API but is deprecated and has moved to Django REST Swagger. - -Both this package and DRF docs are fully documented, well supported, and come highly recommended. - -![Screenshot - Django REST Swagger][image-django-rest-swagger] - ---- - -### DRF AutoDocs - -Oleksander Mashianovs' [DRF Auto Docs][drfautodocs-repo] automated api renderer. - -Collects almost all the code you written into documentation effortlessly. - -Supports: - - * functional view docs - * tree-like structure - * Docstrings: - * markdown - * preserve space & newlines - * formatting with nice syntax - * Fields: - * choices rendering - * help_text (to specify SerializerMethodField output, etc) - * smart read_only/required rendering - * Endpoint properties: - * filter_backends - * authentication_classes - * permission_classes - * extra url params(GET params) - -![whole structure](http://joxi.ru/52aBGNI4k3oyA0.jpg) - ---- - -#### Apiary - -There are various other online tools and services for providing API documentation. One notable service is [Apiary][apiary]. With Apiary, you describe your API using a simple markdown-like syntax. The generated documentation includes API interaction, a mock server for testing & prototyping, and various other tools. - -![Screenshot - Apiary][image-apiary] +It aims to extract as much schema information as possible, while providing decorators and extensions for easy +customization. There is explicit support for [swagger-codegen][swagger], [SwaggerUI][swagger-ui] and [Redoc][redoc], +i18n, versioning, authentication, polymorphism (dynamic requests and responses), query/path/header parameters, +documentation and more. Several popular plugins for DRF are supported out-of-the-box as well. --- @@ -277,7 +174,7 @@ When working with viewsets, an appropriate suffix is appended to each generated The description in the browsable API is generated from the docstring of the view or viewset. -If the python `markdown` library is installed, then [markdown syntax][markdown] may be used in the docstring, and will be converted to HTML in the browsable API. For example: +If the python `Markdown` library is installed, then [markdown syntax][markdown] may be used in the docstring, and will be converted to HTML in the browsable API. For example: class AccountListView(views.APIView): """ @@ -288,7 +185,7 @@ If the python `markdown` library is installed, then [markdown syntax][markdown] [ref]: http://example.com/activating-accounts """ -Note that when using viewsets the basic docstring is used for all generated views. To provide descriptions for each view, such as for the the list and retrieve views, use docstring sections as described in [Schemas as documentation: Examples][schemas-examples]. +Note that when using viewsets the basic docstring is used for all generated views. To provide descriptions for each view, such as for the list and retrieve views, use docstring sections as described in [Schemas as documentation: Examples][schemas-examples]. #### The `OPTIONS` method @@ -305,7 +202,7 @@ You can modify the response behavior to `OPTIONS` requests by overriding the `op meta = self.metadata_class() data = meta.determine_metadata(request, self) data.pop('description') - return data + return Response(data=data, status=status.HTTP_200_OK) See [the Metadata docs][metadata-docs] for more details. @@ -320,23 +217,18 @@ In this approach, rather than documenting the available API endpoints up front, To implement a hypermedia API you'll need to decide on an appropriate media type for the API, and implement a custom renderer and parser for that media type. The [REST, Hypermedia & HATEOAS][hypermedia-docs] section of the documentation includes pointers to background reading, as well as links to various hypermedia formats. [cite]: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven -[drf-yasg]: https://github.com/axnsan12/drf-yasg/ -[image-drf-yasg]: ../img/drf-yasg.png -[drfdocs-repo]: https://github.com/ekonstantinidis/django-rest-framework-docs -[drfdocs-website]: https://www.drfdocs.com/ -[drfdocs-demo]: http://demo.drfdocs.com/ -[drfautodocs-repo]: https://github.com/iMakedonsky/drf-autodocs -[django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger -[swagger]: https://swagger.io/ -[open-api]: https://openapis.org/ -[rest-framework-docs]: https://github.com/marcgibbons/django-rest-framework-docs -[apiary]: https://apiary.io/ -[markdown]: https://daringfireball.net/projects/markdown/ + [hypermedia-docs]: rest-hypermedia-hateoas.md -[image-drf-docs]: ../img/drfdocs.png -[image-django-rest-swagger]: ../img/django-rest-swagger.png -[image-apiary]: ../img/apiary.png +[metadata-docs]: ../api-guide/metadata.md +[schemas-examples]: ../api-guide/schemas.md#examples + +[image-drf-yasg]: ../img/drf-yasg.png [image-self-describing-api]: ../img/self-describing.png -[schemas-examples]: ../api-guide/schemas/#examples -[metadata-docs]: ../api-guide/metadata/ -[client-library-templates]: https://github.com/encode/django-rest-framework/tree/master/rest_framework/templates/rest_framework/docs/langs + +[drf-yasg]: https://github.com/axnsan12/drf-yasg/ +[drf-spectacular]: https://github.com/tfranzel/drf-spectacular/ +[markdown]: https://daringfireball.net/projects/markdown/syntax +[open-api]: https://openapis.org/ +[redoc]: https://github.com/Rebilly/ReDoc +[swagger]: https://swagger.io/ +[swagger-ui]: https://swagger.io/tools/swagger-ui/ diff --git a/docs/topics/html-and-forms.md b/docs/topics/html-and-forms.md index 18774926b..17c9e3314 100644 --- a/docs/topics/html-and-forms.md +++ b/docs/topics/html-and-forms.md @@ -207,14 +207,14 @@ Field templates can also use additional style properties, depending on their typ The complete list of `base_template` options and their associated style options is listed below. -base_template | Valid field types | Additional style options -----|----|---- -input.html | Any string, numeric or date/time field | input_type, placeholder, hide_label, autofocus -textarea.html | `CharField` | rows, placeholder, hide_label -select.html | `ChoiceField` or relational field types | hide_label -radio.html | `ChoiceField` or relational field types | inline, hide_label -select_multiple.html | `MultipleChoiceField` or relational fields with `many=True` | hide_label +base_template | Valid field types | Additional style options +-----------------------|-------------------------------------------------------------|----------------------------------------------- +input.html | Any string, numeric or date/time field | input_type, placeholder, hide_label, autofocus +textarea.html | `CharField` | rows, placeholder, hide_label +select.html | `ChoiceField` or relational field types | hide_label +radio.html | `ChoiceField` or relational field types | inline, hide_label +select_multiple.html | `MultipleChoiceField` or relational fields with `many=True` | hide_label checkbox_multiple.html | `MultipleChoiceField` or relational fields with `many=True` | inline, hide_label -checkbox.html | `BooleanField` | hide_label -fieldset.html | Nested serializer | hide_label -list_fieldset.html | `ListField` or nested serializer with `many=True` | hide_label +checkbox.html | `BooleanField` | hide_label +fieldset.html | Nested serializer | hide_label +list_fieldset.html | `ListField` or nested serializer with `many=True` | hide_label diff --git a/docs/topics/internationalization.md b/docs/topics/internationalization.md index 7cfc6e247..267ccdb37 100644 --- a/docs/topics/internationalization.md +++ b/docs/topics/internationalization.md @@ -17,9 +17,9 @@ You can change the default language by using the standard Django `LANGUAGE_CODE` LANGUAGE_CODE = "es-es" -You can turn on per-request language requests by adding `LocalMiddleware` to your `MIDDLEWARE_CLASSES` setting: +You can turn on per-request language requests by adding `LocalMiddleware` to your `MIDDLEWARE` setting: - MIDDLEWARE_CLASSES = [ + MIDDLEWARE = [ ... 'django.middleware.locale.LocaleMiddleware' ] @@ -90,7 +90,7 @@ If you're only translating custom error messages that exist inside your project ## How the language is determined -If you want to allow per-request language preferences you'll need to include `django.middleware.locale.LocaleMiddleware` in your `MIDDLEWARE_CLASSES` setting. +If you want to allow per-request language preferences you'll need to include `django.middleware.locale.LocaleMiddleware` in your `MIDDLEWARE` setting. You can find more information on how the language preference is determined in the [Django documentation][django-language-preference]. For reference, the method is: @@ -103,10 +103,10 @@ You can find more information on how the language preference is determined in th For API clients the most appropriate of these will typically be to use the `Accept-Language` header; Sessions and cookies will not be available unless using session authentication, and generally better practice to prefer an `Accept-Language` header for API clients rather than using language URL prefixes. [cite]: https://youtu.be/Wa0VfS2q94Y -[django-translation]: https://docs.djangoproject.com/en/1.7/topics/i18n/translation +[django-translation]: https://docs.djangoproject.com/en/stable/topics/i18n/translation [custom-exception-handler]: ../api-guide/exceptions.md#custom-exception-handling [transifex-project]: https://www.transifex.com/projects/p/django-rest-framework/ [django-po-source]: https://raw.githubusercontent.com/encode/django-rest-framework/master/rest_framework/locale/en_US/LC_MESSAGES/django.po -[django-language-preference]: https://docs.djangoproject.com/en/1.7/topics/i18n/translation/#how-django-discovers-language-preference -[django-locale-paths]: https://docs.djangoproject.com/en/1.7/ref/settings/#std:setting-LOCALE_PATHS -[django-locale-name]: https://docs.djangoproject.com/en/1.7/topics/i18n/#term-locale-name +[django-language-preference]: https://docs.djangoproject.com/en/stable/topics/i18n/translation/#how-django-discovers-language-preference +[django-locale-paths]: https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-LOCALE_PATHS +[django-locale-name]: https://docs.djangoproject.com/en/stable/topics/i18n/#term-locale-name diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index d48319a26..3498bddd1 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -4,7 +4,7 @@ > > — Mike Amundsen, [REST fest 2012 keynote][cite]. -First off, the disclaimer. The name "Django REST framework" was decided back in early 2011 and was chosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". +First off, the disclaimer. The name "Django REST framework" was decided back in early 2011 and was chosen simply to ensure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". If you are serious about designing a Hypermedia API, you should look to resources outside of this documentation to help inform your design choices. @@ -34,7 +34,7 @@ REST framework also includes [serialization] and [parser]/[renderer] components What REST framework doesn't do is give you machine readable hypermedia formats such as [HAL][hal], [Collection+JSON][collection], [JSON API][json-api] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. -[cite]: https://vimeo.com/channels/restfest/page:2 +[cite]: https://vimeo.com/channels/restfest/49503453 [dissertation]: https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm [hypertext-driven]: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven [restful-web-apis]: http://restfulwebapis.org/ diff --git a/docs/topics/writable-nested-serializers.md b/docs/topics/writable-nested-serializers.md index 9ba719f4e..3bac84ffa 100644 --- a/docs/topics/writable-nested-serializers.md +++ b/docs/topics/writable-nested-serializers.md @@ -15,14 +15,14 @@ Nested data structures are easy enough to work with if they're read-only - simpl class ToDoItemSerializer(serializers.ModelSerializer): class Meta: model = ToDoItem - fields = ('text', 'is_completed') + fields = ['text', 'is_completed'] class ToDoListSerializer(serializers.ModelSerializer): items = ToDoItemSerializer(many=True, read_only=True) class Meta: model = ToDoList - fields = ('title', 'items') + fields = ['title', 'items'] Some example output from our serializer. diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index 07ee8f208..6db3ea282 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -8,24 +8,24 @@ The tutorial is fairly in-depth, so you should probably get a cookie and a cup o --- -**Note**: The code for this tutorial is available in the [tomchristie/rest-framework-tutorial][repo] repository on GitHub. The completed implementation is also online as a sandbox version for testing, [available here][sandbox]. +**Note**: The code for this tutorial is available in the [encode/rest-framework-tutorial][repo] repository on GitHub. The completed implementation is also online as a sandbox version for testing, [available here][sandbox]. --- ## Setting up a new environment -Before we do anything else we'll create a new virtual environment, using [virtualenv]. This will make sure our package configuration is kept nicely isolated from any other projects we're working on. +Before we do anything else we'll create a new virtual environment, using [venv]. This will make sure our package configuration is kept nicely isolated from any other projects we're working on. - virtualenv env + python3 -m venv env source env/bin/activate -Now that we're inside a virtualenv environment, we can install our package requirements. +Now that we're inside a virtual environment, we can install our package requirements. pip install django pip install djangorestframework pip install pygments # We'll be using this for the code highlighting -**Note:** To exit the virtualenv environment at any time, just type `deactivate`. For more information see the [virtualenv documentation][virtualenv]. +**Note:** To exit the virtual environment at any time, just type `deactivate`. For more information see the [venv documentation][venv]. ## Getting started @@ -42,11 +42,11 @@ Once that's done we can create an app that we'll use to create a simple Web API. 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 = ( + INSTALLED_APPS = [ ... 'rest_framework', - 'snippets.apps.SnippetsConfig', - ) + 'snippets', + ] Okay, we're ready to roll. @@ -60,7 +60,7 @@ For the purposes of this tutorial we're going to start by creating a simple `Sni LEXERS = [item for item in get_all_lexers() if item[1]] LANGUAGE_CHOICES = sorted([(item[1][0], item[0]) for item in LEXERS]) - STYLE_CHOICES = sorted((item, item) for item in get_all_styles()) + STYLE_CHOICES = sorted([(item, item) for item in get_all_styles()]) class Snippet(models.Model): @@ -72,12 +72,12 @@ For the purposes of this tutorial we're going to start by creating a simple `Sni style = models.CharField(choices=STYLE_CHOICES, default='friendly', max_length=100) class Meta: - ordering = ('created',) + ordering = ['created'] We'll also need to create an initial migration for our snippet model, and sync the database for the first time. python manage.py makemigrations snippets - python manage.py migrate + python manage.py migrate snippets ## Creating a Serializer class @@ -179,7 +179,7 @@ We can also serialize querysets instead of model instances. To do so we simply ## Using ModelSerializers -Our `SnippetSerializer` class is replicating a lot of information that's also contained in the `Snippet` model. It would be nice if we could keep our code a bit more concise. +Our `SnippetSerializer` class is replicating a lot of information that's also contained in the `Snippet` model. It would be nice if we could keep our code a bit more concise. In the same way that Django provides both `Form` classes and `ModelForm` classes, REST framework includes both `Serializer` classes, and `ModelSerializer` classes. @@ -189,7 +189,7 @@ Open the file `snippets/serializers.py` again, and replace the `SnippetSerialize class SnippetSerializer(serializers.ModelSerializer): class Meta: model = Snippet - fields = ('id', 'title', 'code', 'linenos', 'language', 'style') + 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 its representation. Open the Django shell with `python manage.py shell`, then try the following: @@ -218,7 +218,6 @@ Edit the `snippets/views.py` file, and add the following. from django.http import HttpResponse, JsonResponse from django.views.decorators.csrf import csrf_exempt - from rest_framework.renderers import JSONRenderer from rest_framework.parsers import JSONParser from snippets.models import Snippet from snippets.serializers import SnippetSerializer @@ -308,8 +307,8 @@ Quit out of the shell... Validating models... 0 errors found - Django version 1.11, using settings 'tutorial.settings' - Development server is running at http://127.0.0.1:8000/ + Django version 4.0, using settings 'tutorial.settings' + Starting Development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C. In another terminal window, we can test the server. @@ -373,7 +372,7 @@ We'll see how we can start to improve things in [part 2 of the tutorial][tut-2]. [quickstart]: quickstart.md [repo]: https://github.com/encode/rest-framework-tutorial [sandbox]: https://restframework.herokuapp.com/ -[virtualenv]: http://www.virtualenv.org/en/latest/index.html +[venv]: https://docs.python.org/3/library/venv.html [tut-2]: 2-requests-and-responses.md -[httpie]: https://github.com/jakubroztocil/httpie#installation +[httpie]: https://github.com/httpie/httpie#installation [curl]: https://curl.haxx.se/ diff --git a/docs/tutorial/2-requests-and-responses.md b/docs/tutorial/2-requests-and-responses.md index e3d21e864..47c7facfc 100644 --- a/docs/tutorial/2-requests-and-responses.md +++ b/docs/tutorial/2-requests-and-responses.md @@ -29,13 +29,11 @@ REST framework provides two wrappers you can use to write API views. These wrappers provide a few bits of functionality such as making sure you receive `Request` instances in your view, and adding context to `Response` objects so that content negotiation can be performed. -The wrappers also provide behaviour such as returning `405 Method Not Allowed` responses when appropriate, and handling any `ParseError` exception that occurs when accessing `request.data` with malformed input. +The wrappers also provide behavior such as returning `405 Method Not Allowed` responses when appropriate, and handling any `ParseError` exceptions that occur when accessing `request.data` with malformed input. ## Pulling it all together -Okay, let's go ahead and start using these new components to write a few views. - -We don't need our `JSONResponse` class in `views.py` any more, so go ahead and delete that. Once that's done we can start refactoring our views slightly. +Okay, let's go ahead and start using these new components to refactor our views slightly. from rest_framework import status from rest_framework.decorators import api_view @@ -114,7 +112,7 @@ Now update the `snippets/urls.py` file slightly, to append a set of `format_suff urlpatterns = [ path('snippets/', views.snippet_list), - path('snippets/', views.snippet_detail), + path('snippets//', views.snippet_detail), ] urlpatterns = format_suffix_patterns(urlpatterns) diff --git a/docs/tutorial/3-class-based-views.md b/docs/tutorial/3-class-based-views.md index e02feaa5e..ccfcd095d 100644 --- a/docs/tutorial/3-class-based-views.md +++ b/docs/tutorial/3-class-based-views.md @@ -79,9 +79,9 @@ Okay, we're done. If you run the development server everything should be workin ## Using mixins -One of the big wins of using class-based views is that it allows us to easily compose reusable bits of behaviour. +One of the big wins of using class-based views is that it allows us to easily compose reusable bits of behavior. -The create/retrieve/update/delete operations that we've been using so far are going to be pretty similar for any model-backed API views we create. Those bits of common behaviour are implemented in REST framework's mixin classes. +The create/retrieve/update/delete operations that we've been using so far are going to be pretty similar for any model-backed API views we create. Those bits of common behavior are implemented in REST framework's mixin classes. Let's take a look at how we can compose the views by using the mixin classes. Here's our `views.py` module again. diff --git a/docs/tutorial/4-authentication-and-permissions.md b/docs/tutorial/4-authentication-and-permissions.md index d616b6539..cb0321ea2 100644 --- a/docs/tutorial/4-authentication-and-permissions.md +++ b/docs/tutorial/4-authentication-and-permissions.md @@ -38,7 +38,7 @@ And now we can add a `.save()` method to our model class: formatter = HtmlFormatter(style=self.style, linenos=linenos, full=True, **options) self.highlighted = highlight(self.code, lexer, formatter) - super(Snippet, self).save(*args, **kwargs) + super().save(*args, **kwargs) When that's all done we'll need to update our database tables. Normally we'd create a database migration in order to do that, but for the purposes of this tutorial, let's just delete the database and start again. @@ -63,7 +63,7 @@ Now that we've got some users to work with, we'd better add representations of t class Meta: model = User - fields = ('id', 'username', 'snippets') + fields = ['id', 'username', 'snippets'] Because `'snippets'` is a *reverse* relationship on the User model, it will not be included by default when using the `ModelSerializer` class, so we needed to add an explicit field for it. @@ -127,7 +127,7 @@ First add the following import in the views module Then, add the following property to **both** the `SnippetList` and `SnippetDetail` view classes. - permission_classes = (permissions.IsAuthenticatedOrReadOnly,) + permission_classes = [permissions.IsAuthenticatedOrReadOnly] ## Adding login to the Browsable API @@ -137,7 +137,7 @@ We can add a login view for use with the browsable API, by editing the URLconf i Add the following import at the top of the file: - from django.conf.urls import include + from django.urls import path, include And, at the end of the file, add a pattern to include the login and logout views for the browsable API. @@ -178,8 +178,8 @@ In the snippets app, create a new file, `permissions.py` Now we can add that custom permission to our snippet instance endpoint, by editing the `permission_classes` property on the `SnippetDetail` view class: - permission_classes = (permissions.IsAuthenticatedOrReadOnly, - IsOwnerOrReadOnly,) + permission_classes = [permissions.IsAuthenticatedOrReadOnly, + IsOwnerOrReadOnly] Make sure to also import the `IsOwnerOrReadOnly` class. diff --git a/docs/tutorial/5-relationships-and-hyperlinked-apis.md b/docs/tutorial/5-relationships-and-hyperlinked-apis.md index 0177afce1..f999fdf50 100644 --- a/docs/tutorial/5-relationships-and-hyperlinked-apis.md +++ b/docs/tutorial/5-relationships-and-hyperlinked-apis.md @@ -31,11 +31,10 @@ The other thing we need to consider when creating the code highlight view is tha Instead of using a concrete generic view, we'll use the base class for representing instances, and create our own `.get()` method. In your `snippets/views.py` add: from rest_framework import renderers - from rest_framework.response import Response class SnippetHighlight(generics.GenericAPIView): queryset = Snippet.objects.all() - renderer_classes = (renderers.StaticHTMLRenderer,) + renderer_classes = [renderers.StaticHTMLRenderer] def get(self, request, *args, **kwargs): snippet = self.get_object() @@ -80,8 +79,8 @@ We can easily re-write our existing serializers to use hyperlinking. In your `sn class Meta: model = Snippet - fields = ('url', 'id', 'highlight', 'owner', - 'title', 'code', 'linenos', 'language', 'style') + fields = ['url', 'id', 'highlight', 'owner', + 'title', 'code', 'linenos', 'language', 'style'] class UserSerializer(serializers.HyperlinkedModelSerializer): @@ -89,7 +88,7 @@ We can easily re-write our existing serializers to use hyperlinking. In your `sn class Meta: model = User - fields = ('url', 'id', 'username', 'snippets') + fields = ['url', 'id', 'username', 'snippets'] Notice that we've also added a new `'highlight'` field. This field is of the same type as the `url` field, except that it points to the `'snippet-highlight'` url pattern, instead of the `'snippet-detail'` url pattern. @@ -143,7 +142,7 @@ We can change the default list style to use pagination, by modifying our `tutori Note that settings in REST framework are all namespaced into a single dictionary setting, named `REST_FRAMEWORK`, which helps keep them well separated from your other project settings. -We could also customize the pagination style if we needed too, but in this case we'll just stick with the default. +We could also customize the pagination style if we needed to, but in this case we'll just stick with the default. ## Browsing the API diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md index 1d4058813..b7a7696a7 100644 --- a/docs/tutorial/6-viewsets-and-routers.md +++ b/docs/tutorial/6-viewsets-and-routers.md @@ -2,7 +2,7 @@ REST framework includes an abstraction for dealing with `ViewSets`, that allows the developer to concentrate on modeling the state and interactions of the API, and leave the URL construction to be handled automatically, based on common conventions. -`ViewSet` classes are almost the same thing as `View` classes, except that they provide operations such as `read`, or `update`, and not method handlers such as `get` or `put`. +`ViewSet` classes are almost the same thing as `View` classes, except that they provide operations such as `retrieve`, or `update`, and not method handlers such as `get` or `put`. A `ViewSet` class is only bound to a set of method handlers at the last moment, when it is instantiated into a set of views, typically by using a `Router` class which handles the complexities of defining the URL conf for you. @@ -16,7 +16,7 @@ First of all let's refactor our `UserList` and `UserDetail` views into a single class UserViewSet(viewsets.ReadOnlyModelViewSet): """ - This viewset automatically provides `list` and `detail` actions. + This viewset automatically provides `list` and `retrieve` actions. """ queryset = User.objects.all() serializer_class = UserSerializer @@ -27,6 +27,7 @@ Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighl from rest_framework.decorators import action from rest_framework.response import Response + from rest_framework import permissions class SnippetViewSet(viewsets.ModelViewSet): """ @@ -37,8 +38,8 @@ Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighl """ queryset = Snippet.objects.all() serializer_class = SnippetSerializer - permission_classes = (permissions.IsAuthenticatedOrReadOnly, - IsOwnerOrReadOnly,) + permission_classes = [permissions.IsAuthenticatedOrReadOnly, + IsOwnerOrReadOnly] @action(detail=True, renderer_classes=[renderers.StaticHTMLRenderer]) def highlight(self, request, *args, **kwargs): @@ -111,8 +112,8 @@ Here's our re-wired `snippets/urls.py` file. # Create a router and register our viewsets with it. router = DefaultRouter() - router.register(r'snippets', views.SnippetViewSet) - router.register(r'users', views.UserViewSet) + router.register(r'snippets', views.SnippetViewSet, basename='snippet') + router.register(r'users', views.UserViewSet, basename='user') # The API URLs are now determined automatically by the router. urlpatterns = [ @@ -128,8 +129,3 @@ The `DefaultRouter` class we're using also automatically creates the API root vi Using viewsets can be a really useful abstraction. It helps ensure that URL conventions will be consistent across your API, minimizes the amount of code you need to write, and allows you to concentrate on the interactions and representations your API provides rather than the specifics of the URL conf. That doesn't mean it's always the right approach to take. There's a similar set of trade-offs to consider as when using class-based views instead of function based views. Using viewsets is less explicit than building your views individually. - -In [part 7][tut-7] of the tutorial we'll look at how we can add an API schema, -and interact with our API using a client library or command line tool. - -[tut-7]: 7-schemas-and-client-libraries.md diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index cbec2501b..754b46f9a 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -10,11 +10,11 @@ Create a new Django project named `tutorial`, then start a new app called `quick mkdir tutorial cd tutorial - # Create a virtualenv to isolate our package dependencies locally - virtualenv env + # Create a virtual environment to isolate our package dependencies locally + python3 -m venv env source env/bin/activate # On Windows use `env\Scripts\activate` - # Install Django and Django REST framework into the virtualenv + # Install Django and Django REST framework into the virtual environment pip install django pip install djangorestframework @@ -30,21 +30,24 @@ The project layout should look like: /tutorial $ find . . - ./manage.py ./tutorial + ./tutorial/asgi.py ./tutorial/__init__.py ./tutorial/quickstart - ./tutorial/quickstart/__init__.py - ./tutorial/quickstart/admin.py - ./tutorial/quickstart/apps.py ./tutorial/quickstart/migrations ./tutorial/quickstart/migrations/__init__.py ./tutorial/quickstart/models.py + ./tutorial/quickstart/__init__.py + ./tutorial/quickstart/apps.py + ./tutorial/quickstart/admin.py ./tutorial/quickstart/tests.py ./tutorial/quickstart/views.py ./tutorial/settings.py ./tutorial/urls.py ./tutorial/wsgi.py + ./env + ./env/... + ./manage.py It may look unusual that the application has been created within the project directory. Using the project's namespace avoids name clashes with external modules (a topic that goes outside the scope of the quickstart). @@ -52,9 +55,9 @@ Now sync your database for the first time: python manage.py migrate -We'll also create an initial user named `admin` with a password of `password123`. We'll authenticate as that user later in our example. +We'll also create an initial user named `admin` with a password. We'll authenticate as that user later in our example. - python manage.py createsuperuser --email admin@example.com --username admin + python manage.py createsuperuser --username admin --email admin@example.com Once you've set up a database and the initial user is created and ready to go, open up the app's directory and we'll get coding... @@ -62,20 +65,20 @@ Once you've set up a database and the initial user is created and ready to go, o First up we're going to define some serializers. Let's create a new module named `tutorial/quickstart/serializers.py` that we'll use for our data representations. - from django.contrib.auth.models import User, Group + from django.contrib.auth.models import Group, User from rest_framework import serializers class UserSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = User - fields = ('url', 'username', 'email', 'groups') + fields = ['url', 'username', 'email', 'groups'] class GroupSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = Group - fields = ('url', 'name') + fields = ['url', 'name'] Notice that we're using hyperlinked relations in this case with `HyperlinkedModelSerializer`. You can also use primary key and various other relationships, but hyperlinking is good RESTful design. @@ -83,9 +86,10 @@ Notice that we're using hyperlinked relations in this case with `HyperlinkedMode Right, we'd better write some views then. Open `tutorial/quickstart/views.py` and get typing. - from django.contrib.auth.models import User, Group - from rest_framework import viewsets - from tutorial.quickstart.serializers import UserSerializer, GroupSerializer + from django.contrib.auth.models import Group, User + from rest_framework import permissions, viewsets + + from tutorial.quickstart.serializers import GroupSerializer, UserSerializer class UserViewSet(viewsets.ModelViewSet): @@ -94,6 +98,7 @@ Right, we'd better write some views then. Open `tutorial/quickstart/views.py` a """ queryset = User.objects.all().order_by('-date_joined') serializer_class = UserSerializer + permission_classes = [permissions.IsAuthenticated] class GroupViewSet(viewsets.ModelViewSet): @@ -102,6 +107,7 @@ Right, we'd better write some views then. Open `tutorial/quickstart/views.py` a """ queryset = Group.objects.all() serializer_class = GroupSerializer + permission_classes = [permissions.IsAuthenticated] Rather than write multiple views we're grouping together all the common behavior into classes called `ViewSets`. @@ -113,6 +119,7 @@ Okay, now let's wire up the API URLs. On to `tutorial/urls.py`... from django.urls import include, path from rest_framework import routers + from tutorial.quickstart import views router = routers.DefaultRouter() @@ -134,20 +141,20 @@ Finally, we're including default login and logout views for use with the browsab ## Pagination Pagination allows you to control how many objects per page are returned. To enable it add the following lines to `tutorial/settings.py` - + REST_FRAMEWORK = { 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination', 'PAGE_SIZE': 10 } - + ## Settings Add `'rest_framework'` to `INSTALLED_APPS`. The settings module will be in `tutorial/settings.py` - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'rest_framework', - ) + ] Okay, we're done. @@ -161,9 +168,30 @@ We're now ready to test the API we've built. Let's fire up the server from the We can now access our API, both from the command-line, using tools like `curl`... - bash: curl -H 'Accept: application/json; indent=4' -u admin:password123 http://127.0.0.1:8000/users/ + bash: curl -u admin -H 'Accept: application/json; indent=4' http://127.0.0.1:8000/users/ + Enter host password for user 'admin': { - "count": 2, + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "url": "http://127.0.0.1:8000/users/1/", + "username": "admin", + "email": "admin@example.com", + "groups": [] + } + ] + } + +Or using the [httpie][httpie], command line tool... + + bash: http -a admin http://127.0.0.1:8000/users/ + http: password for admin@127.0.0.1:8000:: + $HTTP/1.1 200 OK + ... + { + "count": 1, "next": null, "previous": null, "results": [ @@ -172,38 +200,6 @@ We can now access our API, both from the command-line, using tools like `curl`.. "groups": [], "url": "http://127.0.0.1:8000/users/1/", "username": "admin" - }, - { - "email": "tom@example.com", - "groups": [ ], - "url": "http://127.0.0.1:8000/users/2/", - "username": "tom" - } - ] - } - -Or using the [httpie][httpie], command line tool... - - bash: http -a admin:password123 http://127.0.0.1:8000/users/ - - HTTP/1.1 200 OK - ... - { - "count": 2, - "next": null, - "previous": null, - "results": [ - { - "email": "admin@example.com", - "groups": [], - "url": "http://localhost:8000/users/1/", - "username": "paul" - }, - { - "email": "tom@example.com", - "groups": [ ], - "url": "http://127.0.0.1:8000/users/2/", - "username": "tom" } ] } @@ -221,5 +217,5 @@ If you want to get a more in depth understanding of how REST framework fits toge [image]: ../img/quickstart.png [tutorial]: 1-serialization.md -[guide]: ../#api-guide -[httpie]: https://github.com/jakubroztocil/httpie#installation +[guide]: ../api-guide/requests.md +[httpie]: https://httpie.io/docs#installation diff --git a/docs_theme/404.html b/docs_theme/404.html index a89c0a418..bbb6b70ff 100644 --- a/docs_theme/404.html +++ b/docs_theme/404.html @@ -4,6 +4,6 @@

404

Page not found

-

Try the homepage, or search the documentation.

+

Try the homepage, or search the documentation.

{% endblock %} diff --git a/docs_theme/css/default.css b/docs_theme/css/default.css index bb17a3a11..7006f2a66 100644 --- a/docs_theme/css/default.css +++ b/docs_theme/css/default.css @@ -6,7 +6,7 @@ pre { .dropdown .dropdown-menu { display: none; - overflow-y: scroll; + overflow-y: auto; } .dropdown.open .dropdown-menu { @@ -37,7 +37,7 @@ body.index-page #main-content iframe.github-star-button { margin-right: -15px; } -/* Travis CI and PyPI badge */ +/* CI and PyPI badge */ body.index-page #main-content img.status-badge { float: right; margin-right: 8px; @@ -74,6 +74,12 @@ pre { white-space: pre; } +code, pre { + font-family: Consolas,Menlo,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New,monospace,sans-serif; + font-size: 13px; +} + + /* Preserve the spacing of the navbar across different screen sizes. */ .navbar-inner { /*padding: 5px 0;*/ @@ -432,3 +438,4 @@ ul.sponsor { margin: 0 !important; display: inline-block !important; } + diff --git a/docs_theme/js/theme.js b/docs_theme/js/theme.js index ddbd9c905..0918ae85d 100644 --- a/docs_theme/js/theme.js +++ b/docs_theme/js/theme.js @@ -9,11 +9,6 @@ var getSearchTerm = function() { } }; -var initilizeSearch = function() { - require.config({ baseUrl: '/mkdocs/js' }); - require(['search']); -}; - $(function() { var searchTerm = getSearchTerm(), $searchModal = $('#mkdocs_search_modal'), @@ -30,6 +25,5 @@ $(function() { $searchModal.on('shown', function() { $searchQuery.focus(); - initilizeSearch(); }); }); diff --git a/docs_theme/main.html b/docs_theme/main.html index b60b231c2..b4e894781 100644 --- a/docs_theme/main.html +++ b/docs_theme/main.html @@ -5,22 +5,18 @@ {% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }} - - + + - - - - + + + + - - - - - + + + + + + - - + {% for path in config.extra_javascript %} + + {% endfor %} - + diff --git a/rest_framework/templates/rest_framework/base.html b/rest_framework/templates/rest_framework/base.html index 6d740f2b5..a88e1591c 100644 --- a/rest_framework/templates/rest_framework/base.html +++ b/rest_framework/templates/rest_framework/base.html @@ -77,7 +77,7 @@
{% block request_forms %} - + {% if 'GET' in allowed_methods %}
@@ -176,9 +176,9 @@ 
HTTP {{ response.status_code }} {{ response.status_text }}{% for key, val in response_headers|items %}
-{{ key }}: {{ val|break_long_headers|urlize_quoted_links }}{% endfor %}
+{{ key }}: {{ val|break_long_headers|urlize }}{% endfor %}
 
-{{ content|urlize_quoted_links }}
+{{ content|urlize }}
@@ -293,7 +293,7 @@ csrfToken: "{% if request %}{{ csrf_token }}{% endif %}" }; - + diff --git a/rest_framework/templates/rest_framework/docs/auth/session.html b/rest_framework/templates/rest_framework/docs/auth/session.html index d09d3f2aa..59430d95e 100644 --- a/rest_framework/templates/rest_framework/docs/auth/session.html +++ b/rest_framework/templates/rest_framework/docs/auth/session.html @@ -12,7 +12,7 @@
{% if user.is_authenticated %} -

You are logged in as {{ user.username }}.

+

You are logged in as {{ user.get_username }}.

{% else %}
diff --git a/rest_framework/templates/rest_framework/docs/error.html b/rest_framework/templates/rest_framework/docs/error.html index ecdb67830..694f88a15 100644 --- a/rest_framework/templates/rest_framework/docs/error.html +++ b/rest_framework/templates/rest_framework/docs/error.html @@ -48,7 +48,7 @@ being applied unexpectedly?

when including the docs urls:

-   url(r'^docs/', include_docs_urls(title='Your API',
+   path('docs/', include_docs_urls(title='Your API',
                                     authentication_classes=[],
                                     permission_classes=[])),
@@ -66,6 +66,6 @@ at rest_framework/docs/error.html.

- + diff --git a/rest_framework/templates/rest_framework/docs/index.html b/rest_framework/templates/rest_framework/docs/index.html index f73a2a993..dfd363772 100644 --- a/rest_framework/templates/rest_framework/docs/index.html +++ b/rest_framework/templates/rest_framework/docs/index.html @@ -38,7 +38,7 @@ {% include "rest_framework/docs/auth/basic.html" %} {% include "rest_framework/docs/auth/session.html" %} - + diff --git a/rest_framework/templates/rest_framework/filters/search.html b/rest_framework/templates/rest_framework/filters/search.html index edb28d45d..065c3889a 100644 --- a/rest_framework/templates/rest_framework/filters/search.html +++ b/rest_framework/templates/rest_framework/filters/search.html @@ -5,7 +5,7 @@
- +
diff --git a/rest_framework/templatetags/rest_framework.py b/rest_framework/templatetags/rest_framework.py index f48675d5e..ccd9430b4 100644 --- a/rest_framework/templatetags/rest_framework.py +++ b/rest_framework/templatetags/rest_framework.py @@ -1,15 +1,12 @@ -from __future__ import absolute_import, unicode_literals - import re from collections import OrderedDict from django import template from django.template import loader from django.urls import NoReverseMatch, reverse -from django.utils import six -from django.utils.encoding import force_text, iri_to_uri +from django.utils.encoding import iri_to_uri from django.utils.html import escape, format_html, smart_urlquote -from django.utils.safestring import SafeData, mark_safe +from django.utils.safestring import mark_safe from rest_framework.compat import apply_markdown, pygments_highlight from rest_framework.renderers import HTMLFormRenderer @@ -187,7 +184,7 @@ def add_class(value, css_class): In the case of REST Framework, the filter is used to add Bootstrap-specific classes to the forms. """ - html = six.text_type(value) + html = str(value) match = class_re.search(html) if match: m = re.search(r'^%s$|^%s\s|\s%s\s|\s%s$' % (css_class, css_class, @@ -204,12 +201,12 @@ def add_class(value, css_class): @register.filter def format_value(value): if getattr(value, 'is_hyperlink', False): - name = six.text_type(value.obj) + name = str(value.obj) return mark_safe('%s' % (value, escape(name))) if value is None or isinstance(value, bool): return mark_safe('%s' % {True: 'true', False: 'false', None: 'null'}[value]) elif isinstance(value, list): - if any([isinstance(item, (list, dict)) for item in value]): + if any(isinstance(item, (list, dict)) for item in value): template = loader.get_template('rest_framework/admin/list_value.html') else: template = loader.get_template('rest_framework/admin/simple_list_value.html') @@ -219,9 +216,9 @@ def format_value(value): template = loader.get_template('rest_framework/admin/dict_value.html') context = {'value': value} return template.render(context) - elif isinstance(value, six.string_types): + elif isinstance(value, str): if ( - (value.startswith('http:') or value.startswith('https:')) and not + (value.startswith('http:') or value.startswith('https:') or value.startswith('/')) and not re.search(r'\s', value) ): return mark_safe('{value}'.format(value=escape(value))) @@ -229,14 +226,14 @@ def format_value(value): return mark_safe('{value}'.format(value=escape(value))) elif '\n' in value: return mark_safe('
%s
' % escape(value)) - return six.text_type(value) + return str(value) @register.filter def items(value): """ Simple filter to return the items of the dict. Useful when the dict may - have a key 'items' which is resolved first in Django tempalte dot-notation + have a key 'items' which is resolved first in Django template dot-notation lookup. See issue #4931 Also see: https://stackoverflow.com/questions/15416662/django-template-loop-over-dictionary-items-with-items-as-key """ @@ -288,7 +285,7 @@ def schema_links(section, sec_key=None): def add_nested_class(value): if isinstance(value, dict): return 'class=nested' - if isinstance(value, list) and any([isinstance(item, (list, dict)) for item in value]): + if isinstance(value, list) and any(isinstance(item, (list, dict)) for item in value): return 'class=nested' return '' @@ -314,85 +311,6 @@ def smart_urlquote_wrapper(matched_url): return None -@register.filter(needs_autoescape=True) -def urlize_quoted_links(text, trim_url_limit=None, nofollow=True, autoescape=True): - """ - Converts any URLs in text into clickable links. - - Works on http://, https://, www. links, and also on links ending in one of - the original seven gTLDs (.com, .edu, .gov, .int, .mil, .net, and .org). - Links can have trailing punctuation (periods, commas, close-parens) and - leading punctuation (opening parens) and it'll still do the right thing. - - If trim_url_limit is not None, the URLs in link text longer than this limit - will truncated to trim_url_limit-3 characters and appended with an ellipsis. - - If nofollow is True, the URLs in link text will get a rel="nofollow" - attribute. - - If autoescape is True, the link text and URLs will get autoescaped. - """ - def trim_url(x, limit=trim_url_limit): - return limit is not None and (len(x) > limit and ('%s...' % x[:max(0, limit - 3)])) or x - - safe_input = isinstance(text, SafeData) - - # Unfortunately, Django built-in cannot be used here, because escaping - # is to be performed on words, which have been forcibly coerced to text - def conditional_escape(text): - return escape(text) if autoescape and not safe_input else text - - words = word_split_re.split(force_text(text)) - for i, word in enumerate(words): - if '.' in word or '@' in word or ':' in word: - # Deal with punctuation. - lead, middle, trail = '', word, '' - for punctuation in TRAILING_PUNCTUATION: - if middle.endswith(punctuation): - middle = middle[:-len(punctuation)] - trail = punctuation + trail - for opening, closing in WRAPPING_PUNCTUATION: - if middle.startswith(opening): - middle = middle[len(opening):] - lead = lead + opening - # Keep parentheses at the end only if they're balanced. - if ( - middle.endswith(closing) and - middle.count(closing) == middle.count(opening) + 1 - ): - middle = middle[:-len(closing)] - trail = closing + trail - - # Make URL we want to point to. - url = None - nofollow_attr = ' rel="nofollow"' if nofollow else '' - if simple_url_re.match(middle): - url = smart_urlquote_wrapper(middle) - elif simple_url_2_re.match(middle): - url = smart_urlquote_wrapper('http://%s' % middle) - elif ':' not in middle and simple_email_re.match(middle): - local, domain = middle.rsplit('@', 1) - try: - domain = domain.encode('idna').decode('ascii') - except UnicodeError: - continue - url = 'mailto:%s@%s' % (local, domain) - nofollow_attr = '' - - # Make link. - if url: - trimmed = trim_url(middle) - lead, trail = conditional_escape(lead), conditional_escape(trail) - url, trimmed = conditional_escape(url), conditional_escape(trimmed) - middle = '%s' % (url, nofollow_attr, trimmed) - words[i] = '%s%s%s' % (lead, middle, trail) - else: - words[i] = conditional_escape(word) - else: - words[i] = conditional_escape(word) - return mark_safe(''.join(words)) - - @register.filter def break_long_headers(header): """ diff --git a/rest_framework/test.py b/rest_framework/test.py index edacf0066..04409f962 100644 --- a/rest_framework/test.py +++ b/rest_framework/test.py @@ -1,12 +1,9 @@ -# -- coding: utf-8 -- - # Note that we import as `DjangoRequestFactory` and `DjangoClient` in order # to make it harder for the user to import the wrong thing without realizing. -from __future__ import unicode_literals - import io from importlib import import_module +import django from django.conf import settings from django.core.exceptions import ImproperlyConfigured from django.core.handlers.wsgi import WSGIHandler @@ -14,7 +11,6 @@ from django.test import override_settings, testcases from django.test.client import Client as DjangoClient from django.test.client import ClientHandler from django.test.client import RequestFactory as DjangoRequestFactory -from django.utils import six from django.utils.encoding import force_bytes from django.utils.http import urlencode @@ -32,7 +28,7 @@ if requests is not None: def get_all(self, key, default): return self.getheaders(key) - class MockOriginalResponse(object): + class MockOriginalResponse: def __init__(self, headers): self.msg = HeaderDict(headers) self.closed = False @@ -84,7 +80,7 @@ if requests is not None: """ raw_kwargs = {} - def start_response(wsgi_status, wsgi_headers): + def start_response(wsgi_status, wsgi_headers, exc_info=None): status, _, reason = wsgi_status.partition(' ') raw_kwargs['status'] = int(status) raw_kwargs['reason'] = reason @@ -109,7 +105,7 @@ if requests is not None: class RequestsClient(requests.Session): def __init__(self, *args, **kwargs): - super(RequestsClient, self).__init__(*args, **kwargs) + super().__init__(*args, **kwargs) adapter = DjangoTestAdapter() self.mount('http://', adapter) self.mount('https://', adapter) @@ -117,7 +113,7 @@ if requests is not None: def request(self, method, url, *args, **kwargs): if not url.startswith('http'): raise ValueError('Missing "http:" or "https:". Use a fully qualified URL, eg "http://testserver%s"' % url) - return super(RequestsClient, self).request(method, url, *args, **kwargs) + return super().request(method, url, *args, **kwargs) else: def RequestsClient(*args, **kwargs): @@ -129,7 +125,7 @@ if coreapi is not None: def __init__(self, *args, **kwargs): self._session = RequestsClient() kwargs['transports'] = [coreapi.transports.HTTPTransport(session=self.session)] - return super(CoreAPIClient, self).__init__(*args, **kwargs) + super().__init__(*args, **kwargs) @property def session(self): @@ -149,7 +145,7 @@ class APIRequestFactory(DjangoRequestFactory): self.renderer_classes = {} for cls in self.renderer_classes_list: self.renderer_classes[cls.format] = cls - super(APIRequestFactory, self).__init__(**defaults) + super().__init__(**defaults) def _encode_data(self, data, format=None, content_type=None): """ @@ -171,7 +167,7 @@ class APIRequestFactory(DjangoRequestFactory): format = format or self.default_format assert format in self.renderer_classes, ( - "Invalid format '{0}'. Available formats are {1}. " + "Invalid format '{}'. Available formats are {}. " "Set TEST_REQUEST_RENDERER_CLASSES to enable " "extra request formats.".format( format, @@ -184,13 +180,15 @@ class APIRequestFactory(DjangoRequestFactory): ret = renderer.render(data) # Determine the content-type header from the renderer - content_type = "{0}; charset={1}".format( - renderer.media_type, renderer.charset - ) + content_type = renderer.media_type + if renderer.charset: + content_type = "{}; charset={}".format( + content_type, renderer.charset + ) # Coerce text to bytes if required. - if isinstance(ret, six.text_type): - ret = bytes(ret.encode(renderer.charset)) + if isinstance(ret, str): + ret = ret.encode(renderer.charset) return ret, content_type @@ -202,8 +200,7 @@ class APIRequestFactory(DjangoRequestFactory): # Fix to support old behavior where you have the arguments in the # url. See #1461. query_string = force_bytes(path.split('?')[1]) - if six.PY3: - query_string = query_string.decode('iso-8859-1') + query_string = query_string.decode('iso-8859-1') r['QUERY_STRING'] = query_string r.update(extra) return self.generic('GET', path, **r) @@ -234,11 +231,11 @@ class APIRequestFactory(DjangoRequestFactory): if content_type is not None: extra['CONTENT_TYPE'] = str(content_type) - return super(APIRequestFactory, self).generic( + return super().generic( method, path, data, content_type, secure, **extra) def request(self, **kwargs): - request = super(APIRequestFactory, self).request(**kwargs) + request = super().request(**kwargs) request._dont_enforce_csrf_checks = not self.enforce_csrf_checks return request @@ -252,18 +249,18 @@ class ForceAuthClientHandler(ClientHandler): def __init__(self, *args, **kwargs): self._force_user = None self._force_token = None - super(ForceAuthClientHandler, self).__init__(*args, **kwargs) + super().__init__(*args, **kwargs) def get_response(self, request): # This is the simplest place we can hook into to patch the # request object. force_authenticate(request, self._force_user, self._force_token) - return super(ForceAuthClientHandler, self).get_response(request) + return super().get_response(request) class APIClient(APIRequestFactory, DjangoClient): def __init__(self, enforce_csrf_checks=False, **defaults): - super(APIClient, self).__init__(**defaults) + super().__init__(**defaults) self.handler = ForceAuthClientHandler(enforce_csrf_checks) self._credentials = {} @@ -280,58 +277,58 @@ class APIClient(APIRequestFactory, DjangoClient): """ self.handler._force_user = user self.handler._force_token = token - if user is None: + if user is None and token is None: self.logout() # Also clear any possible session info if required def request(self, **kwargs): # Ensure that any credentials set get added to every request. kwargs.update(self._credentials) - return super(APIClient, self).request(**kwargs) + return super().request(**kwargs) def get(self, path, data=None, follow=False, **extra): - response = super(APIClient, self).get(path, data=data, **extra) + response = super().get(path, data=data, **extra) if follow: - response = self._handle_redirects(response, **extra) + response = self._handle_redirects(response, data=data, **extra) return response def post(self, path, data=None, format=None, content_type=None, follow=False, **extra): - response = super(APIClient, self).post( + response = super().post( path, data=data, format=format, content_type=content_type, **extra) if follow: - response = self._handle_redirects(response, **extra) + response = self._handle_redirects(response, data=data, format=format, content_type=content_type, **extra) return response def put(self, path, data=None, format=None, content_type=None, follow=False, **extra): - response = super(APIClient, self).put( + response = super().put( path, data=data, format=format, content_type=content_type, **extra) if follow: - response = self._handle_redirects(response, **extra) + response = self._handle_redirects(response, data=data, format=format, content_type=content_type, **extra) return response def patch(self, path, data=None, format=None, content_type=None, follow=False, **extra): - response = super(APIClient, self).patch( + response = super().patch( path, data=data, format=format, content_type=content_type, **extra) if follow: - response = self._handle_redirects(response, **extra) + response = self._handle_redirects(response, data=data, format=format, content_type=content_type, **extra) return response def delete(self, path, data=None, format=None, content_type=None, follow=False, **extra): - response = super(APIClient, self).delete( + response = super().delete( path, data=data, format=format, content_type=content_type, **extra) if follow: - response = self._handle_redirects(response, **extra) + response = self._handle_redirects(response, data=data, format=format, content_type=content_type, **extra) return response def options(self, path, data=None, format=None, content_type=None, follow=False, **extra): - response = super(APIClient, self).options( + response = super().options( path, data=data, format=format, content_type=content_type, **extra) if follow: - response = self._handle_redirects(response, **extra) + response = self._handle_redirects(response, data=data, format=format, content_type=content_type, **extra) return response def logout(self): @@ -342,7 +339,7 @@ class APIClient(APIRequestFactory, DjangoClient): self.handler._force_token = None if self.session: - super(APIClient, self).logout() + super().logout() class APITransactionTestCase(testcases.TransactionTestCase): @@ -361,6 +358,13 @@ class APILiveServerTestCase(testcases.LiveServerTestCase): client_class = APIClient +def cleanup_url_patterns(cls): + if hasattr(cls, '_module_urlpatterns'): + cls._module.urlpatterns = cls._module_urlpatterns + else: + del cls._module.urlpatterns + + class URLPatternsTestCase(testcases.SimpleTestCase): """ Isolate URL patterns on a per-TestCase basis. For example, @@ -389,14 +393,20 @@ class URLPatternsTestCase(testcases.SimpleTestCase): cls._module.urlpatterns = cls.urlpatterns cls._override.enable() - super(URLPatternsTestCase, cls).setUpClass() - @classmethod - def tearDownClass(cls): - super(URLPatternsTestCase, cls).tearDownClass() - cls._override.disable() + if django.VERSION > (4, 0): + cls.addClassCleanup(cls._override.disable) + cls.addClassCleanup(cleanup_url_patterns, cls) - if hasattr(cls, '_module_urlpatterns'): - cls._module.urlpatterns = cls._module_urlpatterns - else: - del cls._module.urlpatterns + super().setUpClass() + + if django.VERSION < (4, 0): + @classmethod + def tearDownClass(cls): + super().tearDownClass() + cls._override.disable() + + if hasattr(cls, '_module_urlpatterns'): + cls._module.urlpatterns = cls._module_urlpatterns + else: + del cls._module.urlpatterns diff --git a/rest_framework/throttling.py b/rest_framework/throttling.py index 834ced148..c0d6cf42f 100644 --- a/rest_framework/throttling.py +++ b/rest_framework/throttling.py @@ -1,8 +1,6 @@ """ Provides various throttling policies. """ -from __future__ import unicode_literals - import time from django.core.cache import cache as default_cache @@ -11,7 +9,7 @@ from django.core.exceptions import ImproperlyConfigured from rest_framework.settings import api_settings -class BaseThrottle(object): +class BaseThrottle: """ Rate throttling of requests. """ @@ -54,7 +52,7 @@ class SimpleRateThrottle(BaseThrottle): A simple cache implementation, that only requires `.get_cache_key()` to be overridden. - The rate (requests / seconds) is set by a `rate` attribute on the View + The rate (requests / seconds) is set by a `rate` attribute on the Throttle class. The attribute is a string of the form 'number_of_requests/period'. Period should be one of: ('s', 'sec', 'm', 'min', 'h', 'hour', 'd', 'day') @@ -173,7 +171,7 @@ class AnonRateThrottle(SimpleRateThrottle): scope = 'anon' def get_cache_key(self, request, view): - if request.user.is_authenticated: + if request.user and request.user.is_authenticated: return None # Only throttle unauthenticated requests. return self.cache_format % { @@ -193,7 +191,7 @@ class UserRateThrottle(SimpleRateThrottle): scope = 'user' def get_cache_key(self, request, view): - if request.user.is_authenticated: + if request.user and request.user.is_authenticated: ident = request.user.pk else: ident = self.get_ident(request) @@ -232,16 +230,16 @@ class ScopedRateThrottle(SimpleRateThrottle): self.num_requests, self.duration = self.parse_rate(self.rate) # We can now proceed as normal. - return super(ScopedRateThrottle, self).allow_request(request, view) + return super().allow_request(request, view) def get_cache_key(self, request, view): """ If `view.throttle_scope` is not set, don't apply this throttle. Otherwise generate the unique cache key by concatenating the user id - with the '.throttle_scope` property of the view. + with the `.throttle_scope` property of the view. """ - if request.user.is_authenticated: + if request.user and request.user.is_authenticated: ident = request.user.pk else: ident = self.get_ident(request) diff --git a/rest_framework/urlpatterns.py b/rest_framework/urlpatterns.py index ab3a74978..bed5708eb 100644 --- a/rest_framework/urlpatterns.py +++ b/rest_framework/urlpatterns.py @@ -1,10 +1,6 @@ -from __future__ import unicode_literals +from django.urls import URLResolver, include, path, re_path, register_converter +from django.urls.resolvers import RoutePattern -from django.conf.urls import include, url - -from rest_framework.compat import ( - URLResolver, get_regex_pattern, is_route_pattern, path, register_converter -) from rest_framework.settings import api_settings @@ -39,7 +35,7 @@ def apply_suffix_patterns(urlpatterns, suffix_pattern, suffix_required, suffix_r for urlpattern in urlpatterns: if isinstance(urlpattern, URLResolver): # Set of included URL patterns - regex = get_regex_pattern(urlpattern) + regex = urlpattern.pattern.regex.pattern namespace = urlpattern.namespace app_name = urlpattern.app_name kwargs = urlpattern.default_kwargs @@ -50,17 +46,17 @@ def apply_suffix_patterns(urlpatterns, suffix_pattern, suffix_required, suffix_r suffix_route) # if the original pattern was a RoutePattern we need to preserve it - if is_route_pattern(urlpattern): + if isinstance(urlpattern.pattern, RoutePattern): assert path is not None route = str(urlpattern.pattern) new_pattern = path(route, include((patterns, app_name), namespace), kwargs) else: - new_pattern = url(regex, include((patterns, app_name), namespace), kwargs) + new_pattern = re_path(regex, include((patterns, app_name), namespace), kwargs) ret.append(new_pattern) else: # Regular URL pattern - regex = get_regex_pattern(urlpattern).rstrip('$').rstrip('/') + suffix_pattern + regex = urlpattern.pattern.regex.pattern.rstrip('$').rstrip('/') + suffix_pattern view = urlpattern.callback kwargs = urlpattern.default_args name = urlpattern.name @@ -69,13 +65,13 @@ def apply_suffix_patterns(urlpatterns, suffix_pattern, suffix_required, suffix_r ret.append(urlpattern) # if the original pattern was a RoutePattern we need to preserve it - if is_route_pattern(urlpattern): + if isinstance(urlpattern.pattern, RoutePattern): assert path is not None assert suffix_route is not None route = str(urlpattern.pattern).rstrip('$').rstrip('/') + suffix_route new_pattern = path(route, view, kwargs, name) else: - new_pattern = url(regex, view, kwargs, name) + new_pattern = re_path(regex, view, kwargs, name) ret.append(new_pattern) @@ -108,12 +104,9 @@ def format_suffix_patterns(urlpatterns, suffix_required=False, allowed=None): else: suffix_pattern = r'\.(?P<%s>[a-z0-9]+)/?$' % suffix_kwarg - if path and register_converter: - converter_name, suffix_converter = _get_format_path_converter(suffix_kwarg, allowed) - register_converter(suffix_converter, converter_name) + converter_name, suffix_converter = _get_format_path_converter(suffix_kwarg, allowed) + register_converter(suffix_converter, converter_name) - suffix_route = '<%s:%s>' % (converter_name, suffix_kwarg) - else: - suffix_route = None + suffix_route = '<%s:%s>' % (converter_name, suffix_kwarg) return apply_suffix_patterns(urlpatterns, suffix_pattern, suffix_required, suffix_route) diff --git a/rest_framework/urls.py b/rest_framework/urls.py index 0e4c2661b..0aa301332 100644 --- a/rest_framework/urls.py +++ b/rest_framework/urls.py @@ -6,18 +6,16 @@ your API requires authentication: urlpatterns = [ ... - url(r'^auth/', include('rest_framework.urls')) + path('auth/', include('rest_framework.urls')) ] You should make sure your authentication settings include `SessionAuthentication`. """ -from __future__ import unicode_literals - -from django.conf.urls import url from django.contrib.auth import views +from django.urls import path app_name = 'rest_framework' urlpatterns = [ - url(r'^login/$', views.LoginView.as_view(template_name='rest_framework/login.html'), name='login'), - url(r'^logout/$', views.LogoutView.as_view(), name='logout'), + path('login/', views.LoginView.as_view(template_name='rest_framework/login.html'), name='login'), + path('logout/', views.LogoutView.as_view(), name='logout'), ] diff --git a/rest_framework/utils/breadcrumbs.py b/rest_framework/utils/breadcrumbs.py index e0374ffd0..54990e9f6 100644 --- a/rest_framework/utils/breadcrumbs.py +++ b/rest_framework/utils/breadcrumbs.py @@ -1,5 +1,3 @@ -from __future__ import unicode_literals - from django.urls import get_script_prefix, resolve diff --git a/rest_framework/utils/encoders.py b/rest_framework/utils/encoders.py index d8f4aeb4e..35a89eb09 100644 --- a/rest_framework/utils/encoders.py +++ b/rest_framework/utils/encoders.py @@ -1,16 +1,16 @@ """ Helper classes for parsers. """ -from __future__ import absolute_import, unicode_literals +import contextlib import datetime import decimal import json # noqa import uuid from django.db.models.query import QuerySet -from django.utils import six, timezone -from django.utils.encoding import force_text +from django.utils import timezone +from django.utils.encoding import force_str from django.utils.functional import Promise from rest_framework.compat import coreapi @@ -25,7 +25,7 @@ class JSONEncoder(json.JSONEncoder): # For Date Time string spec, see ECMA 262 # https://ecma-international.org/ecma-262/5.1/#sec-15.9.1.15 if isinstance(obj, Promise): - return force_text(obj) + return force_str(obj) elif isinstance(obj, datetime.datetime): representation = obj.isoformat() if representation.endswith('+00:00'): @@ -39,17 +39,17 @@ class JSONEncoder(json.JSONEncoder): representation = obj.isoformat() return representation elif isinstance(obj, datetime.timedelta): - return six.text_type(obj.total_seconds()) + return str(obj.total_seconds()) elif isinstance(obj, decimal.Decimal): # Serializers will coerce decimals to strings by default. return float(obj) elif isinstance(obj, uuid.UUID): - return six.text_type(obj) + return str(obj) elif isinstance(obj, QuerySet): return tuple(obj) elif isinstance(obj, bytes): # Best-effort for binary blobs. See #4187. - return obj.decode('utf-8') + return obj.decode() elif hasattr(obj, 'tolist'): # Numpy arrays and array scalars. return obj.tolist() @@ -59,10 +59,9 @@ class JSONEncoder(json.JSONEncoder): 'You should be using a schema renderer instead for this view.' ) elif hasattr(obj, '__getitem__'): - try: - return dict(obj) - except Exception: - pass + cls = (list if isinstance(obj, (list, tuple)) else dict) + with contextlib.suppress(Exception): + return cls(obj) elif hasattr(obj, '__iter__'): return tuple(item for item in obj) - return super(JSONEncoder, self).default(obj) + return super().default(obj) diff --git a/rest_framework/utils/field_mapping.py b/rest_framework/utils/field_mapping.py index f11b4b94e..7e8e8f046 100644 --- a/rest_framework/utils/field_mapping.py +++ b/rest_framework/utils/field_mapping.py @@ -16,7 +16,7 @@ NUMERIC_FIELD_TYPES = ( ) -class ClassLookupDict(object): +class ClassLookupDict: """ Takes a dictionary with classes as keys. Lookups against this object will traverses the object's inheritance @@ -58,7 +58,6 @@ def get_detail_view_name(model): that refer to instances of the model. """ return '%(model_name)s-detail' % { - 'app_label': model._meta.app_label, 'model_name': model._meta.object_name.lower() } @@ -91,9 +90,14 @@ def get_field_kwargs(field_name, model_field): if isinstance(model_field, models.SlugField): kwargs['allow_unicode'] = model_field.allow_unicode - if isinstance(model_field, models.TextField) or (postgres_fields and isinstance(model_field, postgres_fields.JSONField)): + if isinstance(model_field, models.TextField) and not model_field.choices or \ + (postgres_fields and isinstance(model_field, postgres_fields.JSONField)) or \ + (hasattr(models, 'JSONField') and isinstance(model_field, models.JSONField)): kwargs['style'] = {'base_template': 'textarea.html'} + if model_field.null: + kwargs['allow_null'] = True + if isinstance(model_field, models.AutoField) or not model_field.editable: # If this field is read-only, then return early. # Further keyword arguments are not valid. @@ -103,13 +107,12 @@ def get_field_kwargs(field_name, model_field): if model_field.has_default() or model_field.blank or model_field.null: kwargs['required'] = False - if model_field.null and not isinstance(model_field, models.NullBooleanField): - kwargs['allow_null'] = True - - if model_field.blank and (isinstance(model_field, models.CharField) or - isinstance(model_field, models.TextField)): + if model_field.blank and (isinstance(model_field, (models.CharField, models.TextField))): kwargs['allow_blank'] = True + if not model_field.blank and (postgres_fields and isinstance(model_field, postgres_fields.ArrayField)): + kwargs['allow_empty'] = False + if isinstance(model_field, models.FilePathField): kwargs['path'] = model_field.path @@ -193,9 +196,7 @@ def get_field_kwargs(field_name, model_field): # Ensure that max_length is passed explicitly as a keyword arg, # rather than as a validator. max_length = getattr(model_field, 'max_length', None) - if max_length is not None and (isinstance(model_field, models.CharField) or - isinstance(model_field, models.TextField) or - isinstance(model_field, models.FileField)): + if max_length is not None and (isinstance(model_field, (models.CharField, models.TextField, models.FileField))): kwargs['max_length'] = max_length validator_kwarg = [ validator for validator in validator_kwarg @@ -216,15 +217,9 @@ def get_field_kwargs(field_name, model_field): ] if getattr(model_field, 'unique', False): - unique_error_message = model_field.error_messages.get('unique', None) - if unique_error_message: - unique_error_message = unique_error_message % { - 'model_name': model_field.model._meta.verbose_name, - 'field_label': model_field.verbose_name - } validator = UniqueValidator( queryset=model_field.model._default_manager, - message=unique_error_message) + message=get_unique_error_message(model_field)) validator_kwarg.append(validator) if validator_kwarg: @@ -268,6 +263,8 @@ def get_relation_kwargs(field_name, relation_info): if not model_field.editable: kwargs['read_only'] = True kwargs.pop('queryset', None) + if model_field.null: + kwargs['allow_null'] = True if kwargs.get('read_only', False): # If this field is read-only, then return early. # No further keyword arguments are valid. @@ -275,12 +272,12 @@ def get_relation_kwargs(field_name, relation_info): if model_field.has_default() or model_field.blank or model_field.null: kwargs['required'] = False - if model_field.null: - kwargs['allow_null'] = True if model_field.validators: kwargs['validators'] = model_field.validators if getattr(model_field, 'unique', False): - validator = UniqueValidator(queryset=model_field.model._default_manager) + validator = UniqueValidator( + queryset=model_field.model._default_manager, + message=get_unique_error_message(model_field)) kwargs['validators'] = kwargs.get('validators', []) + [validator] if to_many and not model_field.blank: kwargs['allow_empty'] = False @@ -299,3 +296,13 @@ def get_url_kwargs(model_field): return { 'view_name': get_detail_view_name(model_field) } + + +def get_unique_error_message(model_field): + unique_error_message = model_field.error_messages.get('unique', None) + if unique_error_message: + unique_error_message = unique_error_message % { + 'model_name': model_field.model._meta.verbose_name, + 'field_label': model_field.verbose_name + } + return unique_error_message diff --git a/rest_framework/utils/formatting.py b/rest_framework/utils/formatting.py index aa805f14e..c5917fd41 100644 --- a/rest_framework/utils/formatting.py +++ b/rest_framework/utils/formatting.py @@ -1,11 +1,9 @@ """ Utility functions to return a formatted name and description for a given view. """ -from __future__ import unicode_literals - import re -from django.utils.encoding import force_text +from django.utils.encoding import force_str from django.utils.html import escape from django.utils.safestring import mark_safe @@ -31,7 +29,7 @@ def dedent(content): as it fails to dedent multiline docstrings that include unindented text on the initial line. """ - content = force_text(content) + content = force_str(content) lines = [line for line in content.splitlines()[1:] if line.lstrip()] # unindent the content if needed @@ -67,3 +65,29 @@ def markup_description(description): description = escape(description).replace('\n', '
') description = '

' + description + '

' return mark_safe(description) + + +class lazy_format: + """ + Delay formatting until it's actually needed. + + Useful when the format string or one of the arguments is lazy. + + Not using Django's lazy because it is too slow. + """ + __slots__ = ('format_string', 'args', 'kwargs', 'result') + + def __init__(self, format_string, *args, **kwargs): + self.result = None + self.format_string = format_string + self.args = args + self.kwargs = kwargs + + def __str__(self): + if self.result is None: + self.result = self.format_string.format(*self.args, **self.kwargs) + self.format_string, self.args, self.kwargs = None, None, None + return self.result + + def __mod__(self, value): + return str(self) % value diff --git a/rest_framework/utils/json.py b/rest_framework/utils/json.py index cb5572380..1c1e69bf1 100644 --- a/rest_framework/utils/json.py +++ b/rest_framework/utils/json.py @@ -5,9 +5,6 @@ REST framework should always import this wrapper module in order to maintain spec-compliant encoding/decoding. Support for non-standard features should be handled by users at the renderer and parser layer. """ - -from __future__ import absolute_import - import functools import json # noqa diff --git a/rest_framework/utils/mediatypes.py b/rest_framework/utils/mediatypes.py index f4acf4807..b9004d496 100644 --- a/rest_framework/utils/mediatypes.py +++ b/rest_framework/utils/mediatypes.py @@ -3,12 +3,7 @@ Handling of media types, as found in HTTP Content-Type and Accept headers. See https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7 """ -from __future__ import unicode_literals - -from django.http.multipartparser import parse_header -from django.utils.encoding import python_2_unicode_compatible - -from rest_framework import HTTP_HEADER_ENCODING +from rest_framework.compat import parse_header_parameters def media_type_matches(lhs, rhs): @@ -46,11 +41,10 @@ def order_by_precedence(media_type_lst): return [media_types for media_types in ret if media_types] -@python_2_unicode_compatible -class _MediaType(object): +class _MediaType: def __init__(self, media_type_str): self.orig = '' if (media_type_str is None) else media_type_str - self.full_type, self.params = parse_header(self.orig.encode(HTTP_HEADER_ENCODING)) + self.full_type, self.params = parse_header_parameters(self.orig) self.main_type, sep, self.sub_type = self.full_type.partition('/') def match(self, other): @@ -83,5 +77,5 @@ class _MediaType(object): def __str__(self): ret = "%s/%s" % (self.main_type, self.sub_type) for key, val in self.params.items(): - ret += "; %s=%s" % (key, val.decode('ascii')) + ret += "; %s=%s" % (key, val) return ret diff --git a/rest_framework/utils/representation.py b/rest_framework/utils/representation.py index deeaf1f63..6f2efee16 100644 --- a/rest_framework/utils/representation.py +++ b/rest_framework/utils/representation.py @@ -2,16 +2,12 @@ Helper functions for creating user-friendly representations of serializer classes and serializer fields. """ -from __future__ import unicode_literals - import re from django.db import models -from django.utils.encoding import force_text +from django.utils.encoding import force_str from django.utils.functional import Promise -from rest_framework.compat import unicode_repr - def manager_repr(value): model = value.model @@ -32,9 +28,9 @@ def smart_repr(value): return manager_repr(value) if isinstance(value, Promise) and value._delegate_text: - value = force_text(value) + value = force_str(value) - value = unicode_repr(value) + value = repr(value) # Representations like u'help text' # should simply be presented as 'help text' @@ -45,9 +41,7 @@ def smart_repr(value): # # Should be presented as # - value = re.sub(' at 0x[0-9A-Fa-f]{4,32}>', '>', value) - - return value + return re.sub(' at 0x[0-9A-Fa-f]{4,32}>', '>', value) def field_repr(field, force_many=False): diff --git a/rest_framework/utils/serializer_helpers.py b/rest_framework/utils/serializer_helpers.py index c24e51d09..6ca794584 100644 --- a/rest_framework/utils/serializer_helpers.py +++ b/rest_framework/utils/serializer_helpers.py @@ -1,10 +1,10 @@ -from __future__ import unicode_literals - +import contextlib +import sys from collections import OrderedDict +from collections.abc import Mapping, MutableMapping -from django.utils.encoding import force_text +from django.utils.encoding import force_str -from rest_framework.compat import MutableMapping, unicode_to_repr from rest_framework.utils import json @@ -17,7 +17,7 @@ class ReturnDict(OrderedDict): def __init__(self, *args, **kwargs): self.serializer = kwargs.pop('serializer') - super(ReturnDict, self).__init__(*args, **kwargs) + super().__init__(*args, **kwargs) def copy(self): return ReturnDict(self, serializer=self.serializer) @@ -30,6 +30,22 @@ class ReturnDict(OrderedDict): # but preserve the raw data. return (dict, (dict(self),)) + if sys.version_info >= (3, 9): + # These are basically copied from OrderedDict, with `serializer` added. + def __or__(self, other): + if not isinstance(other, dict): + return NotImplemented + new = self.__class__(self, serializer=self.serializer) + new.update(other) + return new + + def __ror__(self, other): + if not isinstance(other, dict): + return NotImplemented + new = self.__class__(other, serializer=self.serializer) + new.update(self) + return new + class ReturnList(list): """ @@ -40,7 +56,7 @@ class ReturnList(list): def __init__(self, *args, **kwargs): self.serializer = kwargs.pop('serializer') - super(ReturnList, self).__init__(*args, **kwargs) + super().__init__(*args, **kwargs) def __repr__(self): return list.__repr__(self) @@ -51,7 +67,7 @@ class ReturnList(list): return (list, (list(self),)) -class BoundField(object): +class BoundField: """ A field object that also includes `.value` and `.error` properties. Returned when iterating over a serializer instance, @@ -73,9 +89,9 @@ class BoundField(object): return self._field.__class__ def __repr__(self): - return unicode_to_repr('<%s value=%s errors=%s>' % ( + return '<%s value=%s errors=%s>' % ( self.__class__.__name__, self.value, self.errors - )) + ) def as_form_field(self): value = '' if (self.value is None or self.value is False) else self.value @@ -88,10 +104,13 @@ class JSONBoundField(BoundField): # When HTML form input is used and the input is not valid # value will be a JSONString, rather than a JSON primitive. if not getattr(value, 'is_json_string', False): - try: - value = json.dumps(self.value, sort_keys=True, indent=4) - except (TypeError, ValueError): - pass + with contextlib.suppress(TypeError, ValueError): + value = json.dumps( + self.value, + sort_keys=True, + indent=4, + separators=(',', ': '), + ) return self.__class__(self._field, value, self.errors, self._prefix) @@ -103,9 +122,9 @@ class NestedBoundField(BoundField): """ def __init__(self, field, value, errors, prefix=''): - if value is None or value is '': + if value is None or value == '' or not isinstance(value, Mapping): value = {} - super(NestedBoundField, self).__init__(field, value, errors, prefix) + super().__init__(field, value, errors, prefix) def __iter__(self): for field in self.fields.values(): @@ -117,6 +136,8 @@ class NestedBoundField(BoundField): error = self.errors.get(key) if isinstance(self.errors, dict) else None if hasattr(field, 'fields'): return NestedBoundField(field, value, error, prefix=self.name + '.') + elif getattr(field, '_is_jsonfield', False): + return JSONBoundField(field, value, error, prefix=self.name + '.') return BoundField(field, value, error, prefix=self.name + '.') def as_form_field(self): @@ -125,7 +146,7 @@ class NestedBoundField(BoundField): if isinstance(value, (list, dict)): values[key] = value else: - values[key] = '' if (value is None or value is False) else force_text(value) + values[key] = '' if (value is None or value is False) else force_str(value) return self.__class__(self._field, values, self.errors, self._prefix) diff --git a/rest_framework/utils/urls.py b/rest_framework/utils/urls.py index 3766928d4..afb06994c 100644 --- a/rest_framework/utils/urls.py +++ b/rest_framework/utils/urls.py @@ -1,5 +1,6 @@ +from urllib import parse + from django.utils.encoding import force_str -from django.utils.six.moves.urllib import parse as urlparse def replace_query_param(url, key, val): @@ -7,11 +8,11 @@ def replace_query_param(url, key, val): Given a URL and a key/val pair, set or replace an item in the query parameters of the URL, and return the new URL. """ - (scheme, netloc, path, query, fragment) = urlparse.urlsplit(force_str(url)) - query_dict = urlparse.parse_qs(query, keep_blank_values=True) + (scheme, netloc, path, query, fragment) = parse.urlsplit(force_str(url)) + query_dict = parse.parse_qs(query, keep_blank_values=True) query_dict[force_str(key)] = [force_str(val)] - query = urlparse.urlencode(sorted(list(query_dict.items())), doseq=True) - return urlparse.urlunsplit((scheme, netloc, path, query, fragment)) + query = parse.urlencode(sorted(query_dict.items()), doseq=True) + return parse.urlunsplit((scheme, netloc, path, query, fragment)) def remove_query_param(url, key): @@ -19,8 +20,8 @@ def remove_query_param(url, key): Given a URL and a key/val pair, remove an item in the query parameters of the URL, and return the new URL. """ - (scheme, netloc, path, query, fragment) = urlparse.urlsplit(force_str(url)) - query_dict = urlparse.parse_qs(query, keep_blank_values=True) + (scheme, netloc, path, query, fragment) = parse.urlsplit(force_str(url)) + query_dict = parse.parse_qs(query, keep_blank_values=True) query_dict.pop(key, None) - query = urlparse.urlencode(sorted(list(query_dict.items())), doseq=True) - return urlparse.urlunsplit((scheme, netloc, path, query, fragment)) + query = parse.urlencode(sorted(query_dict.items()), doseq=True) + return parse.urlunsplit((scheme, netloc, path, query, fragment)) diff --git a/rest_framework/validators.py b/rest_framework/validators.py index 2ea3e5ac1..a5cb75a84 100644 --- a/rest_framework/validators.py +++ b/rest_framework/validators.py @@ -6,12 +6,9 @@ This gives us better separation of concerns, allows us to use single-step object creation, and makes it possible to switch between using the implicit `ModelSerializer` class and an equivalent explicit `Serializer` class. """ -from __future__ import unicode_literals - from django.db import DataError -from django.utils.translation import ugettext_lazy as _ +from django.utils.translation import gettext_lazy as _ -from rest_framework.compat import unicode_to_repr from rest_framework.exceptions import ValidationError from rest_framework.utils.representation import smart_repr @@ -33,62 +30,57 @@ def qs_filter(queryset, **kwargs): return queryset.none() -class UniqueValidator(object): +class UniqueValidator: """ Validator that corresponds to `unique=True` on a model field. Should be applied to an individual field on the serializer. """ message = _('This field must be unique.') + requires_context = True def __init__(self, queryset, message=None, lookup='exact'): self.queryset = queryset - self.serializer_field = None self.message = message or self.message self.lookup = lookup - def set_context(self, serializer_field): - """ - This hook is called by the serializer instance, - prior to the validation call being made. - """ - # Determine the underlying model field name. This may not be the - # same as the serializer field name if `source=<>` is set. - self.field_name = serializer_field.source_attrs[-1] - # Determine the existing instance, if this is an update operation. - self.instance = getattr(serializer_field.parent, 'instance', None) - - def filter_queryset(self, value, queryset): + def filter_queryset(self, value, queryset, field_name): """ Filter the queryset to all instances matching the given attribute. """ - filter_kwargs = {'%s__%s' % (self.field_name, self.lookup): value} + filter_kwargs = {'%s__%s' % (field_name, self.lookup): value} return qs_filter(queryset, **filter_kwargs) - def exclude_current_instance(self, queryset): + def exclude_current_instance(self, queryset, instance): """ If an instance is being updated, then do not include that instance itself as a uniqueness conflict. """ - if self.instance is not None: - return queryset.exclude(pk=self.instance.pk) + if instance is not None: + return queryset.exclude(pk=instance.pk) return queryset - def __call__(self, value): + def __call__(self, value, serializer_field): + # Determine the underlying model field name. This may not be the + # same as the serializer field name if `source=<>` is set. + field_name = serializer_field.source_attrs[-1] + # Determine the existing instance, if this is an update operation. + instance = getattr(serializer_field.parent, 'instance', None) + queryset = self.queryset - queryset = self.filter_queryset(value, queryset) - queryset = self.exclude_current_instance(queryset) + queryset = self.filter_queryset(value, queryset, field_name) + queryset = self.exclude_current_instance(queryset, instance) if qs_exists(queryset): raise ValidationError(self.message, code='unique') def __repr__(self): - return unicode_to_repr('<%s(queryset=%s)>' % ( + return '<%s(queryset=%s)>' % ( self.__class__.__name__, smart_repr(self.queryset) - )) + ) -class UniqueTogetherValidator(object): +class UniqueTogetherValidator: """ Validator that corresponds to `unique_together = (...)` on a model class. @@ -96,69 +88,67 @@ class UniqueTogetherValidator(object): """ message = _('The fields {field_names} must make a unique set.') missing_message = _('This field is required.') + requires_context = True def __init__(self, queryset, fields, message=None): self.queryset = queryset self.fields = fields - self.serializer_field = None self.message = message or self.message - def set_context(self, serializer): - """ - This hook is called by the serializer instance, - prior to the validation call being made. - """ - # Determine the existing instance, if this is an update operation. - self.instance = getattr(serializer, 'instance', None) - - def enforce_required_fields(self, attrs): + def enforce_required_fields(self, attrs, serializer): """ The `UniqueTogetherValidator` always forces an implied 'required' state on the fields it applies to. """ - if self.instance is not None: + if serializer.instance is not None: return missing_items = { field_name: self.missing_message for field_name in self.fields - if field_name not in attrs + if serializer.fields[field_name].source not in attrs } if missing_items: raise ValidationError(missing_items, code='required') - def filter_queryset(self, attrs, queryset): + def filter_queryset(self, attrs, queryset, serializer): """ Filter the queryset to all instances matching the given attributes. """ + # field names => field sources + sources = [ + serializer.fields[field_name].source + for field_name in self.fields + ] + # If this is an update, then any unprovided field should # have it's value set based on the existing instance attribute. - if self.instance is not None: - for field_name in self.fields: - if field_name not in attrs: - attrs[field_name] = getattr(self.instance, field_name) + if serializer.instance is not None: + for source in sources: + if source not in attrs: + attrs[source] = getattr(serializer.instance, source) # Determine the filter keyword arguments and filter the queryset. filter_kwargs = { - field_name: attrs[field_name] - for field_name in self.fields + source: attrs[source] + for source in sources } return qs_filter(queryset, **filter_kwargs) - def exclude_current_instance(self, attrs, queryset): + def exclude_current_instance(self, attrs, queryset, instance): """ If an instance is being updated, then do not include that instance itself as a uniqueness conflict. """ - if self.instance is not None: - return queryset.exclude(pk=self.instance.pk) + if instance is not None: + return queryset.exclude(pk=instance.pk) return queryset - def __call__(self, attrs): - self.enforce_required_fields(attrs) + def __call__(self, attrs, serializer): + self.enforce_required_fields(attrs, serializer) queryset = self.queryset - queryset = self.filter_queryset(attrs, queryset) - queryset = self.exclude_current_instance(attrs, queryset) + queryset = self.filter_queryset(attrs, queryset, serializer) + queryset = self.exclude_current_instance(attrs, queryset, serializer.instance) # Ignore validation if any field is None checked_values = [ @@ -170,16 +160,28 @@ class UniqueTogetherValidator(object): raise ValidationError(message, code='unique') def __repr__(self): - return unicode_to_repr('<%s(queryset=%s, fields=%s)>' % ( + return '<%s(queryset=%s, fields=%s)>' % ( self.__class__.__name__, smart_repr(self.queryset), smart_repr(self.fields) - )) + ) -class BaseUniqueForValidator(object): +class ProhibitSurrogateCharactersValidator: + message = _('Surrogate characters are not allowed: U+{code_point:X}.') + code = 'surrogate_characters_not_allowed' + + def __call__(self, value): + for surrogate_character in (ch for ch in str(value) + if 0xD800 <= ord(ch) <= 0xDFFF): + message = self.message.format(code_point=ord(surrogate_character)) + raise ValidationError(message, code=self.code) + + +class BaseUniqueForValidator: message = None missing_message = _('This field is required.') + requires_context = True def __init__(self, queryset, field, date_field, message=None): self.queryset = queryset @@ -187,18 +189,6 @@ class BaseUniqueForValidator(object): self.date_field = date_field self.message = message or self.message - def set_context(self, serializer): - """ - This hook is called by the serializer instance, - prior to the validation call being made. - """ - # Determine the underlying model field names. These may not be the - # same as the serializer field names if `source=<>` is set. - self.field_name = serializer.fields[self.field].source_attrs[-1] - self.date_field_name = serializer.fields[self.date_field].source_attrs[-1] - # Determine the existing instance, if this is an update operation. - self.instance = getattr(serializer, 'instance', None) - def enforce_required_fields(self, attrs): """ The `UniqueForValidator` classes always force an implied @@ -212,23 +202,28 @@ class BaseUniqueForValidator(object): if missing_items: raise ValidationError(missing_items, code='required') - def filter_queryset(self, attrs, queryset): + def filter_queryset(self, attrs, queryset, field_name, date_field_name): raise NotImplementedError('`filter_queryset` must be implemented.') - def exclude_current_instance(self, attrs, queryset): + def exclude_current_instance(self, attrs, queryset, instance): """ If an instance is being updated, then do not include that instance itself as a uniqueness conflict. """ - if self.instance is not None: - return queryset.exclude(pk=self.instance.pk) + if instance is not None: + return queryset.exclude(pk=instance.pk) return queryset - def __call__(self, attrs): + def __call__(self, attrs, serializer): + # Determine the underlying model field names. These may not be the + # same as the serializer field names if `source=<>` is set. + field_name = serializer.fields[self.field].source_attrs[-1] + date_field_name = serializer.fields[self.date_field].source_attrs[-1] + self.enforce_required_fields(attrs) queryset = self.queryset - queryset = self.filter_queryset(attrs, queryset) - queryset = self.exclude_current_instance(attrs, queryset) + queryset = self.filter_queryset(attrs, queryset, field_name, date_field_name) + queryset = self.exclude_current_instance(attrs, queryset, serializer.instance) if qs_exists(queryset): message = self.message.format(date_field=self.date_field) raise ValidationError({ @@ -236,50 +231,50 @@ class BaseUniqueForValidator(object): }, code='unique') def __repr__(self): - return unicode_to_repr('<%s(queryset=%s, field=%s, date_field=%s)>' % ( + return '<%s(queryset=%s, field=%s, date_field=%s)>' % ( self.__class__.__name__, smart_repr(self.queryset), smart_repr(self.field), smart_repr(self.date_field) - )) + ) class UniqueForDateValidator(BaseUniqueForValidator): message = _('This field must be unique for the "{date_field}" date.') - def filter_queryset(self, attrs, queryset): + def filter_queryset(self, attrs, queryset, field_name, date_field_name): value = attrs[self.field] date = attrs[self.date_field] filter_kwargs = {} - filter_kwargs[self.field_name] = value - filter_kwargs['%s__day' % self.date_field_name] = date.day - filter_kwargs['%s__month' % self.date_field_name] = date.month - filter_kwargs['%s__year' % self.date_field_name] = date.year + filter_kwargs[field_name] = value + filter_kwargs['%s__day' % date_field_name] = date.day + filter_kwargs['%s__month' % date_field_name] = date.month + filter_kwargs['%s__year' % date_field_name] = date.year return qs_filter(queryset, **filter_kwargs) class UniqueForMonthValidator(BaseUniqueForValidator): message = _('This field must be unique for the "{date_field}" month.') - def filter_queryset(self, attrs, queryset): + def filter_queryset(self, attrs, queryset, field_name, date_field_name): value = attrs[self.field] date = attrs[self.date_field] filter_kwargs = {} - filter_kwargs[self.field_name] = value - filter_kwargs['%s__month' % self.date_field_name] = date.month + filter_kwargs[field_name] = value + filter_kwargs['%s__month' % date_field_name] = date.month return qs_filter(queryset, **filter_kwargs) class UniqueForYearValidator(BaseUniqueForValidator): message = _('This field must be unique for the "{date_field}" year.') - def filter_queryset(self, attrs, queryset): + def filter_queryset(self, attrs, queryset, field_name, date_field_name): value = attrs[self.field] date = attrs[self.date_field] filter_kwargs = {} - filter_kwargs[self.field_name] = value - filter_kwargs['%s__year' % self.date_field_name] = date.year + filter_kwargs[field_name] = value + filter_kwargs['%s__year' % date_field_name] = date.year return qs_filter(queryset, **filter_kwargs) diff --git a/rest_framework/versioning.py b/rest_framework/versioning.py index 206ff6c2e..78cfc9dc8 100644 --- a/rest_framework/versioning.py +++ b/rest_framework/versioning.py @@ -1,9 +1,6 @@ -# coding: utf-8 -from __future__ import unicode_literals - import re -from django.utils.translation import ugettext_lazy as _ +from django.utils.translation import gettext_lazy as _ from rest_framework import exceptions from rest_framework.compat import unicode_http_header @@ -13,7 +10,7 @@ from rest_framework.templatetags.rest_framework import replace_query_param from rest_framework.utils.mediatypes import _MediaType -class BaseVersioning(object): +class BaseVersioning: default_version = api_settings.DEFAULT_VERSION allowed_versions = api_settings.ALLOWED_VERSIONS version_param = api_settings.VERSION_PARAM @@ -63,8 +60,8 @@ class URLPathVersioning(BaseVersioning): An example URL conf for two views that accept two different versions. urlpatterns = [ - url(r'^(?P[v1|v2]+)/users/$', users_list, name='users-list'), - url(r'^(?P[v1|v2]+)/users/(?P[0-9]+)/$', users_detail, name='users-detail') + re_path(r'^(?P[v1|v2]+)/users/$', users_list, name='users-list'), + re_path(r'^(?P[v1|v2]+)/users/(?P[0-9]+)/$', users_detail, name='users-detail') ] GET /1.0/something/ HTTP/1.1 @@ -87,7 +84,7 @@ class URLPathVersioning(BaseVersioning): kwargs = {} if (kwargs is None) else kwargs kwargs[self.version_param] = request.version - return super(URLPathVersioning, self).reverse( + return super().reverse( viewname, args, kwargs, request, format, **extra ) @@ -102,14 +99,14 @@ class NamespaceVersioning(BaseVersioning): # users/urls.py urlpatterns = [ - url(r'^/users/$', users_list, name='users-list'), - url(r'^/users/(?P[0-9]+)/$', users_detail, name='users-detail') + path('/users/', users_list, name='users-list'), + path('/users//', users_detail, name='users-detail') ] # urls.py urlpatterns = [ - url(r'^v1/', include('users.urls', namespace='v1')), - url(r'^v2/', include('users.urls', namespace='v2')) + path('v1/', include('users.urls', namespace='v1')), + path('v2/', include('users.urls', namespace='v2')) ] GET /1.0/something/ HTTP/1.1 @@ -133,7 +130,7 @@ class NamespaceVersioning(BaseVersioning): def reverse(self, viewname, args=None, kwargs=None, request=None, format=None, **extra): if request.version is not None: viewname = self.get_versioned_viewname(viewname, request) - return super(NamespaceVersioning, self).reverse( + return super().reverse( viewname, args, kwargs, request, format, **extra ) @@ -179,7 +176,7 @@ class QueryParameterVersioning(BaseVersioning): return version def reverse(self, viewname, args=None, kwargs=None, request=None, format=None, **extra): - url = super(QueryParameterVersioning, self).reverse( + url = super().reverse( viewname, args, kwargs, request, format, **extra ) if request.version is not None: diff --git a/rest_framework/views.py b/rest_framework/views.py index 9d5d959e9..4c30029fd 100644 --- a/rest_framework/views.py +++ b/rest_framework/views.py @@ -1,15 +1,13 @@ """ Provides an APIView class that is the base of all views in REST framework. """ -from __future__ import unicode_literals - from django.conf import settings from django.core.exceptions import PermissionDenied -from django.db import connection, models, transaction +from django.db import connections, models from django.http import Http404 from django.http.response import HttpResponseBase from django.utils.cache import cc_delim_re, patch_vary_headers -from django.utils.encoding import smart_text +from django.utils.encoding import smart_str from django.views.decorators.csrf import csrf_exempt from django.views.generic import View @@ -58,16 +56,16 @@ def get_view_description(view, html=False): if description is None: description = view.__class__.__doc__ or '' - description = formatting.dedent(smart_text(description)) + description = formatting.dedent(smart_str(description)) if html: return formatting.markup_description(description) return description def set_rollback(): - atomic_requests = connection.settings_dict.get('ATOMIC_REQUESTS', False) - if atomic_requests and connection.in_atomic_block: - transaction.set_rollback(True) + for db in connections.all(): + if db.settings_dict['ATOMIC_REQUESTS'] and db.in_atomic_block: + db.set_rollback(True) def exception_handler(exc, context): @@ -81,9 +79,9 @@ def exception_handler(exc, context): to be raised. """ if isinstance(exc, Http404): - exc = exceptions.NotFound() + exc = exceptions.NotFound(*(exc.args)) elif isinstance(exc, PermissionDenied): - exc = exceptions.PermissionDenied() + exc = exceptions.PermissionDenied(*(exc.args)) if isinstance(exc, exceptions.APIException): headers = {} @@ -137,7 +135,7 @@ class APIView(View): ) cls.queryset._fetch_all = force_evaluation - view = super(APIView, cls).as_view(**initkwargs) + view = super().as_view(**initkwargs) view.cls = cls view.initkwargs = initkwargs @@ -168,13 +166,13 @@ class APIView(View): """ raise exceptions.MethodNotAllowed(request.method) - def permission_denied(self, request, message=None): + def permission_denied(self, request, message=None, code=None): """ If request is not permitted, determine what kind of exception to raise. """ if request.authenticators and not request.successful_authenticator: raise exceptions.NotAuthenticated() - raise exceptions.PermissionDenied(detail=message) + raise exceptions.PermissionDenied(detail=message, code=code) def throttled(self, request, wait): """ @@ -333,7 +331,9 @@ class APIView(View): for permission in self.get_permissions(): if not permission.has_permission(request, self): self.permission_denied( - request, message=getattr(permission, 'message', None) + request, + message=getattr(permission, 'message', None), + code=getattr(permission, 'code', None) ) def check_object_permissions(self, request, obj): @@ -344,7 +344,9 @@ class APIView(View): for permission in self.get_permissions(): if not permission.has_object_permission(request, self, obj): self.permission_denied( - request, message=getattr(permission, 'message', None) + request, + message=getattr(permission, 'message', None), + code=getattr(permission, 'code', None) ) def check_throttles(self, request): @@ -352,9 +354,21 @@ class APIView(View): Check if request should be throttled. Raises an appropriate exception if the request is throttled. """ + throttle_durations = [] for throttle in self.get_throttles(): if not throttle.allow_request(request, self): - self.throttled(request, throttle.wait()) + throttle_durations.append(throttle.wait()) + + if throttle_durations: + # Filter out `None` values which may happen in case of config / rate + # changes, see #1438 + durations = [ + duration for duration in throttle_durations + if duration is not None + ] + + duration = max(durations, default=None) + self.throttled(request, duration) def determine_version(self, request, *args, **kwargs): """ diff --git a/rest_framework/viewsets.py b/rest_framework/viewsets.py index 7146828d2..1c56f61e8 100644 --- a/rest_framework/viewsets.py +++ b/rest_framework/viewsets.py @@ -16,8 +16,6 @@ automatically. router.register(r'users', UserViewSet, 'user') urlpatterns = router.urls """ -from __future__ import unicode_literals - from collections import OrderedDict from functools import update_wrapper from inspect import getmembers @@ -27,14 +25,24 @@ from django.utils.decorators import classonlymethod from django.views.decorators.csrf import csrf_exempt from rest_framework import generics, mixins, views +from rest_framework.decorators import MethodMapper from rest_framework.reverse import reverse def _is_extra_action(attr): - return hasattr(attr, 'mapping') + return hasattr(attr, 'mapping') and isinstance(attr.mapping, MethodMapper) -class ViewSetMixin(object): +def _check_attr_name(func, name): + assert func.__name__ == name, ( + 'Expected function (`{func.__name__}`) to match its attribute name ' + '(`{name}`). If using a decorator, ensure the inner function is ' + 'decorated with `functools.wraps`, or that `{func.__name__}.__name__` ' + 'is otherwise set to `{name}`.').format(func=func, name=name) + return func + + +class ViewSetMixin: """ This is the magic. @@ -55,7 +63,7 @@ class ViewSetMixin(object): and slightly modify the view function that is created and returned. """ # The name and description initkwargs may be explicitly overridden for - # certain route confiugurations. eg, names of extra actions. + # certain route configurations. eg, names of extra actions. cls.name = None cls.description = None @@ -94,6 +102,10 @@ class ViewSetMixin(object): def view(request, *args, **kwargs): self = cls(**initkwargs) + + if 'get' in actions and 'head' not in actions: + actions['head'] = actions['get'] + # We also store the mapping of request methods to actions, # so that we can later set the action attribute. # eg. `self.action = 'list'` on an incoming GET request. @@ -105,9 +117,6 @@ class ViewSetMixin(object): handler = getattr(self, action) setattr(self, method, handler) - if hasattr(self, 'get') and not hasattr(self, 'head'): - self.head = self.get - self.request = request self.args = args self.kwargs = kwargs @@ -134,7 +143,7 @@ class ViewSetMixin(object): """ Set the `.action` attribute on the view, depending on the request method. """ - request = super(ViewSetMixin, self).initialize_request(request, *args, **kwargs) + request = super().initialize_request(request, *args, **kwargs) method = request.method.lower() if method == 'options': # This is a special case as we always provide handling for the @@ -150,6 +159,11 @@ class ViewSetMixin(object): Reverse the action for the given `url_name`. """ url_name = '%s-%s' % (self.basename, url_name) + namespace = None + if self.request and self.request.resolver_match: + namespace = self.request.resolver_match.namespace + if namespace: + url_name = namespace + ':' + url_name kwargs.setdefault('request', self.request) return reverse(url_name, *args, **kwargs) @@ -159,7 +173,9 @@ class ViewSetMixin(object): """ Get the methods that are marked as an extra ViewSet `@action`. """ - return [method for _, method in getmembers(cls, _is_extra_action)] + return [_check_attr_name(method, name) + for name, method + in getmembers(cls, _is_extra_action)] def get_extra_action_url_map(self): """ @@ -182,6 +198,10 @@ class ViewSetMixin(object): for action in actions: try: url_name = '%s-%s' % (self.basename, action.url_name) + namespace = self.request.resolver_match.namespace + if namespace: + url_name = '%s:%s' % (namespace, url_name) + url = reverse(url_name, self.args, self.kwargs, request=self.request) view = self.__class__(**action.kwargs) action_urls[view.get_view_name()] = url diff --git a/runtests.py b/runtests.py index 16b47ce2a..98f34c067 100755 --- a/runtests.py +++ b/runtests.py @@ -1,44 +1,8 @@ -#! /usr/bin/env python -from __future__ import print_function - -import subprocess +#! /usr/bin/env python3 import sys import pytest -PYTEST_ARGS = { - 'default': [], - 'fast': ['-q'], -} - -FLAKE8_ARGS = ['rest_framework', 'tests'] - -ISORT_ARGS = ['--recursive', '--check-only', '--diff', '-o' 'uritemplate', '-p', 'tests', 'rest_framework', 'tests'] - - -def exit_on_failure(ret, message=None): - if ret: - sys.exit(ret) - - -def flake8_main(args): - print('Running flake8 code linting') - ret = subprocess.call(['flake8'] + args) - print('flake8 failed' if ret else 'flake8 passed') - return ret - - -def isort_main(args): - print('Running isort code checking') - ret = subprocess.call(['isort'] + args) - - if ret: - print('isort failed: Some modules have incorrectly ordered imports. Fix by running `isort --recursive .`') - else: - print('isort passed') - - return ret - def split_class_and_function(string): class_string, function_string = string.split('.', 1) @@ -56,31 +20,6 @@ def is_class(string): if __name__ == "__main__": - try: - sys.argv.remove('--nolint') - except ValueError: - run_flake8 = True - run_isort = True - else: - run_flake8 = False - run_isort = False - - try: - sys.argv.remove('--lintonly') - except ValueError: - run_tests = True - else: - run_tests = False - - try: - sys.argv.remove('--fast') - except ValueError: - style = 'default' - else: - style = 'fast' - run_flake8 = False - run_isort = False - if len(sys.argv) > 1: pytest_args = sys.argv[1:] first_arg = pytest_args[0] @@ -107,13 +46,6 @@ if __name__ == "__main__": # `runtests.py test_function [flags]` pytest_args = ['tests', '-k', pytest_args[0]] + pytest_args[1:] else: - pytest_args = PYTEST_ARGS[style] + pytest_args = [] - if run_tests: - exit_on_failure(pytest.main(pytest_args)) - - if run_flake8: - exit_on_failure(flake8_main(FLAKE8_ARGS)) - - if run_isort: - exit_on_failure(isort_main(ISORT_ARGS)) + sys.exit(pytest.main(pytest_args)) diff --git a/setup.cfg b/setup.cfg index c95134600..294e9afdd 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,24 +1,20 @@ -[bdist_wheel] -universal = 1 - [metadata] -license_file = LICENSE.md +license_files = LICENSE.md [tool:pytest] -addopts=--tb=short --strict -ra -testspath = tests +addopts=--tb=short --strict-markers -ra [flake8] -ignore = E501 +ignore = E501,W503,W504 banned-modules = json = use from rest_framework.utils import json! [isort] skip=.tox atomic=true multi_line_output=5 -known_standard_library=types -known_third_party=pytest,_pytest,django,pytz -known_first_party=rest_framework +extra_standard_library=types +known_third_party=pytest,_pytest,django,pytz,uritemplate +known_first_party=rest_framework,tests [coverage:run] # NOTE: source is ignored with pytest-cov (but uses the same). diff --git a/setup.py b/setup.py index cb850a3ae..181740165 100755 --- a/setup.py +++ b/setup.py @@ -1,5 +1,4 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- +#!/usr/bin/env python3 import os import re import shutil @@ -8,6 +7,34 @@ from io import open from setuptools import find_packages, setup +CURRENT_PYTHON = sys.version_info[:2] +REQUIRED_PYTHON = (3, 6) + +# This check and everything above must remain compatible with Python 2.7. +if CURRENT_PYTHON < REQUIRED_PYTHON: + sys.stderr.write(""" +========================== +Unsupported Python version +========================== + +This version of Django REST Framework requires Python {}.{}, but you're trying +to install it on Python {}.{}. + +This may be because you are using a version of pip that doesn't +understand the python_requires classifier. Make sure you +have pip >= 9.0 and setuptools >= 24.2, then try again: + + $ python -m pip install --upgrade pip setuptools + $ python -m pip install djangorestframework + +This will install the latest version of Django REST Framework which works on +your version of Python. If you can't upgrade your pip (or Python), request +an older version of Django REST Framework: + + $ python -m pip install "djangorestframework<3.10" +""".format(*(REQUIRED_PYTHON + CURRENT_PYTHON))) + sys.exit(1) + def read(f): return open(f, 'r', encoding='utf-8').read() @@ -29,6 +56,10 @@ if sys.argv[-1] == 'publish': print("twine not installed.\nUse `pip install twine`.\nExiting.") sys.exit() os.system("python setup.py sdist bdist_wheel") + if os.system("twine check dist/*"): + print("twine check failed. Packages might be outdated.") + print("Try using `pip install -U twine wheel`.\nExiting.") + sys.exit() os.system("twine upload dist/*") print("You probably want to also tag the version now:") print(" git tag -a %s -m 'version %s'" % (version, version)) @@ -51,30 +82,36 @@ setup( author_email='tom@tomchristie.com', # SEE NOTE BELOW (*) packages=find_packages(exclude=['tests*']), include_package_data=True, - install_requires=[], - python_requires=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*", + install_requires=["django>=3.0", "pytz"], + python_requires=">=3.6", zip_safe=False, classifiers=[ 'Development Status :: 5 - Production/Stable', 'Environment :: Web Environment', 'Framework :: Django', - 'Framework :: Django :: 1.11', - 'Framework :: Django :: 2.0', - 'Framework :: Django :: 2.1', - 'Framework :: Django :: 2.2', + 'Framework :: Django :: 3.0', + 'Framework :: Django :: 3.1', + 'Framework :: Django :: 3.2', + 'Framework :: Django :: 4.0', + 'Framework :: Django :: 4.1', 'Intended Audience :: Developers', 'License :: OSI Approved :: BSD License', 'Operating System :: OS Independent', 'Programming Language :: Python', - 'Programming Language :: Python :: 2', - 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3.4', - 'Programming Language :: Python :: 3.5', 'Programming Language :: Python :: 3.6', 'Programming Language :: Python :: 3.7', + 'Programming Language :: Python :: 3.8', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', + 'Programming Language :: Python :: 3 :: Only', 'Topic :: Internet :: WWW/HTTP', - ] + ], + project_urls={ + 'Funding': 'https://fund.django-rest-framework.org/topics/funding/', + 'Source': 'https://github.com/encode/django-rest-framework', + 'Changelog': 'https://www.django-rest-framework.org/community/release-notes/', + }, ) # (*) Please direct queries to the discussion group, rather than to me directly diff --git a/tests/authentication/migrations/0001_initial.py b/tests/authentication/migrations/0001_initial.py index cfc887240..548b3576b 100644 --- a/tests/authentication/migrations/0001_initial.py +++ b/tests/authentication/migrations/0001_initial.py @@ -1,6 +1,3 @@ -# -*- coding: utf-8 -*- -from __future__ import unicode_literals - from django.conf import settings from django.db import migrations, models diff --git a/tests/authentication/models.py b/tests/authentication/models.py index b8d1fd5a6..1a721de4d 100644 --- a/tests/authentication/models.py +++ b/tests/authentication/models.py @@ -1,6 +1,3 @@ -# coding: utf-8 -from __future__ import unicode_literals - from django.conf import settings from django.db import models diff --git a/tests/authentication/test_authentication.py b/tests/authentication/test_authentication.py index 793773542..b64c05de8 100644 --- a/tests/authentication/test_authentication.py +++ b/tests/authentication/test_authentication.py @@ -1,16 +1,12 @@ -# coding: utf-8 - -from __future__ import unicode_literals - import base64 +import django import pytest from django.conf import settings -from django.conf.urls import include, url from django.contrib.auth.models import User from django.http import HttpResponse from django.test import TestCase, override_settings -from django.utils import six +from django.urls import include, path from rest_framework import ( HTTP_HEADER_ENCODING, exceptions, permissions, renderers, status @@ -52,34 +48,34 @@ class MockView(APIView): urlpatterns = [ - url( - r'^session/$', + path( + 'session/', MockView.as_view(authentication_classes=[SessionAuthentication]) ), - url( - r'^basic/$', + path( + 'basic/', MockView.as_view(authentication_classes=[BasicAuthentication]) ), - url( - r'^remote-user/$', + path( + 'remote-user/', MockView.as_view(authentication_classes=[RemoteUserAuthentication]) ), - url( - r'^token/$', + path( + 'token/', MockView.as_view(authentication_classes=[TokenAuthentication]) ), - url( - r'^customtoken/$', + path( + 'customtoken/', MockView.as_view(authentication_classes=[CustomTokenAuthentication]) ), - url( - r'^customkeywordtoken/$', + path( + 'customkeywordtoken/', MockView.as_view( authentication_classes=[CustomKeywordTokenAuthentication] ) ), - url(r'^auth-token/$', obtain_auth_token), - url(r'^auth/', include('rest_framework.urls', namespace='rest_framework')), + path('auth-token/', obtain_auth_token), + path('auth/', include('rest_framework.urls', namespace='rest_framework')), ] @@ -164,6 +160,25 @@ class BasicAuthTests(TestCase): ) assert response.status_code == status.HTTP_401_UNAUTHORIZED + def test_decoding_of_utf8_credentials(self): + username = 'walterwhité' + email = 'walterwhite@example.com' + password = 'pässwörd' + User.objects.create_user( + username, email, password + ) + credentials = ('%s:%s' % (username, password)) + base64_credentials = base64.b64encode( + credentials.encode('utf-8') + ).decode(HTTP_HEADER_ENCODING) + auth = 'Basic %s' % base64_credentials + response = self.csrf_client.post( + '/basic/', + {'example': 'example'}, + HTTP_AUTHORIZATION=auth + ) + assert response.status_code == status.HTTP_200_OK + @override_settings(ROOT_URLCONF=__name__) class SessionAuthTests(TestCase): @@ -188,7 +203,7 @@ class SessionAuthTests(TestCase): cf. [#1810](https://github.com/encode/django-rest-framework/pull/1810) """ response = self.csrf_client.get('/auth/login/') - content = response.content.decode('utf8') + content = response.content.decode() assert '' in content def test_post_form_session_auth_failing_csrf(self): @@ -204,7 +219,16 @@ class SessionAuthTests(TestCase): Ensure POSTing form over session authentication with CSRF token succeeds. Regression test for #6088 """ - from django.middleware.csrf import _get_new_csrf_token + # Remove this shim when dropping support for Django 3.0. + if django.VERSION < (3, 1): + from django.middleware.csrf import _get_new_csrf_token + else: + from django.middleware.csrf import ( + _get_new_csrf_string, _mask_cipher_secret + ) + + def _get_new_csrf_token(): + return _mask_cipher_secret(_get_new_csrf_string()) self.csrf_client.login(username=self.username, password=self.password) @@ -253,7 +277,7 @@ class SessionAuthTests(TestCase): assert response.status_code == status.HTTP_403_FORBIDDEN -class BaseTokenAuthTests(object): +class BaseTokenAuthTests: """Token authentication""" model = None path = None @@ -381,7 +405,11 @@ class TokenAuthTests(BaseTokenAuthTests, TestCase): """Ensure generate_key returns a string""" token = self.model() key = token.generate_key() - assert isinstance(key, six.string_types) + assert isinstance(key, str) + + def test_generate_key_accessible_as_classmethod(self): + key = self.model.generate_key() + assert isinstance(key, str) def test_token_login_json(self): """Ensure token login view using JSON POST works.""" @@ -534,15 +562,17 @@ class BasicAuthenticationUnitTests(TestCase): def test_basic_authentication_raises_error_if_user_not_active(self): from rest_framework import authentication - class MockUser(object): + class MockUser: is_active = False old_authenticate = authentication.authenticate authentication.authenticate = lambda **kwargs: MockUser() - auth = authentication.BasicAuthentication() - with pytest.raises(exceptions.AuthenticationFailed) as error: - auth.authenticate_credentials('foo', 'bar') - assert 'User inactive or deleted.' in str(error) - authentication.authenticate = old_authenticate + try: + auth = authentication.BasicAuthentication() + with pytest.raises(exceptions.AuthenticationFailed) as exc_info: + auth.authenticate_credentials('foo', 'bar') + assert 'User inactive or deleted.' in str(exc_info.value) + finally: + authentication.authenticate = old_authenticate @override_settings(ROOT_URLCONF=__name__, diff --git a/tests/browsable_api/auth_urls.py b/tests/browsable_api/auth_urls.py index 0e9379717..151278cbd 100644 --- a/tests/browsable_api/auth_urls.py +++ b/tests/browsable_api/auth_urls.py @@ -1,10 +1,8 @@ -from __future__ import unicode_literals - -from django.conf.urls import include, url +from django.urls import include, path from .views import MockView urlpatterns = [ - url(r'^$', MockView.as_view()), - url(r'^auth/', include('rest_framework.urls', namespace='rest_framework')), + path('', MockView.as_view()), + path('auth/', include('rest_framework.urls', namespace='rest_framework')), ] diff --git a/tests/browsable_api/no_auth_urls.py b/tests/browsable_api/no_auth_urls.py index 5fc95c727..33491ad92 100644 --- a/tests/browsable_api/no_auth_urls.py +++ b/tests/browsable_api/no_auth_urls.py @@ -1,9 +1,8 @@ -from __future__ import unicode_literals +from django.urls import path -from django.conf.urls import url - -from .views import MockView +from .views import BasicModelWithUsersViewSet, MockView urlpatterns = [ - url(r'^$', MockView.as_view()), + path('', MockView.as_view()), + path('basicviewset', BasicModelWithUsersViewSet.as_view({'get': 'list'})), ] diff --git a/tests/browsable_api/serializers.py b/tests/browsable_api/serializers.py new file mode 100644 index 000000000..e8a1cdef8 --- /dev/null +++ b/tests/browsable_api/serializers.py @@ -0,0 +1,8 @@ +from rest_framework.serializers import ModelSerializer +from tests.models import BasicModelWithUsers + + +class BasicSerializer(ModelSerializer): + class Meta: + model = BasicModelWithUsers + fields = '__all__' diff --git a/tests/browsable_api/test_browsable_api.py b/tests/browsable_api/test_browsable_api.py index 684d7ae14..a76d11fe3 100644 --- a/tests/browsable_api/test_browsable_api.py +++ b/tests/browsable_api/test_browsable_api.py @@ -1,10 +1,35 @@ -from __future__ import unicode_literals - from django.contrib.auth.models import User from django.test import TestCase, override_settings +from rest_framework.permissions import IsAuthenticated from rest_framework.test import APIClient +from .views import BasicModelWithUsersViewSet, OrganizationPermissions + + +@override_settings(ROOT_URLCONF='tests.browsable_api.no_auth_urls') +class AnonymousUserTests(TestCase): + """Tests correct handling of anonymous user request on endpoints with IsAuthenticated permission class.""" + + def setUp(self): + self.client = APIClient(enforce_csrf_checks=True) + + def tearDown(self): + self.client.logout() + + def test_get_raises_typeerror_when_anonymous_user_in_queryset_filter(self): + with self.assertRaises(TypeError): + self.client.get('/basicviewset') + + def test_get_returns_http_forbidden_when_anonymous_user(self): + old_permissions = BasicModelWithUsersViewSet.permission_classes + BasicModelWithUsersViewSet.permission_classes = [IsAuthenticated, OrganizationPermissions] + + response = self.client.get('/basicviewset') + + BasicModelWithUsersViewSet.permission_classes = old_permissions + self.assertEqual(response.status_code, 403) + @override_settings(ROOT_URLCONF='tests.browsable_api.auth_urls') class DropdownWithAuthTests(TestCase): @@ -26,18 +51,18 @@ class DropdownWithAuthTests(TestCase): def test_name_shown_when_logged_in(self): self.client.login(username=self.username, password=self.password) response = self.client.get('/') - content = response.content.decode('utf8') + content = response.content.decode() assert 'john' in content def test_logout_shown_when_logged_in(self): self.client.login(username=self.username, password=self.password) response = self.client.get('/') - content = response.content.decode('utf8') + content = response.content.decode() assert '>Log out<' in content def test_login_shown_when_logged_out(self): response = self.client.get('/') - content = response.content.decode('utf8') + content = response.content.decode() assert '>Log in<' in content @@ -61,16 +86,16 @@ class NoDropdownWithoutAuthTests(TestCase): def test_name_shown_when_logged_in(self): self.client.login(username=self.username, password=self.password) response = self.client.get('/') - content = response.content.decode('utf8') + content = response.content.decode() assert 'john' in content def test_dropdown_not_shown_when_logged_in(self): self.client.login(username=self.username, password=self.password) response = self.client.get('/') - content = response.content.decode('utf8') + content = response.content.decode() assert '
  • ' not in content def test_dropdown_not_shown_when_logged_out(self): response = self.client.get('/') - content = response.content.decode('utf8') + content = response.content.decode() assert '
  • ' not in content diff --git a/tests/browsable_api/test_browsable_nested_api.py b/tests/browsable_api/test_browsable_nested_api.py index 8f38b3c4e..a6c2ee6bd 100644 --- a/tests/browsable_api/test_browsable_nested_api.py +++ b/tests/browsable_api/test_browsable_nested_api.py @@ -1,8 +1,6 @@ -from __future__ import unicode_literals - -from django.conf.urls import url from django.test import TestCase from django.test.utils import override_settings +from django.urls import path from rest_framework import serializers from rest_framework.generics import ListCreateAPIView @@ -25,7 +23,7 @@ class NestedSerializersView(ListCreateAPIView): urlpatterns = [ - url(r'^api/$', NestedSerializersView.as_view(), name='api'), + path('api/', NestedSerializersView.as_view(), name='api'), ] @@ -36,7 +34,7 @@ class DropdownWithAuthTests(TestCase): def test_login(self): response = self.client.get('/api/') assert 200 == response.status_code - content = response.content.decode('utf-8') + content = response.content.decode() assert 'form action="/api/"' in content assert 'input name="nested.one"' in content assert 'input name="nested.two"' in content diff --git a/tests/browsable_api/views.py b/tests/browsable_api/views.py index 03758f10b..e73967bf8 100644 --- a/tests/browsable_api/views.py +++ b/tests/browsable_api/views.py @@ -1,8 +1,16 @@ -from __future__ import unicode_literals - from rest_framework import authentication, renderers +from rest_framework.permissions import BasePermission from rest_framework.response import Response from rest_framework.views import APIView +from rest_framework.viewsets import ModelViewSet + +from ..models import BasicModelWithUsers +from .serializers import BasicSerializer + + +class OrganizationPermissions(BasePermission): + def has_object_permission(self, request, view, obj): + return request.user.is_staff or (request.user == obj.owner.organization_user.user) class MockView(APIView): @@ -11,3 +19,15 @@ class MockView(APIView): def get(self, request): return Response({'a': 1, 'b': 2, 'c': 3}) + + +class BasicModelWithUsersViewSet(ModelViewSet): + queryset = BasicModelWithUsers.objects.all() + serializer_class = BasicSerializer + permission_classes = [OrganizationPermissions] + # permission_classes = [IsAuthenticated, OrganizationPermissions] + renderer_classes = (renderers.BrowsableAPIRenderer, renderers.JSONRenderer) + + def get_queryset(self): + qs = super().get_queryset().filter(users=self.request.user) + return qs diff --git a/tests/conftest.py b/tests/conftest.py index ac29e4a42..79cabd5e1 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -18,18 +18,23 @@ def pytest_addoption(parser): def pytest_configure(config): from django.conf import settings + # USE_L10N is deprecated, and will be removed in Django 5.0. + use_l10n = {"USE_L10N": True} if django.VERSION < (4, 0) else {} settings.configure( DEBUG_PROPAGATE_EXCEPTIONS=True, DATABASES={ 'default': { 'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:' + }, + 'secondary': { + 'ENGINE': 'django.db.backends.sqlite3', + 'NAME': ':memory:' } }, SITE_ID=1, SECRET_KEY='not very secret in tests', USE_I18N=True, - USE_L10N=True, STATIC_URL='/static/', ROOT_URLCONF='tests.urls', TEMPLATES=[ @@ -64,6 +69,7 @@ def pytest_configure(config): PASSWORD_HASHERS=( 'django.contrib.auth.hashers.MD5PasswordHasher', ), + **use_l10n, ) # guardian is optional diff --git a/tests/generic_relations/models.py b/tests/generic_relations/models.py index 55bc243cb..20df3e4a2 100644 --- a/tests/generic_relations/models.py +++ b/tests/generic_relations/models.py @@ -1,14 +1,10 @@ -from __future__ import unicode_literals - from django.contrib.contenttypes.fields import ( GenericForeignKey, GenericRelation ) from django.contrib.contenttypes.models import ContentType from django.db import models -from django.utils.encoding import python_2_unicode_compatible -@python_2_unicode_compatible class Tag(models.Model): """ Tags have a descriptive slug, and are attached to an arbitrary object. @@ -22,7 +18,6 @@ class Tag(models.Model): return self.tag -@python_2_unicode_compatible class Bookmark(models.Model): """ A URL bookmark that may have multiple tags attached. @@ -34,7 +29,6 @@ class Bookmark(models.Model): return 'Bookmark: %s' % self.url -@python_2_unicode_compatible class Note(models.Model): """ A textual note that may have multiple tags attached. diff --git a/tests/generic_relations/test_generic_relations.py b/tests/generic_relations/test_generic_relations.py index c8de332e1..33f8ea1d0 100644 --- a/tests/generic_relations/test_generic_relations.py +++ b/tests/generic_relations/test_generic_relations.py @@ -1,5 +1,3 @@ -from __future__ import unicode_literals - from django.test import TestCase from rest_framework import serializers diff --git a/tests/importable/__init__.py b/tests/importable/__init__.py index b36599027..ded08258c 100644 --- a/tests/importable/__init__.py +++ b/tests/importable/__init__.py @@ -1 +1,16 @@ -from rest_framework import compat # noqa +""" +This test "app" exists to ensure that parts of Django REST Framework can be +imported/invoked before Django itself has been fully initialized. +""" + +from rest_framework import compat, serializers # noqa + + +# test initializing fields with lazy translations +class ExampleSerializer(serializers.Serializer): + charfield = serializers.CharField(min_length=1, max_length=2) + integerfield = serializers.IntegerField(min_value=1, max_value=2) + floatfield = serializers.FloatField(min_value=1, max_value=2) + decimalfield = serializers.DecimalField(max_digits=10, decimal_places=1, min_value=1, max_value=2) + durationfield = serializers.DurationField(min_value=1, max_value=2) + listfield = serializers.ListField(min_length=1, max_length=2) diff --git a/tests/importable/test_installed.py b/tests/importable/test_installed.py index 072d3b2e4..c7e53af23 100644 --- a/tests/importable/test_installed.py +++ b/tests/importable/test_installed.py @@ -4,10 +4,21 @@ from tests import importable def test_installed(): - # ensure that apps can freely import rest_framework.compat + # ensure the test app hasn't been removed from the test suite assert 'tests.importable' in settings.INSTALLED_APPS -def test_imported(): - # ensure that the __init__ hasn't been mucked with +def test_compat(): assert hasattr(importable, 'compat') + + +def test_serializer_fields_initialization(): + assert hasattr(importable, 'ExampleSerializer') + + serializer = importable.ExampleSerializer() + assert 'charfield' in serializer.fields + assert 'integerfield' in serializer.fields + assert 'floatfield' in serializer.fields + assert 'decimalfield' in serializer.fields + assert 'durationfield' in serializer.fields + assert 'listfield' in serializer.fields diff --git a/tests/models.py b/tests/models.py index 17bf23cda..666e9f003 100644 --- a/tests/models.py +++ b/tests/models.py @@ -1,9 +1,8 @@ -from __future__ import unicode_literals - import uuid +from django.contrib.auth.models import User from django.db import models -from django.utils.translation import ugettext_lazy as _ +from django.utils.translation import gettext_lazy as _ class RESTFrameworkModel(models.Model): @@ -35,10 +34,23 @@ class ManyToManySource(RESTFrameworkModel): targets = models.ManyToManyField(ManyToManyTarget, related_name='sources') +class BasicModelWithUsers(RESTFrameworkModel): + users = models.ManyToManyField(User) + + # ForeignKey class ForeignKeyTarget(RESTFrameworkModel): name = models.CharField(max_length=100) + def get_first_source(self): + """Used for testing related field against a callable.""" + return self.sources.all().order_by('pk')[0] + + @property + def first_source(self): + """Used for testing related field against a property.""" + return self.sources.all().order_by('pk')[0] + class UUIDForeignKeyTarget(RESTFrameworkModel): uuid = models.UUIDField(primary_key=True, default=uuid.uuid4) diff --git a/tests/schemas/__init__.py b/tests/schemas/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tests/test_schemas.py b/tests/schemas/test_coreapi.py similarity index 87% rename from tests/test_schemas.py rename to tests/schemas/test_coreapi.py index 3cb9e0cda..eddc5243e 100644 --- a/tests/test_schemas.py +++ b/tests/schemas/test_coreapi.py @@ -1,35 +1,36 @@ import unittest import pytest -from django.conf.urls import include, url from django.core.exceptions import PermissionDenied from django.http import Http404 from django.test import TestCase, override_settings +from django.urls import include, path from rest_framework import ( filters, generics, pagination, permissions, serializers ) -from rest_framework.compat import coreapi, coreschema, get_regex_pattern, path +from rest_framework.compat import coreapi, coreschema from rest_framework.decorators import action, api_view, schema from rest_framework.request import Request from rest_framework.routers import DefaultRouter, SimpleRouter from rest_framework.schemas import ( AutoSchema, ManualSchema, SchemaGenerator, get_schema_view ) +from rest_framework.schemas.coreapi import field_to_schema from rest_framework.schemas.generators import EndpointEnumerator -from rest_framework.schemas.inspectors import field_to_schema from rest_framework.schemas.utils import is_list_view from rest_framework.test import APIClient, APIRequestFactory from rest_framework.utils import formatting from rest_framework.views import APIView from rest_framework.viewsets import GenericViewSet, ModelViewSet -from .models import BasicModel, ForeignKeySource, ManyToManySource +from ..models import BasicModel, ForeignKeySource, ManyToManySource +from . import views factory = APIRequestFactory() -class MockUser(object): +class MockUser: def is_authenticated(self): return True @@ -112,7 +113,7 @@ class ExampleViewSet(ModelViewSet): def get_serializer(self, *args, **kwargs): assert self.request assert self.action - return super(ExampleViewSet, self).get_serializer(*args, **kwargs) + return super().get_serializer(*args, **kwargs) @action(methods=['get', 'post'], detail=False) def documented_custom_action(self, request): @@ -133,22 +134,23 @@ class ExampleViewSet(ModelViewSet): pass -if coreapi: - schema_view = get_schema_view(title='Example API') -else: - def schema_view(request): - pass +with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}): + if coreapi: + schema_view = get_schema_view(title='Example API') + else: + def schema_view(request): + pass router = DefaultRouter() router.register('example', ExampleViewSet, basename='example') urlpatterns = [ - url(r'^$', schema_view), - url(r'^', include(router.urls)) + path('', schema_view), + path('', include(router.urls)) ] @unittest.skipUnless(coreapi, 'coreapi is not installed') -@override_settings(ROOT_URLCONF='tests.test_schemas') +@override_settings(ROOT_URLCONF=__name__, REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestRouterGeneratedSchema(TestCase): def test_anonymous_request(self): client = APIClient() @@ -400,12 +402,13 @@ class ExampleDetailView(APIView): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGenerator(TestCase): def setUp(self): self.patterns = [ - url(r'^example/?$', ExampleListView.as_view()), - url(r'^example/(?P\d+)/?$', ExampleDetailView.as_view()), - url(r'^example/(?P\d+)/sub/?$', ExampleDetailView.as_view()), + path('example/', views.ExampleListView.as_view()), + path('example//', views.ExampleDetailView.as_view()), + path('example//sub/', views.ExampleDetailView.as_view()), ] def test_schema_for_regular_views(self): @@ -452,13 +455,13 @@ class TestSchemaGenerator(TestCase): @unittest.skipUnless(coreapi, 'coreapi is not installed') -@unittest.skipUnless(path, 'needs Django 2') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorDjango2(TestCase): def setUp(self): self.patterns = [ - path('example/', ExampleListView.as_view()), - path('example//', ExampleDetailView.as_view()), - path('example//sub/', ExampleDetailView.as_view()), + path('example/', views.ExampleListView.as_view()), + path('example//', views.ExampleDetailView.as_view()), + path('example//sub/', views.ExampleDetailView.as_view()), ] def test_schema_for_regular_views(self): @@ -505,12 +508,13 @@ class TestSchemaGeneratorDjango2(TestCase): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorNotAtRoot(TestCase): def setUp(self): self.patterns = [ - url(r'^api/v1/example/?$', ExampleListView.as_view()), - url(r'^api/v1/example/(?P\d+)/?$', ExampleDetailView.as_view()), - url(r'^api/v1/example/(?P\d+)/sub/?$', ExampleDetailView.as_view()), + path('api/v1/example/', views.ExampleListView.as_view()), + path('api/v1/example//', views.ExampleDetailView.as_view()), + path('api/v1/example//sub/', views.ExampleDetailView.as_view()), ] def test_schema_for_regular_views(self): @@ -558,12 +562,13 @@ class TestSchemaGeneratorNotAtRoot(TestCase): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorWithMethodLimitedViewSets(TestCase): def setUp(self): router = DefaultRouter() router.register('example1', MethodLimitedViewSet, basename='example1') self.patterns = [ - url(r'^', include(router.urls)) + path('', include(router.urls)) ] def test_schema_for_regular_views(self): @@ -622,14 +627,15 @@ class TestSchemaGeneratorWithMethodLimitedViewSets(TestCase): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorWithRestrictedViewSets(TestCase): def setUp(self): router = DefaultRouter() router.register('example1', Http404ExampleViewSet, basename='example1') router.register('example2', PermissionDeniedExampleViewSet, basename='example2') self.patterns = [ - url('^example/?$', ExampleListView.as_view()), - url(r'^', include(router.urls)) + path('example/', views.ExampleListView.as_view()), + path('', include(router.urls)) ] def test_schema_for_regular_views(self): @@ -668,10 +674,11 @@ class ForeignKeySourceView(generics.CreateAPIView): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorWithForeignKey(TestCase): def setUp(self): self.patterns = [ - url(r'^example/?$', ForeignKeySourceView.as_view()), + path('example/', ForeignKeySourceView.as_view()), ] def test_schema_for_regular_views(self): @@ -713,10 +720,11 @@ class ManyToManySourceView(generics.CreateAPIView): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorWithManyToMany(TestCase): def setUp(self): self.patterns = [ - url(r'^example/?$', ManyToManySourceView.as_view()), + path('example/', ManyToManySourceView.as_view()), ] def test_schema_for_regular_views(self): @@ -747,6 +755,68 @@ class TestSchemaGeneratorWithManyToMany(TestCase): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) +class TestSchemaGeneratorActionKeysViewSets(TestCase): + def test_action_not_coerced_for_get_and_head(self): + """ + Ensure that action name is preserved when action map contains "head". + """ + class CustomViewSet(GenericViewSet): + serializer_class = EmptySerializer + + @action(methods=['get', 'head'], detail=True) + def custom_read(self, request, pk): + raise NotImplementedError + + @action(methods=['put', 'patch'], detail=True) + def custom_mixed_update(self, request, pk): + raise NotImplementedError + + self.router = DefaultRouter() + self.router.register('example', CustomViewSet, basename='example') + self.patterns = [ + path('', include(self.router.urls)) + ] + + generator = SchemaGenerator(title='Example API', patterns=self.patterns) + schema = generator.get_schema() + + expected = coreapi.Document( + url='', + title='Example API', + content={ + 'example': { + 'custom_read': coreapi.Link( + url='/example/{id}/custom_read/', + action='get', + fields=[ + coreapi.Field('id', required=True, location='path', schema=coreschema.String()), + ] + ), + 'custom_mixed_update': { + 'update': coreapi.Link( + url='/example/{id}/custom_mixed_update/', + action='put', + fields=[ + coreapi.Field('id', required=True, location='path', schema=coreschema.String()), + ] + ), + 'partial_update': coreapi.Link( + url='/example/{id}/custom_mixed_update/', + action='patch', + fields=[ + coreapi.Field('id', required=True, location='path', schema=coreschema.String()), + ] + ) + } + } + } + ) + assert schema == expected + + +@unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class Test4605Regression(TestCase): def test_4605_regression(self): generator = SchemaGenerator() @@ -762,6 +832,7 @@ class CustomViewInspector(AutoSchema): pass +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestAutoSchema(TestCase): def test_apiview_schema_descriptor(self): @@ -777,7 +848,7 @@ class TestAutoSchema(TestCase): assert isinstance(view.schema, CustomViewInspector) def test_set_custom_inspector_class_via_settings(self): - with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'tests.test_schemas.CustomViewInspector'}): + with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'tests.schemas.test_coreapi.CustomViewInspector'}): view = APIView() assert isinstance(view.schema, CustomViewInspector) @@ -971,6 +1042,7 @@ class TestAutoSchema(TestCase): self.assertEqual(field_to_schema(case[0]), case[1]) +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) def test_docstring_is_not_stripped_by_get_description(): class ExampleDocstringAPIView(APIView): """ @@ -1007,31 +1079,31 @@ def test_docstring_is_not_stripped_by_get_description(): # Views for SchemaGenerationExclusionTests -class ExcludedAPIView(APIView): - schema = None +with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}): + class ExcludedAPIView(APIView): + schema = None - def get(self, request, *args, **kwargs): + def get(self, request, *args, **kwargs): + pass + + @api_view(['GET']) + @schema(None) + def excluded_fbv(request): + pass + + @api_view(['GET']) + def included_fbv(request): pass -@api_view(['GET']) -@schema(None) -def excluded_fbv(request): - pass - - -@api_view(['GET']) -def included_fbv(request): - pass - - @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class SchemaGenerationExclusionTests(TestCase): def setUp(self): self.patterns = [ - url('^excluded-cbv/$', ExcludedAPIView.as_view()), - url('^excluded-fbv/$', excluded_fbv), - url('^included-fbv/$', included_fbv), + path('excluded-cbv/', ExcludedAPIView.as_view()), + path('excluded-fbv/', excluded_fbv), + path('included-fbv/', included_fbv), ] def test_schema_generator_excludes_correctly(self): @@ -1066,7 +1138,7 @@ class SchemaGenerationExclusionTests(TestCase): inspector = EndpointEnumerator(self.patterns) # Not pretty. Mimics internals of EndpointEnumerator to put should_include_endpoint under test - pairs = [(inspector.get_path_from_regex(get_regex_pattern(pattern)), pattern.callback) + pairs = [(inspector.get_path_from_regex(pattern.pattern.regex.pattern), pattern.callback) for pattern in self.patterns] should_include = [ @@ -1078,11 +1150,6 @@ class SchemaGenerationExclusionTests(TestCase): assert should_include == expected -@api_view(["GET"]) -def simple_fbv(request): - pass - - class BasicModelSerializer(serializers.ModelSerializer): class Meta: model = BasicModel @@ -1118,14 +1185,19 @@ naming_collisions_router.register(r'collision', NamingCollisionViewSet, basename @pytest.mark.skipif(not coreapi, reason='coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestURLNamingCollisions(TestCase): """ Ref: https://github.com/encode/django-rest-framework/issues/4704 """ def test_manually_routing_nested_routes(self): + @api_view(["GET"]) + def simple_fbv(request): + pass + patterns = [ - url(r'^test', simple_fbv), - url(r'^test/list/', simple_fbv), + path('test', simple_fbv), + path('test/list/', simple_fbv), ] generator = SchemaGenerator(title='Naming Colisions', patterns=patterns) @@ -1161,14 +1233,14 @@ class TestURLNamingCollisions(TestCase): def test_manually_routing_generic_view(self): patterns = [ - url(r'^test', NamingCollisionView.as_view()), - url(r'^test/retrieve/', NamingCollisionView.as_view()), - url(r'^test/update/', NamingCollisionView.as_view()), + path('test', NamingCollisionView.as_view()), + path('test/retrieve/', NamingCollisionView.as_view()), + path('test/update/', NamingCollisionView.as_view()), # Fails with method names: - url(r'^test/get/', NamingCollisionView.as_view()), - url(r'^test/put/', NamingCollisionView.as_view()), - url(r'^test/delete/', NamingCollisionView.as_view()), + path('test/get/', NamingCollisionView.as_view()), + path('test/put/', NamingCollisionView.as_view()), + path('test/delete/', NamingCollisionView.as_view()), ] generator = SchemaGenerator(title='Naming Colisions', patterns=patterns) @@ -1184,7 +1256,7 @@ class TestURLNamingCollisions(TestCase): def test_from_router(self): patterns = [ - url(r'from-router', include(naming_collisions_router.urls)), + path('from-router', include(naming_collisions_router.urls)), ] generator = SchemaGenerator(title='Naming Colisions', patterns=patterns) @@ -1216,8 +1288,8 @@ class TestURLNamingCollisions(TestCase): def test_url_under_same_key_not_replaced(self): patterns = [ - url(r'example/(?P\d+)/$', BasicNamingCollisionView.as_view()), - url(r'example/(?P\w+)/$', BasicNamingCollisionView.as_view()), + path('example//', BasicNamingCollisionView.as_view()), + path('example//', BasicNamingCollisionView.as_view()), ] generator = SchemaGenerator(title='Naming Colisions', patterns=patterns) @@ -1228,9 +1300,13 @@ class TestURLNamingCollisions(TestCase): def test_url_under_same_key_not_replaced_another(self): + @api_view(["GET"]) + def simple_fbv(request): + pass + patterns = [ - url(r'^test/list/', simple_fbv), - url(r'^test/(?P\d+)/list/', simple_fbv), + path('test/list/', simple_fbv), + path('test//list/', simple_fbv), ] generator = SchemaGenerator(title='Naming Colisions', patterns=patterns) @@ -1302,10 +1378,8 @@ def test_head_and_options_methods_are_excluded(): assert inspector.get_allowed_methods(callback) == ["GET"] -@pytest.mark.skipif(not coreapi, reason='coreapi is not installed') -class TestAutoSchemaAllowsFilters(object): - class MockAPIView(APIView): - filter_backends = [filters.OrderingFilter] +class MockAPIView(APIView): + filter_backends = [filters.OrderingFilter] def _test(self, method): view = self.MockAPIView() @@ -1358,4 +1432,4 @@ def test_schema_handles_exception(): response = schema_view(request) response.render() assert response.status_code == 403 - assert "You do not have permission to perform this action." in str(response.content) + assert b"You do not have permission to perform this action." in response.content diff --git a/tests/schemas/test_get_schema_view.py b/tests/schemas/test_get_schema_view.py new file mode 100644 index 000000000..f582c6495 --- /dev/null +++ b/tests/schemas/test_get_schema_view.py @@ -0,0 +1,20 @@ +import pytest +from django.test import TestCase, override_settings + +from rest_framework import renderers +from rest_framework.schemas import coreapi, get_schema_view, openapi + + +class GetSchemaViewTests(TestCase): + """For the get_schema_view() helper.""" + def test_openapi(self): + schema_view = get_schema_view(title="With OpenAPI") + assert isinstance(schema_view.initkwargs['schema_generator'], openapi.SchemaGenerator) + assert renderers.OpenAPIRenderer in schema_view.cls().renderer_classes + + @pytest.mark.skipif(not coreapi.coreapi, reason='coreapi is not installed') + def test_coreapi(self): + with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}): + schema_view = get_schema_view(title="With CoreAPI") + assert isinstance(schema_view.initkwargs['schema_generator'], coreapi.SchemaGenerator) + assert renderers.CoreAPIOpenAPIRenderer in schema_view.cls().renderer_classes diff --git a/tests/schemas/test_managementcommand.py b/tests/schemas/test_managementcommand.py new file mode 100644 index 000000000..4104d4ca6 --- /dev/null +++ b/tests/schemas/test_managementcommand.py @@ -0,0 +1,151 @@ +import io +import os +import tempfile + +import pytest +from django.core.management import call_command +from django.test import TestCase +from django.test.utils import override_settings +from django.urls import path + +from rest_framework.compat import uritemplate, yaml +from rest_framework.management.commands import generateschema +from rest_framework.utils import formatting, json +from rest_framework.views import APIView + + +class FooView(APIView): + def get(self, request): + pass + + +urlpatterns = [ + path('', FooView.as_view()) +] + + +class CustomSchemaGenerator: + SCHEMA = {"key": "value"} + + def __init__(self, *args, **kwargs): + pass + + def get_schema(self, **kwargs): + return self.SCHEMA + + +@override_settings(ROOT_URLCONF=__name__) +@pytest.mark.skipif(not uritemplate, reason='uritemplate is not installed') +class GenerateSchemaTests(TestCase): + """Tests for management command generateschema.""" + + def setUp(self): + self.out = io.StringIO() + + def test_command_detects_schema_generation_mode(self): + """Switching between CoreAPI & OpenAPI""" + command = generateschema.Command() + assert command.get_mode() == generateschema.OPENAPI_MODE + with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}): + assert command.get_mode() == generateschema.COREAPI_MODE + + @pytest.mark.skipif(yaml is None, reason='PyYAML is required.') + def test_renders_default_schema_with_custom_title_url_and_description(self): + call_command('generateschema', + '--title=ExampleAPI', + '--url=http://api.example.com', + '--description=Example description', + stdout=self.out) + # Check valid YAML was output. + schema = yaml.safe_load(self.out.getvalue()) + assert schema['openapi'] == '3.0.2' + + def test_renders_openapi_json_schema(self): + call_command('generateschema', + '--format=openapi-json', + stdout=self.out) + # Check valid JSON was output. + out_json = json.loads(self.out.getvalue()) + assert out_json['openapi'] == '3.0.2' + + def test_accepts_custom_schema_generator(self): + call_command('generateschema', + '--generator_class={}.{}'.format(__name__, CustomSchemaGenerator.__name__), + stdout=self.out) + out_json = yaml.safe_load(self.out.getvalue()) + assert out_json == CustomSchemaGenerator.SCHEMA + + def test_writes_schema_to_file_on_parameter(self): + fd, path = tempfile.mkstemp() + try: + call_command('generateschema', '--file={}'.format(path), stdout=self.out) + # nothing on stdout + assert not self.out.getvalue() + + call_command('generateschema', stdout=self.out) + expected_out = self.out.getvalue() + # file output identical to stdout output + with os.fdopen(fd) as fh: + assert expected_out and fh.read() == expected_out + finally: + os.remove(path) + + @pytest.mark.skipif(yaml is None, reason='PyYAML is required.') + @override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) + def test_coreapi_renders_default_schema_with_custom_title_url_and_description(self): + expected_out = """info: + description: Example description + title: ExampleAPI + version: '' + openapi: 3.0.0 + paths: + /: + get: + operationId: list + servers: + - url: http://api.example.com/ + """ + call_command('generateschema', + '--title=ExampleAPI', + '--url=http://api.example.com', + '--description=Example description', + stdout=self.out) + + self.assertIn(formatting.dedent(expected_out), self.out.getvalue()) + + @override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) + def test_coreapi_renders_openapi_json_schema(self): + expected_out = { + "openapi": "3.0.0", + "info": { + "version": "", + "title": "", + "description": "" + }, + "servers": [ + { + "url": "" + } + ], + "paths": { + "/": { + "get": { + "operationId": "list" + } + } + } + } + call_command('generateschema', + '--format=openapi-json', + stdout=self.out) + out_json = json.loads(self.out.getvalue()) + + self.assertDictEqual(out_json, expected_out) + + @override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) + def test_renders_corejson_schema(self): + expected_out = """{"_type":"document","":{"list":{"_type":"link","url":"/","action":"get"}}}""" + call_command('generateschema', + '--format=corejson', + stdout=self.out) + self.assertIn(expected_out, self.out.getvalue()) diff --git a/tests/schemas/test_openapi.py b/tests/schemas/test_openapi.py new file mode 100644 index 000000000..7542bb615 --- /dev/null +++ b/tests/schemas/test_openapi.py @@ -0,0 +1,1253 @@ +import uuid +import warnings + +import pytest +from django.db import models +from django.test import RequestFactory, TestCase, override_settings +from django.urls import path +from django.utils.translation import gettext_lazy as _ + +from rest_framework import filters, generics, pagination, routers, serializers +from rest_framework.authtoken.views import obtain_auth_token +from rest_framework.compat import uritemplate +from rest_framework.parsers import JSONParser, MultiPartParser +from rest_framework.renderers import ( + BaseRenderer, BrowsableAPIRenderer, JSONOpenAPIRenderer, JSONRenderer, + OpenAPIRenderer +) +from rest_framework.request import Request +from rest_framework.schemas.openapi import AutoSchema, SchemaGenerator + +from . import views + + +def create_request(path): + factory = RequestFactory() + request = Request(factory.get(path)) + return request + + +def create_view(view_cls, method, request): + generator = SchemaGenerator() + view = generator.create_view(view_cls.as_view(), method, request) + return view + + +class TestBasics(TestCase): + def dummy_view(request): + pass + + def test_filters(self): + classes = [filters.SearchFilter, filters.OrderingFilter] + for c in classes: + f = c() + assert f.get_schema_operation_parameters(self.dummy_view) + + def test_pagination(self): + classes = [pagination.PageNumberPagination, pagination.LimitOffsetPagination, pagination.CursorPagination] + for c in classes: + f = c() + assert f.get_schema_operation_parameters(self.dummy_view) + + +class TestFieldMapping(TestCase): + def test_list_field_mapping(self): + uuid1 = uuid.uuid4() + uuid2 = uuid.uuid4() + inspector = AutoSchema() + cases = [ + (serializers.ListField(), {'items': {}, 'type': 'array'}), + (serializers.ListField(child=serializers.BooleanField()), {'items': {'type': 'boolean'}, 'type': 'array'}), + (serializers.ListField(child=serializers.FloatField()), {'items': {'type': 'number'}, 'type': 'array'}), + (serializers.ListField(child=serializers.CharField()), {'items': {'type': 'string'}, 'type': 'array'}), + (serializers.ListField(child=serializers.IntegerField(max_value=4294967295)), + {'items': {'type': 'integer', 'maximum': 4294967295, 'format': 'int64'}, 'type': 'array'}), + (serializers.ListField(child=serializers.ChoiceField(choices=[('a', 'Choice A'), ('b', 'Choice B')])), + {'items': {'enum': ['a', 'b'], 'type': 'string'}, 'type': 'array'}), + (serializers.ListField(child=serializers.ChoiceField(choices=[(1, 'One'), (2, 'Two')])), + {'items': {'enum': [1, 2], 'type': 'integer'}, 'type': 'array'}), + (serializers.ListField(child=serializers.ChoiceField(choices=[(1.1, 'First'), (2.2, 'Second')])), + {'items': {'enum': [1.1, 2.2], 'type': 'number'}, 'type': 'array'}), + (serializers.ListField(child=serializers.ChoiceField(choices=[(True, 'true'), (False, 'false')])), + {'items': {'enum': [True, False], 'type': 'boolean'}, 'type': 'array'}), + (serializers.ListField(child=serializers.ChoiceField(choices=[(uuid1, 'uuid1'), (uuid2, 'uuid2')])), + {'items': {'enum': [uuid1, uuid2]}, 'type': 'array'}), + (serializers.ListField(child=serializers.ChoiceField(choices=[(1, 'One'), ('a', 'Choice A')])), + {'items': {'enum': [1, 'a']}, 'type': 'array'}), + (serializers.ListField(child=serializers.ChoiceField(choices=[ + (1, 'One'), ('a', 'Choice A'), (1.1, 'First'), (1.1, 'First'), (1, 'One'), ('a', 'Choice A'), (1, 'One') + ])), + {'items': {'enum': [1, 'a', 1.1]}, 'type': 'array'}), + (serializers.ListField(child=serializers.ChoiceField(choices=[ + (1, 'One'), (2, 'Two'), (3, 'Three'), (2, 'Two'), (3, 'Three'), (1, 'One'), + ])), + {'items': {'enum': [1, 2, 3], 'type': 'integer'}, 'type': 'array'}), + (serializers.IntegerField(min_value=2147483648), + {'type': 'integer', 'minimum': 2147483648, 'format': 'int64'}), + ] + for field, mapping in cases: + with self.subTest(field=field): + assert inspector.map_field(field) == mapping + + def test_lazy_string_field(self): + class ItemSerializer(serializers.Serializer): + text = serializers.CharField(help_text=_('lazy string')) + + inspector = AutoSchema() + + data = inspector.map_serializer(ItemSerializer()) + assert isinstance(data['properties']['text']['description'], str), "description must be str" + + def test_boolean_default_field(self): + class Serializer(serializers.Serializer): + default_true = serializers.BooleanField(default=True) + default_false = serializers.BooleanField(default=False) + without_default = serializers.BooleanField() + + inspector = AutoSchema() + + data = inspector.map_serializer(Serializer()) + assert data['properties']['default_true']['default'] is True, "default must be true" + assert data['properties']['default_false']['default'] is False, "default must be false" + assert 'default' not in data['properties']['without_default'], "default must not be defined" + + def test_custom_field_name(self): + class CustomSchema(AutoSchema): + def get_field_name(self, field): + return 'custom_' + field.field_name + + class Serializer(serializers.Serializer): + text_field = serializers.CharField() + + inspector = CustomSchema() + + data = inspector.map_serializer(Serializer()) + assert 'custom_text_field' in data['properties'] + assert 'text_field' not in data['properties'] + + def test_nullable_fields(self): + class Model(models.Model): + rw_field = models.CharField(null=True) + ro_field = models.CharField(null=True) + + class Serializer(serializers.ModelSerializer): + class Meta: + model = Model + fields = ["rw_field", "ro_field"] + read_only_fields = ["ro_field"] + + inspector = AutoSchema() + + data = inspector.map_serializer(Serializer()) + assert data['properties']['rw_field']['nullable'], "rw_field nullable must be true" + assert data['properties']['ro_field']['nullable'], "ro_field nullable must be true" + assert data['properties']['ro_field']['readOnly'], "ro_field read_only must be true" + + +@pytest.mark.skipif(uritemplate is None, reason='uritemplate not installed.') +class TestOperationIntrospection(TestCase): + + def test_path_without_parameters(self): + path = '/example/' + method = 'GET' + + view = create_view( + views.DocStringExampleListView, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + operation = inspector.get_operation(path, method) + assert operation == { + 'operationId': 'listDocStringExamples', + 'description': 'A description of my GET operation.', + 'parameters': [], + 'tags': ['example'], + 'responses': { + '200': { + 'description': '', + 'content': { + 'application/json': { + 'schema': { + 'type': 'array', + 'items': {}, + }, + }, + }, + }, + }, + } + + def test_path_with_id_parameter(self): + path = '/example/{id}/' + method = 'GET' + + view = create_view( + views.DocStringExampleDetailView, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + operation = inspector.get_operation(path, method) + assert operation == { + 'operationId': 'retrieveDocStringExampleDetail', + 'description': 'A description of my GET operation.', + 'parameters': [{ + 'description': '', + 'in': 'path', + 'name': 'id', + 'required': True, + 'schema': { + 'type': 'string', + }, + }], + 'tags': ['example'], + 'responses': { + '200': { + 'description': '', + 'content': { + 'application/json': { + 'schema': { + }, + }, + }, + }, + }, + } + + def test_request_body(self): + path = '/' + method = 'POST' + + class ItemSerializer(serializers.Serializer): + text = serializers.CharField() + read_only = serializers.CharField(read_only=True) + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + + view = create_view( + View, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + request_body = inspector.get_request_body(path, method) + print(request_body) + assert request_body['content']['application/json']['schema']['$ref'] == '#/components/schemas/Item' + + components = inspector.get_components(path, method) + assert components['Item']['required'] == ['text'] + assert sorted(list(components['Item']['properties'].keys())) == ['read_only', 'text'] + + def test_invalid_serializer_class_name(self): + path = '/' + method = 'POST' + + class Serializer(serializers.Serializer): + text = serializers.CharField() + read_only = serializers.CharField(read_only=True) + + class View(generics.GenericAPIView): + serializer_class = Serializer + + view = create_view( + View, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + serializer = inspector.get_serializer(path, method) + + with pytest.raises(Exception) as exc: + inspector.get_component_name(serializer) + assert "is an invalid class name for schema generation" in str(exc.value) + + def test_empty_required(self): + path = '/' + method = 'POST' + + class ItemSerializer(serializers.Serializer): + read_only = serializers.CharField(read_only=True) + write_only = serializers.CharField(write_only=True, required=False) + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + + view = create_view( + View, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + components = inspector.get_components(path, method) + component = components['Item'] + # there should be no empty 'required' property, see #6834 + assert 'required' not in component + + for response in inspector.get_responses(path, method).values(): + assert 'required' not in component + + def test_empty_required_with_patch_method(self): + path = '/' + method = 'PATCH' + + class ItemSerializer(serializers.Serializer): + read_only = serializers.CharField(read_only=True) + write_only = serializers.CharField(write_only=True, required=False) + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + + view = create_view( + View, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + components = inspector.get_components(path, method) + component = components['Item'] + # there should be no empty 'required' property, see #6834 + assert 'required' not in component + for response in inspector.get_responses(path, method).values(): + assert 'required' not in component + + def test_response_body_generation(self): + path = '/' + method = 'POST' + + class ItemSerializer(serializers.Serializer): + text = serializers.CharField() + write_only = serializers.CharField(write_only=True) + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + + view = create_view( + View, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector.get_responses(path, method) + assert responses['201']['content']['application/json']['schema']['$ref'] == '#/components/schemas/Item' + + components = inspector.get_components(path, method) + assert sorted(components['Item']['required']) == ['text', 'write_only'] + assert sorted(list(components['Item']['properties'].keys())) == ['text', 'write_only'] + assert 'description' in responses['201'] + + def test_response_body_nested_serializer(self): + path = '/' + method = 'POST' + + class NestedSerializer(serializers.Serializer): + number = serializers.IntegerField() + + class ItemSerializer(serializers.Serializer): + text = serializers.CharField() + nested = NestedSerializer() + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector.get_responses(path, method) + assert responses['201']['content']['application/json']['schema']['$ref'] == '#/components/schemas/Item' + components = inspector.get_components(path, method) + assert components['Item'] + + schema = components['Item'] + assert sorted(schema['required']) == ['nested', 'text'] + assert sorted(list(schema['properties'].keys())) == ['nested', 'text'] + assert schema['properties']['nested']['type'] == 'object' + assert list(schema['properties']['nested']['properties'].keys()) == ['number'] + assert schema['properties']['nested']['required'] == ['number'] + + def test_list_response_body_generation(self): + """Test that an array schema is returned for list views.""" + path = '/' + method = 'GET' + + class ItemSerializer(serializers.Serializer): + text = serializers.CharField() + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector.get_responses(path, method) + assert responses == { + '200': { + 'description': '', + 'content': { + 'application/json': { + 'schema': { + 'type': 'array', + 'items': { + '$ref': '#/components/schemas/Item' + }, + }, + }, + }, + }, + } + components = inspector.get_components(path, method) + assert components == { + 'Item': { + 'type': 'object', + 'properties': { + 'text': { + 'type': 'string', + }, + }, + 'required': ['text'], + } + } + + def test_paginated_list_response_body_generation(self): + """Test that pagination properties are added for a paginated list view.""" + path = '/' + method = 'GET' + + class Pagination(pagination.BasePagination): + def get_paginated_response_schema(self, schema): + return { + 'type': 'object', + 'item': schema, + } + + class ItemSerializer(serializers.Serializer): + text = serializers.CharField() + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + pagination_class = Pagination + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector.get_responses(path, method) + assert responses == { + '200': { + 'description': '', + 'content': { + 'application/json': { + 'schema': { + 'type': 'object', + 'item': { + 'type': 'array', + 'items': { + '$ref': '#/components/schemas/Item' + }, + }, + }, + }, + }, + }, + } + components = inspector.get_components(path, method) + assert components == { + 'Item': { + 'type': 'object', + 'properties': { + 'text': { + 'type': 'string', + }, + }, + 'required': ['text'], + } + } + + def test_delete_response_body_generation(self): + """Test that a view's delete method generates a proper response body schema.""" + path = '/{id}/' + method = 'DELETE' + + class View(generics.DestroyAPIView): + serializer_class = views.ExampleSerializer + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector.get_responses(path, method) + assert responses == { + '204': { + 'description': '', + }, + } + + def test_parser_mapping(self): + """Test that view's parsers are mapped to OA media types""" + path = '/{id}/' + method = 'POST' + + class View(generics.CreateAPIView): + serializer_class = views.ExampleSerializer + parser_classes = [JSONParser, MultiPartParser] + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + request_body = inspector.get_request_body(path, method) + + assert len(request_body['content'].keys()) == 2 + assert 'multipart/form-data' in request_body['content'] + assert 'application/json' in request_body['content'] + + def test_renderer_mapping(self): + """Test that view's renderers are mapped to OA media types""" + path = '/{id}/' + method = 'GET' + + class CustomBrowsableAPIRenderer(BrowsableAPIRenderer): + media_type = 'image/jpeg' # that's a wild API renderer + + class TextRenderer(BaseRenderer): + media_type = 'text/plain' + format = 'text' + + class View(generics.CreateAPIView): + serializer_class = views.ExampleSerializer + renderer_classes = [JSONRenderer, TextRenderer, BrowsableAPIRenderer, CustomBrowsableAPIRenderer] + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector.get_responses(path, method) + # TODO this should be changed once the multiple response + # schema support is there + success_response = responses['200'] + + # Check that the API renderers aren't included, but custom renderers are + assert set(success_response['content']) == {'application/json', 'text/plain'} + + def test_openapi_yaml_rendering_without_aliases(self): + renderer = OpenAPIRenderer() + + reused_object = {'test': 'test'} + data = { + 'o1': reused_object, + 'o2': reused_object, + } + assert ( + renderer.render(data) == b'o1:\n test: test\no2:\n test: test\n' or + renderer.render(data) == b'o2:\n test: test\no1:\n test: test\n' # py <= 3.5 + ) + + def test_serializer_filefield(self): + path = '/{id}/' + method = 'POST' + + class ItemSerializer(serializers.Serializer): + attachment = serializers.FileField() + + class View(generics.CreateAPIView): + serializer_class = ItemSerializer + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + components = inspector.get_components(path, method) + component = components['Item'] + properties = component['properties'] + assert properties['attachment']['format'] == 'binary' + + def test_retrieve_response_body_generation(self): + """ + Test that a list of properties is returned for retrieve item views. + + Pagination properties should not be added as the view represents a single item. + """ + path = '/{id}/' + method = 'GET' + + class Pagination(pagination.BasePagination): + def get_paginated_response_schema(self, schema): + return { + 'type': 'object', + 'item': schema, + } + + class ItemSerializer(serializers.Serializer): + text = serializers.CharField() + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + pagination_class = Pagination + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector.get_responses(path, method) + assert responses == { + '200': { + 'description': '', + 'content': { + 'application/json': { + 'schema': { + '$ref': '#/components/schemas/Item' + }, + }, + }, + }, + } + + components = inspector.get_components(path, method) + assert components == { + 'Item': { + 'type': 'object', + 'properties': { + 'text': { + 'type': 'string', + }, + }, + 'required': ['text'], + } + } + + def test_operation_id_generation(self): + path = '/' + method = 'GET' + + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + operationId = inspector.get_operation_id(path, method) + assert operationId == 'listExamples' + + def test_operation_id_custom_operation_id_base(self): + path = '/' + method = 'GET' + + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = AutoSchema(operation_id_base="Ulysse") + inspector.view = view + + operationId = inspector.get_operation_id(path, method) + assert operationId == 'listUlysses' + + def test_operation_id_custom_name(self): + path = '/' + method = 'GET' + + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = AutoSchema(operation_id_base='Ulysse') + inspector.view = view + + operationId = inspector.get_operation_id(path, method) + assert operationId == 'listUlysses' + + def test_operation_id_override_get(self): + class CustomSchema(AutoSchema): + def get_operation_id(self, path, method): + return 'myCustomOperationId' + + path = '/' + method = 'GET' + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = CustomSchema() + inspector.view = view + + operationId = inspector.get_operation_id(path, method) + assert operationId == 'myCustomOperationId' + + def test_operation_id_override_base(self): + class CustomSchema(AutoSchema): + def get_operation_id_base(self, path, method, action): + return 'Item' + + path = '/' + method = 'GET' + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = CustomSchema() + inspector.view = view + + operationId = inspector.get_operation_id(path, method) + assert operationId == 'listItem' + + def test_different_request_response_objects(self): + class RequestSerializer(serializers.Serializer): + text = serializers.CharField() + + class ResponseSerializer(serializers.Serializer): + text = serializers.BooleanField() + + class CustomSchema(AutoSchema): + def get_request_serializer(self, path, method): + return RequestSerializer() + + def get_response_serializer(self, path, method): + return ResponseSerializer() + + path = '/' + method = 'POST' + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = CustomSchema() + inspector.view = view + + components = inspector.get_components(path, method) + assert components == { + 'Request': { + 'properties': { + 'text': { + 'type': 'string' + } + }, + 'required': ['text'], + 'type': 'object' + }, + 'Response': { + 'properties': { + 'text': { + 'type': 'boolean' + } + }, + 'required': ['text'], + 'type': 'object' + } + } + + operation = inspector.get_operation(path, method) + assert operation == { + 'operationId': 'createExample', + 'description': '', + 'parameters': [], + 'requestBody': { + 'content': { + 'application/json': { + 'schema': { + '$ref': '#/components/schemas/Request' + } + }, + 'application/x-www-form-urlencoded': { + 'schema': { + '$ref': '#/components/schemas/Request' + } + }, + 'multipart/form-data': { + 'schema': { + '$ref': '#/components/schemas/Request' + } + } + } + }, + 'responses': { + '201': { + 'content': { + 'application/json': { + 'schema': { + '$ref': '#/components/schemas/Response' + } + } + }, + 'description': '' + } + }, + 'tags': [''] + } + + def test_repeat_operation_ids(self): + router = routers.SimpleRouter() + router.register('account', views.ExampleGenericViewSet, basename="account") + urlpatterns = router.urls + + generator = SchemaGenerator(patterns=urlpatterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + schema_str = str(schema) + print(schema_str) + assert schema_str.count("operationId") == 2 + assert schema_str.count("newExample") == 1 + assert schema_str.count("oldExample") == 1 + + def test_duplicate_operation_id(self): + patterns = [ + path('duplicate1/', views.ExampleOperationIdDuplicate1.as_view()), + path('duplicate2/', views.ExampleOperationIdDuplicate2.as_view()), + ] + + generator = SchemaGenerator(patterns=patterns) + request = create_request('/') + + with warnings.catch_warnings(record=True) as w: + warnings.simplefilter('always') + generator.get_schema(request=request) + + assert len(w) == 1 + assert issubclass(w[-1].category, UserWarning) + print(str(w[-1].message)) + assert 'You have a duplicated operationId' in str(w[-1].message) + + def test_operation_id_viewset(self): + router = routers.SimpleRouter() + router.register('account', views.ExampleViewSet, basename="account") + urlpatterns = router.urls + + generator = SchemaGenerator(patterns=urlpatterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + print(schema) + assert schema['paths']['/account/']['get']['operationId'] == 'listExampleViewSets' + assert schema['paths']['/account/']['post']['operationId'] == 'createExampleViewSet' + assert schema['paths']['/account/{id}/']['get']['operationId'] == 'retrieveExampleViewSet' + assert schema['paths']['/account/{id}/']['put']['operationId'] == 'updateExampleViewSet' + assert schema['paths']['/account/{id}/']['patch']['operationId'] == 'partialUpdateExampleViewSet' + assert schema['paths']['/account/{id}/']['delete']['operationId'] == 'destroyExampleViewSet' + + def test_serializer_datefield(self): + path = '/' + method = 'GET' + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + components = inspector.get_components(path, method) + component = components['Example'] + properties = component['properties'] + assert properties['date']['type'] == properties['datetime']['type'] == 'string' + assert properties['date']['format'] == 'date' + assert properties['datetime']['format'] == 'date-time' + + def test_serializer_hstorefield(self): + path = '/' + method = 'GET' + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + components = inspector.get_components(path, method) + component = components['Example'] + properties = component['properties'] + assert properties['hstore']['type'] == 'object' + + def test_serializer_callable_default(self): + path = '/' + method = 'GET' + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + components = inspector.get_components(path, method) + component = components['Example'] + properties = component['properties'] + assert 'default' not in properties['uuid_field'] + + def test_serializer_validators(self): + path = '/' + method = 'GET' + view = create_view( + views.ExampleValidatedAPIView, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + components = inspector.get_components(path, method) + component = components['ExampleValidated'] + properties = component['properties'] + + assert properties['integer']['type'] == 'integer' + assert properties['integer']['maximum'] == 99 + assert properties['integer']['minimum'] == -11 + + assert properties['string']['minLength'] == 2 + assert properties['string']['maxLength'] == 10 + + assert properties['lst']['minItems'] == 2 + assert properties['lst']['maxItems'] == 10 + + assert properties['regex']['pattern'] == r'[ABC]12{3}' + assert properties['regex']['description'] == 'must have an A, B, or C followed by 1222' + + assert properties['decimal1']['type'] == 'number' + assert properties['decimal1']['multipleOf'] == .01 + assert properties['decimal1']['maximum'] == 10000 + assert properties['decimal1']['minimum'] == -10000 + + assert properties['decimal2']['type'] == 'number' + assert properties['decimal2']['multipleOf'] == .0001 + + assert properties['decimal3'] == { + 'type': 'string', 'format': 'decimal', 'maximum': 1000000, 'minimum': -1000000, 'multipleOf': 0.01 + } + assert properties['decimal4'] == { + 'type': 'string', 'format': 'decimal', 'maximum': 1000000, 'minimum': -1000000, 'multipleOf': 0.01 + } + assert properties['decimal5'] == { + 'type': 'string', 'format': 'decimal', 'maximum': 10000, 'minimum': -10000, 'multipleOf': 0.01 + } + + assert properties['email']['type'] == 'string' + assert properties['email']['format'] == 'email' + assert properties['email']['default'] == 'foo@bar.com' + + assert properties['url']['type'] == 'string' + assert properties['url']['nullable'] is True + assert properties['url']['default'] == 'http://www.example.com' + assert '\\Z' not in properties['url']['pattern'] + + assert properties['uuid']['type'] == 'string' + assert properties['uuid']['format'] == 'uuid' + + assert properties['ip4']['type'] == 'string' + assert properties['ip4']['format'] == 'ipv4' + + assert properties['ip6']['type'] == 'string' + assert properties['ip6']['format'] == 'ipv6' + + assert properties['ip']['type'] == 'string' + assert 'format' not in properties['ip'] + + def test_overridden_tags(self): + class ExampleStringTagsViewSet(views.ExampleGenericAPIView): + schema = AutoSchema(tags=['example1', 'example2']) + + url_patterns = [ + path('test/', ExampleStringTagsViewSet.as_view()), + ] + generator = SchemaGenerator(patterns=url_patterns) + schema = generator.get_schema(request=create_request('/')) + assert schema['paths']['/test/']['get']['tags'] == ['example1', 'example2'] + + def test_overridden_get_tags_method(self): + class MySchema(AutoSchema): + def get_tags(self, path, method): + if path.endswith('/new/'): + tags = ['tag1', 'tag2'] + elif path.endswith('/old/'): + tags = ['tag2', 'tag3'] + else: + tags = ['tag4', 'tag5'] + + return tags + + class ExampleStringTagsViewSet(views.ExampleGenericViewSet): + schema = MySchema() + + router = routers.SimpleRouter() + router.register('example', ExampleStringTagsViewSet, basename="example") + generator = SchemaGenerator(patterns=router.urls) + schema = generator.get_schema(request=create_request('/')) + assert schema['paths']['/example/new/']['get']['tags'] == ['tag1', 'tag2'] + assert schema['paths']['/example/old/']['get']['tags'] == ['tag2', 'tag3'] + + def test_auto_generated_apiview_tags(self): + class RestaurantAPIView(views.ExampleGenericAPIView): + schema = AutoSchema(operation_id_base="restaurant") + pass + + class BranchAPIView(views.ExampleGenericAPIView): + pass + + url_patterns = [ + path('any-dash_underscore/', RestaurantAPIView.as_view()), + path('restaurants/branches/', BranchAPIView.as_view()) + ] + generator = SchemaGenerator(patterns=url_patterns) + schema = generator.get_schema(request=create_request('/')) + assert schema['paths']['/any-dash_underscore/']['get']['tags'] == ['any-dash-underscore'] + assert schema['paths']['/restaurants/branches/']['get']['tags'] == ['restaurants'] + + +@pytest.mark.skipif(uritemplate is None, reason='uritemplate not installed.') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.openapi.AutoSchema'}) +class TestGenerator(TestCase): + + def test_override_settings(self): + assert isinstance(views.ExampleListView.schema, AutoSchema) + + def test_paths_construction(self): + """Construction of the `paths` key.""" + patterns = [ + path('example/', views.ExampleListView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns) + generator._initialise_endpoints() + + paths = generator.get_schema()["paths"] + + assert '/example/' in paths + example_operations = paths['/example/'] + assert len(example_operations) == 2 + assert 'get' in example_operations + assert 'post' in example_operations + + def test_prefixed_paths_construction(self): + """Construction of the `paths` key maintains a common prefix.""" + patterns = [ + path('v1/example/', views.ExampleListView.as_view()), + path('v1/example/{pk}/', views.ExampleDetailView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns) + generator._initialise_endpoints() + + paths = generator.get_schema()["paths"] + + assert '/v1/example/' in paths + assert '/v1/example/{id}/' in paths + + def test_mount_url_prefixed_to_paths(self): + patterns = [ + path('example/', views.ExampleListView.as_view()), + path('example/{pk}/', views.ExampleDetailView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns, url='/api') + generator._initialise_endpoints() + + paths = generator.get_schema()["paths"] + + assert '/api/example/' in paths + assert '/api/example/{id}/' in paths + + def test_schema_construction(self): + """Construction of the top level dictionary.""" + patterns = [ + path('example/', views.ExampleListView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + + assert 'openapi' in schema + assert 'paths' in schema + + def test_schema_rendering_to_json(self): + patterns = [ + path('example/', views.ExampleGenericAPIView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + ret = JSONOpenAPIRenderer().render(schema) + + assert b'"openapi": "' in ret + assert b'"default": "0.0"' in ret + + def test_schema_with_no_paths(self): + patterns = [] + generator = SchemaGenerator(patterns=patterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + + assert schema['paths'] == {} + + def test_schema_information(self): + """Construction of the top level dictionary.""" + patterns = [ + path('example/', views.ExampleListView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns, title='My title', version='1.2.3', description='My description') + + request = create_request('/') + schema = generator.get_schema(request=request) + + assert schema['info']['title'] == 'My title' + assert schema['info']['version'] == '1.2.3' + assert schema['info']['description'] == 'My description' + + def test_schema_information_empty(self): + """Construction of the top level dictionary.""" + patterns = [ + path('example/', views.ExampleListView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + + assert schema['info']['title'] == '' + assert schema['info']['version'] == '' + + def test_serializer_model(self): + """Construction of the top level dictionary.""" + patterns = [ + path('example/', views.ExampleGenericAPIViewModel.as_view()), + ] + + generator = SchemaGenerator(patterns=patterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + + print(schema) + + assert 'components' in schema + assert 'schemas' in schema['components'] + assert 'ExampleModel' in schema['components']['schemas'] + + def test_authtoken_serializer(self): + patterns = [ + path('api-token-auth/', obtain_auth_token) + ] + generator = SchemaGenerator(patterns=patterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + + print(schema) + + route = schema['paths']['/api-token-auth/']['post'] + body_schema = route['requestBody']['content']['application/json']['schema'] + + assert body_schema == { + '$ref': '#/components/schemas/AuthToken' + } + assert schema['components']['schemas']['AuthToken'] == { + 'type': 'object', + 'properties': { + 'username': {'type': 'string', 'writeOnly': True}, + 'password': {'type': 'string', 'writeOnly': True}, + 'token': {'type': 'string', 'readOnly': True}, + }, + 'required': ['username', 'password'] + } + + def test_component_name(self): + patterns = [ + path('example/', views.ExampleAutoSchemaComponentName.as_view()), + ] + + generator = SchemaGenerator(patterns=patterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + + print(schema) + assert 'components' in schema + assert 'schemas' in schema['components'] + assert 'Ulysses' in schema['components']['schemas'] + + def test_duplicate_component_name(self): + patterns = [ + path('duplicate1/', views.ExampleAutoSchemaDuplicate1.as_view()), + path('duplicate2/', views.ExampleAutoSchemaDuplicate2.as_view()), + ] + + generator = SchemaGenerator(patterns=patterns) + request = create_request('/') + + with warnings.catch_warnings(record=True) as w: + warnings.simplefilter('always') + schema = generator.get_schema(request=request) + + assert len(w) == 1 + assert issubclass(w[-1].category, UserWarning) + assert 'has been overriden with a different value.' in str(w[-1].message) + + assert 'components' in schema + assert 'schemas' in schema['components'] + assert 'Duplicate' in schema['components']['schemas'] + + def test_component_should_not_be_generated_for_delete_method(self): + class ExampleView(generics.DestroyAPIView): + schema = AutoSchema(operation_id_base='example') + + url_patterns = [ + path('example/', ExampleView.as_view()), + ] + generator = SchemaGenerator(patterns=url_patterns) + schema = generator.get_schema(request=create_request('/')) + assert 'components' not in schema + assert 'content' not in schema['paths']['/example/']['delete']['responses']['204'] diff --git a/tests/schemas/views.py b/tests/schemas/views.py new file mode 100644 index 000000000..f1ed0bd4e --- /dev/null +++ b/tests/schemas/views.py @@ -0,0 +1,245 @@ +import uuid +from datetime import timedelta + +from django.core.validators import ( + DecimalValidator, MaxLengthValidator, MaxValueValidator, + MinLengthValidator, MinValueValidator, RegexValidator +) +from django.db import models + +from rest_framework import generics, permissions, serializers +from rest_framework.decorators import action +from rest_framework.response import Response +from rest_framework.schemas.openapi import AutoSchema +from rest_framework.views import APIView +from rest_framework.viewsets import GenericViewSet, ViewSet + + +class ExampleListView(APIView): + permission_classes = [permissions.IsAuthenticatedOrReadOnly] + + def get(self, *args, **kwargs): + pass + + def post(self, request, *args, **kwargs): + pass + + +class ExampleDetailView(APIView): + permission_classes = [permissions.IsAuthenticatedOrReadOnly] + + def get(self, *args, **kwargs): + pass + + +class DocStringExampleListView(APIView): + """ + get: A description of my GET operation. + post: A description of my POST operation. + """ + permission_classes = [permissions.IsAuthenticatedOrReadOnly] + + def get(self, *args, **kwargs): + pass + + def post(self, request, *args, **kwargs): + pass + + +class DocStringExampleDetailView(APIView): + permission_classes = [permissions.IsAuthenticatedOrReadOnly] + + def get(self, *args, **kwargs): + """ + A description of my GET operation. + """ + pass + + +# Generics. +class ExampleSerializer(serializers.Serializer): + date = serializers.DateField() + datetime = serializers.DateTimeField() + duration = serializers.DurationField(default=timedelta()) + hstore = serializers.HStoreField() + uuid_field = serializers.UUIDField(default=uuid.uuid4) + + +class ExampleGenericAPIView(generics.GenericAPIView): + serializer_class = ExampleSerializer + + def get(self, *args, **kwargs): + from datetime import datetime + now = datetime.now() + + serializer = self.get_serializer(data=now.date(), datetime=now) + return Response(serializer.data) + + +class ExampleGenericViewSet(GenericViewSet): + serializer_class = ExampleSerializer + + def get(self, *args, **kwargs): + from datetime import datetime + now = datetime.now() + + serializer = self.get_serializer(data=now.date(), datetime=now) + return Response(serializer.data) + + @action(detail=False) + def new(self, *args, **kwargs): + pass + + @action(detail=False) + def old(self, *args, **kwargs): + pass + + +# Validators and/or equivalent Field attributes. +class ExampleValidatedSerializer(serializers.Serializer): + integer = serializers.IntegerField( + validators=( + MaxValueValidator(limit_value=99), + MinValueValidator(limit_value=-11), + ) + ) + string = serializers.CharField( + validators=( + MaxLengthValidator(limit_value=10), + MinLengthValidator(limit_value=2), + ) + ) + regex = serializers.CharField( + validators=( + RegexValidator(regex=r'[ABC]12{3}'), + ), + help_text='must have an A, B, or C followed by 1222' + ) + lst = serializers.ListField( + validators=( + MaxLengthValidator(limit_value=10), + MinLengthValidator(limit_value=2), + ) + ) + decimal1 = serializers.DecimalField(max_digits=6, decimal_places=2, coerce_to_string=False) + decimal2 = serializers.DecimalField(max_digits=5, decimal_places=0, coerce_to_string=False, + validators=(DecimalValidator(max_digits=17, decimal_places=4),)) + decimal3 = serializers.DecimalField(max_digits=8, decimal_places=2, coerce_to_string=True) + decimal4 = serializers.DecimalField(max_digits=8, decimal_places=2, coerce_to_string=True, + validators=(DecimalValidator(max_digits=17, decimal_places=4),)) + decimal5 = serializers.DecimalField(max_digits=6, decimal_places=2) + email = serializers.EmailField(default='foo@bar.com') + url = serializers.URLField(default='http://www.example.com', allow_null=True) + uuid = serializers.UUIDField() + ip4 = serializers.IPAddressField(protocol='ipv4') + ip6 = serializers.IPAddressField(protocol='ipv6') + ip = serializers.IPAddressField() + + +class ExampleValidatedAPIView(generics.GenericAPIView): + serializer_class = ExampleValidatedSerializer + + def get(self, *args, **kwargs): + serializer = self.get_serializer(integer=33, string='hello', regex='foo', decimal1=3.55, + decimal2=5.33, email='a@b.co', + url='http://localhost', uuid=uuid.uuid4(), ip4='127.0.0.1', ip6='::1', + ip='192.168.1.1') + return Response(serializer.data) + + +# Serializer with model. +class OpenAPIExample(models.Model): + first_name = models.CharField(max_length=30) + + +class ExampleSerializerModel(serializers.Serializer): + date = serializers.DateField() + datetime = serializers.DateTimeField() + hstore = serializers.HStoreField() + uuid_field = serializers.UUIDField(default=uuid.uuid4) + + class Meta: + model = OpenAPIExample + + +class ExampleOperationIdDuplicate1(generics.GenericAPIView): + serializer_class = ExampleSerializerModel + + def get(self, *args, **kwargs): + pass + + +class ExampleOperationIdDuplicate2(generics.GenericAPIView): + serializer_class = ExampleSerializerModel + + def get(self, *args, **kwargs): + pass + + +class ExampleGenericAPIViewModel(generics.GenericAPIView): + serializer_class = ExampleSerializerModel + + def get(self, *args, **kwargs): + from datetime import datetime + now = datetime.now() + + serializer = self.get_serializer(data=now.date(), datetime=now) + return Response(serializer.data) + + +class ExampleAutoSchemaComponentName(generics.GenericAPIView): + serializer_class = ExampleSerializerModel + schema = AutoSchema(component_name="Ulysses") + + def get(self, *args, **kwargs): + from datetime import datetime + now = datetime.now() + + serializer = self.get_serializer(data=now.date(), datetime=now) + return Response(serializer.data) + + +class ExampleAutoSchemaDuplicate1(generics.GenericAPIView): + serializer_class = ExampleValidatedSerializer + schema = AutoSchema(component_name="Duplicate") + + def get(self, *args, **kwargs): + from datetime import datetime + now = datetime.now() + + serializer = self.get_serializer(data=now.date(), datetime=now) + return Response(serializer.data) + + +class ExampleAutoSchemaDuplicate2(generics.GenericAPIView): + serializer_class = ExampleSerializerModel + schema = AutoSchema(component_name="Duplicate") + + def get(self, *args, **kwargs): + from datetime import datetime + now = datetime.now() + + serializer = self.get_serializer(data=now.date(), datetime=now) + return Response(serializer.data) + + +class ExampleViewSet(ViewSet): + serializer_class = ExampleSerializerModel + + def list(self, request): + pass + + def create(self, request): + pass + + def retrieve(self, request, pk=None): + pass + + def update(self, request, pk=None): + pass + + def partial_update(self, request, pk=None): + pass + + def destroy(self, request, pk=None): + pass diff --git a/tests/test_api_client.py b/tests/test_api_client.py index e4354ec60..976f10ed1 100644 --- a/tests/test_api_client.py +++ b/tests/test_api_client.py @@ -1,12 +1,10 @@ -from __future__ import unicode_literals - import os import tempfile import unittest -from django.conf.urls import url from django.http import HttpResponse from django.test import override_settings +from django.urls import path, re_path from rest_framework.compat import coreapi, coreschema from rest_framework.parsers import FileUploadParser @@ -180,13 +178,13 @@ class HeadersView(APIView): urlpatterns = [ - url(r'^$', SchemaView.as_view()), - url(r'^example/$', ListView.as_view()), - url(r'^example/(?P[0-9]+)/$', DetailView.as_view()), - url(r'^upload/$', UploadView.as_view()), - url(r'^download/$', DownloadView.as_view()), - url(r'^text/$', TextView.as_view()), - url(r'^headers/$', HeadersView.as_view()), + path('', SchemaView.as_view()), + path('example/', ListView.as_view()), + re_path(r'^example/(?P[0-9]+)/$', DetailView.as_view()), + path('upload/', UploadView.as_view()), + path('download/', DownloadView.as_view()), + path('text/', TextView.as_view()), + path('headers/', HeadersView.as_view()), ] diff --git a/tests/test_atomic_requests.py b/tests/test_atomic_requests.py index bddd480a5..beda5cba1 100644 --- a/tests/test_atomic_requests.py +++ b/tests/test_atomic_requests.py @@ -1,11 +1,9 @@ -from __future__ import unicode_literals - import unittest -from django.conf.urls import url from django.db import connection, connections, transaction from django.http import Http404 from django.test import TestCase, TransactionTestCase, override_settings +from django.urls import path from rest_framework import status from rest_framework.exceptions import APIException @@ -38,7 +36,7 @@ class APIExceptionView(APIView): class NonAtomicAPIExceptionView(APIView): @transaction.non_atomic_requests def dispatch(self, *args, **kwargs): - return super(NonAtomicAPIExceptionView, self).dispatch(*args, **kwargs) + return super().dispatch(*args, **kwargs) def get(self, request, *args, **kwargs): BasicModel.objects.all() @@ -46,7 +44,7 @@ class NonAtomicAPIExceptionView(APIView): urlpatterns = ( - url(r'^$', NonAtomicAPIExceptionView.as_view()), + path('', NonAtomicAPIExceptionView.as_view()), ) @@ -132,6 +130,41 @@ class DBTransactionAPIExceptionTests(TestCase): assert BasicModel.objects.count() == 0 +@unittest.skipUnless( + connection.features.uses_savepoints, + "'atomic' requires transactions and savepoints." +) +class MultiDBTransactionAPIExceptionTests(TestCase): + databases = '__all__' + + def setUp(self): + self.view = APIExceptionView.as_view() + connections.databases['default']['ATOMIC_REQUESTS'] = True + connections.databases['secondary']['ATOMIC_REQUESTS'] = True + + def tearDown(self): + connections.databases['default']['ATOMIC_REQUESTS'] = False + connections.databases['secondary']['ATOMIC_REQUESTS'] = False + + def test_api_exception_rollback_transaction(self): + """ + Transaction is rollbacked by our transaction atomic block. + """ + request = factory.post('/') + num_queries = 4 if connection.features.can_release_savepoints else 3 + with self.assertNumQueries(num_queries): + # 1 - begin savepoint + # 2 - insert + # 3 - rollback savepoint + # 4 - release savepoint + with transaction.atomic(), transaction.atomic(using='secondary'): + response = self.view(request) + assert transaction.get_rollback() + assert transaction.get_rollback(using='secondary') + assert response.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR + assert BasicModel.objects.count() == 0 + + @unittest.skipUnless( connection.features.uses_savepoints, "'atomic' requires transactions and savepoints." diff --git a/tests/test_authtoken.py b/tests/test_authtoken.py index c8957f978..30e416d65 100644 --- a/tests/test_authtoken.py +++ b/tests/test_authtoken.py @@ -1,9 +1,11 @@ +import importlib +from io import StringIO + import pytest from django.contrib.admin import site from django.contrib.auth.models import User from django.core.management import CommandError, call_command -from django.test import TestCase -from django.utils.six import StringIO +from django.test import TestCase, modify_settings from rest_framework.authtoken.admin import TokenAdmin from rest_framework.authtoken.management.commands.drf_create_token import \ @@ -20,6 +22,14 @@ class AuthTokenTests(TestCase): self.user = User.objects.create_user(username='test_user') self.token = Token.objects.create(key='test token', user=self.user) + def test_authtoken_can_be_imported_when_not_included_in_installed_apps(self): + import rest_framework.authtoken.models + with modify_settings(INSTALLED_APPS={'remove': 'rest_framework.authtoken'}): + importlib.reload(rest_framework.authtoken.models) + # Set the proxy and abstract properties back to the version, + # where authtoken is among INSTALLED_APPS. + importlib.reload(rest_framework.authtoken.models) + def test_model_admin_displayed_fields(self): mock_request = object() token_admin = TokenAdmin(self.token, self.site) diff --git a/tests/test_bound_fields.py b/tests/test_bound_fields.py index e588ae623..eee7d9b85 100644 --- a/tests/test_bound_fields.py +++ b/tests/test_bound_fields.py @@ -28,7 +28,7 @@ class TestSimpleBoundField: assert serializer['text'].value == 'abc' assert serializer['text'].errors is None assert serializer['text'].name == 'text' - assert serializer['amount'].value is 123 + assert serializer['amount'].value == 123 assert serializer['amount'].errors is None assert serializer['amount'].name == 'amount' @@ -43,7 +43,7 @@ class TestSimpleBoundField: assert serializer['text'].value == 'x' * 1000 assert serializer['text'].errors == ['Ensure this field has no more than 100 characters.'] assert serializer['text'].name == 'text' - assert serializer['amount'].value is 123 + assert serializer['amount'].value == 123 assert serializer['amount'].errors is None assert serializer['amount'].name == 'amount' @@ -91,6 +91,10 @@ class TestSimpleBoundField: assert rendered_packed == expected_packed +class CustomJSONField(serializers.JSONField): + pass + + class TestNestedBoundField: def test_nested_empty_bound_field(self): class Nested(serializers.Serializer): @@ -117,14 +121,31 @@ class TestNestedBoundField: class Nested(serializers.Serializer): bool_field = serializers.BooleanField() null_field = serializers.IntegerField(allow_null=True) + json_field = serializers.JSONField() + custom_json_field = CustomJSONField() class ExampleSerializer(serializers.Serializer): nested = Nested() - serializer = ExampleSerializer(data={'nested': {'bool_field': False, 'null_field': None}}) + serializer = ExampleSerializer( + data={'nested': { + 'bool_field': False, 'null_field': None, + 'json_field': {'bool_item': True, 'number': 1, 'text_item': 'text'}, + 'custom_json_field': {'bool_item': True, 'number': 1, 'text_item': 'text'}, + }}) assert serializer.is_valid() assert serializer['nested']['bool_field'].as_form_field().value == '' assert serializer['nested']['null_field'].as_form_field().value == '' + assert serializer['nested']['json_field'].as_form_field().value == '''{ + "bool_item": true, + "number": 1, + "text_item": "text" +}''' + assert serializer['nested']['custom_json_field'].as_form_field().value == '''{ + "bool_item": true, + "number": 1, + "text_item": "text" +}''' def test_rendering_nested_fields_with_none_value(self): from rest_framework.renderers import HTMLFormRenderer @@ -163,6 +184,33 @@ class TestNestedBoundField: rendered_packed = ''.join(rendered.split()) assert rendered_packed == expected_packed + def test_rendering_nested_fields_with_not_mappable_value(self): + from rest_framework.renderers import HTMLFormRenderer + + class Nested(serializers.Serializer): + text_field = serializers.CharField() + + class ExampleSerializer(serializers.Serializer): + nested = Nested() + + serializer = ExampleSerializer(data={'nested': 1}) + assert not serializer.is_valid() + renderer = HTMLFormRenderer() + for field in serializer: + rendered = renderer.render_field(field, {}) + expected_packed = ( + '
    ' + 'Nested' + '' + '' + '' + '
    • ' + '' + ) + + rendered_packed = ''.join(rendered.split()) + assert rendered_packed == expected_packed + class TestJSONBoundField: def test_as_form_fields(self): diff --git a/tests/test_decorators.py b/tests/test_decorators.py index 13dd41ff3..99ba13e60 100644 --- a/tests/test_decorators.py +++ b/tests/test_decorators.py @@ -1,14 +1,11 @@ -from __future__ import unicode_literals - import pytest from django.test import TestCase -from rest_framework import RemovedInDRF310Warning, status +from rest_framework import status from rest_framework.authentication import BasicAuthentication from rest_framework.decorators import ( - action, api_view, authentication_classes, detail_route, list_route, - parser_classes, permission_classes, renderer_classes, schema, - throttle_classes + action, api_view, authentication_classes, parser_classes, + permission_classes, renderer_classes, schema, throttle_classes ) from rest_framework.parsers import JSONParser from rest_framework.permissions import IsAuthenticated @@ -25,10 +22,6 @@ class DecoratorTestCase(TestCase): def setUp(self): self.factory = APIRequestFactory() - def _finalize_response(self, request, response, *args, **kwargs): - response.request = request - return APIView.finalize_response(self, request, response, *args, **kwargs) - def test_api_view_incorrect(self): """ If @api_view is not applied correct, we should raise an assertion. @@ -204,8 +197,7 @@ class ActionDecoratorTestCase(TestCase): def method(): raise NotImplementedError - # Python 2.x compatibility - cast __name__ to str - method.__name__ = str(name) + method.__name__ = name getattr(test_action.mapping, name)(method) # ensure the mapping returns the correct method name @@ -288,39 +280,3 @@ class ActionDecoratorTestCase(TestCase): @test_action.mapping.post def test_action(): raise NotImplementedError - - def test_detail_route_deprecation(self): - with pytest.warns(RemovedInDRF310Warning) as record: - @detail_route() - def view(request): - raise NotImplementedError - - assert len(record) == 1 - assert str(record[0].message) == ( - "`detail_route` is deprecated and will be removed in " - "3.10 in favor of `action`, which accepts a `detail` bool. Use " - "`@action(detail=True)` instead." - ) - - def test_list_route_deprecation(self): - with pytest.warns(RemovedInDRF310Warning) as record: - @list_route() - def view(request): - raise NotImplementedError - - assert len(record) == 1 - assert str(record[0].message) == ( - "`list_route` is deprecated and will be removed in " - "3.10 in favor of `action`, which accepts a `detail` bool. Use " - "`@action(detail=False)` instead." - ) - - def test_route_url_name_from_path(self): - # pre-3.8 behavior was to base the `url_name` off of the `url_path` - with pytest.warns(RemovedInDRF310Warning): - @list_route(url_path='foo_bar') - def view(request): - raise NotImplementedError - - assert view.url_path == 'foo_bar' - assert view.url_name == 'foo-bar' diff --git a/tests/test_description.py b/tests/test_description.py index 702e56332..ecc6b9776 100644 --- a/tests/test_description.py +++ b/tests/test_description.py @@ -1,197 +1,155 @@ -# -- coding: utf-8 -- - -from __future__ import unicode_literals - -from django.test import TestCase -from django.utils.encoding import python_2_unicode_compatible - -from rest_framework.compat import apply_markdown -from rest_framework.utils.formatting import dedent -from rest_framework.views import APIView - -# We check that docstrings get nicely un-indented. -DESCRIPTION = """an example docstring -==================== - -* list -* list - -another header --------------- - - code block - -indented - -# hash style header # - -``` json -[{ - "alpha": 1, - "beta: "this is a string" -}] -```""" - - -# If markdown is installed we also test it's working -# (and that our wrapped forces '=' to h2 and '-' to h3) -MARKED_DOWN_HILITE = """ -
    [{
        "alpha": 1,
    \
-    "beta: "this\
- is a \
-string"
    }]
    - -


    """ - -MARKED_DOWN_NOT_HILITE = """ -

    json -[{ - "alpha": 1, - "beta: "this is a string" -}]

    """ - -# We support markdown < 2.1 and markdown >= 2.1 -MARKED_DOWN_lt_21 = """

    an example docstring

    -
      -
    • list
      • -
    • list
      • -
    -

    another header

    -
    code block
-
    -

    indented

    -

    hash style header

    %s""" - -MARKED_DOWN_gte_21 = """

    an example docstring

    -
      -
    • list
      • -
    • list
      • -
    -

    another header

    -
    code block
-
    -

    indented

    -

    hash style header

    %s""" - - -class TestViewNamesAndDescriptions(TestCase): - def test_view_name_uses_class_name(self): - """ - Ensure view names are based on the class name. - """ - class MockView(APIView): - pass - assert MockView().get_view_name() == 'Mock' - - def test_view_name_uses_name_attribute(self): - class MockView(APIView): - name = 'Foo' - assert MockView().get_view_name() == 'Foo' - - def test_view_name_uses_suffix_attribute(self): - class MockView(APIView): - suffix = 'List' - assert MockView().get_view_name() == 'Mock List' - - def test_view_name_preferences_name_over_suffix(self): - class MockView(APIView): - name = 'Foo' - suffix = 'List' - assert MockView().get_view_name() == 'Foo' - - def test_view_description_uses_docstring(self): - """Ensure view descriptions are based on the docstring.""" - class MockView(APIView): - """an example docstring - ==================== - - * list - * list - - another header - -------------- - - code block - - indented - - # hash style header # - - ``` json - [{ - "alpha": 1, - "beta: "this is a string" - }] - ```""" - - assert MockView().get_view_description() == DESCRIPTION - - def test_view_description_uses_description_attribute(self): - class MockView(APIView): - description = 'Foo' - assert MockView().get_view_description() == 'Foo' - - def test_view_description_allows_empty_description(self): - class MockView(APIView): - """Description.""" - description = '' - assert MockView().get_view_description() == '' - - def test_view_description_can_be_empty(self): - """ - Ensure that if a view has no docstring, - then it's description is the empty string. - """ - class MockView(APIView): - pass - assert MockView().get_view_description() == '' - - def test_view_description_can_be_promise(self): - """ - Ensure a view may have a docstring that is actually a lazily evaluated - class that can be converted to a string. - - See: https://github.com/encode/django-rest-framework/issues/1708 - """ - # use a mock object instead of gettext_lazy to ensure that we can't end - # up with a test case string in our l10n catalog - @python_2_unicode_compatible - class MockLazyStr(object): - def __init__(self, string): - self.s = string - - def __str__(self): - return self.s - - class MockView(APIView): - __doc__ = MockLazyStr("a gettext string") - - assert MockView().get_view_description() == 'a gettext string' - - def test_markdown(self): - """ - Ensure markdown to HTML works as expected. - """ - if apply_markdown: - md_applied = apply_markdown(DESCRIPTION) - gte_21_match = ( - md_applied == ( - MARKED_DOWN_gte_21 % MARKED_DOWN_HILITE) or - md_applied == ( - MARKED_DOWN_gte_21 % MARKED_DOWN_NOT_HILITE)) - lt_21_match = ( - md_applied == ( - MARKED_DOWN_lt_21 % MARKED_DOWN_HILITE) or - md_applied == ( - MARKED_DOWN_lt_21 % MARKED_DOWN_NOT_HILITE)) - assert gte_21_match or lt_21_match - - -def test_dedent_tabs(): - result = 'first string\n\nsecond string' - assert dedent(" first string\n\n second string") == result - assert dedent("first string\n\n second string") == result - assert dedent("\tfirst string\n\n\tsecond string") == result - assert dedent("first string\n\n\tsecond string") == result +import pytest +from django.test import TestCase + +from rest_framework.compat import apply_markdown +from rest_framework.utils.formatting import dedent +from rest_framework.views import APIView + +# We check that docstrings get nicely un-indented. +DESCRIPTION = """an example docstring +==================== + +* list +* list + +another header +-------------- + + code block + +indented + +# hash style header # + +```json +[{ + "alpha": 1, + "beta": "this is a string" +}] +```""" + + +# If markdown is installed we also test it's working +# (and that our wrapped forces '=' to h2 and '-' to h3) +MARKDOWN_DOCSTRING = """

    an example docstring

    +
      +
    • list
      • +
    • list
      • +
    +

    another header

    +
    code block
+
    +

    indented

    +

    hash style header

    +
    [{
        "alpha": 1,
        "beta": "this is a string"
    }]
    +


    """ + + +class TestViewNamesAndDescriptions(TestCase): + def test_view_name_uses_class_name(self): + """ + Ensure view names are based on the class name. + """ + class MockView(APIView): + pass + assert MockView().get_view_name() == 'Mock' + + def test_view_name_uses_name_attribute(self): + class MockView(APIView): + name = 'Foo' + assert MockView().get_view_name() == 'Foo' + + def test_view_name_uses_suffix_attribute(self): + class MockView(APIView): + suffix = 'List' + assert MockView().get_view_name() == 'Mock List' + + def test_view_name_preferences_name_over_suffix(self): + class MockView(APIView): + name = 'Foo' + suffix = 'List' + assert MockView().get_view_name() == 'Foo' + + def test_view_description_uses_docstring(self): + """Ensure view descriptions are based on the docstring.""" + class MockView(APIView): + """an example docstring + ==================== + + * list + * list + + another header + -------------- + + code block + + indented + + # hash style header # + + ```json + [{ + "alpha": 1, + "beta": "this is a string" + }] + ```""" + + assert MockView().get_view_description() == DESCRIPTION + + def test_view_description_uses_description_attribute(self): + class MockView(APIView): + description = 'Foo' + assert MockView().get_view_description() == 'Foo' + + def test_view_description_allows_empty_description(self): + class MockView(APIView): + """Description.""" + description = '' + assert MockView().get_view_description() == '' + + def test_view_description_can_be_empty(self): + """ + Ensure that if a view has no docstring, + then it's description is the empty string. + """ + class MockView(APIView): + pass + assert MockView().get_view_description() == '' + + def test_view_description_can_be_promise(self): + """ + Ensure a view may have a docstring that is actually a lazily evaluated + class that can be converted to a string. + + See: https://github.com/encode/django-rest-framework/issues/1708 + """ + # use a mock object instead of gettext_lazy to ensure that we can't end + # up with a test case string in our l10n catalog + + class MockLazyStr: + def __init__(self, string): + self.s = string + + def __str__(self): + return self.s + + class MockView(APIView): + __doc__ = MockLazyStr("a gettext string") + + assert MockView().get_view_description() == 'a gettext string' + + @pytest.mark.skipif(not apply_markdown, reason="Markdown is not installed") + def test_markdown(self): + """ + Ensure markdown to HTML works as expected. + """ + assert apply_markdown(DESCRIPTION) == MARKDOWN_DOCSTRING + + +def test_dedent_tabs(): + result = 'first string\n\nsecond string' + assert dedent(" first string\n\n second string") == result + assert dedent("first string\n\n second string") == result + assert dedent("\tfirst string\n\n\tsecond string") == result + assert dedent("first string\n\n\tsecond string") == result diff --git a/tests/test_encoders.py b/tests/test_encoders.py index 12eca8105..953e5564b 100644 --- a/tests/test_encoders.py +++ b/tests/test_encoders.py @@ -1,16 +1,18 @@ -from datetime import date, datetime, timedelta +from datetime import date, datetime, timedelta, timezone from decimal import Decimal from uuid import uuid4 import pytest from django.test import TestCase -from django.utils.timezone import utc from rest_framework.compat import coreapi from rest_framework.utils.encoders import JSONEncoder +from rest_framework.utils.serializer_helpers import ReturnList + +utc = timezone.utc -class MockList(object): +class MockList: def tolist(self): return [1, 2, 3] @@ -93,3 +95,10 @@ class JSONEncoderTests(TestCase): """ foo = MockList() assert self.encoder.default(foo) == [1, 2, 3] + + def test_encode_empty_returnlist(self): + """ + Tests encoding an empty ReturnList + """ + foo = ReturnList(serializer=None) + assert self.encoder.default(foo) == [] diff --git a/tests/test_exceptions.py b/tests/test_exceptions.py index ce0ed8514..9516bfec9 100644 --- a/tests/test_exceptions.py +++ b/tests/test_exceptions.py @@ -1,9 +1,6 @@ -# -*- coding: utf-8 -*- -from __future__ import unicode_literals - from django.test import RequestFactory, TestCase -from django.utils import six, translation -from django.utils.translation import ugettext_lazy as _ +from django.utils import translation +from django.utils.translation import gettext_lazy as _ from rest_framework.exceptions import ( APIException, ErrorDetail, Throttled, _get_error_details, bad_request, @@ -46,12 +43,12 @@ class ExceptionTestCase(TestCase): exception = Throttled(wait=2) assert exception.get_full_details() == { - 'message': 'Request was throttled. Expected available in {} seconds.'.format(2 if six.PY3 else 2.), + 'message': 'Request was throttled. Expected available in {} seconds.'.format(2), 'code': 'throttled'} exception = Throttled(wait=2, detail='Slow down!') assert exception.get_full_details() == { - 'message': 'Slow down! Expected available in {} seconds.'.format(2 if six.PY3 else 2.), + 'message': 'Slow down! Expected available in {} seconds.'.format(2), 'code': 'throttled'} @@ -92,7 +89,7 @@ class TranslationTests(TestCase): def test_message(self): # this test largely acts as a sanity test to ensure the translation files are present. self.assertEqual(_('A server error occurred.'), 'Une erreur du serveur est survenue.') - self.assertEqual(six.text_type(APIException()), 'Une erreur du serveur est survenue.') + self.assertEqual(str(APIException()), 'Une erreur du serveur est survenue.') def test_server_error(): diff --git a/tests/test_fields.py b/tests/test_fields.py index 1e5a25cba..3112fc2cc 100644 --- a/tests/test_fields.py +++ b/tests/test_fields.py @@ -1,7 +1,6 @@ import datetime import os import re -import unittest import uuid from decimal import ROUND_DOWN, ROUND_UP, Decimal @@ -10,23 +9,20 @@ import pytz from django.core.exceptions import ValidationError as DjangoValidationError from django.http import QueryDict from django.test import TestCase, override_settings -from django.utils import six -from django.utils.timezone import activate, deactivate, override, utc +from django.utils.timezone import activate, deactivate, override import rest_framework from rest_framework import exceptions, serializers -from rest_framework.compat import ProhibitNullCharactersValidator -from rest_framework.fields import DjangoImageField, is_simple_callable - -try: - import typings -except ImportError: - typings = False +from rest_framework.fields import ( + BuiltinSignatureError, DjangoImageField, is_simple_callable +) +utc = datetime.timezone.utc # Tests for helper functions. # --------------------------- + class TestIsSimpleCallable: def test_method(self): @@ -79,6 +75,10 @@ class TestIsSimpleCallable: assert is_simple_callable(valid_vargs_kwargs) assert not is_simple_callable(invalid) + @pytest.mark.parametrize('obj', (True, None, "str", b'bytes', 123, 1.23)) + def test_not_callable(self, obj): + assert not is_simple_callable(obj) + def test_4602_regression(self): from django.db import models @@ -93,11 +93,23 @@ class TestIsSimpleCallable: assert is_simple_callable(ChoiceModel().get_choice_field_display) - @unittest.skipUnless(typings, 'requires python 3.5') + def test_builtin_function(self): + # Built-in function signatures are not easily inspectable, so the + # current expectation is to just raise a helpful error message. + timestamp = datetime.datetime.now() + + with pytest.raises(BuiltinSignatureError) as exc_info: + is_simple_callable(timestamp.date) + + assert str(exc_info.value) == ( + 'Built-in function signatures are not inspectable. Wrap the ' + 'function call in a simple, pure Python function.') + def test_type_annotation(self): # The annotation will otherwise raise a syntax error in python < 3.5 - exec("def valid(param: str='value'): pass", locals()) - valid = locals()['valid'] + locals = {} + exec("def valid(param: str='value'): pass", locals) + valid = locals['valid'] assert is_simple_callable(valid) @@ -166,7 +178,7 @@ class TestEmpty: """ field = serializers.IntegerField(default=123) output = field.run_validation() - assert output is 123 + assert output == 123 class TestSource: @@ -192,7 +204,7 @@ class TestSource: class ExampleSerializer(serializers.Serializer): example_field = serializers.CharField(source='example_callable') - class ExampleInstance(object): + class ExampleInstance: def example_callable(self): return 'example callable value' @@ -203,7 +215,7 @@ class TestSource: class ExampleSerializer(serializers.Serializer): example_field = serializers.CharField(source='example_callable', read_only=True) - class ExampleInstance(object): + class ExampleInstance: def example_callable(self): raise AttributeError('method call failed') @@ -213,9 +225,21 @@ class TestSource: assert 'method call failed' in str(exc_info.value) + def test_builtin_callable_source_raises(self): + class BuiltinSerializer(serializers.Serializer): + date = serializers.ReadOnlyField(source='timestamp.date') + + with pytest.raises(BuiltinSignatureError) as exc_info: + BuiltinSerializer({'timestamp': datetime.datetime.now()}).data + + assert str(exc_info.value) == ( + 'Field source for `BuiltinSerializer.date` maps to a built-in ' + 'function type and is invalid. Define a property or method on ' + 'the `dict` instance that wraps the call to the built-in function.') + class TestReadOnly: - def setup(self): + def setup_method(self): class TestSerializer(serializers.Serializer): read_only = serializers.ReadOnlyField(default="789") writable = serializers.IntegerField() @@ -226,7 +250,7 @@ class TestReadOnly: Read-only fields should not be writable, even with default () """ serializer = self.Serializer() - assert len(serializer._writable_fields) == 1 + assert len(list(serializer._writable_fields)) == 1 def test_validate_read_only(self): """ @@ -247,7 +271,7 @@ class TestReadOnly: class TestWriteOnly: - def setup(self): + def setup_method(self): class TestSerializer(serializers.Serializer): write_only = serializers.IntegerField(write_only=True) readable = serializers.IntegerField() @@ -272,7 +296,7 @@ class TestWriteOnly: class TestInitial: - def setup(self): + def setup_method(self): class TestSerializer(serializers.Serializer): initial_field = serializers.IntegerField(initial=123) blank_field = serializers.IntegerField() @@ -289,7 +313,7 @@ class TestInitial: class TestInitialWithCallable: - def setup(self): + def setup_method(self): def initial_value(): return 123 @@ -307,7 +331,7 @@ class TestInitialWithCallable: class TestLabel: - def setup(self): + def setup_method(self): class TestSerializer(serializers.Serializer): labeled = serializers.IntegerField(label='My label') self.serializer = TestSerializer() @@ -321,7 +345,7 @@ class TestLabel: class TestInvalidErrorKey: - def setup(self): + def setup_method(self): class ExampleField(serializers.Field): def to_native(self, data): self.fail('incorrect') @@ -515,7 +539,7 @@ class TestHTMLInput: class TestCreateOnlyDefault: - def setup(self): + def setup_method(self): default = serializers.CreateOnlyDefault('2001-01-01') class TestSerializer(serializers.Serializer): @@ -542,15 +566,14 @@ class TestCreateOnlyDefault: def test_create_only_default_callable_sets_context(self): """ - CreateOnlyDefault instances with a callable default should set_context + CreateOnlyDefault instances with a callable default should set context on the callable if possible """ class TestCallableDefault: - def set_context(self, serializer_field): - self.field = serializer_field + requires_context = True - def __call__(self): - return "success" if hasattr(self, 'field') else "failure" + def __call__(self, field=None): + return "success" if field is not None else "failure" class TestSerializer(serializers.Serializer): context_set = serializers.CharField(default=serializers.CreateOnlyDefault(TestCallableDefault())) @@ -652,13 +675,13 @@ class TestBooleanField(FieldValues): for input_value in inputs: with pytest.raises(serializers.ValidationError) as exc_info: field.run_validation(input_value) - expected = ['Must be a valid boolean.'.format(input_value)] + expected = ['Must be a valid boolean.'] assert exc_info.value.detail == expected -class TestNullBooleanField(TestBooleanField): +class TestNullableBooleanField(TestBooleanField): """ - Valid and invalid values for `NullBooleanField`. + Valid and invalid values for `BooleanField` when `allow_null=True`. """ valid_inputs = { 'true': True, @@ -680,17 +703,7 @@ class TestNullBooleanField(TestBooleanField): None: None, 'other': True } - field = serializers.NullBooleanField() - - -class TestNullableBooleanField(TestNullBooleanField): - """ - Valid and invalid values for `BooleanField` when `allow_null=True`. - """ - - @property - def field(self): - return serializers.BooleanField(allow_null=True) + field = serializers.BooleanField(allow_null=True) # String types... @@ -729,7 +742,6 @@ class TestCharField(FieldValues): field.run_validation(' ') assert exc_info.value.detail == ['This field may not be blank.'] - @pytest.mark.skipif(ProhibitNullCharactersValidator is None, reason="Skipped on Django < 2.0") def test_null_bytes(self): field = serializers.CharField() @@ -740,6 +752,21 @@ class TestCharField(FieldValues): 'Null characters are not allowed.' ] + def test_surrogate_characters(self): + field = serializers.CharField() + + for code_point, expected_message in ( + (0xD800, 'Surrogate characters are not allowed: U+D800.'), + (0xDFFF, 'Surrogate characters are not allowed: U+DFFF.'), + ): + with pytest.raises(serializers.ValidationError) as exc_info: + field.run_validation(chr(code_point)) + assert exc_info.value.detail[0].code == 'surrogate_characters_not_allowed' + assert str(exc_info.value.detail[0]) == expected_message + + for code_point in (0xD800 - 1, 0xDFFF + 1): + field.run_validation(chr(code_point)) + def test_iterable_validators(self): """ Ensure `validators` parameter is compatible with reasonable iterables. @@ -753,7 +780,7 @@ class TestCharField(FieldValues): def raise_exception(value): raise exceptions.ValidationError('Raised error') - for validators in ([raise_exception], (raise_exception,), set([raise_exception])): + for validators in ([raise_exception], (raise_exception,), {raise_exception}): field = serializers.CharField(validators=validators) with pytest.raises(serializers.ValidationError) as exc_info: field.run_validation(value) @@ -821,7 +848,7 @@ class TestSlugField(FieldValues): validation_error = False try: - field.run_validation(u'slug-99-\u0420') + field.run_validation('slug-99-\u0420') except serializers.ValidationError: validation_error = True @@ -1059,8 +1086,12 @@ class TestDecimalField(FieldValues): '2E+1': Decimal('20'), } invalid_inputs = ( + (None, ["This field may not be null."]), + ('', ["A valid number is required."]), + (' ', ["A valid number is required."]), ('abc', ["A valid number is required."]), (Decimal('Nan'), ["A valid number is required."]), + (Decimal('Snan'), ["A valid number is required."]), (Decimal('Inf'), ["A valid number is required."]), ('12.345', ["Ensure that there are no more than 3 digits in total."]), (200000000000.0, ["Ensure that there are no more than 3 digits in total."]), @@ -1083,6 +1114,32 @@ class TestDecimalField(FieldValues): field = serializers.DecimalField(max_digits=3, decimal_places=1) +class TestAllowNullDecimalField(FieldValues): + valid_inputs = { + None: None, + '': None, + ' ': None, + } + invalid_inputs = {} + outputs = { + None: '', + } + field = serializers.DecimalField(max_digits=3, decimal_places=1, allow_null=True) + + +class TestAllowNullNoStringCoercionDecimalField(FieldValues): + valid_inputs = { + None: None, + '': None, + ' ': None, + } + invalid_inputs = {} + outputs = { + None: None, + } + field = serializers.DecimalField(max_digits=3, decimal_places=1, allow_null=True, coerce_to_string=False) + + class TestMinMaxDecimalField(FieldValues): """ Valid and invalid values for `DecimalField` with min and max limits. @@ -1102,6 +1159,30 @@ class TestMinMaxDecimalField(FieldValues): ) +class TestAllowEmptyStrDecimalFieldWithValidators(FieldValues): + """ + Check that empty string ('', ' ') is acceptable value for the DecimalField + if allow_null=True and there are max/min validators + """ + valid_inputs = { + None: None, + '': None, + ' ': None, + ' ': None, + 5: Decimal('5'), + '0': Decimal('0'), + '10': Decimal('10'), + } + invalid_inputs = { + -1: ['Ensure this value is greater than or equal to 0.'], + 11: ['Ensure this value is less than or equal to 10.'], + } + outputs = { + None: '', + } + field = serializers.DecimalField(max_digits=3, decimal_places=1, allow_null=True, min_value=0, max_value=10) + + class TestNoMaxDigitsDecimalField(FieldValues): field = serializers.DecimalField( max_value=100, min_value=0, @@ -1135,19 +1216,19 @@ class TestNoStringCoercionDecimalField(FieldValues): class TestLocalizedDecimalField(TestCase): - @override_settings(USE_L10N=True, LANGUAGE_CODE='pl') + @override_settings(LANGUAGE_CODE='pl') def test_to_internal_value(self): field = serializers.DecimalField(max_digits=2, decimal_places=1, localize=True) assert field.to_internal_value('1,1') == Decimal('1.1') - @override_settings(USE_L10N=True, LANGUAGE_CODE='pl') + @override_settings(LANGUAGE_CODE='pl') def test_to_representation(self): field = serializers.DecimalField(max_digits=2, decimal_places=1, localize=True) assert field.to_representation(Decimal('1.1')) == '1,1' def test_localize_forces_coerce_to_string(self): field = serializers.DecimalField(max_digits=2, decimal_places=1, coerce_to_string=False, localize=True) - assert isinstance(field.to_representation(Decimal('1.1')), six.string_types) + assert isinstance(field.to_representation(Decimal('1.1')), str) class TestQuantizedValueForDecimal(TestCase): @@ -1239,7 +1320,7 @@ class TestDateField(FieldValues): outputs = { datetime.date(2001, 1, 1): '2001-01-01', '2001-01-01': '2001-01-01', - six.text_type('2016-01-10'): '2016-01-10', + str('2016-01-10'): '2016-01-10', None: None, '': None, } @@ -1306,7 +1387,7 @@ class TestDateTimeField(FieldValues): datetime.datetime(2001, 1, 1, 13, 00): '2001-01-01T13:00:00Z', datetime.datetime(2001, 1, 1, 13, 00, tzinfo=utc): '2001-01-01T13:00:00Z', '2001-01-01T00:00:00': '2001-01-01T00:00:00', - six.text_type('2016-01-10T00:00:00'): '2016-01-10T00:00:00', + str('2016-01-10T00:00:00'): '2016-01-10T00:00:00', None: None, '': None, } @@ -1400,15 +1481,24 @@ class TestDefaultTZDateTimeField(TestCase): cls.field = serializers.DateTimeField() cls.kolkata = pytz.timezone('Asia/Kolkata') + def assertUTC(self, tzinfo): + """ + Check UTC for datetime.timezone, ZoneInfo, and pytz tzinfo instances. + """ + assert ( + tzinfo is utc or + (getattr(tzinfo, "key", None) or getattr(tzinfo, "zone", None)) == "UTC" + ) + def test_default_timezone(self): - assert self.field.default_timezone() == utc + self.assertUTC(self.field.default_timezone()) def test_current_timezone(self): - assert self.field.default_timezone() == utc + self.assertUTC(self.field.default_timezone()) activate(self.kolkata) assert self.field.default_timezone() == self.kolkata deactivate() - assert self.field.default_timezone() == utc + self.assertUTC(self.field.default_timezone()) @pytest.mark.skipif(pytz is None, reason='pytz not installed') @@ -1445,7 +1535,7 @@ class TestNaiveDayLightSavingTimeTimeZoneDateTimeField(FieldValues): } outputs = {} - class MockTimezone: + class MockTimezone(pytz.BaseTzInfo): @staticmethod def localize(value, is_dst): raise pytz.InvalidTimeError() @@ -1648,7 +1738,7 @@ class TestChoiceField(FieldValues): ] ) field.choices = [1] - assert field.run_validation(1) is 1 + assert field.run_validation(1) == 1 with pytest.raises(serializers.ValidationError) as exc_info: field.run_validation(2) assert exc_info.value.detail == ['"2" is not a valid choice.'] @@ -1786,9 +1876,9 @@ class TestMultipleChoiceField(FieldValues): def test_against_partial_and_full_updates(self): field = serializers.MultipleChoiceField(choices=(('a', 'a'), ('b', 'b'))) field.partial = False - assert field.get_value(QueryDict({})) == [] + assert field.get_value(QueryDict('')) == [] field.partial = True - assert field.get_value(QueryDict({})) == rest_framework.fields.empty + assert field.get_value(QueryDict('')) == rest_framework.fields.empty class TestEmptyMultipleChoiceField(FieldValues): @@ -1946,6 +2036,11 @@ class TestListField(FieldValues): field.to_internal_value(input_value) assert exc_info.value.detail == ['Expected a list of items but got type "dict".'] + def test_constructor_misuse_raises(self): + # Test that `ListField` can only be instantiated with keyword arguments + with pytest.raises(TypeError): + serializers.ListField(serializers.CharField()) + class TestNestedListField(FieldValues): """ @@ -2010,6 +2105,7 @@ class TestDictField(FieldValues): """ valid_inputs = [ ({'a': 1, 'b': '2', 3: 3}, {'a': '1', 'b': '2', '3': '3'}), + ({}, {}), ] invalid_inputs = [ ({'a': 1, 'b': None, 'c': None}, {'b': ['This field may not be null.'], 'c': ['This field may not be null.']}), @@ -2037,6 +2133,16 @@ class TestDictField(FieldValues): output = field.run_validation(None) assert output is None + def test_allow_empty_disallowed(self): + """ + If allow_empty is False then an empty dict is not a valid input. + """ + field = serializers.DictField(allow_empty=False) + with pytest.raises(serializers.ValidationError) as exc_info: + field.run_validation({}) + + assert exc_info.value.detail == ['This dictionary may not be empty.'] + class TestNestedDictField(FieldValues): """ @@ -2195,8 +2301,8 @@ class TestBinaryJSONField(FieldValues): field = serializers.JSONField(binary=True) -# Tests for FieldField. -# --------------------- +# Tests for FileField. +# -------------------- class MockRequest: def build_absolute_uri(self, value): @@ -2229,19 +2335,30 @@ class TestSerializerMethodField: } def test_redundant_method_name(self): + # Prior to v3.10, redundant method names were not allowed. + # This restriction has since been removed. class ExampleSerializer(serializers.Serializer): example_field = serializers.SerializerMethodField('get_example_field') - with pytest.raises(AssertionError) as exc_info: - ExampleSerializer().fields - assert str(exc_info.value) == ( - "It is redundant to specify `get_example_field` on " - "SerializerMethodField 'example_field' in serializer " - "'ExampleSerializer', because it is the same as the default " - "method name. Remove the `method_name` argument." - ) + field = ExampleSerializer().fields['example_field'] + assert field.method_name == 'get_example_field' +# Tests for ModelField. +# --------------------- + +class TestModelField: + def test_max_length_init(self): + field = serializers.ModelField(None) + assert len(field.validators) == 0 + + field = serializers.ModelField(None, max_length=10) + assert len(field.validators) == 1 + + +# Tests for validation errors +# --------------------------- + class TestValidationErrorCode: @pytest.mark.parametrize('use_list', (False, True)) def test_validationerror_code_with_msg(self, use_list): @@ -2250,14 +2367,33 @@ class TestValidationErrorCode: password = serializers.CharField() def validate_password(self, obj): - err = DjangoValidationError('exc_msg', code='exc_code') + err = DjangoValidationError( + 'exc_msg %s', code='exc_code', params=('exc_param',), + ) if use_list: err = DjangoValidationError([err]) raise err serializer = ExampleSerializer(data={'password': 123}) serializer.is_valid() - assert serializer.errors == {'password': ['exc_msg']} + assert serializer.errors == {'password': ['exc_msg exc_param']} + assert serializer.errors['password'][0].code == 'exc_code' + + @pytest.mark.parametrize('use_list', (False, True)) + def test_validationerror_code_with_msg_including_percent(self, use_list): + + class ExampleSerializer(serializers.Serializer): + password = serializers.CharField() + + def validate_password(self, obj): + err = DjangoValidationError('exc_msg with %', code='exc_code') + if use_list: + err = DjangoValidationError([err]) + raise err + + serializer = ExampleSerializer(data={'password': 123}) + serializer.is_valid() + assert serializer.errors == {'password': ['exc_msg with %']} assert serializer.errors['password'][0].code == 'exc_code' @pytest.mark.parametrize('code', (None, 'exc_code',)) diff --git a/tests/test_filters.py b/tests/test_filters.py index 088d25436..37ae4c7cf 100644 --- a/tests/test_filters.py +++ b/tests/test_filters.py @@ -1,14 +1,13 @@ -from __future__ import unicode_literals - import datetime +from importlib import reload as reload_module import pytest from django.core.exceptions import ImproperlyConfigured from django.db import models +from django.db.models import CharField, Transform from django.db.models.functions import Concat, Upper from django.test import TestCase from django.test.utils import override_settings -from django.utils.six.moves import reload_module from rest_framework import filters, generics, serializers from rest_framework.compat import coreschema @@ -163,7 +162,7 @@ class SearchFilterTests(TestCase): def get_search_fields(self, view, request): if request.query_params.get('title_only'): return ('$title',) - return super(CustomSearchFilter, self).get_search_fields(view, request) + return super().get_search_fields(view, request) class SearchListView(generics.ListAPIView): queryset = SearchFilterModel.objects.all() @@ -172,16 +171,60 @@ class SearchFilterTests(TestCase): search_fields = ('$title', '$text') view = SearchListView.as_view() - request = factory.get('/', {'search': '^\w{3}$'}) + request = factory.get('/', {'search': r'^\w{3}$'}) response = view(request) assert len(response.data) == 10 - request = factory.get('/', {'search': '^\w{3}$', 'title_only': 'true'}) + request = factory.get('/', {'search': r'^\w{3}$', 'title_only': 'true'}) response = view(request) assert response.data == [ {'id': 3, 'title': 'zzz', 'text': 'cde'} ] + def test_search_field_with_null_characters(self): + view = generics.GenericAPIView() + request = factory.get('/?search=\0as%00d\x00f') + request = view.initialize_request(request) + + terms = filters.SearchFilter().get_search_terms(request) + + assert terms == ['asdf'] + + def test_search_field_with_additional_transforms(self): + from django.test.utils import register_lookup + + class SearchListView(generics.ListAPIView): + queryset = SearchFilterModel.objects.all() + serializer_class = SearchFilterSerializer + filter_backends = (filters.SearchFilter,) + search_fields = ('text__trim', ) + + view = SearchListView.as_view() + + # an example custom transform, that trims `a` from the string. + class TrimA(Transform): + function = 'TRIM' + lookup_name = 'trim' + + def as_sql(self, compiler, connection): + sql, params = compiler.compile(self.lhs) + return "trim(%s, 'a')" % sql, params + + with register_lookup(CharField, TrimA): + # Search including `a` + request = factory.get('/', {'search': 'abc'}) + + response = view(request) + assert response.data == [] + + # Search excluding `a` + request = factory.get('/', {'search': 'bc'}) + response = view(request) + assert response.data == [ + {'id': 1, 'title': 'z', 'text': 'abc'}, + {'id': 2, 'title': 'zz', 'text': 'bcd'}, + ] + class AttributeModel(models.Model): label = models.CharField(max_length=32) @@ -361,11 +404,30 @@ class SearchFilterAnnotatedFieldTests(TestCase): assert len(response.data) == 1 assert response.data[0]['title_text'] == 'ABCDEF' + def test_must_call_distinct_subsequent_m2m_fields(self): + f = filters.SearchFilter() + + queryset = SearchFilterModelM2M.objects.annotate( + title_text=Upper( + Concat(models.F('title'), models.F('text')) + ) + ).all() + + # Sanity check that m2m must call distinct + assert f.must_call_distinct(queryset, ['attributes']) + + # Annotated field should not prevent m2m must call distinct + assert f.must_call_distinct(queryset, ['title_text', 'attributes']) + class OrderingFilterModel(models.Model): title = models.CharField(max_length=20, verbose_name='verbose title') text = models.CharField(max_length=100) + @property + def description(self): + return self.title + ": " + self.text + class OrderingFilterRelatedModel(models.Model): related_object = models.ForeignKey(OrderingFilterModel, related_name="relateds", on_delete=models.CASCADE) @@ -378,6 +440,17 @@ class OrderingFilterSerializer(serializers.ModelSerializer): fields = '__all__' +class OrderingFilterSerializerWithModelProperty(serializers.ModelSerializer): + class Meta: + model = OrderingFilterModel + fields = ( + "id", + "title", + "text", + "description" + ) + + class OrderingDottedRelatedSerializer(serializers.ModelSerializer): related_text = serializers.CharField(source='related_object.text') related_title = serializers.CharField(source='related_object.title') @@ -493,6 +566,42 @@ class OrderingFilterTests(TestCase): {'id': 1, 'title': 'zyx', 'text': 'abc'}, ] + def test_ordering_without_ordering_fields(self): + class OrderingListView(generics.ListAPIView): + queryset = OrderingFilterModel.objects.all() + serializer_class = OrderingFilterSerializerWithModelProperty + filter_backends = (filters.OrderingFilter,) + ordering = ('title',) + + view = OrderingListView.as_view() + + # Model field ordering works fine. + request = factory.get('/', {'ordering': 'text'}) + response = view(request) + assert response.data == [ + {'id': 1, 'title': 'zyx', 'text': 'abc', 'description': 'zyx: abc'}, + {'id': 2, 'title': 'yxw', 'text': 'bcd', 'description': 'yxw: bcd'}, + {'id': 3, 'title': 'xwv', 'text': 'cde', 'description': 'xwv: cde'}, + ] + + # `incorrectfield` ordering works fine. + request = factory.get('/', {'ordering': 'foobar'}) + response = view(request) + assert response.data == [ + {'id': 3, 'title': 'xwv', 'text': 'cde', 'description': 'xwv: cde'}, + {'id': 2, 'title': 'yxw', 'text': 'bcd', 'description': 'yxw: bcd'}, + {'id': 1, 'title': 'zyx', 'text': 'abc', 'description': 'zyx: abc'}, + ] + + # `description` is a Model property, which should be ignored. + request = factory.get('/', {'ordering': 'description'}) + response = view(request) + assert response.data == [ + {'id': 3, 'title': 'xwv', 'text': 'cde', 'description': 'xwv: cde'}, + {'id': 2, 'title': 'yxw', 'text': 'bcd', 'description': 'yxw: bcd'}, + {'id': 1, 'title': 'zyx', 'text': 'abc', 'description': 'zyx: abc'}, + ] + def test_default_ordering(self): class OrderingListView(generics.ListAPIView): queryset = OrderingFilterModel.objects.all() diff --git a/tests/test_generateschema.py b/tests/test_generateschema.py deleted file mode 100644 index 915c6ea05..000000000 --- a/tests/test_generateschema.py +++ /dev/null @@ -1,88 +0,0 @@ -from __future__ import unicode_literals - -import pytest -from django.conf.urls import url -from django.core.management import call_command -from django.test import TestCase -from django.test.utils import override_settings -from django.utils import six - -from rest_framework.compat import coreapi -from rest_framework.utils import formatting, json -from rest_framework.views import APIView - - -class FooView(APIView): - def get(self, request): - pass - - -urlpatterns = [ - url(r'^$', FooView.as_view()) -] - - -@override_settings(ROOT_URLCONF='tests.test_generateschema') -@pytest.mark.skipif(not coreapi, reason='coreapi is not installed') -class GenerateSchemaTests(TestCase): - """Tests for management command generateschema.""" - - def setUp(self): - self.out = six.StringIO() - - @pytest.mark.skipif(six.PY2, reason='PyYAML unicode output is malformed on PY2.') - def test_renders_default_schema_with_custom_title_url_and_description(self): - expected_out = """info: - description: Sample description - title: SampleAPI - version: '' - openapi: 3.0.0 - paths: - /: - get: - operationId: list - servers: - - url: http://api.sample.com/ - """ - call_command('generateschema', - '--title=SampleAPI', - '--url=http://api.sample.com', - '--description=Sample description', - stdout=self.out) - - self.assertIn(formatting.dedent(expected_out), self.out.getvalue()) - - def test_renders_openapi_json_schema(self): - expected_out = { - "openapi": "3.0.0", - "info": { - "version": "", - "title": "", - "description": "" - }, - "servers": [ - { - "url": "" - } - ], - "paths": { - "/": { - "get": { - "operationId": "list" - } - } - } - } - call_command('generateschema', - '--format=openapi-json', - stdout=self.out) - out_json = json.loads(self.out.getvalue()) - - self.assertDictEqual(out_json, expected_out) - - def test_renders_corejson_schema(self): - expected_out = """{"_type":"document","":{"list":{"_type":"link","url":"/","action":"get"}}}""" - call_command('generateschema', - '--format=corejson', - stdout=self.out) - self.assertIn(expected_out, self.out.getvalue()) diff --git a/tests/test_generics.py b/tests/test_generics.py index c0ff1c5c4..78dc5afb6 100644 --- a/tests/test_generics.py +++ b/tests/test_generics.py @@ -1,13 +1,11 @@ -from __future__ import unicode_literals - import pytest from django.db import models from django.http import Http404 from django.shortcuts import get_object_or_404 from django.test import TestCase -from django.utils import six from rest_framework import generics, renderers, serializers, status +from rest_framework.exceptions import ErrorDetail from rest_framework.response import Response from rest_framework.test import APIRequestFactory from tests.models import ( @@ -167,7 +165,7 @@ class TestRootView(TestCase): request = factory.post('/', data, HTTP_ACCEPT='text/html') response = self.view(request).render() expected_error = 'Ensure this field has no more than 100 characters.' - assert expected_error in response.rendered_content.decode('utf-8') + assert expected_error in response.rendered_content.decode() EXPECTED_QUERIES_FOR_PUT = 2 @@ -245,7 +243,7 @@ class TestInstanceView(TestCase): with self.assertNumQueries(2): response = self.view(request, pk=1).render() assert response.status_code == status.HTTP_204_NO_CONTENT - assert response.content == six.b('') + assert response.content == b'' ids = [obj.id for obj in self.objects.all()] assert ids == [2, 3] @@ -291,7 +289,7 @@ class TestInstanceView(TestCase): """ data = {'text': 'foo'} filtered_out_pk = BasicModel.objects.filter(text='filtered out')[0].pk - request = factory.put('/{0}'.format(filtered_out_pk), data, format='json') + request = factory.put('/{}'.format(filtered_out_pk), data, format='json') response = self.view(request, pk=filtered_out_pk).render() assert response.status_code == status.HTTP_404_NOT_FOUND @@ -314,7 +312,7 @@ class TestInstanceView(TestCase): request = factory.put('/', data, HTTP_ACCEPT='text/html') response = self.view(request, pk=1).render() expected_error = 'Ensure this field has no more than 100 characters.' - assert expected_error in response.rendered_content.decode('utf-8') + assert expected_error in response.rendered_content.decode() class TestFKInstanceView(TestCase): @@ -446,12 +444,12 @@ class TestM2MBrowsableAPI(TestCase): assert response.status_code == status.HTTP_200_OK -class InclusiveFilterBackend(object): +class InclusiveFilterBackend: def filter_queryset(self, request, queryset, view): return queryset.filter(text='foo') -class ExclusiveFilterBackend(object): +class ExclusiveFilterBackend: def filter_queryset(self, request, queryset, view): return queryset.filter(text='other') @@ -522,7 +520,12 @@ class TestFilterBackendAppliedToViews(TestCase): request = factory.get('/1') response = instance_view(request, pk=1).render() assert response.status_code == status.HTTP_404_NOT_FOUND - assert response.data == {'detail': 'Not found.'} + assert response.data == { + 'detail': ErrorDetail( + string='No BasicModel matches the given query.', + code='not_found' + ) + } def test_get_instance_view_will_return_single_object_when_filter_does_not_exclude_it(self): """ @@ -541,7 +544,7 @@ class TestFilterBackendAppliedToViews(TestCase): view = DynamicSerializerView.as_view() request = factory.get('/') response = view(request).render() - content = response.content.decode('utf8') + content = response.content.decode() assert 'field_b' in content assert 'field_a' not in content @@ -653,7 +656,7 @@ class ApiViewsTests(TestCase): class GetObjectOr404Tests(TestCase): def setUp(self): - super(GetObjectOr404Tests, self).setUp() + super().setUp() self.uuid_object = UUIDForeignKeyTarget.objects.create(name='bar') def test_get_object_or_404_with_valid_uuid(self): @@ -665,3 +668,33 @@ class GetObjectOr404Tests(TestCase): def test_get_object_or_404_with_invalid_string_for_uuid(self): with pytest.raises(Http404): generics.get_object_or_404(UUIDForeignKeyTarget, pk='not-a-uuid') + + +class TestSerializer(TestCase): + + def test_serializer_class_not_provided(self): + class NoSerializerClass(generics.GenericAPIView): + pass + + with pytest.raises(AssertionError) as excinfo: + NoSerializerClass().get_serializer_class() + + assert str(excinfo.value) == ( + "'NoSerializerClass' should either include a `serializer_class` " + "attribute, or override the `get_serializer_class()` method.") + + def test_given_context_not_overridden(self): + context = object() + + class View(generics.ListAPIView): + serializer_class = serializers.Serializer + + def list(self, request): + response = Response() + response.serializer = self.get_serializer(context=context) + return response + + response = View.as_view()(factory.get('/')) + serializer = response.serializer + + assert serializer.context is context diff --git a/tests/test_htmlrenderer.py b/tests/test_htmlrenderer.py index decd25a3f..fa0f4efc6 100644 --- a/tests/test_htmlrenderer.py +++ b/tests/test_htmlrenderer.py @@ -1,13 +1,10 @@ -from __future__ import unicode_literals - import django.template.loader import pytest -from django.conf.urls import url from django.core.exceptions import ImproperlyConfigured, PermissionDenied from django.http import Http404 from django.template import TemplateDoesNotExist, engines from django.test import TestCase, override_settings -from django.utils import six +from django.urls import path from rest_framework import status from rest_framework.decorators import api_view, renderer_classes @@ -38,16 +35,16 @@ def not_found(request): urlpatterns = [ - url(r'^$', example), - url(r'^permission_denied$', permission_denied), - url(r'^not_found$', not_found), + path('', example), + path('permission_denied', permission_denied), + path('not_found', not_found), ] @override_settings(ROOT_URLCONF='tests.test_htmlrenderer') class TemplateHTMLRendererTests(TestCase): def setUp(self): - class MockResponse(object): + class MockResponse: template_name = None self.mock_response = MockResponse() self._monkey_patch_get_template() @@ -85,13 +82,13 @@ class TemplateHTMLRendererTests(TestCase): def test_not_found_html_view(self): response = self.client.get('/not_found') self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND) - self.assertEqual(response.content, six.b("404 Not Found")) + self.assertEqual(response.content, b"404 Not Found") self.assertEqual(response['Content-Type'], 'text/html; charset=utf-8') def test_permission_denied_html_view(self): response = self.client.get('/permission_denied') self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN) - self.assertEqual(response.content, six.b("403 Forbidden")) + self.assertEqual(response.content, b"403 Forbidden") self.assertEqual(response['Content-Type'], 'text/html; charset=utf-8') # 2 tests below are based on order of if statements in corresponding method @@ -105,14 +102,14 @@ class TemplateHTMLRendererTests(TestCase): def test_get_template_names_returns_view_template_name(self): renderer = TemplateHTMLRenderer() - class MockResponse(object): + class MockResponse: template_name = None - class MockView(object): + class MockView: def get_template_names(self): return ['template from get_template_names method'] - class MockView2(object): + class MockView2: template_name = 'template from template_name attribute' template_name = renderer.get_template_names(self.mock_response, @@ -156,12 +153,11 @@ class TemplateHTMLRendererExceptionTests(TestCase): response = self.client.get('/not_found') self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND) self.assertTrue(response.content in ( - six.b("404: Not found"), six.b("404 Not Found"))) + b"404: Not found", b"404 Not Found")) self.assertEqual(response['Content-Type'], 'text/html; charset=utf-8') def test_permission_denied_html_view_with_template(self): response = self.client.get('/permission_denied') self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN) - self.assertTrue(response.content in ( - six.b("403: Permission denied"), six.b("403 Forbidden"))) + self.assertTrue(response.content in (b"403: Permission denied", b"403 Forbidden")) self.assertEqual(response['Content-Type'], 'text/html; charset=utf-8') diff --git a/tests/test_lazy_hyperlinks.py b/tests/test_lazy_hyperlinks.py index cf3ee735f..716d02d2a 100644 --- a/tests/test_lazy_hyperlinks.py +++ b/tests/test_lazy_hyperlinks.py @@ -1,6 +1,6 @@ -from django.conf.urls import url from django.db import models from django.test import TestCase, override_settings +from django.urls import path from rest_framework import serializers from rest_framework.renderers import JSONRenderer @@ -29,7 +29,7 @@ def dummy_view(request): urlpatterns = [ - url(r'^example/(?P[0-9]+)/$', dummy_view, name='example-detail'), + path('example//', dummy_view, name='example-detail'), ] diff --git a/tests/test_metadata.py b/tests/test_metadata.py index fe4ea4b42..4abc0fc07 100644 --- a/tests/test_metadata.py +++ b/tests/test_metadata.py @@ -1,5 +1,3 @@ -from __future__ import unicode_literals - import pytest from django.core.validators import MaxValueValidator, MinValueValidator from django.db import models @@ -313,7 +311,8 @@ class TestMetadata: class TestSimpleMetadataFieldInfo(TestCase): def test_null_boolean_field_info_type(self): options = metadata.SimpleMetadata() - field_info = options.get_field_info(serializers.NullBooleanField()) + field_info = options.get_field_info(serializers.BooleanField( + allow_null=True)) assert field_info['type'] == 'boolean' def test_related_field_choices(self): diff --git a/tests/test_middleware.py b/tests/test_middleware.py index 9df7d8e3e..6b2c91db7 100644 --- a/tests/test_middleware.py +++ b/tests/test_middleware.py @@ -1,7 +1,7 @@ -from django.conf.urls import url from django.contrib.auth.models import User from django.http import HttpRequest from django.test import override_settings +from django.urls import path from rest_framework.authentication import TokenAuthentication from rest_framework.authtoken.models import Token @@ -17,12 +17,12 @@ class PostView(APIView): urlpatterns = [ - url(r'^auth$', APIView.as_view(authentication_classes=(TokenAuthentication,))), - url(r'^post$', PostView.as_view()), + path('auth', APIView.as_view(authentication_classes=(TokenAuthentication,))), + path('post', PostView.as_view()), ] -class RequestUserMiddleware(object): +class RequestUserMiddleware: def __init__(self, get_response): self.get_response = get_response @@ -34,7 +34,7 @@ class RequestUserMiddleware(object): return response -class RequestPOSTMiddleware(object): +class RequestPOSTMiddleware: def __init__(self, get_response): self.get_response = get_response diff --git a/tests/test_model_serializer.py b/tests/test_model_serializer.py index 898c859a4..419eae632 100644 --- a/tests/test_model_serializer.py +++ b/tests/test_model_serializer.py @@ -5,25 +5,27 @@ shortcuts for automatically creating serializers based on a given model class. These tests deal with ensuring that we correctly map the model fields onto an appropriate set of serializer fields for each case. """ -from __future__ import unicode_literals - import datetime import decimal +import json # noqa import sys +import tempfile from collections import OrderedDict import django import pytest from django.core.exceptions import ImproperlyConfigured +from django.core.serializers.json import DjangoJSONEncoder from django.core.validators import ( MaxValueValidator, MinLengthValidator, MinValueValidator ) from django.db import models +from django.db.models.signals import m2m_changed +from django.dispatch import receiver from django.test import TestCase -from django.utils import six from rest_framework import serializers -from rest_framework.compat import postgres_fields, unicode_repr +from rest_framework.compat import postgres_fields from .models import NestedForeignKeySource @@ -61,7 +63,7 @@ class RegularFieldsModel(models.Model): email_field = models.EmailField(max_length=100) float_field = models.FloatField() integer_field = models.IntegerField() - null_boolean_field = models.NullBooleanField() + null_boolean_field = models.BooleanField(null=True, default=False) positive_integer_field = models.PositiveIntegerField() positive_small_integer_field = models.PositiveSmallIntegerField() slug_field = models.SlugField(max_length=100) @@ -71,7 +73,7 @@ class RegularFieldsModel(models.Model): time_field = models.TimeField() url_field = models.URLField(max_length=100) custom_field = CustomField() - file_path_field = models.FilePathField(path='/tmp/') + file_path_field = models.FilePathField(path=tempfile.gettempdir()) def method(self): return 'method' @@ -89,6 +91,7 @@ class FieldOptionsModel(models.Model): default_field = models.IntegerField(default=0) descriptive_field = models.IntegerField(help_text='Some help text', verbose_name='A label') choices_field = models.CharField(max_length=100, choices=COLOR_CHOICES) + text_choices_field = models.TextField(choices=COLOR_CHOICES) class ChoicesModel(models.Model): @@ -180,7 +183,7 @@ class TestRegularFieldMappings(TestCase): email_field = EmailField(max_length=100) float_field = FloatField() integer_field = IntegerField() - null_boolean_field = NullBooleanField(required=False) + null_boolean_field = BooleanField(allow_null=True, required=False) positive_integer_field = IntegerField() positive_small_integer_field = IntegerField() slug_field = SlugField(allow_unicode=False, max_length=100) @@ -190,10 +193,10 @@ class TestRegularFieldMappings(TestCase): time_field = TimeField() url_field = URLField(max_length=100) custom_field = ModelField(model_field=) - file_path_field = FilePathField(path='/tmp/') - """) + file_path_field = FilePathField(path=%r) + """ % tempfile.gettempdir()) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_field_options(self): class TestSerializer(serializers.ModelSerializer): @@ -211,34 +214,30 @@ class TestRegularFieldMappings(TestCase): default_field = IntegerField(required=False) descriptive_field = IntegerField(help_text='Some help text', label='A label') choices_field = ChoiceField(choices=(('red', 'Red'), ('blue', 'Blue'), ('green', 'Green'))) + text_choices_field = ChoiceField(choices=(('red', 'Red'), ('blue', 'Blue'), ('green', 'Green'))) """) - if six.PY2: - # This particular case is too awkward to resolve fully across - # both py2 and py3. - expected = expected.replace( - "('red', 'Red'), ('blue', 'Blue'), ('green', 'Green')", - "(u'red', u'Red'), (u'blue', u'Blue'), (u'green', u'Green')" + self.assertEqual(repr(TestSerializer()), expected) + + def test_nullable_boolean_field_choices(self): + class NullableBooleanChoicesModel(models.Model): + CHECKLIST_OPTIONS = ( + (None, 'Unknown'), + (True, 'Yes'), + (False, 'No'), ) - self.assertEqual(unicode_repr(TestSerializer()), expected) - # merge this into test_regular_fields / RegularFieldsModel when - # Django 2.1 is the minimum supported version - @pytest.mark.skipif(django.VERSION < (2, 1), reason='Django version < 2.1') - def test_nullable_boolean_field(self): - class NullableBooleanModel(models.Model): - field = models.BooleanField(null=True, default=False) + field = models.BooleanField(null=True, choices=CHECKLIST_OPTIONS) - class NullableBooleanSerializer(serializers.ModelSerializer): + class NullableBooleanChoicesSerializer(serializers.ModelSerializer): class Meta: - model = NullableBooleanModel + model = NullableBooleanChoicesModel fields = ['field'] - expected = dedent(""" - NullableBooleanSerializer(): - field = BooleanField(allow_null=True, required=False) - """) - - self.assertEqual(unicode_repr(NullableBooleanSerializer()), expected) + serializer = NullableBooleanChoicesSerializer(data=dict( + field=None, + )) + self.assertTrue(serializer.is_valid()) + self.assertEqual(serializer.errors, {}) def test_method_field(self): """ @@ -310,7 +309,7 @@ class TestRegularFieldMappings(TestCase): def test_invalid_field(self): """ Field names that do not map to a model field or relationship should - raise a configuration errror. + raise a configuration error. """ class TestSerializer(serializers.ModelSerializer): class Meta: @@ -382,7 +381,7 @@ class TestDurationFieldMapping(TestCase): id = IntegerField(label='ID', read_only=True) duration_field = DurationField() """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_duration_field_with_validators(self): class ValidatedDurationFieldModel(models.Model): @@ -407,7 +406,7 @@ class TestDurationFieldMapping(TestCase): id = IntegerField(label='ID', read_only=True) duration_field = DurationField(max_value=datetime.timedelta(days=3), min_value=datetime.timedelta(days=1)) """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) class TestGenericIPAddressFieldValidation(TestCase): @@ -424,7 +423,7 @@ class TestGenericIPAddressFieldValidation(TestCase): self.assertFalse(s.is_valid()) self.assertEqual(1, len(s.errors['address']), 'Unexpected number of validation errors: ' - '{0}'.format(s.errors)) + '{}'.format(s.errors)) @pytest.mark.skipif('not postgres_fields') @@ -442,37 +441,69 @@ class TestPosgresFieldsMapping(TestCase): TestSerializer(): hstore_field = HStoreField() """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_array_field(self): class ArrayFieldModel(models.Model): array_field = postgres_fields.ArrayField(base_field=models.CharField()) + array_field_with_blank = postgres_fields.ArrayField(blank=True, base_field=models.CharField()) class TestSerializer(serializers.ModelSerializer): class Meta: model = ArrayFieldModel - fields = ['array_field'] + fields = ['array_field', 'array_field_with_blank'] + validators = "" + if django.VERSION < (4, 1): + validators = ", validators=[]" expected = dedent(""" TestSerializer(): - array_field = ListField(child=CharField(label='Array field', validators=[])) - """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + array_field = ListField(allow_empty=False, child=CharField(label='Array field'%s)) + array_field_with_blank = ListField(child=CharField(label='Array field with blank'%s), required=False) + """ % (validators, validators)) + self.assertEqual(repr(TestSerializer()), expected) + @pytest.mark.skipif(hasattr(models, 'JSONField'), reason='has models.JSONField') def test_json_field(self): class JSONFieldModel(models.Model): json_field = postgres_fields.JSONField() + json_field_with_encoder = postgres_fields.JSONField(encoder=DjangoJSONEncoder) class TestSerializer(serializers.ModelSerializer): class Meta: model = JSONFieldModel - fields = ['json_field'] + fields = ['json_field', 'json_field_with_encoder'] expected = dedent(""" TestSerializer(): - json_field = JSONField(style={'base_template': 'textarea.html'}) + json_field = JSONField(encoder=None, style={'base_template': 'textarea.html'}) + json_field_with_encoder = JSONField(encoder=, style={'base_template': 'textarea.html'}) """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) + + +class CustomJSONDecoder(json.JSONDecoder): + pass + + +@pytest.mark.skipif(not hasattr(models, 'JSONField'), reason='no models.JSONField') +class TestDjangoJSONFieldMapping(TestCase): + def test_json_field(self): + class JSONFieldModel(models.Model): + json_field = models.JSONField() + json_field_with_encoder = models.JSONField(encoder=DjangoJSONEncoder, decoder=CustomJSONDecoder) + + class TestSerializer(serializers.ModelSerializer): + class Meta: + model = JSONFieldModel + fields = ['json_field', 'json_field_with_encoder'] + + expected = dedent(""" + TestSerializer(): + json_field = JSONField(decoder=None, encoder=None, style={'base_template': 'textarea.html'}) + json_field_with_encoder = JSONField(decoder=, encoder=, style={'base_template': 'textarea.html'}) + """) + self.assertEqual(repr(TestSerializer()), expected) # Tests for relational field mappings. @@ -530,7 +561,7 @@ class TestRelationalFieldMappings(TestCase): many_to_many = PrimaryKeyRelatedField(allow_empty=False, many=True, queryset=ManyToManyTargetModel.objects.all()) through = PrimaryKeyRelatedField(many=True, read_only=True) """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_nested_relations(self): class TestSerializer(serializers.ModelSerializer): @@ -555,7 +586,7 @@ class TestRelationalFieldMappings(TestCase): id = IntegerField(label='ID', read_only=True) name = CharField(max_length=100) """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_hyperlinked_relations(self): class TestSerializer(serializers.HyperlinkedModelSerializer): @@ -571,7 +602,7 @@ class TestRelationalFieldMappings(TestCase): many_to_many = HyperlinkedRelatedField(allow_empty=False, many=True, queryset=ManyToManyTargetModel.objects.all(), view_name='manytomanytargetmodel-detail') through = HyperlinkedRelatedField(many=True, read_only=True, view_name='throughtargetmodel-detail') """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_nested_hyperlinked_relations(self): class TestSerializer(serializers.HyperlinkedModelSerializer): @@ -596,7 +627,7 @@ class TestRelationalFieldMappings(TestCase): url = HyperlinkedIdentityField(view_name='throughtargetmodel-detail') name = CharField(max_length=100) """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_nested_hyperlinked_relations_starred_source(self): class TestSerializer(serializers.HyperlinkedModelSerializer): @@ -627,7 +658,7 @@ class TestRelationalFieldMappings(TestCase): name = CharField(max_length=100) """) self.maxDiff = None - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_nested_unique_together_relations(self): class TestSerializer(serializers.HyperlinkedModelSerializer): @@ -646,14 +677,7 @@ class TestRelationalFieldMappings(TestCase): url = HyperlinkedIdentityField(view_name='onetoonetargetmodel-detail') name = CharField(max_length=100) """) - if six.PY2: - # This case is also too awkward to resolve fully across both py2 - # and py3. (See above) - expected = expected.replace( - "('foreign_key', 'one_to_one')", - "(u'foreign_key', u'one_to_one')" - ) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_pk_reverse_foreign_key(self): class TestSerializer(serializers.ModelSerializer): @@ -667,7 +691,7 @@ class TestRelationalFieldMappings(TestCase): name = CharField(max_length=100) reverse_foreign_key = PrimaryKeyRelatedField(many=True, queryset=RelationalModel.objects.all()) """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_pk_reverse_one_to_one(self): class TestSerializer(serializers.ModelSerializer): @@ -681,7 +705,7 @@ class TestRelationalFieldMappings(TestCase): name = CharField(max_length=100) reverse_one_to_one = PrimaryKeyRelatedField(queryset=RelationalModel.objects.all()) """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_pk_reverse_many_to_many(self): class TestSerializer(serializers.ModelSerializer): @@ -695,7 +719,7 @@ class TestRelationalFieldMappings(TestCase): name = CharField(max_length=100) reverse_many_to_many = PrimaryKeyRelatedField(many=True, queryset=RelationalModel.objects.all()) """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) def test_pk_reverse_through(self): class TestSerializer(serializers.ModelSerializer): @@ -709,7 +733,7 @@ class TestRelationalFieldMappings(TestCase): name = CharField(max_length=100) reverse_through = PrimaryKeyRelatedField(many=True, read_only=True) """) - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) class DisplayValueTargetModel(models.Model): @@ -1001,6 +1025,73 @@ class Issue2704TestCase(TestCase): assert serializer.data == expected +class Issue7550FooModel(models.Model): + text = models.CharField(max_length=100) + bar = models.ForeignKey( + 'Issue7550BarModel', null=True, blank=True, on_delete=models.SET_NULL, + related_name='foos', related_query_name='foo') + + +class Issue7550BarModel(models.Model): + pass + + +class Issue7550TestCase(TestCase): + + def test_dotted_source(self): + + class _FooSerializer(serializers.ModelSerializer): + class Meta: + model = Issue7550FooModel + fields = ('id', 'text') + + class FooSerializer(serializers.ModelSerializer): + other_foos = _FooSerializer(source='bar.foos', many=True) + + class Meta: + model = Issue7550BarModel + fields = ('id', 'other_foos') + + bar = Issue7550BarModel.objects.create() + foo_a = Issue7550FooModel.objects.create(bar=bar, text='abc') + foo_b = Issue7550FooModel.objects.create(bar=bar, text='123') + + assert FooSerializer(foo_a).data == { + 'id': foo_a.id, + 'other_foos': [ + { + 'id': foo_a.id, + 'text': foo_a.text, + }, + { + 'id': foo_b.id, + 'text': foo_b.text, + }, + ], + } + + def test_dotted_source_with_default(self): + + class _FooSerializer(serializers.ModelSerializer): + class Meta: + model = Issue7550FooModel + fields = ('id', 'text') + + class FooSerializer(serializers.ModelSerializer): + other_foos = _FooSerializer(source='bar.foos', default=[], many=True) + + class Meta: + model = Issue7550FooModel + fields = ('id', 'other_foos') + + foo = Issue7550FooModel.objects.create(bar=None, text='abc') + + assert FooSerializer(foo).data == { + 'id': foo.id, + 'other_foos': [], + } + + class DecimalFieldModel(models.Model): decimal_field = models.DecimalField( max_digits=3, @@ -1078,9 +1169,9 @@ class TestMetaInheritance(TestCase): char_field = CharField(max_length=100) non_model_field = CharField() """) - self.assertEqual(unicode_repr(ChildSerializer()), child_expected) - self.assertEqual(unicode_repr(TestSerializer()), test_expected) - self.assertEqual(unicode_repr(ChildSerializer()), child_expected) + self.assertEqual(repr(ChildSerializer()), child_expected) + self.assertEqual(repr(TestSerializer()), test_expected) + self.assertEqual(repr(ChildSerializer()), child_expected) class OneToOneTargetTestModel(models.Model): @@ -1149,14 +1240,14 @@ class Issue3674Test(TestCase): title = CharField(max_length=64) children = PrimaryKeyRelatedField(many=True, queryset=TestChildModel.objects.all()) """) - self.assertEqual(unicode_repr(TestParentModelSerializer()), parent_expected) + self.assertEqual(repr(TestParentModelSerializer()), parent_expected) child_expected = dedent(""" TestChildModelSerializer(): value = CharField(max_length=64, validators=[]) parent = PrimaryKeyRelatedField(queryset=TestParentModel.objects.all()) """) - self.assertEqual(unicode_repr(TestChildModelSerializer()), child_expected) + self.assertEqual(repr(TestChildModelSerializer()), child_expected) def test_nonID_PK_foreignkey_model_serializer(self): @@ -1248,7 +1339,7 @@ class TestFieldSource(TestCase): number_field = IntegerField(source='integer_field') """) self.maxDiff = None - self.assertEqual(unicode_repr(TestSerializer()), expected) + self.assertEqual(repr(TestSerializer()), expected) class Issue6110TestModel(models.Model): @@ -1265,7 +1356,6 @@ class Issue6110ModelSerializer(serializers.ModelSerializer): class Issue6110Test(TestCase): - def test_model_serializer_custom_manager(self): instance = Issue6110ModelSerializer().create({'name': 'test_name'}) self.assertEqual(instance.name, 'test_name') @@ -1274,3 +1364,43 @@ class Issue6110Test(TestCase): msginitial = ('Got a `TypeError` when calling `Issue6110TestModel.all_objects.create()`.') with self.assertRaisesMessage(TypeError, msginitial): Issue6110ModelSerializer().create({'wrong_param': 'wrong_param'}) + + +class Issue6751Model(models.Model): + many_to_many = models.ManyToManyField(ManyToManyTargetModel, related_name='+') + char_field = models.CharField(max_length=100) + char_field2 = models.CharField(max_length=100) + + +@receiver(m2m_changed, sender=Issue6751Model.many_to_many.through) +def process_issue6751model_m2m_changed(action, instance, **_): + if action == 'post_add': + instance.char_field = 'value changed by signal' + instance.save() + + +class Issue6751Test(TestCase): + def test_model_serializer_save_m2m_after_instance(self): + class TestSerializer(serializers.ModelSerializer): + class Meta: + model = Issue6751Model + fields = ( + 'many_to_many', + 'char_field', + ) + + instance = Issue6751Model.objects.create(char_field='initial value') + m2m_target = ManyToManyTargetModel.objects.create(name='target') + + serializer = TestSerializer( + instance=instance, + data={ + 'many_to_many': (m2m_target.id,), + 'char_field': 'will be changed by signal', + } + ) + + serializer.is_valid() + serializer.save() + + self.assertEqual(instance.char_field, 'value changed by signal') diff --git a/tests/test_multitable_inheritance.py b/tests/test_multitable_inheritance.py index 2ddd37ebb..1e8ab3448 100644 --- a/tests/test_multitable_inheritance.py +++ b/tests/test_multitable_inheritance.py @@ -1,5 +1,3 @@ -from __future__ import unicode_literals - from django.db import models from django.test import TestCase diff --git a/tests/test_negotiation.py b/tests/test_negotiation.py index 7ce3f92a9..089a86c62 100644 --- a/tests/test_negotiation.py +++ b/tests/test_negotiation.py @@ -1,5 +1,3 @@ -from __future__ import unicode_literals - import pytest from django.http import Http404 from django.test import TestCase @@ -80,7 +78,7 @@ class TestAcceptedMediaType(TestCase): assert str(mediatype) == 'test/*; foo=bar' def test_raise_error_if_no_suitable_renderers_found(self): - class MockRenderer(object): + class MockRenderer: format = 'xml' renderers = [MockRenderer()] with pytest.raises(Http404): diff --git a/tests/test_one_to_one_with_inheritance.py b/tests/test_one_to_one_with_inheritance.py index 789c7fcb9..40793d7ca 100644 --- a/tests/test_one_to_one_with_inheritance.py +++ b/tests/test_one_to_one_with_inheritance.py @@ -1,5 +1,3 @@ -from __future__ import unicode_literals - from django.db import models from django.test import TestCase diff --git a/tests/test_pagination.py b/tests/test_pagination.py index 6d940fe2b..74a65bf50 100644 --- a/tests/test_pagination.py +++ b/tests/test_pagination.py @@ -1,11 +1,7 @@ -# coding: utf-8 -from __future__ import unicode_literals - import pytest from django.core.paginator import Paginator as DjangoPaginator from django.db import models from django.test import TestCase -from django.utils import six from rest_framework import ( exceptions, filters, generics, pagination, serializers, status @@ -22,7 +18,7 @@ class TestPaginationIntegration: Integration tests. """ - def setup(self): + def setup_method(self): class PassThroughSerializer(serializers.BaseSerializer): def to_representation(self, item): return item @@ -144,7 +140,7 @@ class TestPaginationDisabledIntegration: Integration tests for disabled pagination. """ - def setup(self): + def setup_method(self): class PassThroughSerializer(serializers.BaseSerializer): def to_representation(self, item): return item @@ -167,7 +163,7 @@ class TestPageNumberPagination: Unit tests for `pagination.PageNumberPagination`. """ - def setup(self): + def setup_method(self): class ExamplePagination(pagination.PageNumberPagination): page_size = 5 @@ -208,7 +204,7 @@ class TestPageNumberPagination: ] } assert self.pagination.display_page_controls - assert isinstance(self.pagination.to_html(), six.text_type) + assert isinstance(self.pagination.to_html(), str) def test_second_page(self): request = Request(factory.get('/', {'page': 2})) @@ -263,6 +259,41 @@ class TestPageNumberPagination: with pytest.raises(exceptions.NotFound): self.paginate_queryset(request) + def test_get_paginated_response_schema(self): + unpaginated_schema = { + 'type': 'object', + 'item': { + 'properties': { + 'test-property': { + 'type': 'integer', + }, + }, + }, + } + + assert self.pagination.get_paginated_response_schema(unpaginated_schema) == { + 'type': 'object', + 'properties': { + 'count': { + 'type': 'integer', + 'example': 123, + }, + 'next': { + 'type': 'string', + 'nullable': True, + 'format': 'uri', + 'example': 'http://api.example.org/accounts/?page=4', + }, + 'previous': { + 'type': 'string', + 'nullable': True, + 'format': 'uri', + 'example': 'http://api.example.org/accounts/?page=2', + }, + 'results': unpaginated_schema, + }, + } + class TestPageNumberPaginationOverride: """ @@ -271,7 +302,7 @@ class TestPageNumberPaginationOverride: the Django Paginator Class is overridden. """ - def setup(self): + def setup_method(self): class OverriddenDjangoPaginator(DjangoPaginator): # override the count in our overridden Django Paginator # we will only return one page, with one item @@ -314,7 +345,7 @@ class TestPageNumberPaginationOverride: ] } assert not self.pagination.display_page_controls - assert isinstance(self.pagination.to_html(), six.text_type) + assert isinstance(self.pagination.to_html(), str) def test_invalid_page(self): request = Request(factory.get('/', {'page': 'invalid'})) @@ -327,7 +358,7 @@ class TestLimitOffset: Unit tests for `pagination.LimitOffsetPagination`. """ - def setup(self): + def setup_method(self): class ExamplePagination(pagination.LimitOffsetPagination): default_limit = 10 max_limit = 15 @@ -369,7 +400,7 @@ class TestLimitOffset: ] } assert self.pagination.display_page_controls - assert isinstance(self.pagination.to_html(), six.text_type) + assert isinstance(self.pagination.to_html(), str) def test_pagination_not_applied_if_limit_or_default_limit_not_set(self): class MockPagination(pagination.LimitOffsetPagination): @@ -503,7 +534,7 @@ class TestLimitOffset: content = self.get_paginated_content(queryset) next_limit = self.pagination.default_limit next_offset = self.pagination.default_limit - next_url = 'http://testserver/?limit={0}&offset={1}'.format(next_limit, next_offset) + next_url = 'http://testserver/?limit={}&offset={}'.format(next_limit, next_offset) assert queryset == [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] assert content.get('next') == next_url @@ -516,7 +547,7 @@ class TestLimitOffset: content = self.get_paginated_content(queryset) next_limit = self.pagination.default_limit next_offset = self.pagination.default_limit - next_url = 'http://testserver/?limit={0}&offset={1}'.format(next_limit, next_offset) + next_url = 'http://testserver/?limit={}&offset={}'.format(next_limit, next_offset) assert queryset == [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] assert content.get('next') == next_url @@ -532,13 +563,48 @@ class TestLimitOffset: max_limit = self.pagination.max_limit next_offset = offset + max_limit prev_offset = offset - max_limit - base_url = 'http://testserver/?limit={0}'.format(max_limit) - next_url = base_url + '&offset={0}'.format(next_offset) - prev_url = base_url + '&offset={0}'.format(prev_offset) + base_url = 'http://testserver/?limit={}'.format(max_limit) + next_url = base_url + '&offset={}'.format(next_offset) + prev_url = base_url + '&offset={}'.format(prev_offset) assert queryset == list(range(51, 66)) assert content.get('next') == next_url assert content.get('previous') == prev_url + def test_get_paginated_response_schema(self): + unpaginated_schema = { + 'type': 'object', + 'item': { + 'properties': { + 'test-property': { + 'type': 'integer', + }, + }, + }, + } + + assert self.pagination.get_paginated_response_schema(unpaginated_schema) == { + 'type': 'object', + 'properties': { + 'count': { + 'type': 'integer', + 'example': 123, + }, + 'next': { + 'type': 'string', + 'nullable': True, + 'format': 'uri', + 'example': 'http://api.example.org/accounts/?offset=400&limit=100', + }, + 'previous': { + 'type': 'string', + 'nullable': True, + 'format': 'uri', + 'example': 'http://api.example.org/accounts/?offset=200&limit=100', + }, + 'results': unpaginated_schema, + }, + } + class CursorPaginationTestsMixin: @@ -632,7 +698,53 @@ class CursorPaginationTestsMixin: assert current == [1, 1, 1, 1, 1] assert next == [1, 2, 3, 4, 4] - assert isinstance(self.pagination.to_html(), six.text_type) + assert isinstance(self.pagination.to_html(), str) + + def test_cursor_pagination_current_page_empty_forward(self): + # Regression test for #6504 + self.pagination.base_url = "/" + + # We have a cursor on the element at position 100, but this element doesn't exist + # anymore. + cursor = pagination.Cursor(reverse=False, offset=0, position=100) + url = self.pagination.encode_cursor(cursor) + self.pagination.base_url = "/" + + # Loading the page with this cursor doesn't crash + (previous, current, next, previous_url, next_url) = self.get_pages(url) + + # The previous url doesn't crash either + (previous, current, next, previous_url, next_url) = self.get_pages(previous_url) + + # And point to things that are not completely off. + assert previous == [7, 7, 7, 8, 9] + assert current == [9, 9, 9, 9, 9] + assert next == [] + assert previous_url is not None + assert next_url is not None + + def test_cursor_pagination_current_page_empty_reverse(self): + # Regression test for #6504 + self.pagination.base_url = "/" + + # We have a cursor on the element at position 100, but this element doesn't exist + # anymore. + cursor = pagination.Cursor(reverse=True, offset=0, position=100) + url = self.pagination.encode_cursor(cursor) + self.pagination.base_url = "/" + + # Loading the page with this cursor doesn't crash + (previous, current, next, previous_url, next_url) = self.get_pages(url) + + # The previous url doesn't crash either + (previous, current, next, previous_url, next_url) = self.get_pages(next_url) + + # And point to things that are not completely off. + assert previous == [7, 7, 7, 7, 8] + assert current == [] + assert next is None + assert previous_url is not None + assert next_url is None def test_cursor_pagination_with_page_size(self): (previous, current, next, previous_url, next_url) = self.get_pages('/?page_size=20') @@ -792,18 +904,49 @@ class CursorPaginationTestsMixin: assert current == [1, 1, 1, 1, 1] assert next == [1, 2, 3, 4, 4] + def test_get_paginated_response_schema(self): + unpaginated_schema = { + 'type': 'object', + 'item': { + 'properties': { + 'test-property': { + 'type': 'integer', + }, + }, + }, + } + + assert self.pagination.get_paginated_response_schema(unpaginated_schema) == { + 'type': 'object', + 'properties': { + 'next': { + 'type': 'string', + 'nullable': True, + 'format': 'uri', + 'example': 'http://api.example.org/accounts/?cursor=cD00ODY%3D"' + }, + 'previous': { + 'type': 'string', + 'nullable': True, + 'format': 'uri', + 'example': 'http://api.example.org/accounts/?cursor=cj0xJnA9NDg3' + }, + 'results': unpaginated_schema, + }, + } + class TestCursorPagination(CursorPaginationTestsMixin): """ Unit tests for `pagination.CursorPagination`. """ - def setup(self): - class MockObject(object): + def setup_method(self): + class MockObject: def __init__(self, idx): self.created = idx - class MockQuerySet(object): + class MockQuerySet: def __init__(self, items): self.items = items diff --git a/tests/test_parsers.py b/tests/test_parsers.py index e793948e3..dcd62fac9 100644 --- a/tests/test_parsers.py +++ b/tests/test_parsers.py @@ -1,6 +1,3 @@ -# -*- coding: utf-8 -*- -from __future__ import unicode_literals - import io import math @@ -11,7 +8,6 @@ from django.core.files.uploadhandler import ( ) from django.http.request import RawPostDataException from django.test import TestCase -from django.utils.six import StringIO from rest_framework.exceptions import ParseError from rest_framework.parsers import ( @@ -34,7 +30,7 @@ class TestFormParser(TestCase): """ Make sure the `QueryDict` works OK """ parser = FormParser() - stream = StringIO(self.string) + stream = io.StringIO(self.string) data = parser.parse(stream) assert Form(data).is_valid() is True @@ -42,11 +38,9 @@ class TestFormParser(TestCase): class TestFileUploadParser(TestCase): def setUp(self): - class MockRequest(object): + class MockRequest: pass - self.stream = io.BytesIO( - "Test text file".encode('utf-8') - ) + self.stream = io.BytesIO(b"Test text file") request = MockRequest() request.upload_handlers = (MemoryFileUploadHandler(),) request.META = { @@ -132,7 +126,7 @@ class TestFileUploadParser(TestCase): class TestJSONParser(TestCase): def bytes(self, value): - return io.BytesIO(value.encode('utf-8')) + return io.BytesIO(value.encode()) def test_float_strictness(self): parser = JSONParser() diff --git a/tests/test_permissions.py b/tests/test_permissions.py index 2fabdfa05..f00b57ec1 100644 --- a/tests/test_permissions.py +++ b/tests/test_permissions.py @@ -1,22 +1,17 @@ -from __future__ import unicode_literals - import base64 import unittest -import warnings +from unittest import mock -import django -import pytest +from django.conf import settings from django.contrib.auth.models import AnonymousUser, Group, Permission, User from django.db import models from django.test import TestCase from django.urls import ResolverMatch from rest_framework import ( - HTTP_HEADER_ENCODING, RemovedInDRF310Warning, authentication, generics, - permissions, serializers, status, views + HTTP_HEADER_ENCODING, authentication, generics, permissions, serializers, + status, views ) -from rest_framework.compat import PY36, is_guardian_installed, mock -from rest_framework.filters import DjangoObjectPermissionsFilter from rest_framework.routers import DefaultRouter from rest_framework.test import APIRequestFactory from tests.models import BasicModel @@ -252,12 +247,6 @@ class BasicPermModel(models.Model): class Meta: app_label = 'tests' - if django.VERSION < (2, 1): - permissions = ( - ('view_basicpermmodel', 'Can view basic perm model'), - # add, change, delete built in to django - ) - class BasicPermSerializer(serializers.ModelSerializer): class Meta: @@ -310,7 +299,7 @@ class GetQuerysetObjectPermissionInstanceView(generics.RetrieveUpdateDestroyAPIV get_queryset_object_permissions_view = GetQuerysetObjectPermissionInstanceView.as_view() -@unittest.skipUnless(is_guardian_installed(), 'django-guardian not installed') +@unittest.skipUnless('guardian' in settings.INSTALLED_APPS, 'django-guardian not installed') class ObjectPermissionsIntegrationTests(TestCase): """ Integration tests for the object level permissions API. @@ -331,14 +320,14 @@ class ObjectPermissionsIntegrationTests(TestCase): everyone = Group.objects.create(name='everyone') model_name = BasicPermModel._meta.model_name app_label = BasicPermModel._meta.app_label - f = '{0}_{1}'.format + f = '{}_{}'.format perms = { 'view': f('view', model_name), 'change': f('change', model_name), 'delete': f('delete', model_name) } for perm in perms.values(): - perm = '{0}.{1}'.format(app_label, perm) + perm = '{}.{}'.format(app_label, perm) assign_perm(perm, everyone) everyone.user_set.add(*users.values()) @@ -419,37 +408,14 @@ class ObjectPermissionsIntegrationTests(TestCase): self.assertEqual(response.status_code, status.HTTP_200_OK) # Read list - def test_django_object_permissions_filter_deprecated(self): - with warnings.catch_warnings(record=True) as w: - warnings.simplefilter("always") - DjangoObjectPermissionsFilter() - - message = ("`DjangoObjectPermissionsFilter` has been deprecated and moved " - "to the 3rd-party django-rest-framework-guardian package.") - self.assertEqual(len(w), 1) - self.assertIs(w[-1].category, RemovedInDRF310Warning) - self.assertEqual(str(w[-1].message), message) - + # Note: this previously tested `DjangoObjectPermissionsFilter`, which has + # since been moved to a separate package. These now act as sanity checks. def test_can_read_list_permissions(self): request = factory.get('/', HTTP_AUTHORIZATION=self.credentials['readonly']) - object_permissions_list_view.cls.filter_backends = (DjangoObjectPermissionsFilter,) - # TODO: remove in version 3.10 - with warnings.catch_warnings(record=True): - warnings.simplefilter("always") - response = object_permissions_list_view(request) + response = object_permissions_list_view(request) self.assertEqual(response.status_code, status.HTTP_200_OK) self.assertEqual(response.data[0].get('id'), 1) - def test_cannot_read_list_permissions(self): - request = factory.get('/', HTTP_AUTHORIZATION=self.credentials['writeonly']) - object_permissions_list_view.cls.filter_backends = (DjangoObjectPermissionsFilter,) - # TODO: remove in version 3.10 - with warnings.catch_warnings(record=True): - warnings.simplefilter("always") - response = object_permissions_list_view(request) - self.assertEqual(response.status_code, status.HTTP_200_OK) - self.assertListEqual(response.data, []) - def test_cannot_method_not_allowed(self): request = factory.generic('METHOD_NOT_ALLOWED', '/', HTTP_AUTHORIZATION=self.credentials['readonly']) response = object_permissions_list_view(request) @@ -463,6 +429,7 @@ class BasicPerm(permissions.BasePermission): class BasicPermWithDetail(permissions.BasePermission): message = 'Custom: You cannot access this resource' + code = 'permission_denied_custom' def has_permission(self, request, view): return False @@ -475,6 +442,7 @@ class BasicObjectPerm(permissions.BasePermission): class BasicObjectPermWithDetail(permissions.BasePermission): message = 'Custom: You cannot access this resource' + code = 'permission_denied_custom' def has_object_permission(self, request, view, obj): return False @@ -517,30 +485,35 @@ class CustomPermissionsTests(TestCase): credentials = basic_auth_header('username', 'password') self.request = factory.get('/1', format='json', HTTP_AUTHORIZATION=credentials) self.custom_message = 'Custom: You cannot access this resource' + self.custom_code = 'permission_denied_custom' def test_permission_denied(self): - response = denied_view(self.request, pk=1) - detail = response.data.get('detail') - self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN) - self.assertNotEqual(detail, self.custom_message) + response = denied_view(self.request, pk=1) + detail = response.data.get('detail') + self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN) + self.assertNotEqual(detail, self.custom_message) + self.assertNotEqual(detail.code, self.custom_code) def test_permission_denied_with_custom_detail(self): - response = denied_view_with_detail(self.request, pk=1) - detail = response.data.get('detail') - self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN) - self.assertEqual(detail, self.custom_message) + response = denied_view_with_detail(self.request, pk=1) + detail = response.data.get('detail') + self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN) + self.assertEqual(detail, self.custom_message) + self.assertEqual(detail.code, self.custom_code) def test_permission_denied_for_object(self): - response = denied_object_view(self.request, pk=1) - detail = response.data.get('detail') - self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN) - self.assertNotEqual(detail, self.custom_message) + response = denied_object_view(self.request, pk=1) + detail = response.data.get('detail') + self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN) + self.assertNotEqual(detail, self.custom_message) + self.assertNotEqual(detail.code, self.custom_code) def test_permission_denied_for_object_with_custom_detail(self): - response = denied_object_view_with_detail(self.request, pk=1) - detail = response.data.get('detail') - self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN) - self.assertEqual(detail, self.custom_message) + response = denied_object_view_with_detail(self.request, pk=1) + detail = response.data.get('detail') + self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN) + self.assertEqual(detail, self.custom_message) + self.assertEqual(detail.code, self.custom_code) class PermissionsCompositionTests(TestCase): @@ -625,7 +598,6 @@ class PermissionsCompositionTests(TestCase): ) assert composed_perm().has_permission(request, None) is True - @pytest.mark.skipif(not PY36, reason="assert_called_once() not available") def test_or_lazyness(self): request = factory.get('/1', format='json') request.user = AnonymousUser() @@ -634,19 +606,18 @@ class PermissionsCompositionTests(TestCase): with mock.patch.object(permissions.IsAuthenticated, 'has_permission', return_value=False) as mock_deny: composed_perm = (permissions.AllowAny | permissions.IsAuthenticated) hasperm = composed_perm().has_permission(request, None) - self.assertIs(hasperm, True) - mock_allow.assert_called_once() + assert hasperm is True + assert mock_allow.call_count == 1 mock_deny.assert_not_called() with mock.patch.object(permissions.AllowAny, 'has_permission', return_value=True) as mock_allow: with mock.patch.object(permissions.IsAuthenticated, 'has_permission', return_value=False) as mock_deny: composed_perm = (permissions.IsAuthenticated | permissions.AllowAny) hasperm = composed_perm().has_permission(request, None) - self.assertIs(hasperm, True) - mock_deny.assert_called_once() - mock_allow.assert_called_once() + assert hasperm is True + assert mock_deny.call_count == 1 + assert mock_allow.call_count == 1 - @pytest.mark.skipif(not PY36, reason="assert_called_once() not available") def test_object_or_lazyness(self): request = factory.get('/1', format='json') request.user = AnonymousUser() @@ -655,19 +626,18 @@ class PermissionsCompositionTests(TestCase): with mock.patch.object(permissions.IsAuthenticated, 'has_object_permission', return_value=False) as mock_deny: composed_perm = (permissions.AllowAny | permissions.IsAuthenticated) hasperm = composed_perm().has_object_permission(request, None, None) - self.assertIs(hasperm, True) - mock_allow.assert_called_once() + assert hasperm is True + assert mock_allow.call_count == 1 mock_deny.assert_not_called() with mock.patch.object(permissions.AllowAny, 'has_object_permission', return_value=True) as mock_allow: with mock.patch.object(permissions.IsAuthenticated, 'has_object_permission', return_value=False) as mock_deny: composed_perm = (permissions.IsAuthenticated | permissions.AllowAny) hasperm = composed_perm().has_object_permission(request, None, None) - self.assertIs(hasperm, True) - mock_deny.assert_called_once() - mock_allow.assert_called_once() + assert hasperm is True + assert mock_deny.call_count == 0 + assert mock_allow.call_count == 1 - @pytest.mark.skipif(not PY36, reason="assert_called_once() not available") def test_and_lazyness(self): request = factory.get('/1', format='json') request.user = AnonymousUser() @@ -676,19 +646,18 @@ class PermissionsCompositionTests(TestCase): with mock.patch.object(permissions.IsAuthenticated, 'has_permission', return_value=False) as mock_deny: composed_perm = (permissions.AllowAny & permissions.IsAuthenticated) hasperm = composed_perm().has_permission(request, None) - self.assertIs(hasperm, False) - mock_allow.assert_called_once() - mock_deny.assert_called_once() + assert hasperm is False + assert mock_allow.call_count == 1 + assert mock_deny.call_count == 1 with mock.patch.object(permissions.AllowAny, 'has_permission', return_value=True) as mock_allow: with mock.patch.object(permissions.IsAuthenticated, 'has_permission', return_value=False) as mock_deny: composed_perm = (permissions.IsAuthenticated & permissions.AllowAny) hasperm = composed_perm().has_permission(request, None) - self.assertIs(hasperm, False) + assert hasperm is False + assert mock_deny.call_count == 1 mock_allow.assert_not_called() - mock_deny.assert_called_once() - @pytest.mark.skipif(not PY36, reason="assert_called_once() not available") def test_object_and_lazyness(self): request = factory.get('/1', format='json') request.user = AnonymousUser() @@ -697,14 +666,27 @@ class PermissionsCompositionTests(TestCase): with mock.patch.object(permissions.IsAuthenticated, 'has_object_permission', return_value=False) as mock_deny: composed_perm = (permissions.AllowAny & permissions.IsAuthenticated) hasperm = composed_perm().has_object_permission(request, None, None) - self.assertIs(hasperm, False) - mock_allow.assert_called_once() - mock_deny.assert_called_once() + assert hasperm is False + assert mock_allow.call_count == 1 + assert mock_deny.call_count == 1 with mock.patch.object(permissions.AllowAny, 'has_object_permission', return_value=True) as mock_allow: with mock.patch.object(permissions.IsAuthenticated, 'has_object_permission', return_value=False) as mock_deny: composed_perm = (permissions.IsAuthenticated & permissions.AllowAny) hasperm = composed_perm().has_object_permission(request, None, None) - self.assertIs(hasperm, False) + assert hasperm is False + assert mock_deny.call_count == 1 mock_allow.assert_not_called() - mock_deny.assert_called_once() + + def test_unimplemented_has_object_permission(self): + "test for issue 6402 https://github.com/encode/django-rest-framework/issues/6402" + request = factory.get('/1', format='json') + request.user = AnonymousUser() + + class IsAuthenticatedUserOwner(permissions.IsAuthenticated): + def has_object_permission(self, request, view, obj): + return True + + composed_perm = (IsAuthenticatedUserOwner | permissions.IsAdminUser) + hasperm = composed_perm().has_object_permission(request, None, None) + assert hasperm is False diff --git a/tests/test_relations.py b/tests/test_relations.py index 3c4b7d90b..7a4db1c48 100644 --- a/tests/test_relations.py +++ b/tests/test_relations.py @@ -2,9 +2,9 @@ import uuid import pytest from _pytest.monkeypatch import MonkeyPatch -from django.conf.urls import url from django.core.exceptions import ImproperlyConfigured, ObjectDoesNotExist from django.test import override_settings +from django.urls import re_path from django.utils.datastructures import MultiValueDict from rest_framework import relations, serializers @@ -26,7 +26,7 @@ class TestStringRelatedField(APISimpleTestCase): assert representation == '' -class MockApiSettings(object): +class MockApiSettings: def __init__(self, cutoff, cutoff_text): self.HTML_SELECT_CUTOFF = cutoff self.HTML_SELECT_CUTOFF_TEXT = cutoff_text @@ -107,6 +107,12 @@ class TestPrimaryKeyRelatedField(APISimpleTestCase): msg = excinfo.value.detail[0] assert msg == 'Incorrect type. Expected pk value, received BadType.' + def test_pk_related_lookup_bool(self): + with pytest.raises(serializers.ValidationError) as excinfo: + self.field.to_internal_value(True) + msg = excinfo.value.detail[0] + assert msg == 'Incorrect type. Expected pk value, received bool.' + def test_pk_representation(self): representation = self.field.to_representation(self.instance) assert representation == self.instance.pk @@ -145,14 +151,18 @@ class TestProxiedPrimaryKeyRelatedField(APISimpleTestCase): assert representation == self.instance.pk.int -@override_settings(ROOT_URLCONF=[ - url(r'^example/(?P.+)/$', lambda: None, name='example'), -]) +urlpatterns = [ + re_path(r'^example/(?P.+)/$', lambda: None, name='example'), +] + + +@override_settings(ROOT_URLCONF='tests.test_relations') class TestHyperlinkedRelatedField(APISimpleTestCase): def setUp(self): self.queryset = MockQueryset([ MockObject(pk=1, name='foobar'), MockObject(pk=2, name='bazABCqux'), + MockObject(pk=2, name='bazABC qux'), ]) self.field = serializers.HyperlinkedRelatedField( view_name='example', @@ -191,6 +201,10 @@ class TestHyperlinkedRelatedField(APISimpleTestCase): instance = self.field.to_internal_value('http://example.org/example/baz%41%42%43qux/') assert instance is self.queryset.items[1] + def test_hyperlinked_related_lookup_url_space_encoded_exists(self): + instance = self.field.to_internal_value('http://example.org/example/bazABC%20qux/') + assert instance is self.queryset.items[2] + def test_hyperlinked_related_lookup_does_not_exist(self): with pytest.raises(serializers.ValidationError) as excinfo: self.field.to_internal_value('http://example.org/example/doesnotexist/') @@ -251,7 +265,7 @@ class TestHyperlinkedIdentityField(APISimpleTestCase): def test_improperly_configured(self): """ If a matching view cannot be reversed with the given instance, - the the user has misconfigured something, as the URL conf and the + the user has misconfigured something, as the URL conf and the hyperlinked field do not match. """ self.field.reverse = fail_reverse @@ -360,7 +374,7 @@ class TestManyRelatedField(APISimpleTestCase): class TestHyperlink: - def setup(self): + def setup_method(self): self.default_hyperlink = serializers.Hyperlink('http://example.com', 'test') def test_can_be_pickled(self): diff --git a/tests/test_relations_hyperlink.py b/tests/test_relations_hyperlink.py index 887a6f423..77e4cd95f 100644 --- a/tests/test_relations_hyperlink.py +++ b/tests/test_relations_hyperlink.py @@ -1,7 +1,5 @@ -from __future__ import unicode_literals - -from django.conf.urls import url from django.test import TestCase, override_settings +from django.urls import path from rest_framework import serializers from rest_framework.test import APIRequestFactory @@ -19,14 +17,14 @@ def dummy_view(request, pk): urlpatterns = [ - url(r'^dummyurl/(?P[0-9]+)/$', dummy_view, name='dummy-url'), - url(r'^manytomanysource/(?P[0-9]+)/$', dummy_view, name='manytomanysource-detail'), - url(r'^manytomanytarget/(?P[0-9]+)/$', dummy_view, name='manytomanytarget-detail'), - url(r'^foreignkeysource/(?P[0-9]+)/$', dummy_view, name='foreignkeysource-detail'), - url(r'^foreignkeytarget/(?P[0-9]+)/$', dummy_view, name='foreignkeytarget-detail'), - url(r'^nullableforeignkeysource/(?P[0-9]+)/$', dummy_view, name='nullableforeignkeysource-detail'), - url(r'^onetoonetarget/(?P[0-9]+)/$', dummy_view, name='onetoonetarget-detail'), - url(r'^nullableonetoonesource/(?P[0-9]+)/$', dummy_view, name='nullableonetoonesource-detail'), + path('dummyurl//', dummy_view, name='dummy-url'), + path('manytomanysource//', dummy_view, name='manytomanysource-detail'), + path('manytomanytarget//', dummy_view, name='manytomanytarget-detail'), + path('foreignkeysource//', dummy_view, name='foreignkeysource-detail'), + path('foreignkeytarget//', dummy_view, name='foreignkeytarget-detail'), + path('nullableforeignkeysource//', dummy_view, name='nullableforeignkeysource-detail'), + path('onetoonetarget//', dummy_view, name='onetoonetarget-detail'), + path('nullableonetoonesource//', dummy_view, name='nullableonetoonesource-detail'), ] diff --git a/tests/test_relations_pk.py b/tests/test_relations_pk.py index 2cffb62e6..7a4878a2b 100644 --- a/tests/test_relations_pk.py +++ b/tests/test_relations_pk.py @@ -1,7 +1,4 @@ -from __future__ import unicode_literals - from django.test import TestCase -from django.utils import six from rest_framework import serializers from tests.models import ( @@ -33,6 +30,25 @@ class ForeignKeyTargetSerializer(serializers.ModelSerializer): fields = ('id', 'name', 'sources') +class ForeignKeyTargetCallableSourceSerializer(serializers.ModelSerializer): + first_source = serializers.PrimaryKeyRelatedField( + source='get_first_source', + read_only=True, + ) + + class Meta: + model = ForeignKeyTarget + fields = ('id', 'name', 'first_source') + + +class ForeignKeyTargetPropertySourceSerializer(serializers.ModelSerializer): + first_source = serializers.PrimaryKeyRelatedField(read_only=True) + + class Meta: + model = ForeignKeyTarget + fields = ('id', 'name', 'first_source') + + class ForeignKeySourceSerializer(serializers.ModelSerializer): class Meta: model = ForeignKeySource @@ -263,7 +279,7 @@ class PKForeignKeyTests(TestCase): instance = ForeignKeySource.objects.get(pk=1) serializer = ForeignKeySourceSerializer(instance, data=data) assert not serializer.is_valid() - assert serializer.errors == {'target': ['Incorrect type. Expected pk value, received %s.' % six.text_type.__name__]} + assert serializer.errors == {'target': ['Incorrect type. Expected pk value, received str.']} def test_reverse_foreign_key_update(self): data = {'id': 2, 'name': 'target-2', 'sources': [1, 3]} @@ -392,6 +408,34 @@ class PKForeignKeyTests(TestCase): assert len(queryset) == 1 +class PKRelationTests(TestCase): + + def setUp(self): + self.target = ForeignKeyTarget.objects.create(name='target-1') + ForeignKeySource.objects.create(name='source-1', target=self.target) + ForeignKeySource.objects.create(name='source-2', target=self.target) + + def test_relation_field_callable_source(self): + serializer = ForeignKeyTargetCallableSourceSerializer(self.target) + expected = { + 'id': 1, + 'name': 'target-1', + 'first_source': 1, + } + with self.assertNumQueries(1): + self.assertEqual(serializer.data, expected) + + def test_relation_field_property_source(self): + serializer = ForeignKeyTargetPropertySourceSerializer(self.target) + expected = { + 'id': 1, + 'name': 'target-1', + 'first_source': 1, + } + with self.assertNumQueries(1): + self.assertEqual(serializer.data, expected) + + class PKNullableForeignKeyTests(TestCase): def setUp(self): target = ForeignKeyTarget(name='target-1') @@ -562,7 +606,7 @@ class OneToOnePrimaryKeyTests(TestCase): # When: Trying to create a second object second_source = OneToOnePKSourceSerializer(data=data) self.assertFalse(second_source.is_valid()) - expected = {'target': [u'one to one pk source with this target already exists.']} + expected = {'target': ['one to one pk source with this target already exists.']} self.assertDictEqual(second_source.errors, expected) def test_one_to_one_when_primary_key_does_not_exist(self): diff --git a/tests/test_renderers.py b/tests/test_renderers.py index b4c41b148..8271608e1 100644 --- a/tests/test_renderers.py +++ b/tests/test_renderers.py @@ -1,22 +1,19 @@ -# -*- coding: utf-8 -*- -from __future__ import unicode_literals - import re from collections import OrderedDict +from collections.abc import MutableMapping import pytest -from django.conf.urls import include, url from django.core.cache import cache from django.db import models from django.http.request import HttpRequest from django.template import loader from django.test import TestCase, override_settings -from django.utils import six +from django.urls import include, path, re_path from django.utils.safestring import SafeText -from django.utils.translation import ugettext_lazy as _ +from django.utils.translation import gettext_lazy as _ from rest_framework import permissions, serializers, status -from rest_framework.compat import MutableMapping, coreapi +from rest_framework.compat import coreapi from rest_framework.decorators import action from rest_framework.renderers import ( AdminRenderer, BaseRenderer, BrowsableAPIRenderer, DocumentationRenderer, @@ -79,8 +76,7 @@ class MockView(APIView): renderer_classes = (RendererA, RendererB) def get(self, request, **kwargs): - response = Response(DUMMYCONTENT, status=DUMMYSTATUS) - return response + return Response(DUMMYCONTENT, status=DUMMYSTATUS) class MockGETView(APIView): @@ -115,14 +111,14 @@ class HTMLView1(APIView): urlpatterns = [ - url(r'^.*\.(?P.+)$', MockView.as_view(renderer_classes=[RendererA, RendererB])), - url(r'^$', MockView.as_view(renderer_classes=[RendererA, RendererB])), - url(r'^cache$', MockGETView.as_view()), - url(r'^parseerror$', MockPOSTView.as_view(renderer_classes=[JSONRenderer, BrowsableAPIRenderer])), - url(r'^html$', HTMLView.as_view()), - url(r'^html1$', HTMLView1.as_view()), - url(r'^empty$', EmptyGETView.as_view()), - url(r'^api', include('rest_framework.urls', namespace='rest_framework')) + re_path(r'^.*\.(?P.+)$', MockView.as_view(renderer_classes=[RendererA, RendererB])), + path('', MockView.as_view(renderer_classes=[RendererA, RendererB])), + path('cache', MockGETView.as_view()), + path('parseerror', MockPOSTView.as_view(renderer_classes=[JSONRenderer, BrowsableAPIRenderer])), + path('html', HTMLView.as_view()), + path('html1', HTMLView1.as_view()), + path('empty', EmptyGETView.as_view()), + path('api', include('rest_framework.urls', namespace='rest_framework')) ] @@ -175,7 +171,7 @@ class RendererEndToEndTests(TestCase): resp = self.client.head('/') self.assertEqual(resp.status_code, DUMMYSTATUS) self.assertEqual(resp['Content-Type'], RendererA.media_type + '; charset=utf-8') - self.assertEqual(resp.content, six.b('')) + self.assertEqual(resp.content, b'') def test_default_renderer_serializes_content_on_accept_any(self): """If the Accept header is set to */* the default renderer should serialize the response.""" @@ -307,14 +303,14 @@ class JSONRendererTests(TestCase): o = DummyTestModel.objects.create(name='dummy') qs = DummyTestModel.objects.values('id', 'name') ret = JSONRenderer().render(qs) - data = json.loads(ret.decode('utf-8')) + data = json.loads(ret.decode()) self.assertEqual(data, [{'id': o.id, 'name': o.name}]) def test_render_queryset_values_list(self): o = DummyTestModel.objects.create(name='dummy') qs = DummyTestModel.objects.values_list('id', 'name') ret = JSONRenderer().render(qs) - data = json.loads(ret.decode('utf-8')) + data = json.loads(ret.decode()) self.assertEqual(data, [[o.id, o.name]]) def test_render_dict_abc_obj(self): @@ -344,11 +340,11 @@ class JSONRendererTests(TestCase): x['key'] = 'string value' x[2] = 3 ret = JSONRenderer().render(x) - data = json.loads(ret.decode('utf-8')) + data = json.loads(ret.decode()) self.assertEqual(data, {'key': 'string value', '2': 3}) def test_render_obj_with_getitem(self): - class DictLike(object): + class DictLike: def __init__(self): self._dict = {} @@ -384,7 +380,7 @@ class JSONRendererTests(TestCase): renderer = JSONRenderer() content = renderer.render(obj, 'application/json') # Fix failing test case which depends on version of JSON library. - self.assertEqual(content.decode('utf-8'), _flat_repr) + self.assertEqual(content.decode(), _flat_repr) def test_with_content_type_args(self): """ @@ -393,7 +389,7 @@ class JSONRendererTests(TestCase): obj = {'foo': ['bar', 'baz']} renderer = JSONRenderer() content = renderer.render(obj, 'application/json; indent=2') - self.assertEqual(strip_trailing_whitespace(content.decode('utf-8')), _indented_repr) + self.assertEqual(strip_trailing_whitespace(content.decode()), _indented_repr) class UnicodeJSONRendererTests(TestCase): @@ -404,7 +400,7 @@ class UnicodeJSONRendererTests(TestCase): obj = {'countries': ['United Kingdom', 'France', 'España']} renderer = JSONRenderer() content = renderer.render(obj, 'application/json') - self.assertEqual(content, '{"countries":["United Kingdom","France","España"]}'.encode('utf-8')) + self.assertEqual(content, '{"countries":["United Kingdom","France","España"]}'.encode()) def test_u2028_u2029(self): # The \u2028 and \u2029 characters should be escaped, @@ -413,7 +409,7 @@ class UnicodeJSONRendererTests(TestCase): obj = {'should_escape': '\u2028\u2029'} renderer = JSONRenderer() content = renderer.render(obj, 'application/json') - self.assertEqual(content, '{"should_escape":"\\u2028\\u2029"}'.encode('utf-8')) + self.assertEqual(content, '{"should_escape":"\\u2028\\u2029"}'.encode()) class AsciiJSONRendererTests(TestCase): @@ -426,7 +422,7 @@ class AsciiJSONRendererTests(TestCase): obj = {'countries': ['United Kingdom', 'France', 'España']} renderer = AsciiJSONRenderer() content = renderer.render(obj, 'application/json') - self.assertEqual(content, '{"countries":["United Kingdom","France","Espa\\u00f1a"]}'.encode('utf-8')) + self.assertEqual(content, '{"countries":["United Kingdom","France","Espa\\u00f1a"]}'.encode()) # Tests for caching issue, #346 @@ -635,9 +631,13 @@ class BrowsableAPIRendererTests(URLPatternsTestCase): def list_action(self, request): raise NotImplementedError + class AuthExampleViewSet(ExampleViewSet): + permission_classes = [permissions.IsAuthenticated] + router = SimpleRouter() - router.register('examples', ExampleViewSet, base_name='example') - urlpatterns = [url(r'^api/', include(router.urls))] + router.register('examples', ExampleViewSet, basename='example') + router.register('auth-examples', AuthExampleViewSet, basename='auth-example') + urlpatterns = [path('api/', include(router.urls))] def setUp(self): self.renderer = BrowsableAPIRenderer() @@ -647,7 +647,7 @@ class BrowsableAPIRendererTests(URLPatternsTestCase): assert self.renderer.get_description({}, status_code=403) == '' def test_get_filter_form_returns_none_if_data_is_not_list_instance(self): - class DummyView(object): + class DummyView: get_queryset = None filter_backends = None @@ -657,9 +657,15 @@ class BrowsableAPIRendererTests(URLPatternsTestCase): def test_extra_actions_dropdown(self): resp = self.client.get('/api/examples/', HTTP_ACCEPT='text/html') - assert 'id="extra-actions-menu"' in resp.content.decode('utf-8') - assert '/api/examples/list_action/' in resp.content.decode('utf-8') - assert '>Extra list action<' in resp.content.decode('utf-8') + assert 'id="extra-actions-menu"' in resp.content.decode() + assert '/api/examples/list_action/' in resp.content.decode() + assert '>Extra list action<' in resp.content.decode() + + def test_extra_actions_dropdown_not_authed(self): + resp = self.client.get('/api/unauth-examples/', HTTP_ACCEPT='text/html') + assert 'id="extra-actions-menu"' not in resp.content.decode() + assert '/api/examples/list_action/' not in resp.content.decode() + assert '>Extra list action<' not in resp.content.decode() class AdminRendererTests(TestCase): @@ -735,6 +741,11 @@ class AdminRendererTests(TestCase): class DummyGenericViewsetLike(APIView): lookup_field = 'test' + def get(self, request): + response = Response() + response.view = self + return response + def reverse_action(view, *args, **kwargs): self.assertEqual(kwargs['kwargs']['test'], 1) return '/example/' @@ -743,7 +754,7 @@ class AdminRendererTests(TestCase): view = DummyGenericViewsetLike.as_view() request = factory.get('/') response = view(request) - view = response.renderer_context['view'] + view = response.view self.assertEqual(self.renderer.get_result_url({'test': 1}, view), '/example/') self.assertIsNone(self.renderer.get_result_url({}, view)) @@ -754,11 +765,16 @@ class AdminRendererTests(TestCase): class DummyView(APIView): lookup_field = 'test' + def get(self, request): + response = Response() + response.view = self + return response + # get the view instance instead of the view function view = DummyView.as_view() request = factory.get('/') response = view(request) - view = response.renderer_context['view'] + view = response.view self.assertIsNone(self.renderer.get_result_url({'test': 1}, view)) self.assertIsNone(self.renderer.get_result_url({}, view)) diff --git a/tests/test_request.py b/tests/test_request.py index 83d295a12..8c18aea9e 100644 --- a/tests/test_request.py +++ b/tests/test_request.py @@ -1,13 +1,11 @@ """ Tests for content parsing, and form-overloaded content parsing. """ -from __future__ import unicode_literals - +import copy import os.path import tempfile import pytest -from django.conf.urls import url from django.contrib.auth import authenticate, login, logout from django.contrib.auth.middleware import AuthenticationMiddleware from django.contrib.auth.models import User @@ -15,7 +13,7 @@ from django.contrib.sessions.middleware import SessionMiddleware from django.core.files.uploadedfile import SimpleUploadedFile from django.http.request import RawPostDataException from django.test import TestCase, override_settings -from django.utils import six +from django.urls import path from rest_framework import status from rest_framework.authentication import SessionAuthentication @@ -82,7 +80,7 @@ class TestContentParsing(TestCase): Ensure request.data returns content for POST request with non-form content. """ - content = six.b('qwerty') + content = b'qwerty' content_type = 'text/plain' request = Request(factory.post('/', content, content_type=content_type)) request.parsers = (PlainTextParser(),) @@ -121,7 +119,7 @@ class TestContentParsing(TestCase): Ensure request.data returns content for PUT request with non-form content. """ - content = six.b('qwerty') + content = b'qwerty' content_type = 'text/plain' request = Request(factory.put('/', content, content_type=content_type)) request.parsers = (PlainTextParser(), ) @@ -140,7 +138,9 @@ class MockView(APIView): class EchoView(APIView): def post(self, request): - return Response(status=status.HTTP_200_OK, data=request.data) + response = Response(status=status.HTTP_200_OK, data=request.data) + response._request = request # test client sets `request` input + return response class FileUploadView(APIView): @@ -154,9 +154,9 @@ class FileUploadView(APIView): urlpatterns = [ - url(r'^$', MockView.as_view()), - url(r'^echo/$', EchoView.as_view()), - url(r'^upload/$', FileUploadView.as_view()) + path('', MockView.as_view()), + path('echo/', EchoView.as_view()), + path('upload/', FileUploadView.as_view()) ] @@ -206,8 +206,12 @@ class TestUserSetter(TestCase): # available to login and logout functions self.wrapped_request = factory.get('/') self.request = Request(self.wrapped_request) - SessionMiddleware().process_request(self.wrapped_request) - AuthenticationMiddleware().process_request(self.wrapped_request) + + def dummy_get_response(request): # pragma: no cover + return None + + SessionMiddleware(dummy_get_response).process_request(self.wrapped_request) + AuthenticationMiddleware(dummy_get_response).process_request(self.wrapped_request) User.objects.create_user('ringo', 'starr@thebeatles.com', 'yellow') self.user = authenticate(username='ringo', password='yellow') @@ -235,7 +239,7 @@ class TestUserSetter(TestCase): This proves that when an AttributeError is raised inside of the request.user property, that we can handle this and report the true, underlying error. """ - class AuthRaisesAttributeError(object): + class AuthRaisesAttributeError: def authenticate(self, request): self.MISSPELLED_NAME_THAT_DOESNT_EXIST @@ -249,10 +253,6 @@ class TestUserSetter(TestCase): with pytest.raises(WrappedAttributeError, match=expected): request.user - # python 2 hasattr fails for *any* exception, not just AttributeError - if six.PY2: - return - with pytest.raises(WrappedAttributeError, match=expected): hasattr(request, 'user') @@ -279,6 +279,12 @@ class TestSecure(TestCase): class TestHttpRequest(TestCase): + def test_repr(self): + http_request = factory.get('/path') + request = Request(http_request) + + assert repr(request) == "" + def test_attribute_access_proxy(self): http_request = factory.get('/') request = Request(http_request) @@ -307,7 +313,7 @@ class TestHttpRequest(TestCase): `RawPostDataException` being raised. """ response = APIClient().post('/echo/', data={'a': 'b'}, format='json') - request = response.renderer_context['request'] + request = response._request # ensure that request stream was consumed by json parser assert request.content_type.startswith('application/json') @@ -326,7 +332,7 @@ class TestHttpRequest(TestCase): the duplicate stream parse exception. """ response = APIClient().post('/echo/', data={'a': 'b'}) - request = response.renderer_context['request'] + request = response._request # ensure that request stream was consumed by form parser assert request.content_type.startswith('multipart/form-data') @@ -334,8 +340,15 @@ class TestHttpRequest(TestCase): # pass same HttpRequest to view, form data set on underlying request response = EchoView.as_view()(request._request) - request = response.renderer_context['request'] + request = response._request # ensure that request stream was consumed by form parser assert request.content_type.startswith('multipart/form-data') assert response.data == {'a': ['b']} + + +class TestDeepcopy(TestCase): + + def test_deepcopy_works(self): + request = Request(factory.get('/', secure=False)) + copy.deepcopy(request) diff --git a/tests/test_requests_client.py b/tests/test_requests_client.py index 161429f73..c8e7be6ee 100644 --- a/tests/test_requests_client.py +++ b/tests/test_requests_client.py @@ -1,12 +1,10 @@ -from __future__ import unicode_literals - import unittest -from django.conf.urls import url from django.contrib.auth import authenticate, login from django.contrib.auth.models import User from django.shortcuts import redirect from django.test import override_settings +from django.urls import path from django.utils.decorators import method_decorator from django.views.decorators.csrf import csrf_protect, ensure_csrf_cookie @@ -92,10 +90,10 @@ class AuthView(APIView): urlpatterns = [ - url(r'^$', Root.as_view(), name='root'), - url(r'^headers/$', HeadersView.as_view(), name='headers'), - url(r'^session/$', SessionView.as_view(), name='session'), - url(r'^auth/$', AuthView.as_view(), name='auth'), + path('', Root.as_view(), name='root'), + path('headers/', HeadersView.as_view(), name='headers'), + path('session/', SessionView.as_view(), name='session'), + path('auth/', AuthView.as_view(), name='auth'), ] diff --git a/tests/test_response.py b/tests/test_response.py index e92bf54c1..0d5528dc9 100644 --- a/tests/test_response.py +++ b/tests/test_response.py @@ -1,8 +1,5 @@ -from __future__ import unicode_literals - -from django.conf.urls import include, url from django.test import TestCase, override_settings -from django.utils import six +from django.urls import include, path, re_path from rest_framework import generics, routers, serializers, status, viewsets from rest_framework.parsers import JSONParser @@ -120,15 +117,15 @@ new_model_viewset_router.register(r'', HTMLNewModelViewSet) urlpatterns = [ - url(r'^setbyview$', MockViewSettingContentType.as_view(renderer_classes=[RendererA, RendererB, RendererC])), - url(r'^.*\.(?P.+)$', MockView.as_view(renderer_classes=[RendererA, RendererB, RendererC])), - url(r'^$', MockView.as_view(renderer_classes=[RendererA, RendererB, RendererC])), - url(r'^html$', HTMLView.as_view()), - url(r'^json$', JSONView.as_view()), - url(r'^html1$', HTMLView1.as_view()), - url(r'^html_new_model$', HTMLNewModelView.as_view()), - url(r'^html_new_model_viewset', include(new_model_viewset_router.urls)), - url(r'^restframework', include('rest_framework.urls', namespace='rest_framework')) + path('setbyview', MockViewSettingContentType.as_view(renderer_classes=[RendererA, RendererB, RendererC])), + re_path(r'^.*\.(?P.+)$', MockView.as_view(renderer_classes=[RendererA, RendererB, RendererC])), + path('', MockView.as_view(renderer_classes=[RendererA, RendererB, RendererC])), + path('html', HTMLView.as_view()), + path('json', JSONView.as_view()), + path('html1', HTMLView1.as_view()), + path('html_new_model', HTMLNewModelView.as_view()), + path('html_new_model_viewset', include(new_model_viewset_router.urls)), + path('restframework', include('rest_framework.urls', namespace='rest_framework')) ] @@ -150,7 +147,7 @@ class RendererIntegrationTests(TestCase): resp = self.client.head('/') self.assertEqual(resp.status_code, DUMMYSTATUS) self.assertEqual(resp['Content-Type'], RendererA.media_type + '; charset=utf-8') - self.assertEqual(resp.content, six.b('')) + self.assertEqual(resp.content, b'') def test_default_renderer_serializes_content_on_accept_any(self): """If the Accept header is set to */* the default renderer should serialize the response.""" @@ -260,7 +257,7 @@ class Issue807Tests(TestCase): """ headers = {"HTTP_ACCEPT": RendererA.media_type} resp = self.client.get('/', **headers) - expected = "{0}; charset={1}".format(RendererA.media_type, 'utf-8') + expected = "{}; charset={}".format(RendererA.media_type, 'utf-8') self.assertEqual(expected, resp['Content-Type']) def test_if_there_is_charset_specified_on_renderer_it_gets_appended(self): @@ -270,7 +267,7 @@ class Issue807Tests(TestCase): """ headers = {"HTTP_ACCEPT": RendererC.media_type} resp = self.client.get('/', **headers) - expected = "{0}; charset={1}".format(RendererC.media_type, RendererC.charset) + expected = "{}; charset={}".format(RendererC.media_type, RendererC.charset) self.assertEqual(expected, resp['Content-Type']) def test_content_type_set_explicitly_on_response(self): diff --git a/tests/test_reverse.py b/tests/test_reverse.py index 145b1a54f..b26b448c9 100644 --- a/tests/test_reverse.py +++ b/tests/test_reverse.py @@ -1,8 +1,5 @@ -from __future__ import unicode_literals - -from django.conf.urls import url from django.test import TestCase, override_settings -from django.urls import NoReverseMatch +from django.urls import NoReverseMatch, path from rest_framework.reverse import reverse from rest_framework.test import APIRequestFactory @@ -15,11 +12,11 @@ def null_view(request): urlpatterns = [ - url(r'^view$', null_view, name='view'), + path('view', null_view, name='view'), ] -class MockVersioningScheme(object): +class MockVersioningScheme: def __init__(self, raise_error=False): self.raise_error = raise_error diff --git a/tests/test_routers.py b/tests/test_routers.py index a3a731f93..f767a843d 100644 --- a/tests/test_routers.py +++ b/tests/test_routers.py @@ -1,19 +1,12 @@ -from __future__ import unicode_literals - -import warnings from collections import namedtuple import pytest -from django.conf.urls import include, url from django.core.exceptions import ImproperlyConfigured from django.db import models from django.test import TestCase, override_settings -from django.urls import resolve, reverse +from django.urls import include, path, resolve, reverse -from rest_framework import ( - RemovedInDRF311Warning, permissions, serializers, viewsets -) -from rest_framework.compat import get_regex_pattern +from rest_framework import permissions, serializers, viewsets from rest_framework.decorators import action from rest_framework.response import Response from rest_framework.routers import DefaultRouter, SimpleRouter @@ -121,10 +114,10 @@ class BasicViewSet(viewsets.ViewSet): class TestSimpleRouter(URLPatternsTestCase, TestCase): router = SimpleRouter() - router.register('basics', BasicViewSet, base_name='basic') + router.register('basics', BasicViewSet, basename='basic') urlpatterns = [ - url(r'^api/', include(router.urls)), + path('api/', include(router.urls)), ] def setUp(self): @@ -169,8 +162,8 @@ class TestSimpleRouter(URLPatternsTestCase, TestCase): class TestRootView(URLPatternsTestCase, TestCase): urlpatterns = [ - url(r'^non-namespaced/', include(namespaced_router.urls)), - url(r'^namespaced/', include((namespaced_router.urls, 'namespaced'), namespace='namespaced')), + path('non-namespaced/', include(namespaced_router.urls)), + path('namespaced/', include((namespaced_router.urls, 'namespaced'), namespace='namespaced')), ] def test_retrieve_namespaced_root(self): @@ -187,8 +180,8 @@ class TestCustomLookupFields(URLPatternsTestCase, TestCase): Ensure that custom lookup fields are correctly routed. """ urlpatterns = [ - url(r'^example/', include(notes_router.urls)), - url(r'^example2/', include(kwarged_notes_router.urls)), + path('example/', include(notes_router.urls)), + path('example2/', include(kwarged_notes_router.urls)), ] def setUp(self): @@ -197,8 +190,7 @@ class TestCustomLookupFields(URLPatternsTestCase, TestCase): def test_custom_lookup_field_route(self): detail_route = notes_router.urls[-1] - detail_url_pattern = get_regex_pattern(detail_route) - assert '' in detail_url_pattern + assert '' in detail_route.pattern.regex.pattern def test_retrieve_lookup_field_list_view(self): response = self.client.get('/example/notes/') @@ -234,7 +226,7 @@ class TestLookupValueRegex(TestCase): def test_urls_limited_by_lookup_value_regex(self): expected = ['^notes/$', '^notes/(?P[0-9a-f]{32})/$'] for idx in range(len(expected)): - assert expected[idx] == get_regex_pattern(self.urls[idx]) + assert expected[idx] == self.urls[idx].pattern.regex.pattern @override_settings(ROOT_URLCONF='tests.test_routers') @@ -245,8 +237,8 @@ class TestLookupUrlKwargs(URLPatternsTestCase, TestCase): Setup a deep lookup_field, but map it to a simple URL kwarg. """ urlpatterns = [ - url(r'^example/', include(notes_router.urls)), - url(r'^example2/', include(kwarged_notes_router.urls)), + path('example/', include(notes_router.urls)), + path('example2/', include(kwarged_notes_router.urls)), ] def setUp(self): @@ -254,8 +246,7 @@ class TestLookupUrlKwargs(URLPatternsTestCase, TestCase): def test_custom_lookup_url_kwarg_route(self): detail_route = kwarged_notes_router.urls[-1] - detail_url_pattern = get_regex_pattern(detail_route) - assert '^notes/(?P' in detail_url_pattern + assert '^notes/(?P' in detail_route.pattern.regex.pattern def test_retrieve_lookup_url_kwarg_detail_view(self): response = self.client.get('/example2/notes/fo/') @@ -278,7 +269,7 @@ class TestTrailingSlashIncluded(TestCase): def test_urls_have_trailing_slash_by_default(self): expected = ['^notes/$', '^notes/(?P[^/.]+)/$'] for idx in range(len(expected)): - assert expected[idx] == get_regex_pattern(self.urls[idx]) + assert expected[idx] == self.urls[idx].pattern.regex.pattern class TestTrailingSlashRemoved(TestCase): @@ -293,7 +284,7 @@ class TestTrailingSlashRemoved(TestCase): def test_urls_can_have_trailing_slash_removed(self): expected = ['^notes$', '^notes/(?P[^/.]+)$'] for idx in range(len(expected)): - assert expected[idx] == get_regex_pattern(self.urls[idx]) + assert expected[idx] == self.urls[idx].pattern.regex.pattern class TestNameableRoot(TestCase): @@ -434,43 +425,43 @@ class TestDynamicListAndDetailRouter(TestCase): class TestEmptyPrefix(URLPatternsTestCase, TestCase): urlpatterns = [ - url(r'^empty-prefix/', include(empty_prefix_router.urls)), + path('empty-prefix/', include(empty_prefix_router.urls)), ] def test_empty_prefix_list(self): response = self.client.get('/empty-prefix/') assert response.status_code == 200 - assert json.loads(response.content.decode('utf-8')) == [{'uuid': '111', 'text': 'First'}, - {'uuid': '222', 'text': 'Second'}] + assert json.loads(response.content.decode()) == [{'uuid': '111', 'text': 'First'}, + {'uuid': '222', 'text': 'Second'}] def test_empty_prefix_detail(self): response = self.client.get('/empty-prefix/1/') assert response.status_code == 200 - assert json.loads(response.content.decode('utf-8')) == {'uuid': '111', 'text': 'First'} + assert json.loads(response.content.decode()) == {'uuid': '111', 'text': 'First'} class TestRegexUrlPath(URLPatternsTestCase, TestCase): urlpatterns = [ - url(r'^regex/', include(regex_url_path_router.urls)), + path('regex/', include(regex_url_path_router.urls)), ] def test_regex_url_path_list(self): kwarg = '1234' response = self.client.get('/regex/list/{}/'.format(kwarg)) assert response.status_code == 200 - assert json.loads(response.content.decode('utf-8')) == {'kwarg': kwarg} + assert json.loads(response.content.decode()) == {'kwarg': kwarg} def test_regex_url_path_detail(self): pk = '1' kwarg = '1234' response = self.client.get('/regex/{}/detail/{}/'.format(pk, kwarg)) assert response.status_code == 200 - assert json.loads(response.content.decode('utf-8')) == {'pk': pk, 'kwarg': kwarg} + assert json.loads(response.content.decode()) == {'pk': pk, 'kwarg': kwarg} class TestViewInitkwargs(URLPatternsTestCase, TestCase): urlpatterns = [ - url(r'^example/', include(notes_router.urls)), + path('example/', include(notes_router.urls)), ] def test_suffix(self): @@ -490,71 +481,3 @@ class TestViewInitkwargs(URLPatternsTestCase, TestCase): initkwargs = match.func.initkwargs assert initkwargs['basename'] == 'routertestmodel' - - -class TestBaseNameRename(TestCase): - - def test_base_name_and_basename_assertion(self): - router = SimpleRouter() - - msg = "Do not provide both the `basename` and `base_name` arguments." - with warnings.catch_warnings(record=True) as w, \ - self.assertRaisesMessage(AssertionError, msg): - warnings.simplefilter('always') - router.register('mock', MockViewSet, 'mock', base_name='mock') - - msg = "The `base_name` argument is pending deprecation in favor of `basename`." - assert len(w) == 1 - assert str(w[0].message) == msg - - def test_base_name_argument_deprecation(self): - router = SimpleRouter() - - with pytest.warns(RemovedInDRF311Warning) as w: - warnings.simplefilter('always') - router.register('mock', MockViewSet, base_name='mock') - - msg = "The `base_name` argument is pending deprecation in favor of `basename`." - assert len(w) == 1 - assert str(w[0].message) == msg - assert router.registry == [ - ('mock', MockViewSet, 'mock'), - ] - - def test_basename_argument_no_warnings(self): - router = SimpleRouter() - - with warnings.catch_warnings(record=True) as w: - warnings.simplefilter('always') - router.register('mock', MockViewSet, basename='mock') - - assert len(w) == 0 - assert router.registry == [ - ('mock', MockViewSet, 'mock'), - ] - - def test_get_default_base_name_deprecation(self): - msg = "`CustomRouter.get_default_base_name` method should be renamed `get_default_basename`." - - # Class definition should raise a warning - with pytest.warns(RemovedInDRF311Warning) as w: - warnings.simplefilter('always') - - class CustomRouter(SimpleRouter): - def get_default_base_name(self, viewset): - return 'foo' - - assert len(w) == 1 - assert str(w[0].message) == msg - - # Deprecated method implementation should still be called - with warnings.catch_warnings(record=True) as w: - warnings.simplefilter('always') - - router = CustomRouter() - router.register('mock', MockViewSet) - - assert len(w) == 0 - assert router.registry == [ - ('mock', MockViewSet, 'foo'), - ] diff --git a/tests/test_serializer.py b/tests/test_serializer.py index 0f1e81965..1d9efaa43 100644 --- a/tests/test_serializer.py +++ b/tests/test_serializer.py @@ -1,16 +1,14 @@ -# coding: utf-8 -from __future__ import unicode_literals - import inspect import pickle import re -import unittest +import sys +from collections import ChainMap +from collections.abc import Mapping import pytest from django.db import models from rest_framework import exceptions, fields, relations, serializers -from rest_framework.compat import Mapping, unicode_repr from rest_framework.fields import Field from .models import ( @@ -18,15 +16,9 @@ from .models import ( ) from .utils import MockObject -try: - from collections import ChainMap -except ImportError: - ChainMap = False - # Test serializer fields imports. # ------------------------------- - class TestFieldImports: def is_field(self, name, value): return ( @@ -69,7 +61,7 @@ class TestFieldImports: # ----------------------------- class TestSerializer: - def setup(self): + def setup_method(self): class ExampleSerializer(serializers.Serializer): char = serializers.CharField() integer = serializers.IntegerField() @@ -130,7 +122,6 @@ class TestSerializer: assert not serializer.is_valid() assert serializer.errors == {'non_field_errors': ['No data provided']} - @unittest.skipUnless(ChainMap, 'requires python 3.3') def test_serialize_chainmap(self): data = ChainMap({'char': 'abc'}, {'integer': 123}) serializer = self.Serializer(data=data) @@ -160,7 +151,7 @@ class TestSerializer: to_internal_value() is expected to return a dict, but subclasses may return application specific type. """ - class Point(object): + class Point: def __init__(self, srid, x, y): self.srid = srid self.coords = (x, y) @@ -171,7 +162,7 @@ class TestSerializer: latitude = serializers.FloatField(source='y') def to_internal_value(self, data): - kwargs = super(NestedPointSerializer, self).to_internal_value(data) + kwargs = super().to_internal_value(data) return Point(srid=4326, **kwargs) serializer = NestedPointSerializer(data={'longitude': 6.958307, 'latitude': 50.941357}) @@ -201,7 +192,7 @@ class TestSerializer: def raise_exception(value): raise exceptions.ValidationError('Raised error') - for validators in ([raise_exception], (raise_exception,), set([raise_exception])): + for validators in ([raise_exception], (raise_exception,), {raise_exception}): class ExampleSerializer(serializers.Serializer): char = serializers.CharField(validators=validators) integer = serializers.IntegerField() @@ -214,6 +205,13 @@ class TestSerializer: exceptions.ErrorDetail(string='Raised error', code='invalid') ]} + @pytest.mark.skipif( + sys.version_info < (3, 7), + reason="subscriptable classes requires Python 3.7 or higher", + ) + def test_serializer_is_subscriptable(self): + assert serializers.Serializer is serializers.Serializer["foo"] + class TestValidateMethod: def test_non_field_error_validate_method(self): @@ -242,7 +240,7 @@ class TestValidateMethod: class TestBaseSerializer: - def setup(self): + def setup_method(self): class ExampleSerializer(serializers.BaseSerializer): def to_representation(self, obj): return { @@ -327,7 +325,8 @@ class TestBaseSerializer: class TestStarredSource: """ - Tests for `source='*'` argument, which is used for nested representations. + Tests for `source='*'` argument, which is often used for complex field or + nested representations. For example: @@ -338,7 +337,7 @@ class TestStarredSource: 'nested2': {'c': 3, 'd': 4} } - def setup(self): + def setup_method(self): class NestedSerializer1(serializers.Serializer): a = serializers.IntegerField() b = serializers.IntegerField() @@ -347,11 +346,28 @@ class TestStarredSource: c = serializers.IntegerField() d = serializers.IntegerField() - class TestSerializer(serializers.Serializer): + class NestedBaseSerializer(serializers.Serializer): nested1 = NestedSerializer1(source='*') nested2 = NestedSerializer2(source='*') - self.Serializer = TestSerializer + # nullable nested serializer testing + class NullableNestedSerializer(serializers.Serializer): + nested = NestedSerializer1(source='*', allow_null=True) + + # nullable custom field testing + class CustomField(serializers.Field): + def to_representation(self, instance): + return getattr(instance, 'foo', None) + + def to_internal_value(self, data): + return {'foo': data} + + class NullableFieldSerializer(serializers.Serializer): + field = CustomField(source='*', allow_null=True) + + self.Serializer = NestedBaseSerializer + self.NullableNestedSerializer = NullableNestedSerializer + self.NullableFieldSerializer = NullableFieldSerializer def test_nested_validate(self): """ @@ -366,6 +382,12 @@ class TestStarredSource: 'd': 4 } + def test_nested_null_validate(self): + serializer = self.NullableNestedSerializer(data={'nested': None}) + + # validation should fail (but not error) since nested fields are required + assert not serializer.is_valid() + def test_nested_serialize(self): """ An object can be serialized into a nested representation. @@ -374,6 +396,20 @@ class TestStarredSource: serializer = self.Serializer(instance) assert serializer.data == self.data + def test_field_validate(self): + serializer = self.NullableFieldSerializer(data={'field': 'bar'}) + + # validation should pass since no internal validation + assert serializer.is_valid() + assert serializer.validated_data == {'foo': 'bar'} + + def test_field_null_validate(self): + serializer = self.NullableFieldSerializer(data={'field': None}) + + # validation should pass since no internal validation + assert serializer.is_valid() + assert serializer.validated_data == {'foo': None} + class TestIncorrectlyConfigured: def test_incorrect_field_name(self): @@ -396,23 +432,6 @@ class TestIncorrectlyConfigured: ) -class TestUnicodeRepr: - def test_unicode_repr(self): - class ExampleSerializer(serializers.Serializer): - example = serializers.CharField() - - class ExampleObject: - def __init__(self): - self.example = '한국' - - def __repr__(self): - return unicode_repr(self.example) - - instance = ExampleObject() - serializer = ExampleSerializer(instance) - repr(serializer) # Should not error. - - class TestNotRequiredOutput: def test_not_required_output_for_dict(self): """ @@ -444,7 +463,7 @@ class TestNotRequiredOutput: class TestDefaultOutput: - def setup(self): + def setup_method(self): class ExampleSerializer(serializers.Serializer): has_default = serializers.CharField(default='x') has_default_callable = serializers.CharField(default=lambda: 'y') @@ -544,7 +563,7 @@ class TestDefaultOutput: bar = serializers.CharField(source='foo.bar', allow_null=True) optional = serializers.CharField(required=False, allow_null=True) - # allow_null=True should imply default=None when serialising: + # allow_null=True should imply default=None when serializing: assert Serializer({'foo': None}).data == {'foo': None, 'bar': None, 'optional': None, } @@ -565,7 +584,7 @@ class TestCacheSerializerData: class TestDefaultInclusions: - def setup(self): + def setup_method(self): class ExampleSerializer(serializers.Serializer): char = serializers.CharField(default='abc') integer = serializers.IntegerField() @@ -593,7 +612,7 @@ class TestDefaultInclusions: class TestSerializerValidationWithCompiledRegexField: - def setup(self): + def setup_method(self): class ExampleSerializer(serializers.Serializer): name = serializers.RegexField(re.compile(r'\d'), required=True) self.Serializer = ExampleSerializer @@ -609,7 +628,7 @@ class Test2555Regression: def test_serializer_context(self): class NestedSerializer(serializers.Serializer): def __init__(self, *args, **kwargs): - super(NestedSerializer, self).__init__(*args, **kwargs) + super().__init__(*args, **kwargs) # .context should not cache self.context @@ -622,7 +641,7 @@ class Test2555Regression: class Test4606Regression: - def setup(self): + def setup_method(self): class ExampleSerializer(serializers.Serializer): name = serializers.CharField(required=True) choices = serializers.CharField(required=True) @@ -671,3 +690,75 @@ class TestDeclaredFieldInheritance: assert len(Parent().get_fields()) == 2 assert len(Child().get_fields()) == 2 assert len(Grandchild().get_fields()) == 2 + + def test_multiple_inheritance(self): + class A(serializers.Serializer): + field = serializers.CharField() + + class B(serializers.Serializer): + field = serializers.IntegerField() + + class TestSerializer(A, B): + pass + + fields = { + name: type(f) for name, f + in TestSerializer()._declared_fields.items() + } + assert fields == { + 'field': serializers.CharField, + } + + def test_field_ordering(self): + class Base(serializers.Serializer): + f1 = serializers.CharField() + f2 = serializers.CharField() + + class A(Base): + f3 = serializers.IntegerField() + + class B(serializers.Serializer): + f3 = serializers.CharField() + f4 = serializers.CharField() + + class TestSerializer(A, B): + f2 = serializers.IntegerField() + f5 = serializers.CharField() + + fields = { + name: type(f) for name, f + in TestSerializer()._declared_fields.items() + } + + # `IntegerField`s should be the 'winners' in field name conflicts + # - `TestSerializer.f2` should override `Base.F2` + # - `A.f3` should override `B.f3` + assert fields == { + 'f1': serializers.CharField, + 'f2': serializers.IntegerField, + 'f3': serializers.IntegerField, + 'f4': serializers.CharField, + 'f5': serializers.CharField, + } + + +class Test8301Regression: + @pytest.mark.skipif( + sys.version_info < (3, 9), + reason="dictionary union operator requires Python 3.9 or higher", + ) + def test_ReturnDict_merging(self): + # Serializer.data returns ReturnDict, this is essentially a test for that. + + class TestSerializer(serializers.Serializer): + char = serializers.CharField() + + s = TestSerializer(data={'char': 'x'}) + assert s.is_valid() + assert s.data | {} == {'char': 'x'} + assert s.data | {'other': 'y'} == {'char': 'x', 'other': 'y'} + assert {} | s.data == {'char': 'x'} + assert {'other': 'y'} | s.data == {'char': 'x', 'other': 'y'} + + assert (s.data | {}).__class__ == s.data.__class__ + assert ({} | s.data).__class__ == s.data.__class__ diff --git a/tests/test_serializer_bulk_update.py b/tests/test_serializer_bulk_update.py index d9e5d7978..0465578bb 100644 --- a/tests/test_serializer_bulk_update.py +++ b/tests/test_serializer_bulk_update.py @@ -1,10 +1,7 @@ """ Tests to cover bulk create and update using serializers. """ -from __future__ import unicode_literals - from django.test import TestCase -from django.utils import six from rest_framework import serializers @@ -87,8 +84,7 @@ class BulkCreateSerializerTests(TestCase): serializer = self.BookSerializer(data=data, many=True) assert serializer.is_valid() is False - text_type_string = six.text_type.__name__ - message = 'Invalid data. Expected a dictionary, but got %s.' % text_type_string + message = 'Invalid data. Expected a dictionary, but got str.' expected_errors = [ {'non_field_errors': [message]}, {'non_field_errors': [message]}, diff --git a/tests/test_serializer_lists.py b/tests/test_serializer_lists.py index 12ed78b84..4b60643a8 100644 --- a/tests/test_serializer_lists.py +++ b/tests/test_serializer_lists.py @@ -1,7 +1,11 @@ +import sys + +import pytest from django.http import QueryDict from django.utils.datastructures import MultiValueDict from rest_framework import serializers +from rest_framework.exceptions import ErrorDetail class BasicObject: @@ -28,7 +32,7 @@ class TestListSerializer: Note that this is in contrast to using ListSerializer as a field. """ - def setup(self): + def setup_method(self): class IntegerListSerializer(serializers.ListSerializer): child = serializers.IntegerField() self.Serializer = IntegerListSerializer @@ -53,13 +57,20 @@ class TestListSerializer: assert serializer.is_valid() assert serializer.validated_data == expected_output + @pytest.mark.skipif( + sys.version_info < (3, 7), + reason="subscriptable classes requires Python 3.7 or higher", + ) + def test_list_serializer_is_subscriptable(self): + assert serializers.ListSerializer is serializers.ListSerializer["foo"] + class TestListSerializerContainingNestedSerializer: """ Tests for using a ListSerializer containing another serializer. """ - def setup(self): + def setup_method(self): class TestSerializer(serializers.Serializer): integer = serializers.IntegerField() boolean = serializers.BooleanField() @@ -145,7 +156,7 @@ class TestNestedListSerializer: Tests for using a ListSerializer as a field. """ - def setup(self): + def setup_method(self): class TestSerializer(serializers.Serializer): integers = serializers.ListSerializer(child=serializers.IntegerField()) booleans = serializers.ListSerializer(child=serializers.BooleanField()) @@ -223,8 +234,51 @@ class TestNestedListSerializer: assert serializer.validated_data == expected_output +class TestNestedListSerializerAllowEmpty: + """Tests the behaviour of allow_empty=False when a ListSerializer is used as a field.""" + + @pytest.mark.parametrize('partial', (False, True)) + def test_allow_empty_true(self, partial): + """ + If allow_empty is True, empty lists should be allowed regardless of the value + of partial on the parent serializer. + """ + class ChildSerializer(serializers.Serializer): + id = serializers.IntegerField() + + class ParentSerializer(serializers.Serializer): + ids = ChildSerializer(many=True, allow_empty=True) + + serializer = ParentSerializer(data={'ids': []}, partial=partial) + assert serializer.is_valid() + assert serializer.validated_data == { + 'ids': [], + } + + @pytest.mark.parametrize('partial', (False, True)) + def test_allow_empty_false(self, partial): + """ + If allow_empty is False, empty lists should fail validation regardless of the value + of partial on the parent serializer. + """ + class ChildSerializer(serializers.Serializer): + id = serializers.IntegerField() + + class ParentSerializer(serializers.Serializer): + ids = ChildSerializer(many=True, allow_empty=False) + + serializer = ParentSerializer(data={'ids': []}, partial=partial) + assert not serializer.is_valid() + assert serializer.errors == { + 'ids': { + 'non_field_errors': [ + ErrorDetail(string='This list may not be empty.', code='empty')], + } + } + + class TestNestedListOfListsSerializer: - def setup(self): + def setup_method(self): class TestSerializer(serializers.Serializer): integers = serializers.ListSerializer( child=serializers.ListSerializer( @@ -540,7 +594,7 @@ class TestEmptyListSerializer: Tests the behaviour of ListSerializers when there is no data passed to it """ - def setup(self): + def setup_method(self): class ExampleListSerializer(serializers.ListSerializer): child = serializers.IntegerField() @@ -562,3 +616,70 @@ class TestEmptyListSerializer: assert serializer.is_valid() assert serializer.validated_data == [] + + +class TestMaxMinLengthListSerializer: + """ + Tests the behaviour of ListSerializers when max_length and min_length are used + """ + + def setup_method(self): + class IntegerSerializer(serializers.Serializer): + some_int = serializers.IntegerField() + + class MaxLengthSerializer(serializers.Serializer): + many_int = IntegerSerializer(many=True, max_length=5) + + class MinLengthSerializer(serializers.Serializer): + many_int = IntegerSerializer(many=True, min_length=3) + + class MaxMinLengthSerializer(serializers.Serializer): + many_int = IntegerSerializer(many=True, min_length=3, max_length=5) + + self.MaxLengthSerializer = MaxLengthSerializer + self.MinLengthSerializer = MinLengthSerializer + self.MaxMinLengthSerializer = MaxMinLengthSerializer + + def test_min_max_length_two_items(self): + input_data = {'many_int': [{'some_int': i} for i in range(2)]} + + max_serializer = self.MaxLengthSerializer(data=input_data) + min_serializer = self.MinLengthSerializer(data=input_data) + max_min_serializer = self.MaxMinLengthSerializer(data=input_data) + + assert max_serializer.is_valid() + assert max_serializer.validated_data == input_data + + assert not min_serializer.is_valid() + + assert not max_min_serializer.is_valid() + + def test_min_max_length_four_items(self): + input_data = {'many_int': [{'some_int': i} for i in range(4)]} + + max_serializer = self.MaxLengthSerializer(data=input_data) + min_serializer = self.MinLengthSerializer(data=input_data) + max_min_serializer = self.MaxMinLengthSerializer(data=input_data) + + assert max_serializer.is_valid() + assert max_serializer.validated_data == input_data + + assert min_serializer.is_valid() + assert min_serializer.validated_data == input_data + + assert max_min_serializer.is_valid() + assert min_serializer.validated_data == input_data + + def test_min_max_length_six_items(self): + input_data = {'many_int': [{'some_int': i} for i in range(6)]} + + max_serializer = self.MaxLengthSerializer(data=input_data) + min_serializer = self.MinLengthSerializer(data=input_data) + max_min_serializer = self.MaxMinLengthSerializer(data=input_data) + + assert not max_serializer.is_valid() + + assert min_serializer.is_valid() + assert min_serializer.validated_data == input_data + + assert not max_min_serializer.is_valid() diff --git a/tests/test_serializer_nested.py b/tests/test_serializer_nested.py index 1cd0caf85..986972a65 100644 --- a/tests/test_serializer_nested.py +++ b/tests/test_serializer_nested.py @@ -1,10 +1,15 @@ +import pytest +from django.db import models from django.http import QueryDict +from django.test import TestCase from rest_framework import serializers +from rest_framework.compat import postgres_fields +from rest_framework.serializers import raise_errors_on_nested_writes class TestNestedSerializer: - def setup(self): + def setup_method(self): class NestedSerializer(serializers.Serializer): one = serializers.IntegerField(max_value=10) two = serializers.IntegerField(max_value=10) @@ -49,7 +54,7 @@ class TestNestedSerializer: class TestNotRequiredNestedSerializer: - def setup(self): + def setup_method(self): class NestedSerializer(serializers.Serializer): one = serializers.IntegerField(max_value=10) @@ -78,7 +83,7 @@ class TestNotRequiredNestedSerializer: class TestNestedSerializerWithMany: - def setup(self): + def setup_method(self): class NestedSerializer(serializers.Serializer): example = serializers.IntegerField(max_value=10) @@ -176,7 +181,7 @@ class TestNestedSerializerWithMany: class TestNestedSerializerWithList: - def setup(self): + def setup_method(self): class NestedSerializer(serializers.Serializer): example = serializers.MultipleChoiceField(choices=[1, 2, 3]) @@ -205,7 +210,7 @@ class TestNestedSerializerWithList: class TestNotRequiredNestedSerializerWithMany: - def setup(self): + def setup_method(self): class NestedSerializer(serializers.Serializer): one = serializers.IntegerField(max_value=10) @@ -241,3 +246,111 @@ class TestNotRequiredNestedSerializerWithMany: serializer = self.Serializer(data=input_data) assert serializer.is_valid() assert 'nested' in serializer.validated_data + + +class NestedWriteProfile(models.Model): + address = models.CharField(max_length=100) + + +class NestedWritePerson(models.Model): + profile = models.ForeignKey(NestedWriteProfile, on_delete=models.CASCADE) + + +class TestNestedWriteErrors(TestCase): + # tests for rests_framework.serializers.raise_errors_on_nested_writes + def test_nested_serializer_error(self): + class ProfileSerializer(serializers.ModelSerializer): + class Meta: + model = NestedWriteProfile + fields = ['address'] + + class NestedProfileSerializer(serializers.ModelSerializer): + profile = ProfileSerializer() + + class Meta: + model = NestedWritePerson + fields = ['profile'] + + serializer = NestedProfileSerializer(data={'profile': {'address': '52 festive road'}}) + assert serializer.is_valid() + assert serializer.validated_data == {'profile': {'address': '52 festive road'}} + with pytest.raises(AssertionError) as exc_info: + serializer.save() + + assert str(exc_info.value) == ( + 'The `.create()` method does not support writable nested fields by ' + 'default.\nWrite an explicit `.create()` method for serializer ' + '`tests.test_serializer_nested.NestedProfileSerializer`, or set ' + '`read_only=True` on nested serializer fields.' + ) + + def test_dotted_source_field_error(self): + class DottedAddressSerializer(serializers.ModelSerializer): + address = serializers.CharField(source='profile.address') + + class Meta: + model = NestedWritePerson + fields = ['address'] + + serializer = DottedAddressSerializer(data={'address': '52 festive road'}) + assert serializer.is_valid() + assert serializer.validated_data == {'profile': {'address': '52 festive road'}} + with pytest.raises(AssertionError) as exc_info: + serializer.save() + + assert str(exc_info.value) == ( + 'The `.create()` method does not support writable dotted-source ' + 'fields by default.\nWrite an explicit `.create()` method for ' + 'serializer `tests.test_serializer_nested.DottedAddressSerializer`, ' + 'or set `read_only=True` on dotted-source serializer fields.' + ) + + +if postgres_fields: + class NonRelationalPersonModel(models.Model): + """Model declaring a postgres JSONField""" + data = postgres_fields.JSONField() + + class Meta: + required_db_features = {'supports_json_field'} + + +@pytest.mark.skipif(not postgres_fields, reason='psycopg2 is not installed') +class TestNestedNonRelationalFieldWrite: + """ + Test that raise_errors_on_nested_writes does not raise `AssertionError` when the + model field is not a relation. + """ + + def test_nested_serializer_create_and_update(self): + + class NonRelationalPersonDataSerializer(serializers.Serializer): + occupation = serializers.CharField() + + class NonRelationalPersonSerializer(serializers.ModelSerializer): + data = NonRelationalPersonDataSerializer() + + class Meta: + model = NonRelationalPersonModel + fields = ['data'] + + serializer = NonRelationalPersonSerializer(data={'data': {'occupation': 'developer'}}) + assert serializer.is_valid() + assert serializer.validated_data == {'data': {'occupation': 'developer'}} + raise_errors_on_nested_writes('create', serializer, serializer.validated_data) + raise_errors_on_nested_writes('update', serializer, serializer.validated_data) + + def test_dotted_source_field_create_and_update(self): + + class DottedNonRelationalPersonSerializer(serializers.ModelSerializer): + occupation = serializers.CharField(source='data.occupation') + + class Meta: + model = NonRelationalPersonModel + fields = ['occupation'] + + serializer = DottedNonRelationalPersonSerializer(data={'occupation': 'developer'}) + assert serializer.is_valid() + assert serializer.validated_data == {'data': {'occupation': 'developer'}} + raise_errors_on_nested_writes('create', serializer, serializer.validated_data) + raise_errors_on_nested_writes('update', serializer, serializer.validated_data) diff --git a/tests/test_settings.py b/tests/test_settings.py index 51e9751b2..b78125ff9 100644 --- a/tests/test_settings.py +++ b/tests/test_settings.py @@ -1,5 +1,3 @@ -from __future__ import unicode_literals - from django.test import TestCase, override_settings from rest_framework.settings import APISettings, api_settings diff --git a/tests/test_status.py b/tests/test_status.py index 1cd6e229e..b10f7df99 100644 --- a/tests/test_status.py +++ b/tests/test_status.py @@ -1,10 +1,7 @@ -from __future__ import unicode_literals - from django.test import TestCase from rest_framework.status import ( - is_client_error, is_informational, is_redirect, is_server_error, - is_success + is_client_error, is_informational, is_redirect, is_server_error, is_success ) diff --git a/tests/test_templates.py b/tests/test_templates.py index 19f511b96..0dba78ea2 100644 --- a/tests/test_templates.py +++ b/tests/test_templates.py @@ -6,7 +6,7 @@ from django.shortcuts import render def test_base_template_with_context(): context = {'request': True, 'csrf_token': 'TOKEN'} result = render({}, 'rest_framework/base.html', context=context) - assert re.search(r'\bcsrfToken: "TOKEN"', result.content.decode('utf-8')) + assert re.search(r'\bcsrfToken: "TOKEN"', result.content.decode()) def test_base_template_with_no_context(): @@ -14,4 +14,4 @@ def test_base_template_with_no_context(): # so it can be easily extended. result = render({}, 'rest_framework/base.html') # note that this response will not include a valid CSRF token - assert re.search(r'\bcsrfToken: ""', result.content.decode('utf-8')) + assert re.search(r'\bcsrfToken: ""', result.content.decode()) diff --git a/tests/test_templatetags.py b/tests/test_templatetags.py index 45bfd4aeb..4b84f6647 100644 --- a/tests/test_templatetags.py +++ b/tests/test_templatetags.py @@ -1,17 +1,15 @@ -# encoding: utf-8 -from __future__ import unicode_literals - import unittest from django.template import Context, Template from django.test import TestCase +from django.utils.html import urlize from rest_framework.compat import coreapi, coreschema from rest_framework.relations import Hyperlink from rest_framework.templatetags import rest_framework from rest_framework.templatetags.rest_framework import ( add_nested_class, add_query_param, as_string, break_long_headers, - format_value, get_pagination_html, schema_links, urlize_quoted_links + format_value, get_pagination_html, schema_links ) from rest_framework.test import APIRequestFactory @@ -225,7 +223,7 @@ class TemplateTagTests(TestCase): assert result == '' def test_get_pagination_html(self): - class MockPager(object): + class MockPager: def __init__(self): self.called = False @@ -249,7 +247,7 @@ class Issue1386Tests(TestCase): def test_issue_1386(self): """ - Test function urlize_quoted_links with different args + Test function urlize with different args """ correct_urls = [ "asdf.com", @@ -258,7 +256,7 @@ class Issue1386Tests(TestCase): "as.d8f.ghj8.gov", ] for i in correct_urls: - res = urlize_quoted_links(i) + res = urlize(i) self.assertNotEqual(res, i) self.assertIn(i, res) @@ -267,11 +265,11 @@ class Issue1386Tests(TestCase): "asdf.netnet", ] for i in incorrect_urls: - res = urlize_quoted_links(i) + res = urlize(i) self.assertEqual(i, res) # example from issue #1386, this shouldn't raise an exception - urlize_quoted_links("asdf:[/p]zxcv.com") + urlize("asdf:[/p]zxcv.com") def test_smart_urlquote_wrapper_handles_value_error(self): def mock_smart_urlquote(url): @@ -292,7 +290,7 @@ class URLizerTests(TestCase): For all items in dict test assert that the value is urlized key """ for original, urlized in data.items(): - assert urlize_quoted_links(original, nofollow=False) == urlized + assert urlize(original, nofollow=False) == urlized def test_json_with_url(self): """ @@ -300,26 +298,26 @@ class URLizerTests(TestCase): """ data = {} data['"url": "http://api/users/1/", '] = \ - '"url": "http://api/users/1/", ' + '"url": "http://api/users/1/", ' data['"foo_set": [\n "http://api/foos/1/"\n], '] = \ - '"foo_set": [\n "http://api/foos/1/"\n], ' + '"foo_set": [\n "http://api/foos/1/"\n], ' self._urlize_dict_check(data) def test_template_render_with_autoescape(self): """ Test that HTML is correctly escaped in Browsable API views. """ - template = Template("{% load rest_framework %}{{ content|urlize_quoted_links }}") + template = Template("{% load rest_framework %}{{ content|urlize }}") rendered = template.render(Context({'content': ' http://example.com'})) assert rendered == '<script>alert()</script>' \ ' http://example.com' def test_template_render_with_noautoescape(self): """ - Test if the autoescape value is getting passed to urlize_quoted_links filter. + Test if the autoescape value is getting passed to urlize filter. """ template = Template("{% load rest_framework %}" - "{% autoescape off %}{{ content|urlize_quoted_links }}" + "{% autoescape off %}{{ content|urlize }}" "{% endautoescape %}") rendered = template.render(Context({'content': ' "http://example.com" '})) assert rendered == ' "http://example.com" ' @@ -340,7 +338,7 @@ class SchemaLinksTests(TestCase): ) section = schema['users'] flat_links = schema_links(section) - assert len(flat_links) is 0 + assert len(flat_links) == 0 def test_single_action(self): schema = coreapi.Document( @@ -358,7 +356,7 @@ class SchemaLinksTests(TestCase): ) section = schema['users'] flat_links = schema_links(section) - assert len(flat_links) is 1 + assert len(flat_links) == 1 assert 'list' in flat_links def test_default_actions(self): @@ -396,7 +394,7 @@ class SchemaLinksTests(TestCase): ) section = schema['users'] flat_links = schema_links(section) - assert len(flat_links) is 4 + assert len(flat_links) == 4 assert 'list' in flat_links assert 'create' in flat_links assert 'read' in flat_links @@ -444,7 +442,7 @@ class SchemaLinksTests(TestCase): ) section = schema['users'] flat_links = schema_links(section) - assert len(flat_links) is 5 + assert len(flat_links) == 5 assert 'list' in flat_links assert 'create' in flat_links assert 'read' in flat_links @@ -502,7 +500,7 @@ class SchemaLinksTests(TestCase): ) section = schema['users'] flat_links = schema_links(section) - assert len(flat_links) is 6 + assert len(flat_links) == 6 assert 'list' in flat_links assert 'create' in flat_links assert 'read' in flat_links @@ -543,7 +541,7 @@ class SchemaLinksTests(TestCase): ] ), 'create': coreapi.Link( - url='/aniamls/cat', + url='/animals/cat', action='post', fields=[] ) @@ -553,7 +551,7 @@ class SchemaLinksTests(TestCase): ) section = schema['animals'] flat_links = schema_links(section) - assert len(flat_links) is 4 + assert len(flat_links) == 4 assert 'cat > create' in flat_links assert 'cat > list' in flat_links assert 'dog > read' in flat_links @@ -592,7 +590,7 @@ class SchemaLinksTests(TestCase): ] ), 'create': coreapi.Link( - url='/aniamls/cat', + url='/animals/cat', action='post', fields=[] ) @@ -622,7 +620,7 @@ class SchemaLinksTests(TestCase): ) section = schema['animals'] flat_links = schema_links(section) - assert len(flat_links) is 4 + assert len(flat_links) == 4 assert 'cat > create' in flat_links assert 'cat > list' in flat_links assert 'dog > read' in flat_links @@ -630,6 +628,6 @@ class SchemaLinksTests(TestCase): section = schema['farmers'] flat_links = schema_links(section) - assert len(flat_links) is 2 + assert len(flat_links) == 2 assert 'silo > list' in flat_links assert 'silo > soy > list' in flat_links diff --git a/tests/test_testing.py b/tests/test_testing.py index 7868f724c..196319a29 100644 --- a/tests/test_testing.py +++ b/tests/test_testing.py @@ -1,14 +1,16 @@ -# encoding: utf-8 -from __future__ import unicode_literals - +import itertools from io import BytesIO +from unittest.mock import patch -from django.conf.urls import url +import django from django.contrib.auth.models import User +from django.http import HttpResponseRedirect from django.shortcuts import redirect from django.test import TestCase, override_settings +from django.urls import path from rest_framework import fields, serializers +from rest_framework.authtoken.models import Token from rest_framework.decorators import api_view from rest_framework.response import Response from rest_framework.test import ( @@ -16,12 +18,14 @@ from rest_framework.test import ( ) -@api_view(['GET', 'POST']) +@api_view(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']) def view(request): - return Response({ - 'auth': request.META.get('HTTP_AUTHORIZATION', b''), - 'user': request.user.username - }) + data = {'auth': request.META.get('HTTP_AUTHORIZATION', b'')} + if request.user: + data['user'] = request.user.username + if request.auth: + data['token'] = request.auth.key + return Response(data) @api_view(['GET', 'POST']) @@ -38,6 +42,11 @@ def redirect_view(request): return redirect('/view/') +@api_view(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']) +def redirect_307_308_view(request, code): + return HttpResponseRedirect('/view/', status=code) + + class BasicSerializer(serializers.Serializer): flag = fields.BooleanField(default=lambda: True) @@ -50,10 +59,11 @@ def post_view(request): urlpatterns = [ - url(r'^view/$', view), - url(r'^session-view/$', session_view), - url(r'^redirect-view/$', redirect_view), - url(r'^post-view/$', post_view) + path('view/', view), + path('session-view/', session_view), + path('redirect-view/', redirect_view), + path('redirect-view//', redirect_307_308_view), + path('post-view/', post_view) ] @@ -71,14 +81,46 @@ class TestAPITestClient(TestCase): response = self.client.get('/view/') assert response.data['auth'] == 'example' - def test_force_authenticate(self): + def test_force_authenticate_with_user(self): """ - Setting `.force_authenticate()` forcibly authenticates each request. + Setting `.force_authenticate()` with a user forcibly authenticates each + request with that user. """ user = User.objects.create_user('example', 'example@example.com') - self.client.force_authenticate(user) + + self.client.force_authenticate(user=user) response = self.client.get('/view/') + assert response.data['user'] == 'example' + assert 'token' not in response.data + + def test_force_authenticate_with_token(self): + """ + Setting `.force_authenticate()` with a token forcibly authenticates each + request with that token. + """ + user = User.objects.create_user('example', 'example@example.com') + token = Token.objects.create(key='xyz', user=user) + + self.client.force_authenticate(token=token) + response = self.client.get('/view/') + + assert response.data['token'] == 'xyz' + assert 'user' not in response.data + + def test_force_authenticate_with_user_and_token(self): + """ + Setting `.force_authenticate()` with a user and token forcibly + authenticates each request with that user and token. + """ + user = User.objects.create_user('example', 'example@example.com') + token = Token.objects.create(key='xyz', user=user) + + self.client.force_authenticate(user=user, token=token) + response = self.client.get('/view/') + + assert response.data['user'] == 'example' + assert response.data['token'] == 'xyz' def test_force_authenticate_with_sessions(self): """ @@ -95,8 +137,9 @@ class TestAPITestClient(TestCase): response = self.client.get('/session-view/') assert response.data['active_session'] is True - # Force authenticating as `None` should also logout the user session. - self.client.force_authenticate(None) + # Force authenticating with `None` user and token should also logout + # the user session. + self.client.force_authenticate(user=None, token=None) response = self.client.get('/session-view/') assert response.data['active_session'] is False @@ -148,41 +191,32 @@ class TestAPITestClient(TestCase): """ Follow redirect by setting follow argument. """ - response = self.client.get('/redirect-view/') - assert response.status_code == 302 - response = self.client.get('/redirect-view/', follow=True) - assert response.redirect_chain is not None - assert response.status_code == 200 + for method in ('get', 'post', 'put', 'patch', 'delete', 'options'): + with self.subTest(method=method): + req_method = getattr(self.client, method) + response = req_method('/redirect-view/') + assert response.status_code == 302 + response = req_method('/redirect-view/', follow=True) + assert response.redirect_chain is not None + assert response.status_code == 200 - response = self.client.post('/redirect-view/') - assert response.status_code == 302 - response = self.client.post('/redirect-view/', follow=True) - assert response.redirect_chain is not None - assert response.status_code == 200 - - response = self.client.put('/redirect-view/') - assert response.status_code == 302 - response = self.client.put('/redirect-view/', follow=True) - assert response.redirect_chain is not None - assert response.status_code == 200 - - response = self.client.patch('/redirect-view/') - assert response.status_code == 302 - response = self.client.patch('/redirect-view/', follow=True) - assert response.redirect_chain is not None - assert response.status_code == 200 - - response = self.client.delete('/redirect-view/') - assert response.status_code == 302 - response = self.client.delete('/redirect-view/', follow=True) - assert response.redirect_chain is not None - assert response.status_code == 200 - - response = self.client.options('/redirect-view/') - assert response.status_code == 302 - response = self.client.options('/redirect-view/', follow=True) - assert response.redirect_chain is not None - assert response.status_code == 200 + def test_follow_307_308_preserve_kwargs(self, *mocked_methods): + """ + Follow redirect by setting follow argument, and make sure the following + method called with appropriate kwargs. + """ + methods = ('get', 'post', 'put', 'patch', 'delete', 'options') + codes = (307, 308) + for method, code in itertools.product(methods, codes): + subtest_ctx = self.subTest(method=method, code=code) + patch_ctx = patch.object(self.client, method, side_effect=getattr(self.client, method)) + with subtest_ctx, patch_ctx as req_method: + kwargs = {'data': {'example': 'test'}, 'format': 'json'} + response = req_method('/redirect-view/%s/' % code, follow=True, **kwargs) + assert response.redirect_chain is not None + assert response.status_code == 200 + for _, call_args, call_kwargs in req_method.mock_calls: + assert all(call_kwargs[k] == kwargs[k] for k in kwargs if k in call_kwargs) def test_invalid_multipart_data(self): """ @@ -285,22 +319,33 @@ class TestAPIRequestFactory(TestCase): assert request.META['CONTENT_TYPE'] == 'application/json' +def check_urlpatterns(cls): + assert urlpatterns is not cls.urlpatterns + + class TestUrlPatternTestCase(URLPatternsTestCase): urlpatterns = [ - url(r'^$', view), + path('', view), ] @classmethod def setUpClass(cls): assert urlpatterns is not cls.urlpatterns - super(TestUrlPatternTestCase, cls).setUpClass() + super().setUpClass() assert urlpatterns is cls.urlpatterns - @classmethod - def tearDownClass(cls): - assert urlpatterns is cls.urlpatterns - super(TestUrlPatternTestCase, cls).tearDownClass() - assert urlpatterns is not cls.urlpatterns + if django.VERSION > (4, 0): + cls.addClassCleanup( + check_urlpatterns, + cls + ) + + if django.VERSION < (4, 0): + @classmethod + def tearDownClass(cls): + assert urlpatterns is cls.urlpatterns + super().tearDownClass() + assert urlpatterns is not cls.urlpatterns def test_urlpatterns(self): assert self.client.get('/').status_code == 200 diff --git a/tests/test_throttling.py b/tests/test_throttling.py index b220a33a6..d5a61232d 100644 --- a/tests/test_throttling.py +++ b/tests/test_throttling.py @@ -1,7 +1,6 @@ """ Tests for the throttling implementations in the permissions module. """ -from __future__ import unicode_literals import pytest from django.contrib.auth.models import User @@ -31,6 +30,11 @@ class User3MinRateThrottle(UserRateThrottle): scope = 'minutes' +class User6MinRateThrottle(UserRateThrottle): + rate = '6/min' + scope = 'minutes' + + class NonTimeThrottle(BaseThrottle): def allow_request(self, request, view): if not hasattr(self.__class__, 'called'): @@ -39,6 +43,13 @@ class NonTimeThrottle(BaseThrottle): return False +class MockView_DoubleThrottling(APIView): + throttle_classes = (User3SecRateThrottle, User6MinRateThrottle,) + + def get(self, request): + return Response('foo') + + class MockView(APIView): throttle_classes = (User3SecRateThrottle,) @@ -81,7 +92,8 @@ class ThrottlingTests(TestCase): """ Explicitly set the timer, overriding time.time() """ - view.throttle_classes[0].timer = lambda self: value + for cls in view.throttle_classes: + cls.timer = lambda self: value def test_request_throttling_expires(self): """ @@ -116,6 +128,58 @@ class ThrottlingTests(TestCase): """ self.ensure_is_throttled(MockView, 200) + def test_request_throttling_multiple_throttles(self): + """ + Ensure all throttle classes see each request even when the request is + already being throttled + """ + self.set_throttle_timer(MockView_DoubleThrottling, 0) + request = self.factory.get('/') + for dummy in range(4): + response = MockView_DoubleThrottling.as_view()(request) + assert response.status_code == 429 + assert int(response['retry-after']) == 1 + + # At this point our client made 4 requests (one was throttled) in a + # second. If we advance the timer by one additional second, the client + # should be allowed to make 2 more before being throttled by the 2nd + # throttle class, which has a limit of 6 per minute. + self.set_throttle_timer(MockView_DoubleThrottling, 1) + for dummy in range(2): + response = MockView_DoubleThrottling.as_view()(request) + assert response.status_code == 200 + + response = MockView_DoubleThrottling.as_view()(request) + assert response.status_code == 429 + assert int(response['retry-after']) == 59 + + # Just to make sure check again after two more seconds. + self.set_throttle_timer(MockView_DoubleThrottling, 2) + response = MockView_DoubleThrottling.as_view()(request) + assert response.status_code == 429 + assert int(response['retry-after']) == 58 + + def test_throttle_rate_change_negative(self): + self.set_throttle_timer(MockView_DoubleThrottling, 0) + request = self.factory.get('/') + for dummy in range(24): + response = MockView_DoubleThrottling.as_view()(request) + assert response.status_code == 429 + assert int(response['retry-after']) == 60 + + previous_rate = User3SecRateThrottle.rate + try: + User3SecRateThrottle.rate = '1/sec' + + for dummy in range(24): + response = MockView_DoubleThrottling.as_view()(request) + + assert response.status_code == 429 + assert int(response['retry-after']) == 60 + finally: + # reset + User3SecRateThrottle.rate = previous_rate + def ensure_response_header_contains_proper_throttle_field(self, view, expected_headers): """ Ensure the response returns an Retry-After field with status and next attributes @@ -296,7 +360,7 @@ class ScopedRateThrottleTests(TestCase): assert response.status_code == 200 def test_get_cache_key_returns_correct_key_if_user_is_authenticated(self): - class DummyView(object): + class DummyView: throttle_scope = 'user' request = Request(HttpRequest()) diff --git a/tests/test_urlpatterns.py b/tests/test_urlpatterns.py index 59ba395d2..adcd0a742 100644 --- a/tests/test_urlpatterns.py +++ b/tests/test_urlpatterns.py @@ -1,13 +1,9 @@ -from __future__ import unicode_literals - -import unittest from collections import namedtuple -from django.conf.urls import include, url from django.test import TestCase -from django.urls import Resolver404 +from django.urls import Resolver404, URLResolver, include, path, re_path +from django.urls.resolvers import RegexPattern -from rest_framework.compat import make_url_resolver, path, re_path from rest_framework.test import APIRequestFactory from rest_framework.urlpatterns import format_suffix_patterns @@ -30,7 +26,7 @@ class FormatSuffixTests(TestCase): urlpatterns = format_suffix_patterns(urlpatterns, allowed=allowed) except Exception: self.fail("Failed to apply `format_suffix_patterns` on the supplied urlpatterns") - resolver = make_url_resolver(r'^/', urlpatterns) + resolver = URLResolver(RegexPattern(r'^/'), urlpatterns) for test_path in test_paths: try: test_path, expected_resolved = test_path @@ -64,11 +60,10 @@ class FormatSuffixTests(TestCase): def test_trailing_slash(self): urlpatterns = [ - url(r'^test/$', dummy_view), + path('test/', dummy_view), ] self._test_trailing_slash(urlpatterns) - @unittest.skipUnless(path, 'needs Django 2') def test_trailing_slash_django2(self): urlpatterns = [ path('test/', dummy_view), @@ -85,18 +80,16 @@ class FormatSuffixTests(TestCase): def test_format_suffix(self): urlpatterns = [ - url(r'^test$', dummy_view), + path('test', dummy_view), ] self._test_format_suffix(urlpatterns) - @unittest.skipUnless(path, 'needs Django 2') def test_format_suffix_django2(self): urlpatterns = [ path('test', dummy_view), ] self._test_format_suffix(urlpatterns) - @unittest.skipUnless(path, 'needs Django 2') def test_format_suffix_django2_args(self): urlpatterns = [ path('convtest/', dummy_view), @@ -122,11 +115,10 @@ class FormatSuffixTests(TestCase): def test_default_args(self): urlpatterns = [ - url(r'^test$', dummy_view, {'foo': 'bar'}), + path('test', dummy_view, {'foo': 'bar'}), ] self._test_default_args(urlpatterns) - @unittest.skipUnless(path, 'needs Django 2') def test_default_args_django2(self): urlpatterns = [ path('test', dummy_view, {'foo': 'bar'}), @@ -142,16 +134,6 @@ class FormatSuffixTests(TestCase): self._resolve_urlpatterns(urlpatterns, test_paths) def test_included_urls(self): - nested_patterns = [ - url(r'^path$', dummy_view) - ] - urlpatterns = [ - url(r'^test/', include(nested_patterns), {'foo': 'bar'}), - ] - self._test_included_urls(urlpatterns) - - @unittest.skipUnless(path, 'needs Django 2') - def test_included_urls_django2(self): nested_patterns = [ path('path', dummy_view) ] @@ -160,46 +142,35 @@ class FormatSuffixTests(TestCase): ] self._test_included_urls(urlpatterns) - @unittest.skipUnless(path, 'needs Django 2') - def test_included_urls_django2_mixed(self): - nested_patterns = [ - path('path', dummy_view) - ] - urlpatterns = [ - url('^test/', include(nested_patterns), {'foo': 'bar'}), - ] - self._test_included_urls(urlpatterns) - - @unittest.skipUnless(path, 'needs Django 2') - def test_included_urls_django2_mixed_args(self): + def test_included_urls_mixed(self): nested_patterns = [ path('path/', dummy_view), - url('^url/(?P[0-9]+)$', dummy_view) + re_path(r'^re_path/(?P[0-9]+)$', dummy_view) ] urlpatterns = [ - url('^purl/(?P[0-9]+)/', include(nested_patterns), {'foo': 'bar'}), + re_path(r'^pre_path/(?P[0-9]+)/', include(nested_patterns), {'foo': 'bar'}), path('ppath//', include(nested_patterns), {'foo': 'bar'}), ] test_paths = [ - # parent url() nesting child path() - URLTestPath('/purl/87/path/42', (), {'parent': '87', 'child': 42, 'foo': 'bar', }), - URLTestPath('/purl/87/path/42.api', (), {'parent': '87', 'child': 42, 'foo': 'bar', 'format': 'api'}), - URLTestPath('/purl/87/path/42.asdf', (), {'parent': '87', 'child': 42, 'foo': 'bar', 'format': 'asdf'}), + # parent re_path() nesting child path() + URLTestPath('/pre_path/87/path/42', (), {'parent': '87', 'child': 42, 'foo': 'bar', }), + URLTestPath('/pre_path/87/path/42.api', (), {'parent': '87', 'child': 42, 'foo': 'bar', 'format': 'api'}), + URLTestPath('/pre_path/87/path/42.asdf', (), {'parent': '87', 'child': 42, 'foo': 'bar', 'format': 'asdf'}), - # parent path() nesting child url() - URLTestPath('/ppath/87/url/42', (), {'parent': 87, 'child': '42', 'foo': 'bar', }), - URLTestPath('/ppath/87/url/42.api', (), {'parent': 87, 'child': '42', 'foo': 'bar', 'format': 'api'}), - URLTestPath('/ppath/87/url/42.asdf', (), {'parent': 87, 'child': '42', 'foo': 'bar', 'format': 'asdf'}), + # parent path() nesting child re_path() + URLTestPath('/ppath/87/re_path/42', (), {'parent': 87, 'child': '42', 'foo': 'bar', }), + URLTestPath('/ppath/87/re_path/42.api', (), {'parent': 87, 'child': '42', 'foo': 'bar', 'format': 'api'}), + URLTestPath('/ppath/87/re_path/42.asdf', (), {'parent': 87, 'child': '42', 'foo': 'bar', 'format': 'asdf'}), # parent path() nesting child path() URLTestPath('/ppath/87/path/42', (), {'parent': 87, 'child': 42, 'foo': 'bar', }), URLTestPath('/ppath/87/path/42.api', (), {'parent': 87, 'child': 42, 'foo': 'bar', 'format': 'api'}), URLTestPath('/ppath/87/path/42.asdf', (), {'parent': 87, 'child': 42, 'foo': 'bar', 'format': 'asdf'}), - # parent url() nesting child url() - URLTestPath('/purl/87/url/42', (), {'parent': '87', 'child': '42', 'foo': 'bar', }), - URLTestPath('/purl/87/url/42.api', (), {'parent': '87', 'child': '42', 'foo': 'bar', 'format': 'api'}), - URLTestPath('/purl/87/url/42.asdf', (), {'parent': '87', 'child': '42', 'foo': 'bar', 'format': 'asdf'}), + # parent re_path() nesting child re_path() + URLTestPath('/pre_path/87/re_path/42', (), {'parent': '87', 'child': '42', 'foo': 'bar', }), + URLTestPath('/pre_path/87/re_path/42.api', (), {'parent': '87', 'child': '42', 'foo': 'bar', 'format': 'api'}), + URLTestPath('/pre_path/87/re_path/42.asdf', (), {'parent': '87', 'child': '42', 'foo': 'bar', 'format': 'asdf'}), ] self._resolve_urlpatterns(urlpatterns, test_paths) @@ -212,14 +183,13 @@ class FormatSuffixTests(TestCase): ] self._resolve_urlpatterns(urlpatterns, test_paths, allowed=allowed_formats) - def test_allowed_formats(self): + def test_allowed_formats_re_path(self): urlpatterns = [ - url('^test$', dummy_view), + re_path(r'^test$', dummy_view), ] self._test_allowed_formats(urlpatterns) - @unittest.skipUnless(path, 'needs Django 2') - def test_allowed_formats_django2(self): + def test_allowed_formats_path(self): urlpatterns = [ path('test', dummy_view), ] diff --git a/tests/test_utils.py b/tests/test_utils.py index 28b06b173..c72f680fe 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -1,14 +1,14 @@ -# -*- coding: utf-8 -*- -from __future__ import unicode_literals +from unittest import mock -from django.conf.urls import url from django.test import TestCase, override_settings +from django.urls import path from rest_framework.decorators import action from rest_framework.routers import SimpleRouter from rest_framework.serializers import ModelSerializer from rest_framework.utils import json from rest_framework.utils.breadcrumbs import get_breadcrumbs +from rest_framework.utils.formatting import lazy_format from rest_framework.utils.urls import remove_query_param, replace_query_param from rest_framework.views import APIView from rest_framework.viewsets import ModelViewSet @@ -64,12 +64,12 @@ class ResourceViewSet(ModelViewSet): router = SimpleRouter() router.register(r'resources', ResourceViewSet) urlpatterns = [ - url(r'^$', Root.as_view()), - url(r'^resource/$', ResourceRoot.as_view()), - url(r'^resource/customname$', CustomNameResourceInstance.as_view()), - url(r'^resource/(?P[0-9]+)$', ResourceInstance.as_view()), - url(r'^resource/(?P[0-9]+)/$', NestedResourceRoot.as_view()), - url(r'^resource/(?P[0-9]+)/(?P[A-Za-z]+)$', NestedResourceInstance.as_view()), + path('', Root.as_view()), + path('resource/', ResourceRoot.as_view()), + path('resource/customname', CustomNameResourceInstance.as_view()), + path('resource/', ResourceInstance.as_view()), + path('resource//', NestedResourceRoot.as_view()), + path('resource//', NestedResourceInstance.as_view()), ] urlpatterns += router.urls @@ -174,7 +174,7 @@ class BreadcrumbTests(TestCase): class JsonFloatTests(TestCase): """ - Internaly, wrapped json functions should adhere to strict float handling + Internally, wrapped json functions should adhere to strict float handling """ def test_dumps(self): @@ -192,7 +192,7 @@ class JsonFloatTests(TestCase): json.loads("NaN") -@override_settings(STRICT_JSON=False) +@override_settings(REST_FRAMEWORK={'STRICT_JSON': False}) class NonStrictJsonFloatTests(JsonFloatTests): """ 'STRICT_JSON = False' should not somehow affect internal json behavior @@ -235,15 +235,6 @@ class UrlsRemoveQueryParamTests(TestCase): """ Tests the remove_query_param functionality. """ - def test_valid_unicode_preserved(self): - q = '/?q=%E6%9F%A5%E8%AF%A2' - new_key = 'page' - new_value = 2 - value = '%E6%9F%A5%E8%AF%A2' - - assert new_key in replace_query_param(q, new_key, new_value) - assert value in replace_query_param(q, new_key, new_value) - def test_valid_unicode_removed(self): q = '/?page=2345&q=%E6%9F%A5%E8%AF%A2' key = 'page' @@ -260,3 +251,19 @@ class UrlsRemoveQueryParamTests(TestCase): removed_key = 'page' assert key in remove_query_param(q, removed_key) + + +class LazyFormatTests(TestCase): + def test_it_formats_correctly(self): + formatted = lazy_format('Does {} work? {answer}: %s', 'it', answer='Yes') + assert str(formatted) == 'Does it work? Yes: %s' + assert formatted % 'it does' == 'Does it work? Yes: it does' + + def test_it_formats_lazily(self): + message = mock.Mock(wraps='message') + formatted = lazy_format(message) + assert message.format.call_count == 0 + str(formatted) + assert message.format.call_count == 1 + str(formatted) + assert message.format.call_count == 1 diff --git a/tests/test_validation.py b/tests/test_validation.py index 4132a7b00..6e00b48c2 100644 --- a/tests/test_validation.py +++ b/tests/test_validation.py @@ -1,11 +1,8 @@ -from __future__ import unicode_literals - import re from django.core.validators import MaxValueValidator, RegexValidator from django.db import models from django.test import TestCase -from django.utils import six from rest_framework import generics, serializers, status from rest_framework.test import APIRequestFactory @@ -112,7 +109,7 @@ class TestAvoidValidation(TestCase): assert not serializer.is_valid() assert serializer.errors == { 'non_field_errors': [ - 'Invalid data. Expected a dictionary, but got %s.' % six.text_type.__name__ + 'Invalid data. Expected a dictionary, but got str.', ] } @@ -151,14 +148,14 @@ class TestMaxValueValidatorValidation(TestCase): def test_max_value_validation_success(self): obj = ValidationMaxValueValidatorModel.objects.create(number_value=100) - request = factory.patch('/{0}'.format(obj.pk), {'number_value': 98}, format='json') + request = factory.patch('/{}'.format(obj.pk), {'number_value': 98}, format='json') view = UpdateMaxValueValidationModel().as_view() response = view(request, pk=obj.pk).render() assert response.status_code == status.HTTP_200_OK def test_max_value_validation_fail(self): obj = ValidationMaxValueValidatorModel.objects.create(number_value=100) - request = factory.patch('/{0}'.format(obj.pk), {'number_value': 101}, format='json') + request = factory.patch('/{}'.format(obj.pk), {'number_value': 101}, format='json') view = UpdateMaxValueValidationModel().as_view() response = view(request, pk=obj.pk).render() assert response.content == b'{"number_value":["Ensure this value is less than or equal to 100."]}' diff --git a/tests/test_validation_error.py b/tests/test_validation_error.py index 562fe37e6..341c4342a 100644 --- a/tests/test_validation_error.py +++ b/tests/test_validation_error.py @@ -2,6 +2,7 @@ from django.test import TestCase from rest_framework import serializers, status from rest_framework.decorators import api_view +from rest_framework.exceptions import ValidationError from rest_framework.response import Response from rest_framework.settings import api_settings from rest_framework.test import APIRequestFactory @@ -99,3 +100,12 @@ class TestValidationErrorWithCodes(TestCase): response = view(request) assert response.status_code == status.HTTP_400_BAD_REQUEST assert response.data == self.expected_response_data + + +class TestValidationErrorConvertsTuplesToLists(TestCase): + def test_validation_error_details(self): + error = ValidationError(detail=('message1', 'message2')) + assert isinstance(error.detail, list) + assert len(error.detail) == 2 + assert str(error.detail[0]) == 'message1' + assert str(error.detail[1]) == 'message2' diff --git a/tests/test_validators.py b/tests/test_validators.py index 4bbddb64b..39490ac86 100644 --- a/tests/test_validators.py +++ b/tests/test_validators.py @@ -7,8 +7,7 @@ from django.test import TestCase from rest_framework import serializers from rest_framework.exceptions import ValidationError from rest_framework.validators import ( - BaseUniqueForValidator, UniqueTogetherValidator, UniqueValidator, - qs_exists + BaseUniqueForValidator, UniqueTogetherValidator, UniqueValidator, qs_exists ) @@ -43,6 +42,12 @@ class RelatedModelSerializer(serializers.ModelSerializer): fields = ('username', 'email') +class RelatedModelUserSerializer(serializers.ModelSerializer): + class Meta: + model = RelatedModel + fields = ('user',) + + class AnotherUniquenessModel(models.Model): code = models.IntegerField(unique=True) @@ -84,6 +89,13 @@ class TestUniquenessValidation(TestCase): assert not serializer.is_valid() assert serializer.errors == {'username': ['uniqueness model with this username already exists.']} + def test_relation_is_not_unique(self): + RelatedModel.objects.create(user=self.instance) + data = {'user': self.instance.pk} + serializer = RelatedModelUserSerializer(data=data) + assert not serializer.is_valid() + assert serializer.errors == {'user': ['related model with this user already exists.']} + def test_is_unique(self): data = {'username': 'other'} serializer = UniquenessSerializer(data=data) @@ -301,6 +313,92 @@ class TestUniquenessTogetherValidation(TestCase): ] } + def test_read_only_fields_with_default_and_source(self): + class ReadOnlySerializer(serializers.ModelSerializer): + name = serializers.CharField(source='race_name', default='test', read_only=True) + + class Meta: + model = UniquenessTogetherModel + fields = ['name', 'position'] + validators = [ + UniqueTogetherValidator( + queryset=UniquenessTogetherModel.objects.all(), + fields=['name', 'position'] + ) + ] + + serializer = ReadOnlySerializer(data={'position': 1}) + assert serializer.is_valid(raise_exception=True) + + def test_writeable_fields_with_source(self): + class WriteableSerializer(serializers.ModelSerializer): + name = serializers.CharField(source='race_name') + + class Meta: + model = UniquenessTogetherModel + fields = ['name', 'position'] + validators = [ + UniqueTogetherValidator( + queryset=UniquenessTogetherModel.objects.all(), + fields=['name', 'position'] + ) + ] + + serializer = WriteableSerializer(data={'name': 'test', 'position': 1}) + assert serializer.is_valid(raise_exception=True) + + # Validation error should use seriazlier field name, not source + serializer = WriteableSerializer(data={'position': 1}) + assert not serializer.is_valid() + assert serializer.errors == { + 'name': [ + 'This field is required.' + ] + } + + def test_default_validator_with_fields_with_source(self): + class TestSerializer(serializers.ModelSerializer): + name = serializers.CharField(source='race_name') + + class Meta: + model = UniquenessTogetherModel + fields = ['name', 'position'] + + serializer = TestSerializer() + expected = dedent(""" + TestSerializer(): + name = CharField(source='race_name') + position = IntegerField() + class Meta: + validators = [] + """) + assert repr(serializer) == expected + + def test_default_validator_with_multiple_fields_with_same_source(self): + class TestSerializer(serializers.ModelSerializer): + name = serializers.CharField(source='race_name') + other_name = serializers.CharField(source='race_name') + + class Meta: + model = UniquenessTogetherModel + fields = ['name', 'other_name', 'position'] + + serializer = TestSerializer(data={ + 'name': 'foo', + 'other_name': 'foo', + 'position': 1, + }) + with pytest.raises(AssertionError) as excinfo: + serializer.is_valid() + + expected = ( + "Unable to create `UniqueTogetherValidator` for " + "`UniquenessTogetherModel.race_name` as `TestSerializer` has " + "multiple fields (name, other_name) that map to this model field. " + "Either remove the extra fields, or override `Meta.validators` " + "with a `UniqueTogetherValidator` using the desired field names.") + assert str(excinfo.value) == expected + def test_allow_explict_override(self): """ Ensure validators can be explicitly removed.. @@ -353,16 +451,16 @@ class TestUniquenessTogetherValidation(TestCase): filter_queryset should add value from existing instance attribute if it is not provided in attributes dict """ - class MockQueryset(object): + class MockQueryset: def filter(self, **kwargs): self.called_with = kwargs data = {'race_name': 'bar'} queryset = MockQueryset() + serializer = UniquenessTogetherSerializer(instance=self.instance) validator = UniqueTogetherValidator(queryset, fields=('race_name', 'position')) - validator.instance = self.instance - validator.filter_queryset(attrs=data, queryset=queryset) + validator.filter_queryset(attrs=data, queryset=queryset, serializer=serializer) assert queryset.called_with == {'race_name': 'bar', 'position': 1} @@ -558,19 +656,19 @@ class TestHiddenFieldUniquenessForDateValidation(TestCase): class ValidatorsTests(TestCase): def test_qs_exists_handles_type_error(self): - class TypeErrorQueryset(object): + class TypeErrorQueryset: def exists(self): raise TypeError assert qs_exists(TypeErrorQueryset()) is False def test_qs_exists_handles_value_error(self): - class ValueErrorQueryset(object): + class ValueErrorQueryset: def exists(self): raise ValueError assert qs_exists(ValueErrorQueryset()) is False def test_qs_exists_handles_data_error(self): - class DataErrorQueryset(object): + class DataErrorQueryset: def exists(self): raise DataError assert qs_exists(DataErrorQueryset()) is False @@ -586,4 +684,6 @@ class ValidatorsTests(TestCase): validator = BaseUniqueForValidator(queryset=object(), field='foo', date_field='bar') with pytest.raises(NotImplementedError): - validator.filter_queryset(attrs=None, queryset=None) + validator.filter_queryset( + attrs=None, queryset=None, field_name='', date_field_name='' + ) diff --git a/tests/test_versioning.py b/tests/test_versioning.py index 7e650e275..d40d54229 100644 --- a/tests/test_versioning.py +++ b/tests/test_versioning.py @@ -1,6 +1,6 @@ import pytest -from django.conf.urls import include, url from django.test import override_settings +from django.urls import include, path, re_path from rest_framework import serializers, status, versioning from rest_framework.decorators import APIView @@ -144,14 +144,14 @@ class TestRequestVersion: class TestURLReversing(URLPatternsTestCase, APITestCase): included = [ - url(r'^namespaced/$', dummy_view, name='another'), - url(r'^example/(?P\d+)/$', dummy_pk_view, name='example-detail') + path('namespaced/', dummy_view, name='another'), + path('example//', dummy_pk_view, name='example-detail') ] urlpatterns = [ - url(r'^v1/', include((included, 'v1'), namespace='v1')), - url(r'^another/$', dummy_view, name='another'), - url(r'^(?P[v1|v2]+)/another/$', dummy_view, name='another'), + path('v1/', include((included, 'v1'), namespace='v1')), + path('another/', dummy_view, name='another'), + re_path(r'^(?P[v1|v2]+)/another/$', dummy_view, name='another'), ] def test_reverse_unversioned(self): @@ -310,18 +310,18 @@ class TestAllowedAndDefaultVersion: class TestHyperlinkedRelatedField(URLPatternsTestCase, APITestCase): included = [ - url(r'^namespaced/(?P\d+)/$', dummy_pk_view, name='namespaced'), + path('namespaced//', dummy_pk_view, name='namespaced'), ] urlpatterns = [ - url(r'^v1/', include((included, 'v1'), namespace='v1')), - url(r'^v2/', include((included, 'v2'), namespace='v2')) + path('v1/', include((included, 'v1'), namespace='v1')), + path('v2/', include((included, 'v2'), namespace='v2')) ] def setUp(self): - super(TestHyperlinkedRelatedField, self).setUp() + super().setUp() - class MockQueryset(object): + class MockQueryset: def get(self, pk): return 'object %s' % pk @@ -342,17 +342,17 @@ class TestHyperlinkedRelatedField(URLPatternsTestCase, APITestCase): class TestNamespaceVersioningHyperlinkedRelatedFieldScheme(URLPatternsTestCase, APITestCase): nested = [ - url(r'^namespaced/(?P\d+)/$', dummy_pk_view, name='nested'), + path('namespaced//', dummy_pk_view, name='nested'), ] included = [ - url(r'^namespaced/(?P\d+)/$', dummy_pk_view, name='namespaced'), - url(r'^nested/', include((nested, 'nested-namespace'), namespace='nested-namespace')) + path('namespaced//', dummy_pk_view, name='namespaced'), + path('nested/', include((nested, 'nested-namespace'), namespace='nested-namespace')) ] urlpatterns = [ - url(r'^v1/', include((included, 'restframeworkv1'), namespace='v1')), - url(r'^v2/', include((included, 'restframeworkv2'), namespace='v2')), - url(r'^non-api/(?P\d+)/$', dummy_pk_view, name='non-api-view') + path('v1/', include((included, 'restframeworkv1'), namespace='v1')), + path('v2/', include((included, 'restframeworkv2'), namespace='v2')), + path('non-api//', dummy_pk_view, name='non-api-view') ] def _create_field(self, view_name, version): diff --git a/tests/test_views.py b/tests/test_views.py index f0919e846..2648c9fb3 100644 --- a/tests/test_views.py +++ b/tests/test_views.py @@ -1,7 +1,4 @@ -from __future__ import unicode_literals - import copy -import sys from django.test import TestCase @@ -14,10 +11,7 @@ from rest_framework.views import APIView factory = APIRequestFactory() -if sys.version_info[:2] >= (3, 4): - JSON_ERROR = 'JSON parse error - Expecting value:' -else: - JSON_ERROR = 'JSON parse error - No JSON object could be decoded' +JSON_ERROR = 'JSON parse error - Expecting value:' class BasicView(APIView): diff --git a/tests/test_viewsets.py b/tests/test_viewsets.py index eac36f095..8842b0b1c 100644 --- a/tests/test_viewsets.py +++ b/tests/test_viewsets.py @@ -1,9 +1,10 @@ from collections import OrderedDict +from functools import wraps import pytest -from django.conf.urls import include, url from django.db import models from django.test import TestCase, override_settings +from django.urls import include, path from rest_framework import status from rest_framework.decorators import action @@ -33,18 +34,31 @@ class Action(models.Model): pass +def decorate(fn): + @wraps(fn) + def wrapper(self, request, *args, **kwargs): + return fn(self, request, *args, **kwargs) + return wrapper + + class ActionViewSet(GenericViewSet): queryset = Action.objects.all() def list(self, request, *args, **kwargs): - return Response() + response = Response() + response.view = self + return response def retrieve(self, request, *args, **kwargs): - return Response() + response = Response() + response.view = self + return response @action(detail=False) def list_action(self, request, *args, **kwargs): - raise NotImplementedError + response = Response() + response.view = self + return response @action(detail=False, url_name='list-custom') def custom_list_action(self, request, *args, **kwargs): @@ -62,11 +76,23 @@ class ActionViewSet(GenericViewSet): def unresolvable_detail_action(self, request, *args, **kwargs): raise NotImplementedError + @action(detail=False) + @decorate + def wrapped_list_action(self, request, *args, **kwargs): + raise NotImplementedError + + @action(detail=True) + @decorate + def wrapped_detail_action(self, request, *args, **kwargs): + raise NotImplementedError + class ActionNamesViewSet(GenericViewSet): def retrieve(self, request, *args, **kwargs): - return Response() + response = Response() + response.view = self + return response @action(detail=True) def unnamed_action(self, request, *args, **kwargs): @@ -81,14 +107,24 @@ class ActionNamesViewSet(GenericViewSet): raise NotImplementedError +class ThingWithMapping: + def __init__(self): + self.mapping = {} + + +class ActionViewSetWithMapping(ActionViewSet): + mapper = ThingWithMapping() + + router = SimpleRouter() router.register(r'actions', ActionViewSet) router.register(r'actions-alt', ActionViewSet, basename='actions-alt') router.register(r'names', ActionNamesViewSet, basename='names') +router.register(r'mapping', ActionViewSetWithMapping, basename='mapping') urlpatterns = [ - url(r'^api/', include(router.urls)), + path('api/', include(router.urls)), ] @@ -103,7 +139,7 @@ class InitializeViewSetsTestCase(TestCase): assert response.status_code == status.HTTP_200_OK assert response.data == {'ACTION': 'LIST'} - def testhead_request_against_viewset(self): + def test_head_request_against_viewset(self): request = factory.head('/', '', content_type='application/json') my_view = BasicViewSet.as_view(actions={ 'get': 'list', @@ -145,6 +181,22 @@ class InitializeViewSetsTestCase(TestCase): self.assertNotIn(attribute, dir(bare_view)) self.assertIn(attribute, dir(view)) + def test_viewset_action_attr(self): + view = ActionViewSet.as_view(actions={'get': 'list'}) + + get = view(factory.get('/')) + head = view(factory.head('/')) + assert get.view.action == 'list' + assert head.view.action == 'list' + + def test_viewset_action_attr_for_extra_action(self): + view = ActionViewSet.as_view(actions=dict(ActionViewSet.list_action.mapping)) + + get = view(factory.get('/')) + head = view(factory.head('/')) + assert get.view.action == 'list_action' + assert head.view.action == 'list_action' + class GetExtraActionsTests(TestCase): @@ -157,32 +209,74 @@ class GetExtraActionsTests(TestCase): 'detail_action', 'list_action', 'unresolvable_detail_action', + 'wrapped_detail_action', + 'wrapped_list_action', ] self.assertEqual(actual, expected) + def test_should_only_return_decorated_methods(self): + view = ActionViewSetWithMapping() + actual = [action.__name__ for action in view.get_extra_actions()] + expected = [ + 'custom_detail_action', + 'custom_list_action', + 'detail_action', + 'list_action', + 'unresolvable_detail_action', + 'wrapped_detail_action', + 'wrapped_list_action', + ] + self.assertEqual(actual, expected) + + def test_attr_name_check(self): + def decorate(fn): + def wrapper(self, request, *args, **kwargs): + return fn(self, request, *args, **kwargs) + return wrapper + + class ActionViewSet(GenericViewSet): + queryset = Action.objects.all() + + @action(detail=False) + @decorate + def wrapped_list_action(self, request, *args, **kwargs): + raise NotImplementedError + + view = ActionViewSet() + with pytest.raises(AssertionError) as excinfo: + view.get_extra_actions() + + assert str(excinfo.value) == ( + 'Expected function (`wrapper`) to match its attribute name ' + '(`wrapped_list_action`). If using a decorator, ensure the inner ' + 'function is decorated with `functools.wraps`, or that ' + '`wrapper.__name__` is otherwise set to `wrapped_list_action`.') + @override_settings(ROOT_URLCONF='tests.test_viewsets') class GetExtraActionUrlMapTests(TestCase): def test_list_view(self): response = self.client.get('/api/actions/') - view = response.renderer_context['view'] + view = response.view expected = OrderedDict([ ('Custom list action', 'http://testserver/api/actions/custom_list_action/'), ('List action', 'http://testserver/api/actions/list_action/'), + ('Wrapped list action', 'http://testserver/api/actions/wrapped_list_action/'), ]) self.assertEqual(view.get_extra_action_url_map(), expected) def test_detail_view(self): response = self.client.get('/api/actions/1/') - view = response.renderer_context['view'] + view = response.view expected = OrderedDict([ ('Custom detail action', 'http://testserver/api/actions/1/custom_detail_action/'), ('Detail action', 'http://testserver/api/actions/1/detail_action/'), + ('Wrapped detail action', 'http://testserver/api/actions/1/wrapped_detail_action/'), # "Unresolvable detail action" excluded, since it's not resolvable ]) @@ -194,7 +288,7 @@ class GetExtraActionUrlMapTests(TestCase): def test_action_names(self): # Action 'name' and 'suffix' kwargs should be respected response = self.client.get('/api/names/1/') - view = response.renderer_context['view'] + view = response.view expected = OrderedDict([ ('Custom Name', 'http://testserver/api/names/1/named_action/'), diff --git a/tests/urls.py b/tests/urls.py index 76ada5e3d..d9147683f 100644 --- a/tests/urls.py +++ b/tests/urls.py @@ -3,14 +3,14 @@ URLConf for test suite. We need only the docs urls for DocumentationRenderer tests. """ -from django.conf.urls import url +from django.urls import path from rest_framework.compat import coreapi from rest_framework.documentation import include_docs_urls if coreapi: urlpatterns = [ - url(r'^docs/', include_docs_urls(title='Test Suite API')), + path('docs/', include_docs_urls(title='Test Suite API')), ] else: urlpatterns = [] diff --git a/tests/utils.py b/tests/utils.py index 509e6a102..06e5b9abe 100644 --- a/tests/utils.py +++ b/tests/utils.py @@ -2,7 +2,7 @@ from django.core.exceptions import ObjectDoesNotExist from django.urls import NoReverseMatch -class MockObject(object): +class MockObject: def __init__(self, **kwargs): self._kwargs = kwargs for key, val in kwargs.items(): @@ -16,7 +16,7 @@ class MockObject(object): return '' % kwargs_str -class MockQueryset(object): +class MockQueryset: def __init__(self, iterable): self.items = iterable @@ -33,7 +33,7 @@ class MockQueryset(object): raise ObjectDoesNotExist() -class BadType(object): +class BadType: """ When used as a lookup with a `MockQueryset`, these objects will raise a `TypeError`, as occurs in Django when making diff --git a/tox.ini b/tox.ini index 4226f1a92..957d8a2e7 100644 --- a/tox.ini +++ b/tox.ini @@ -1,32 +1,33 @@ [tox] envlist = - {py27,py34,py35,py36}-django111, - {py34,py35,py36,py37}-django20, - {py35,py36,py37}-django21 - {py35,py36,py37}-django22 - {py36,py37}-djangomaster, - base,dist,lint,docs, + {py36,py37,py38,py39}-django30, + {py36,py37,py38,py39}-django31, + {py36,py37,py38,py39,py310}-django32, + {py38,py39,py310}-{django40,django41,djangomain}, + base,dist,docs, [travis:env] DJANGO = - 1.11: django111 - 2.0: django20 - 2.1: django21 - 2.2: django22 - master: djangomaster + 3.0: django30 + 3.1: django31 + 3.2: django32 + 4.0: django40 + 4.1: django41 + main: djangomain [testenv] -commands = ./runtests.py --fast --coverage {posargs} +commands = python -W error::DeprecationWarning -W error::PendingDeprecationWarning runtests.py --coverage {posargs} envdir = {toxworkdir}/venvs/{envname} setenv = PYTHONDONTWRITEBYTECODE=1 PYTHONWARNINGS=once deps = - django111: Django>=1.11,<2.0 - django20: Django>=2.0,<2.1 - django21: Django>=2.1,<2.2 - django22: Django>=2.2b1,<3.0 - djangomaster: https://github.com/django/django/archive/master.tar.gz + django30: Django>=3.0,<3.1 + django31: Django>=3.1,<3.2 + django32: Django>=3.2,<4.0 + django40: Django>=4.0,<4.1 + django41: Django>=4.1a1,<4.2 + djangomain: https://github.com/django/django/archive/main.tar.gz -rrequirements/requirements-testing.txt -rrequirements/requirements-optionals.txt @@ -37,22 +38,24 @@ deps = -rrequirements/requirements-testing.txt [testenv:dist] -commands = ./runtests.py --fast --no-pkgroot --staticfiles {posargs} +commands = ./runtests.py --no-pkgroot --staticfiles {posargs} deps = django -rrequirements/requirements-testing.txt -rrequirements/requirements-optionals.txt -[testenv:lint] -basepython = python2.7 -commands = ./runtests.py --lintonly -deps = - -rrequirements/requirements-codestyle.txt - -rrequirements/requirements-testing.txt - [testenv:docs] -basepython = python2.7 +skip_install = true commands = mkdocs build deps = -rrequirements/requirements-testing.txt -rrequirements/requirements-documentation.txt + +[testenv:py38-djangomain] +ignore_outcome = true + +[testenv:py39-djangomain] +ignore_outcome = true + +[testenv:py310-djangomain] +ignore_outcome = true